Recursos para IA

Cartões

A integração de pagamentos com cartão de crédito e/ou débito no Checkout API pode ser realizada de duas maneiras para aplicativos mobile. A integração recomendada é através do Card Payment Brick (via Mercado Pago SDK Checkout), mas, se quiser ter a opção de definir como as informações serão buscadas, é possível integrar através de Core Methods (via Mercado Pago SDK Core Methods), disponíveis para aplicativos Android e iOS.

A integração mobile via Card Payment Brick usa internamente o módulo Core Methods para se comunicar com a API de Orders e enviar o pagamento. Ao usar ambas as integrações no mesmo aplicativo, controle as versões para evitar conflitos.

Confira abaixo o fluxo principal da integração mobile via Card Payment.

Card Payment

O Card Payment (via Mercado Pago SDK Checkout) acelera a implementação de pagamentos com cartão em aplicativos Android e iOS nativos. O SDK exibe o formulário, busca os dados necessários do cartão, permite a seleção de parcelas, tokeniza as informações de forma segura e processa o pagamento contra uma order criada previamente no backend.

O fluxo principal dessa integração com o SDK Checkout é o CardTransaction, onde o backend cria a order com o Access Token e envia ao aplicativo apenas o orderId e o clientToken. Dessa forma, a credencial privada permanece protegida e os dados sensíveis do cartão são tratados em conformidade com os padrões de segurança PCI.

Para integrar o Card Payment, é preciso ter configurado o Mercado Pago SDK Checkout no ambiente de desenvolvimento e, a partir disso, seguir as etapas abaixo de acordo com o sistema operacional escolhido.

Além do fluxo principal apresentado nesta seção, o Mercado Pago SDK Checkout oferece recursos adicionais para a integração mobile com Card Payment, como restringir os meios de pagamento aceitos, limitar o intervalo de parcelas, tokenizar um cartão sem realizar a cobrança e tratar o cancelamento pelo comprador. Para mais detalhes, consulte a seção de Personalização de comportamento do checkout.

O SDK Checkout para Android é a biblioteca nativa para integrar pagamentos com cartão em aplicativos Android. Desenvolvido em Kotlin com suporte a Jetpack Compose, ele encapsula toda a comunicação com a Orders API — tokenização de cartão, seleção de parcelas, validação de bandeira e submissão do pagamento — em um fluxo gerenciado, sem precisar manipular dados sensíveis.

A distribuição é feita via Jetpack Compose BoM para garantir versões coerentes entre os módulos, com requisitos mínimos de Android 6.0+ (SDK versão 23 ou superior) e Kotlin 2.0+.

Para aprofundar o entendimento sobre a implementação e utilização do SDK, consulte o repositório no GitHub para exemplos de referências, tanto da integração via Card Payment como a de Core Methods, apresentando um fluxo de checkout integrado e seguro.

Criar order

Antes de exibir o Card Payment, crie uma order no seu backend por meio do endpoint /v1/ordersPOST, utilizando seu Access Token de testeChave privada da aplicação criada no Mercado Pago e utilizada no backend. Você pode acessá-la em Suas integrações > Dados da integração > Testes > Credenciais de teste..

No fluxo CardTransaction, crie a order em modo manual (processing_mode=manual) e não envie a transação de pagamento nesse momento. A resposta fornecerá o id da order e o client_token necessários para o SDK tokenizar o cartão e processar o pagamento contra a order existente.

Também é possível tokenizar um cartão sem realizar uma cobrança, útil para capturar os dados do comprador em um momento e efetuar o pagamento em outro. Nesse caso, o SDK gera o token sem criar uma order nem movimentar dinheiro. Para mais informações, consulte Tokenizar cartão sem realizar pagamento.

curl
curl -X POST \
    'https://api.mercadopago.com/v1/orders' \
    -H 'Content-Type: application/json' \
    -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \
    -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
    -d '{
    "type": "online",
    "processing_mode": "manual",
    "total_amount": "100.00",
    "external_reference": "ext_ref_1234",
    "payer": {
        "email": "test@testuser.com"
    },
    "items": [
        {
            "title": "Produto",
            "quantity": 1,
            "unit_price": "100.00"
        }
    ]
}'

Parâmetro	Tipo	Descrição	Obrigatoriedade
`Authorization`	Header	Faz referência à sua chave privada, o Access Token de testeChave privada da aplicação criada no Mercado Pago e que é utilizada no backend. Você pode acessá-la através de Suas integrações > Dados da integração > Testes > Credenciais de teste. O Access Token de teste começa com o prefixo `APP_USR`..	Obrigatório
`X-Idempotency-Key`	Header	Chave de idempotência. Essa chave garante que cada solicitação seja processada apenas uma vez, evitando duplicidades. Use um valor exclusivo no `header` da requisição, como um UUID V4 ou uma string aleatória.	Obrigatório
`processing_mode`	Body. String	Modo de processamento da order. Os valores possíveis são: - `automatic`: para criar e processar a order em modo automático. - `manual`: para criar a order e processá-la posteriormente. Nesse caso, use `manual` para permitir que o SDK complete e processe a transação por meio do `client_token`.	Obrigatório
`total_amount`	Body. String	Valor total da transação.	Obrigatório
`payer.email`	Body. String	E-mail do pagador.	Obrigatório

Em caso de sucesso, a API retornará a order criada e o token de autenticação para o processamento no aplicativo.

json
{
  "id": "ORD01JS2V6CM8KJ0EC4H502TGK1WP",
  "status": "created",
  "client_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "total_amount": "100.00"
}

Use o valor de id como orderId e o valor de client_token como clientToken na configuração do SDK.

Para conhecer todos os parâmetros disponíveis, consulte a Referência de APIAPI. Caso receba um erro, consulte a lista de erros.

Configurar e exibir o Card Payment

No SDK Checkout, passe ao MPOrder os dados da order criada no seu backend. O SDK exibirá o formulário, permitirá a seleção de parcelas, tokenizará o cartão e processará o pagamento contra essa order.

Se for necessário restringir algum tipo de cartão, as bandeiras aceitas ou o intervalo de parcelas, essa configuração deve ser aplicada antes de iniciar a tokenização. As regras são avaliadas no momento em que o formulário é exibido, portanto um cartão fora das restrições é recusado sem gerar nenhum token. Para mais informações, consulte a seção Restringir meios de pagamento e limitar parcelas.

kotlin
val checkout = MercadoPagoCheckout.Builder(
    context = this,
    checkoutType = MPCheckoutType.CardTransaction(
        order = MPOrder(
            orderId = "ORD01JS2V6CM8KJ0EC4H502TGK1WP",
            clientToken = "client-token-da-order"
        )
    )
).build()

checkout.show { result ->
    when (result) {
        is MercadoPagoCheckoutResult.Success -> {
            val data = result.paymentData // MPPaymentData.CardTransaction
            // Use data.orderId, data.orderStatus, etc.
        }
        is MercadoPagoCheckoutResult.Error -> {
            // Exiba uma mensagem de erro ou ofereça uma nova tentativa
        }
        is MercadoPagoCheckoutResult.UserCancelled -> {
            // Retorne ao carrinho ou à etapa anterior
        }
    }
}

Parâmetro	Tipo	Descrição
`orderId`	`String`	Identificador da order (`id`) retornado na sua criação.
`clientToken`	`String`	Token (`client_token`) retornado na criação da order e que representa as credenciais do usuário.

Em caso de sucesso, o SDK retornará em MPPaymentData.CardTransaction as seguintes informações:

Parâmetro	Tipo	Descrição
`orderId`	`String`	Identificador da order.
`orderStatus`	`String`	Status da order após o processamento.
`paymentMethodId`	`String`	Identificador do meio de pagamento.
`paymentTypeId`	`String`	Tipo do meio de pagamento.

Com o Card Payment também é possível alinhar a aparência do checkout à identidade visual do seu aplicativo. O Mercado Pago SDK Checkout usa componentes tokenizados em design atômico, de modo que alterar um token repercute automaticamente em componentes, telas e estados. Para mais informações, consulte Customizações visuais do Card Payment.

Core Methods

Na integração via Core Methods (via Mercado Pago SDK Core Methods) para aplicativos mobile, o desenvolvedor define a forma de buscar as informações necessárias para completar o pagamento, incluindo o tipo de documento e o cartão (emissor e parcelas).

Isso permite total flexibilidade na construção da experiência do fluxo de checkout, diferente da integração via Card Payment, em que a busca pelas informações é automática e a interface é pré-estabelecida.

O SDK Core Methods utiliza informações capturadas pelos campos seguros, viabilizando a execução das principais operações de pagamento.

Na integração via Core Methods para aplicativos Android, cada método deve ser utilizado de acordo com as necessidades do seu fluxo de pagamento. Para utilizá-los, comece criando uma instância do Core Methods na sua classe utilizando o seguinte código Kotlin: val coreMethods = MercadoPagoSDK.getInstance().coreMethods.

Dessa forma, você poderá utilizar qualquer um dos métodos listados abaixo:

Configurar campos seguros

Os campos seguros são componentes criados para proteger os dados sensíveis digitados pelo comprador. Desenvolvido conforme os padrões PCIConjunto de regras de segurança que buscam proteger os dados dos cartões de pagamento contra fraudes e vazamentos de dados., esses campos asseguram que o aplicativo nunca acesse as informações inseridas, que são transmitidas com segurança apenas para a criação de tokens e transações.

Todas as interações com esses campos ocorrem por meio de callbacks, permitindo a captura de eventos relevantes sem expor os dados do usuário. Os métodos descritos a seguir utilizam instâncias desses campos seguros, por isso é essencial que estejam devidamente configurados na interface do checkout antes de utilizá-los.

Cada componente notifica a aplicação integradora quando ocorre alteração no valor, sem expor os dados digitados, e também informa o resultado da validação do campo conforme as regras do PCI e do cartão.

Os dados digitados nos campos seguros nunca ficam disponíveis para a aplicação integradora. Eles são encaminhados em segurança apenas para a criação de tokens e transações.

A tabela abaixo detalha dos componentes disponíveis. Para mais informações sobre a configuração de cada um deles, consulte a referência correspondente no GitHub.

Nome do componente	Referência no GitHub	Descrição
CardNumberTextField	Referência	Campo seguro para digitar o número do cartão.
ExpirationDateTextField	Referência	Campo seguro para digitar a data de validade do cartão.
SecurityTextField	Referência	Campo seguro para digitar o código de segurança (CVV).

Obter meios de pagamento

O método Obter meios de pagamento retorna a lista de meios de pagamento disponíveis a partir do BIN do cartão informado, considerando as regras e instituições financeiras válidas para o país configurado. Por meio desse método, é possível identificar a bandeira do cartão, definir corretamente os próximos passos do checkout e validar a aceitação do cartão.

kotlin
val coreMethods = MercadoPagoSDK.getInstance().coreMethods
coroutineScope {
   val result = coreMethods.getPaymentMethods(bin = bin)
   when (result) {
       is Result.Success -> {
           print("Sucesso de request: ${result.data}")
       }
       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   print("Erro de request: ${result.error}")
               }
               is ResultError.Validation -> {
                   print("Erro de validação: ${result.error}")
               }
           }
       }
   }
}

Parâmetro	Tipo	Descrição	Obrigatoriedade
`bin`	String	Os 8 primeiros dígitos do cartão de crédito, obtidos pelo callback `onBinChange` do `CardNumberTextFieldEvent`.	Obrigatório

Para mais informações sobre a resposta da chamada, consulte a documentação do método no GitHub.

Obter condições de parcelamento

O método Obter condições de parcelamento busca todas as opções de parcelamento disponíveis para um determinado cartão e valor de transação. Ele considera as regras do emissor, do método de pagamento e do valor da compra, retornando todas as opções válidas de parcelamento, incluindo quantidade de parcelas, juros, valor de cada parcela e valor total.

A chamada ao método getInstallments deve ser feita para todos os tipos de cartão (débito e crédito) para verificar se o pagamento pode ser concluído por esse meio.

kotlin
val coreMethods = MercadoPagoSDK.getInstance().coreMethods
coroutineScope {
   val result = coreMethods.getInstallments(
       bin = bin,
       amount = BigDecimal("100.00")
   )
   when (result) {
       is Result.Success -> {
           print("Sucesso de request: ${result.data}")
       }
       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   print("Erro de request: ${result.error}")
               }
               is ResultError.Validation -> {
                   print("Erro de validação: ${result.error}")
               }
           }
       }
   }
}

Utilize as informações do Installment para exibir ao comprador todos os detalhes do valor e do parcelamento da compra, antes da finalização do pagamento.

Parâmetro	Tipo	Descrição	Obrigatoriedade
`bin`	String	Os 8 primeiros dígitos do cartão de crédito, obtidos pelo callback `onBinChange` do `CardNumberTextFieldEvent`.	Obrigatório
`amount`	BigDecimal	Valor total da transação.	Obrigatório

Para mais informações sobre a resposta da chamada, consulte a documentação do método no GitHub.

Obter emissor do cartão

Em determinados meios de pagamento e bandeiras, o Mercado Pago exige a identificação do emissor do cartão (issuer). Este método retorna a lista de emissores disponíveis para o BIN informado, permitindo ao comprador selecionar o emissor correto quando necessário.

kotlin
val coreMethods = MercadoPagoSDK.getInstance().coreMethods
coroutineScope {
   val result = coreMethods.getCardIssuers(
       bin = bin,
       paymentMethodId = paymentMethodId,
   )
   when (result) {
       is Result.Success -> {
           print("Sucesso de request: ${result.data}")
       }
       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   print("Erro de request: ${result.error}")
               }
               is ResultError.Validation -> {
                   print("Erro de validação: ${result.error}")
               }
           }
       }
   }
}

Parâmetro	Tipo	Descrição	Obrigatoriedade
`bin`	String	Os 8 primeiros dígitos do cartão de crédito, obtidos pelo callback `onBinChange` do `CardNumberTextFieldEvent`.	Obrigatório
`paymentMethodId`	String	ID do método de pagamento, normalmente obtido a partir do resultado do método `PaymentMethods`.	Obrigatório

Para mais informações sobre a resposta da chamada, consulte a documentação do método no GitHub.

Obter tipos de documento

O Mercado Pago exige a validação de um documento de identificação do titular do cartão. Utilize este método para receber todos os tipos de documentos aceitos para o país configurado na integração.

kotlin
val coreMethods = MercadoPagoSDK.getInstance().coreMethods
coroutineScope {
   val result = coreMethods.getIdentificationTypes()
   when (result) {
       is Result.Success -> {
           print("Sucesso de request: ${result.data}")
       }
       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   print("Erro de request: ${result.error}")
               }
               is ResultError.Validation -> {
                   print("Erro de validação: ${result.error}")
               }
           }
       }
   }
}

Para mais informações sobre a resposta da chamada, consulte a documentação do método no GitHub.

Criar token do cartão

Este método permite gerar um token temporário a partir dos dados do cartão informado. Este token é obrigatório para realizar a transação de pagamento via API do Mercado Pago, pois substitui os dados sensíveis do cartão, garantindo maior segurança no processo.

Este método exige a configuração prévia dos campos seguros na interface do checkout. Antes de utilizar o generateCardToken, certifique-se de que os campos foram devidamente implementados e configurados.

Criar um token para um novo cartão

Para gerar um token para um novo cartão de forma segura, utilize a classe que protege os dados digitados e passe-a para o método generateCardToken. Antes de executar o método, verifique se todos os campos obrigatórios estão preenchidos corretamente.

kotlin
val coreMethods = MercadoPagoSDK.getInstance().coreMethods
coroutineScope {
   val result = coreMethods.generateCardToken(
      cardNumberState = cardNumberPCIFieldState,
      expirationDateState = expirationDatePCIFieldState,
      securityCodeState = securityCodePCIFieldState,
      buyerIdentification = BuyerIdentification(
          name = "APRO",
          number = "12345678909",
          type = "CPF"
      )
   )
   when (result) {
       is Result.Success -> {
           print("Sucesso de request: ${result.data}")
       }
       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   print("Erro de request: ${result.error}")
               }
               is ResultError.Validation -> {
                   print("Erro de validação: ${result.error}")
               }
           }
       }
   }
}

Parâmetro	Tipo	Descrição	Obrigatoriedade
`cardNumberState`	PCIFieldState	Estado do campo de número de cartão.	Obrigatório
`expirationDateState`	PCIFieldState	Estado do campo de expiração do cartão.	Obrigatório
`securityCodeState`	PCIFieldState	Estado do campo de código de segurança do cartão.	Obrigatório
`buyerIdentification`	BuyerIdentification	Classe de identificação do comprador.	Obrigatório

Para mais informações sobre a resposta da chamada, consulte a documentação do método no GitHub.

Criar um token para um cartão existente

Nas transações com o Mercado Pago, os dados dos cartões cadastrados pelo comprador são armazenados com segurança e não ficam acessíveis a partir do seu backend. A aplicação recebe apenas o id do cartão, que deve ser utilizado para gerar um token temporário. Isso protege as informações sensíveis, pois apenas o id é manipulado, enquanto o número do cartão, CVV e data de vencimento não são expostos e permanecem seguros.

kotlin
val coreMethods = MercadoPagoSDK.getInstance().coreMethods
coroutineScope {
   val result = coreMethods.generateCardToken(
      cardId = cardId,
      expirationDateState = expirationDatePCIFieldState,
      securityCodeState = securityCodePCIFieldState,
      buyerIdentification = BuyerIdentification(
          name = "APRO",
          number = "12345678909",
          type = "CPF"
      )
   )
   when (result) {
       is Result.Success -> {
           print("Sucesso de request: ${result.data}")
       }
       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   print("Erro de request: ${result.error}")
               }
               is ResultError.Validation -> {
                   print("Erro de validação: ${result.error}")
               }
           }
       }
   }
}

Parâmetro	Tipo	Descrição	Obrigatoriedade
`cardId`	String	ID do cartão existente gerado.	Obrigatório
`securityCodeState`	PCIFieldState	Estado do campo de código de segurança do cartão.	Obrigatório
`expirationDateState`	PCIFieldState	Estado do campo de expiração do cartão.	Opcional
`buyerIdentification`	BuyerIdentification	Classe de identificação do comprador.	Obrigatório

Para mais informações sobre a resposta da chamada, consulte a documentação do método no GitHub.

Realizar pagamento

O envio do pagamento deve ser realizado mediante a criação de uma order que contenha a transação de pagamento associada.

Para isso, envie uma requisição com seu Access Token de testeChave privada da aplicação criada no Mercado Pago e que é utilizada no backend. Você pode acessá-la através de Suas integrações > Dados da integração > Testes > Credenciais de teste. O Access Token de teste começa com o prefixo `APP_USR`. e os parâmetros requeridos listados abaixo ao endpoint /v1/ordersPOST.

curl
curl -X POST \
    'https://api.mercadopago.com/v1/orders'\
    -H 'Content-Type: application/json' \
       -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \
       -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
    -d '{
    "type": "online",
    "processing_mode": "automatic",
    "total_amount": "50.00",
    "external_reference": "ext_ref_1234",
    "payer": {
        "email": "test@testuser.com"
    },
    "transactions": {
        "payments": [
            {
                "amount": "50.00",
                "payment_method": {
                    "id": "master",
                    "type": "credit_card",
                    "token": "1223123",
                    "installments": 1
                }
            }
        ]
    }
}'

Parâmetro	Tipo	Descrição	Obrigatoriedade
`Authorization`	Header	Faz referência à sua chave privada, o Access Token de testeChave privada da aplicação criada no Mercado Pago e que é utilizada no backend. Você pode acessá-la através de Suas integrações > Dados da integração > Testes > Credenciais de teste. O Access Token de teste começa com o prefixo `APP_USR`..	Obrigatório
`X-Idempotency-Key`	Header	Chave de idempotência. Essa chave garante que cada solicitação seja processada apenas uma vez, evitando duplicidades. Use um valor exclusivo no `header` da requisição, como um UUID V4 ou uma string aleatória.	Obrigatório
`processing_mode`	Body. String	Modo de processamento da order. Os valores possíveis são: - `automatic`: para criar e processar a order em modo automático. - `manual`: para criar a order e processá-la posteriormente. Para mais informações, acesse a seção Modelo de integração.	Obrigatório
`total_amount`	Body. String	Valor total da transação.	Obrigatório
`transactions.payments.payment_method.id`	Body. String	Identificador do meio de pagamento. Neste caso, é a bandeira de cada cartão. Você pode consultar a lista completa de identificadores disponíveis enviando uma requisição ao endpoint Obter meios de pagamentoGET.	Obrigatório
`transactions.payments.payment_method.type`	Body. String	Tipo de meio de pagamento. Para pagamentos com cartão de crédito, deve ser `credit_card`, e para pagamentos com cartão de débito, deve ser `debit_card`.	Obrigatório
`transactions.payments.payment_method.token`	Body. String	Token do cartão. Campo obrigatório para pagamentos com cartão de crédito e débito.	Obrigatório

Para conhecer em detalhe todos os parâmetros enviados nesta requisição, consulte nossa Referência de APIAPI. Caso receba um erro ao enviar o pagamento, consulte nossa lista de erros.

Em caso de sucesso, a resposta será semelhante ao exemplo abaixo.

json
{
  "id": "ORD01JS2V6CM8KJ0EC4H502TGK1WP",
  "type": "online",
  "processing_mode": "automatic",
  "external_reference": "ext_ref_1234",
  "total_amount": "50.00",
  "total_paid_amount": "50.00",
  "country_code": "COL",
  "user_id": "2021490138",
  "status": "processed",
  "status_detail": "accredited",
  "capture_mode": "automatic_async",
  "created_date": "2025-04-17T21:41:33.96Z",
  "last_updated_date": "2025-04-17T21:41:35.144Z",
  "integration_data": {
    "application_id": "874202490252970"
  },
  "transactions": {
    "payments": [
      {
        "id": "PAY01JS2V6CM8KJ0EC4H504R7YE34",
        "amount": "50.00",
        "paid_amount": "50.00",
        "reference_id": "0002yjis6j",
        "status": "processed",
        "status_detail": "accredited",
        "payment_method": {
          "id": "master",
          "type": "credit_card",
          "token": "519ada5ac7431ef6ce24ac19c38f6768",
          "installments": 1
        }
      }
    ]
  }
}

Parâmetro	Tipo	Descrição
`transactions.payments.status`	String	Status da transação. Por exemplo, `processed` indica que o pagamento foi aprovado. Consulte a seção Status da transação para ver todos os valores possíveis.
`transactions.payments.status_detail`	String	Detalhe do status da transação. Por exemplo, `accredited` indica que o pagamento foi aprovado e creditado.
`transactions.payments.paid_amount`	String	Valor efetivamente pago na transação.

Caso tenha a order em modo manual, lembre-se de que o processamento do pagamento requer a etapa adicional de requisição ao endpoint Processar orderPOST. Além disso, é possível realizar uma reserva e captura de valores. Saiba mais na seção Reservar, capturar e cancelar valores.

Uma vez criada a order e o pagamento, você pode consultar os estados possíveis dirigindo-se às seções Status da order e Status da transação, respectivamente.

AnteriorIntroduçãoConheça quais meios de pagamento você pode disponibilizar utilizando o Checkout API em sua loja online mobile.

PróximoConfigurar notificações de ordersConfigure notificações de orders para receber alertas das suas transações com o Checkout API.