Recursos para IA

Integrar para aplicativos móveis

A integração de pagamentos via cartão em aplicativos móveis é realizada por meio dos Core Methods, que oferecem controle total sobre a captura e o processamento das informações de pagamento. Além disso, você pode criar e personalizar seu próprio formulário, aplicando estilizações que garantam uma experiência do usuário alinhada à identidade visual do aplicativo.

Para integrar cartões utilizando os Core Methods, consulte as instruções específicas para cada tecnologia:

Requisitos

Antes de começar a integração, certifique-se de que seu projeto atende aos seguintes requisitos:

Requisitos	Descrição
SDK	Versão 23 ou superior
Jetpack Compose BoM	Versão 2024.12.01 ou superior
Kotlin	Versão 2.0 ou superior
Public Key	A Public KeyChave pública que é utilizada no frontend para acessar informações e criptografar dados. Você pode acessá-la através de Suas integrações > Detalhes da aplicação > Produção > Credenciais de produção. está diretamente vinculada à aplicaçãoEntidade registrada no Mercado Pago que atua como um identificador para gerenciar suas integrações. Para mais informações, acesse o link abaixo.Detalhes da aplicação que você criou, por isso cada uma delas é única para cada integração.

Integrar SDK

O SDK nativo do Mercado Pago fornece uma solução robusta e segura para a integração de cartões, assegurando total conformidade com as normas PCI.

Para integrar o SDK do Mercado Pago ao seu projeto Android, siga as etapas descritas na documentação do SDK Nativo.

Configurar campos seguros

Os campos seguros são componentes desenvolvidos para garantir a privacidade e a proteção dos dados sensíveis digitados pelo comprador. Em total conformidade com 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 tenha acesso direto às 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.

Na tabela abaixo, você encontrará o detalhamento dos componentes disponíveis. Para mais informações sobre a configuração, consulte a referência correspondente a cada um deles 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).

Core Methods

Os Core Methods são essenciais para a construção de um fluxo de checkout integrado ao Mercado Pago. Eles utilizam informações capturadas pelos campos seguros e viabilizam a execução das principais operações de pagamento.

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:

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 {
   // Se deve usar o bin retornado do CardNumberTextFieldEvent.OnBinChanged
   val result = coreMethods.getPaymentMethods(bin = bin)
   when (result) {
       is Result.Success -> {
           // Sucesso da chamada
           print("Sucesso de request: ${result.data}")
       }

       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   // Erro da chamada do tipo request
                   print("Erro de request: ${result.error}")
               }

               is ResultError.Validation -> {
                   // Erro da chamada do tipo validation
                   print("Erro de validação: ${result.error}")
               }
           }
       }
   }
}

Os parâmetros estão listados na tabela abaixo.

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 realiza a busca por 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, valor total, entre outros.

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 { 
   // Se deve usar o bin retornado do CardNumberTextFieldEvent.OnBinChanged
   val result = coreMethods.getInstallments(
       bin = bin,
       amount = BigDecimal("100.00")
   )
   when (result) {
       is Result.Success -> {
           // Sucesso da chamada
           print("Sucesso de request: ${result.data}")
       }

       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   // Erro da chamada do tipo request
                   print("Erro de request: ${result.error}")
               }

               is ResultError.Validation -> {
                   // Erro da chamada do tipo 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.

Os parâmetros estão listados na tabela abaixo.

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	Long	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 usuário selecionar o emissor correto quando necessário.

kotlin
val coreMethods = MercadoPagoSDK.getInstance().coreMethods
coroutineScope {
   // Se deve usar o bin retornado do CardNumberTextFieldEvent.OnBinChanged
   // Se deve usar o paymentMethodId retornado da request de PaymentMethods
   val result = coreMethods.getCardIssuers(
       bin = bin,
       paymentMethodId = paymentMethodId,
   )
   when (result) {
       is Result.Success -> {
           // Sucesso da chamada
           print("Sucesso de request: ${result.data}")
       }

       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   // Erro da chamada do tipo request
                   print("Erro de request: ${result.error}")
               }

               is ResultError.Validation -> {
                   // Erro da chamada do tipo validation
                   print("Erro de validação: ${result.error}")
               }
           }
       }
   }
}

Os parâmetros estão listados na tabela abaixo.

Parâmetro	Tipo	Descrição	Obrigatório
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, como CPF, RG, DNI, para o país configurado na integração.

kotlin
val coreMethods = MercadoPagoSDK.getInstance().coreMethods
coroutineScope {
   val result = coreMethods.getIdentificationTypes()
   when (result) {
       is Result.Success -> {
           // Sucesso da chamada
           print("Sucesso de request: ${result.data}")
       }

       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   // Erro da chamada do tipo request
                   print("Erro de request: ${result.error}")
               }

               is ResultError.Validation -> {
                   // Erro da chamada do tipo 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 é responsável por gerar um token temporário a partir dos dados do cartão informado. O token gerado é obrigatório para a realização da transação de pagamento via API do Mercado Pago, pois substitui os dados sensíveis do cartão, garantindo maior segurança no processo.

A chamada deste método utiliza uma instância dos campos seguros previamente configurados na interface do checkout. Portanto, certifique-se de que os campos seguros estejam devidamente implementados e configurados antes de utilizar o método generateCardToken.

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 -> {
           // Sucesso da chamada
           print("Sucesso de request: ${result.data}")
       }

       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   // Erro da chamada do tipo request
                   print("Erro de request: ${result.error}")
               }

               is ResultError.Validation -> {
                   // Erro da chamada do tipo validation
                   print("Erro de validação: ${result.error}")
               }
           }
       }
   }
}

Os parâmetros estão listados na tabela abaixo.

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 registrados pelo comprador são armazenados de forma segura e não são acessíveis a partir do seu backend. Apenas o ID do cartão é fornecido à aplicação, que você deverá utilizar 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 -> {
           // Sucesso da chamada
           print("Sucesso de request: ${result.data}")
       }

       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   // Erro da chamada do tipo request
                   print("Erro de request: ${result.error}")
               }

               is ResultError.Validation -> {
                   // Erro da chamada do tipo validation
                   print("Erro de validação: ${result.error}")
               }
           }
       }
   }
}

Os parâmetros estão listados na tabela abaixo.

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`	PCIFieldStat	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 deve ser realizado mediante a criação de um pagamento que contenha a transação associada.
Para isso, envie um POST com seu Access Token produtivoChave privada da aplicação criada no Mercado Pago e que é utilizada no backend em ambientes de desenvolvimento e para receber pagamentos reais. Você pode acessá-la através de Suas integrações > Detalhes da aplicação > Produção > Credenciais de produção. e os parâmetros requeridos listados abaixo para o endpoint /v1/paymentsAPI e execute a requisição.

curl
curl -X POST \
    'https://api.mercadopago.com/v1/payments' \
    -H 'Content-Type: application/json' \
    -H 'X-Idempotency-Key: 0d5020ed-1af6-469c-ae06-c3bec19954bb' \
    -H 'Authorization: Bearer TEST-774********25348-05********b89beeed********f053e824********0424235' \
    -d '{
  "additional_info": {
    "items": [
      {
        "id": "MLB2907679857",
        "title": "Point Mini",
        "description": "Point product for card payments via Bluetooth.",
        "picture_url": "https://http2.mlstatic.com/resources/frontend/statics/growth-sellers-landings/device-mlb-point-i_medium2x.png",
        "category_id": "electronics",
        "quantity": 1,
        "unit_price": 58,
        "type": "electronics",
        "event_date": "2023-12-31T09:37:52.000-04:00",
        "warranty": false,
        "category_descriptor": {
          "passenger": {},
          "route": {}
        }
      }
    ],
    "payer": {
      "first_name": "Test",
      "last_name": "Test",
      "phone": {
        "area_code": 11,
        "number": "987654321"
      },
      "address": {
        "zip_code": "12312-123",
        "street_name": "Av das Nacoes Unidas",
        "street_number": 3003,
        "neighborhood": null,
        "city": 3003,
        "federal_unit": 3003
      }
    },
    "shipments": {
      "receiver_address": {
        "zip_code": "12312-123",
        "state_name": "Rio de Janeiro",
        "city_name": "Buzios",
        "street_name": "Av das Nacoes Unidas",
        "street_number": 3003
      },
      "width": null,
      "height": null
    }
  },
  "application_fee": null,
  "binary_mode": false,
  "campaign_id": null,
  "capture": false,
  "coupon_amount": null,
  "description": "Payment for product",
  "differential_pricing_id": null,
  "external_reference": "MP0001",
  "installments": 1,
  "metadata": null,
  "payer": {
    "entity_type": "individual",
    "type": "customer",
    "id": null,
    "email": "test_payer@example.com",
    "identification": {
      "type": "CPF",
      "number": "95749019047"
    }
  },
  "payment_method_id": "master",
  "token": "ff8080814c11e237014c1ff593b57b4d",
  "transaction_amount": 58
}'

Veja na tabela abaixo as descrições dos parâmetros que possuem alguma particularidade importante de ser destacada:

Atributo	Tipo	Descrição	Obrigatoriedade
`Authorization`	Header	Faz referência à sua chave privada, o Access Token.	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
`token`	Body.String	Identificador do token do cartão. O token é gerado a partir dos dados do próprio cartão, proporcionando maior segurança no processo de pagamento. Após ser utilizado em uma compra, o token é descartado, exigindo a criação de um novo token para cada transação.	Obrigatório
`transaction_amount`	Body.String	Custo do produto. Para Chile, deve ser um número inteiro.	Obrigatório
`installments`	Body.String	Número de parcelas selecionado.	Obrigatório
`payment_method_id`	Body.String	Indica o identificador do meio de pagamento selecionado para efetuar o pagamento. Obtenha todos os meios de pagamento disponíveis enviando um GET ao endpoint `/v1/payment_methods` da API.	Obrigatório
`payer.email`	Body.String	Email associado ao pagador.	Obrigatório

Para conhecer em detalhe todos os parâmetros enviados nesta requisição, consulte a Referência de API.

Exemplos e referências

Para aprofundar o entendimento sobre a implementação e utilização do SDK, consulte o repositório no GitHub.

O repositório inclui um módulo de exemplo completo, demonstrando a integração dos campos seguros e dos Core Methods, além de apresentar um fluxo de checkout integrado e seguro.

AnteriorIntegrar para websitesSaiba como configurar pagamentos com cartão em Checkout API para websites.

PróximoConta Mercado PagoPermita o processamento automático de pagamentos através da carteira digital do Mercado Pago.