Card Payment behavior customizations
The Mercado Pago SDK Checkout offers additional resources for the mobile integration of the Card Payment Brick for card payments in iOS and Android applications. In this section, you will see how to tokenize a card without making a charge, handle user cancellation, and restrict the accepted payment methods. See below how to configure these resources.
If your operation does not accept certain card types or brands, or works with a specific installment range, you can apply these rules directly in the checkout through the setPaymentMethodConfiguration method of the SDK Builder.
Validation happens client-side, before tokenization: cards outside the rule are rejected in the form itself, without any token being generated, and only the installments within the configured range are shown to the buyer. The configuration is done by exclusion, meaning you specify what you do not accept.
kotlinMercadoPagoCheckout.Builder( context = this, checkoutType = MPCheckoutType.CardTransaction( order = MPOrder( orderId = "order-id", clientToken = "order-client-token" ) ) ).setPaymentMethodConfiguration( listOf( MPPaymentMethodConfig.Card( excludedPaymentTypes = listOf(MPCardType.DEBIT, MPCardType.PREPAID), excludedPaymentMethods = listOf(MPCardBrand.AMEX), installment = MPInstallment(minInstallments = 1, maxInstallments = 6) ) ) ).build()
| Parameter | Type | Description |
excludedPaymentTypes | MPCardType | Excluded card types, which can be: DEBIT, PREPAID or CREDIT. |
excludedPaymentMethods | MPCardBrand | Excluded brands, such as MPCardBrand.Visa, MPCardBrand.Mastercard, or MPCardBrand.AMEX. Use MPCardBrand.Custom(...) for brands outside the default list. |
installment | MPInstallment | Minimum and maximum accepted installments. |
In subscription, delivery, or recurring service applications, it is common to capture the card data at one moment and make the charge at another. For these cases, the SDK offers a flow that displays the card form, validates the entered data, and generates the token without creating an order or moving money.
Upon completion, the SDK returns a single-use token along with paymentMethodId, paymentTypeId, and issuerId. To do this, follow the steps below according to the chosen operating system.
CardSave does not associate the card with a customer nor make a charge. To store the card, send the token to your backend following the Save cards flow.For Android applications, the flow responsible for this tokenization is CardSave, defined in the checkoutType when building the 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 // Send data.token to your backend to continue the storage flow } is MercadoPagoCheckoutResult.Error -> { // Show an error message or offer retry } is MercadoPagoCheckoutResult.UserCancelled -> { // Return to the cart or to the previous step } } }
On success, the SDK will return the following information in MPPaymentData.CardSave:
| Parameter | Type | Description | Required |
token | String | Payment token generated for the transaction. | Required |
paymentMethodId | String | Identifier of the selected payment method. | Required |
paymentTypeId | String | Identifier of the selected payment type. | Required |
payer | Payer? | Payer information (documentType and documentNumber). | Optional |
issuerId | String? | Card issuer identifier. | Optional |
The buyer can abandon the checkout before completing the operation, whether by closing the screen, returning to the previous navigation, or interrupting the form completion. In these cases, the SDK does not return an error, but rather returns a specific cancellation result (MercadoPagoCheckoutResult.UserCancelled) containing the state of each field at the moment the flow was closed.
Use this information to define the application behavior after the abandonment, such as resuming the completion from where the buyer stopped or identifying at which stage of the form the abandonment occurred. See below the data returned in each operating system.
On Android, the cancellation data is available in the cancelledData property, with the concrete type defined by the checkoutType configured in the Builder.
kotlincheckout.show { result -> when (result) { is MercadoPagoCheckoutResult.UserCancelled -> { // Iterate over the fields to know what had already been filled in result.cancelledData.fields.forEach { fieldState -> when (fieldState.state) { is State.Valid -> { /* Valid field: reuse it on the next attempt */ } is State.Empty -> { /* Field not filled in */ } is State.Incomplete -> { /* Field partially filled in */ } is State.Invalid -> { /* Field with an invalid value */ } is State.CardBrandNotAccepted -> { /* Brand not accepted */ } is State.CardTypeNotAccepted -> { /* Card type not accepted */ } } } } is MercadoPagoCheckoutResult.Success -> { /* Handle the success */ } is MercadoPagoCheckoutResult.Error -> { /* Handle the error */ } } }
The object received in cancelledData is an MPUserCancelledContext and has the properties below.
| Property | Type | Description |
fields | List<MPCancelledFieldState> | State of each form field at the moment of cancellation. |
screens | List<Screen> | Screens visited by the buyer before cancelling, in the order they were accessed. Available only in the CardTransaction flow. Possible values: CARD_FORM and INSTALLMENTS. |
Each item in fields is an MPCancelledFieldState, composed of:
| Property | Type | Description |
field | Field | Form field, which can be: CARD_NUMBER, CARD_HOLDER, EXPIRATION_DATE, SECURITY_CODE and DOCUMENT. |
state | State | Field state, which can be: Valid, Empty, Incomplete, Invalid, CardBrandNotAccepted(brand) and CardTypeNotAccepted(cardType). |