Personalização de comportamento do Card Payment
O Mercado Pago SDK Checkout oferece recursos adicionais para a integração mobile do Card Payment Brick para pagamentos com cartão em aplicativos iOS e Android. Nesta seção, você verá como tokenizar um cartão sem realizar uma cobrança, tratar o cancelamento pelo usuário e restringir os meios de pagamento aceitos. Veja abaixo como configurar esses recursos.
Caso a sua operação não aceite determinados tipos de cartão ou bandeiras, ou trabalhe com uma faixa específica de parcelamento, é possível aplicar essas regras diretamente no checkout através do método setPaymentMethodConfiguration do Builder do SDK.
A validação ocorre no client-side, antes da tokenização: cartões fora da regra são recusados no próprio formulário, sem gerar nenhum token, e apenas as parcelas dentro do intervalo configurado são exibidas ao comprador. A configuração é feita por exclusão, ou seja, você informa o que não aceita.
kotlinMercadoPagoCheckout.Builder( context = this, checkoutType = MPCheckoutType.CardTransaction( order = MPOrder( orderId = "id-da-ordem", clientToken = "client-token-da-ordem" ) ) ).setPaymentMethodConfiguration( listOf( MPPaymentMethodConfig.Card( excludedPaymentTypes = listOf(MPCardType.DEBIT, MPCardType.PREPAID), excludedPaymentMethods = listOf(MPCardBrand.AMEX), installment = MPInstallment(minInstallments = 1, maxInstallments = 6) ) ) ).build()
| Parâmetro | Tipo | Descrição |
excludedPaymentTypes | MPCardType | Tipos de cartão excluídos, podendo ser: DEBIT, PREPAID ou CREDIT. |
excludedPaymentMethods | MPCardBrand | Bandeiras excluídas, como MPCardBrand.Visa, MPCardBrand.Mastercard ou MPCardBrand.AMEX. Use MPCardBrand.Custom(...) para bandeiras fora da lista padrão. |
installment | MPInstallment | Mínimo e máximo de parcelas aceitas. |
Em aplicativos de assinatura, delivery ou serviços recorrentes, é comum capturar os dados do cartão em um momento e efetuar a cobrança em outro. Para esses casos, o SDK oferece um fluxo que exibe o formulário de cartão, valida os dados preenchidos e gera o token sem criar uma order nem movimentar dinheiro.
Ao concluir, o SDK devolve um token de uso único junto com paymentMethodId, paymentTypeId e issuerId. Para isso, siga as etapas abaixo de acordo com o sistema operacional escolhido.
CardSave não associa o cartão a um cliente nem realiza uma cobrança. Para armazenar o cartão, envie o token ao seu backend seguindo o fluxo de Salvar cartões.Para aplicativos Android, o fluxo responsável por essa tokenização é o CardSave, definido no checkoutType ao construir o checkout.
kotlinval checkout = MercadoPagoCheckout.Builder( context = this, checkoutType = MPCheckoutType.CardSave ).build() checkout.show { result -> when (result) { is MercadoPagoCheckoutResult.Success -> { val data = result.paymentData // MPPaymentData.CardSave // Envie data.token ao seu backend para continuar o fluxo de armazenamento } is MercadoPagoCheckoutResult.Error -> { // Exiba mensagem de erro ou ofereça retry } is MercadoPagoCheckoutResult.UserCancelled -> { // Retorne ao carrinho ou ao passo anterior } } }
Em caso de sucesso, o SDK retornará em MPPaymentData.CardSave as seguintes informações:
| Parâmetro | Tipo | Descrição | Obrigatoriedade |
token | String | Token de pagamento gerado para a transação. | Obrigatório |
paymentMethodId | String | Identificador do meio de pagamento selecionado. | Obrigatório |
paymentTypeId | String | Identificador do tipo de pagamento selecionado. | Obrigatório |
payer | Payer? | Informações do pagador (documentType e documentNumber). | Opcional |
issuerId | String? | Identificador do emissor do cartão. | Opcional |
O comprador pode abandonar o checkout antes de concluir a operação, seja fechando a tela, retornando à navegação anterior ou interrompendo o preenchimento do formulário. Nesses casos, o SDK não retorna um erro, mas sim devolve um resultado específico de cancelamento (MercadoPagoCheckoutResult.UserCancelled) contendo o estado de cada campo no momento em que o fluxo foi encerrado.
Utilize essa informação para definir o comportamento do aplicativo após a desistência, como retomar o preenchimento do ponto em que o comprador parou ou identificar em qual etapa do formulário ocorreu o abandono. Veja abaixo os dados retornados em cada sistema operacional.
No Android, os dados do cancelamento ficam disponíveis na propriedade cancelledData, sendo o tipo concreto definido pelo checkoutType configurado no Builder.
kotlincheckout.show { result -> when (result) { is MercadoPagoCheckoutResult.UserCancelled -> { // Percorra os campos para saber o que já havia sido preenchido result.cancelledData.fields.forEach { fieldState -> when (fieldState.state) { is State.Valid -> { /* Campo válido: reaproveite na próxima tentativa */ } is State.Empty -> { /* Campo não preenchido */ } is State.Incomplete -> { /* Campo preenchido parcialmente */ } is State.Invalid -> { /* Campo com valor inválido */ } is State.CardBrandNotAccepted -> { /* Bandeira não aceita */ } is State.CardTypeNotAccepted -> { /* Tipo de cartão não aceito */ } } } } is MercadoPagoCheckoutResult.Success -> { /* Trate o sucesso */ } is MercadoPagoCheckoutResult.Error -> { /* Trate o erro */ } } }
O objeto recebido em cancelledData é um MPUserCancelledContext e possui as propriedades abaixo.
| Propriedade | Tipo | Descrição |
fields | List<MPCancelledFieldState> | Estado de cada campo do formulário no momento do cancelamento. |
screens | List<Screen> | Telas visitadas pelo comprador antes de cancelar, na ordem de acesso. Disponível apenas no fluxo CardTransaction. Valores possíveis: CARD_FORM e INSTALLMENTS. |
Cada item de fields é um MPCancelledFieldState, composto por:
| Propriedade | Tipo | Descrição |
field | Field | Campo do formulário, podendo ser: CARD_NUMBER, CARD_HOLDER, EXPIRATION_DATE, SECURITY_CODE e DOCUMENT. |
state | State | Estado do campo, podendo ser: Valid, Empty, Incomplete, Invalid, CardBrandNotAccepted(brand) e CardTypeNotAccepted(cardType). |