Integrar para aplicativos móveis - Cartão - Mercado Pago Developers
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.
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:
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 callbackonBinChange do CardNumberTextFieldEvent.
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 callbackonBinChange do CardNumberTextFieldEvent.
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 callbackonBinChange do CardNumberTextFieldEvent.
Obrigatório
paymentMethodId
String
ID do método de pagamento, normalmente obtido a partir do resultado do método PaymentMethods.
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}")
}
}
}
}
}
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}")
}
}
}
}
}
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}")
}
}
}
}
}
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.
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.
