AI resources

Cards

Payment integration with credit and/or debit cards in the Checkout API can be done in two ways for mobile applications. The recommended integration is through the Card Payment Brick (via Mercado Pago SDK Checkout), but if you want to be responsible for defining how the information is retrieved, you can integrate through Core Methods (via Mercado Pago SDK Core Methods), available for Android and iOS applications.

The mobile integration via Card Payment Brick internally uses the Core Methods module to communicate with the Orders API and submit the payment. When using both integrations in the same application, control the versions to avoid conflicts.

See below the main flow of the mobile integration via Card Payment.

Card Payment

The Card Payment (via Mercado Pago SDK Checkout) accelerates the implementation of card payments in native Android and iOS applications. The SDK displays the form, retrieves the required card data, allows installment selection, securely tokenizes the information, and processes the payment against an order previously created in the backend.

The main flow of this integration with the SDK Checkout is CardTransaction, where the backend creates the order with the Access Token and sends only the orderId and the clientToken to the application. This way, the private credential remains protected and the sensitive card data is handled in compliance with PCI security standards.

To integrate the Card Payment, you must first have configured the Mercado Pago SDK Checkout in the development environment and, from there, follow the steps below according to the chosen operating system.

In addition to the main flow presented in this section, the Mercado Pago SDK Checkout offers additional resources for the mobile integration with Card Payment, such as restricting the accepted payment methods, limiting the installment range, tokenizing a card without making a charge, and handling cancellation by the buyer. To learn about them, see the Behavior customization for checkout documentation.

The SDK Checkout for Android is the native library for integrating card payments in Android applications. Built in Kotlin with Jetpack Compose support, it encapsulates all communication with the Orders API — card tokenization, installment selection, brand validation, and payment submission — in a managed flow, without the developer having to handle sensitive data directly.

Distribution is done via Jetpack Compose BoM to ensure consistent versions across modules, with minimum requirements of Android 6.0+ (SDK version 23 or higher) and Kotlin 2.0+.

To deepen your understanding of the SDK implementation and usage, consult the GitHub repository for reference examples of both the Card Payment and Core Methods integrations, showcasing an integrated and secure checkout flow.

Create order

Before displaying the Card Payment, create an order in your backend through the /v1/ordersPOST endpoint, using your test Access TokenPrivate key of the application created in Mercado Pago and used in the backend. You can access it in Your integrations > Integration data > Tests > Test credentials..

In the CardTransaction flow, create the order in manual mode (processing_mode=manual) and do not send the payment transaction at this point. The response will provide the order id and the client_token required for the SDK to tokenize the card and process the payment against the existing order.

It is also possible to tokenize a card without making a charge, useful for capturing the buyer's data at one moment and making the payment at another. In this case, the SDK generates the token without creating an order or moving money. For more information, see Tokenize card without making a payment.

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": "Product",
            "quantity": 1,
            "unit_price": "100.00"
        }
    ]
}'

Parameter	Type	Description	Required
`Authorization`	Header	Refers to your private key, the test Access TokenPrivate key of the application created in Mercado Pago, used in the backend. You can access it through Your integrations > Integration data > Tests > Test credentials. The test Access Token starts with the prefix `APP_USR`..	Required
`X-Idempotency-Key`	Header	Idempotency key. This key ensures each request is processed only once, avoiding duplicates. Use a unique value in the request `header`, such as a UUID V4 or a random string.	Required
`processing_mode`	Body. String	Order processing mode. Possible values are: - `automatic`: to create and process the order in automatic mode. - `manual`: to create the order and process it later. In this case, use `manual` to allow the SDK to complete and process the transaction through the `client_token`.	Required
`total_amount`	Body. String	Total transaction amount.	Required
`payer.email`	Body. String	Payer email.	Required

On success, the API will return the created order and the authentication token for processing in the application.

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

Use the id value as orderId and the client_token value as clientToken in the SDK configuration.

To learn about all available parameters, see the API ReferenceAPI. If you receive an error, see the error list.

Configure and display the Card Payment

In the SDK Checkout, pass the data from the order created in your backend to MPOrder. The SDK will display the form, allow installment selection, tokenize the card, and process the payment against that order.

If your integration needs to restrict a card type, the accepted brands, or the installment range, this configuration must be applied before starting the tokenization. The rules are evaluated at the moment the form is displayed, so a card outside the restrictions is rejected without any token being generated. For more information, see the Restrict payment methods and limit installments section.

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

checkout.show { result ->
    when (result) {
        is MercadoPagoCheckoutResult.Success -> {
            val data = result.paymentData // MPPaymentData.CardTransaction
            // Use data.orderId, data.orderStatus, etc.
        }
        is MercadoPagoCheckoutResult.Error -> {
            // Show an error message or offer a new attempt
        }
        is MercadoPagoCheckoutResult.UserCancelled -> {
            // Return to the cart or to the previous step
        }
    }
}

Parameter	Type	Description
`orderId`	`String`	Order identifier (`id`) returned upon its creation.
`clientToken`	`String`	Token (`client_token`) returned upon the order creation, representing the user credentials.

On success, the SDK will return the following information in MPPaymentData.CardTransaction:

Parameter	Type	Description
`orderId`	`String`	Order identifier.
`orderStatus`	`String`	Order status after processing.
`paymentMethodId`	`String`	Payment method identifier.
`paymentTypeId`	`String`	Payment method type.

With the Card Payment you can also align the checkout appearance with your application's visual identity. The Mercado Pago SDK Checkout uses tokenized components in atomic design, so changing a token automatically cascades to components, screens, and states. For more information, see Card Payment visual customizations.

Core Methods

In the Core Methods integration (via the Mercado Pago SDK Core Methods) for mobile applications, the developer is responsible for defining how the information needed to complete the payment will be retrieved, including the document type and the card data (issuer and installments). This gives full flexibility to build the checkout flow experience, unlike the Card Payment integration, where the information is retrieved automatically and the interface is predefined.

The SDK Core Methods uses information captured by the secure fields, enabling the execution of the main payment operations.

In the Core Methods integration for Android applications, each method should be used according to your payment flow needs. To use them, start by creating a Core Methods instance in your class using the following Kotlin code: val coreMethods = MercadoPagoSDK.getInstance().coreMethods.

This way, you can use any of the methods listed below:

Configure secure fields

Secure fields are components designed to ensure the privacy and protection of sensitive data entered by the buyer. In full compliance with PCI standardsSet of security rules that seek to protect payment card data against fraud and data breaches., these fields ensure the application never has direct access to the entered information, which is transmitted securely only for token and transaction creation.

All interactions with these fields occur through callbacks, allowing the capture of relevant events without exposing user data. The methods described below use instances of these secure fields, so it is essential that they are properly configured in the checkout interface before using them.

Each component notifies the integrating application when a value changes, without exposing the entered data, and also reports the validation result of the field according to PCI and card rules.

Data entered in secure fields is never available to the integrating application. It is securely forwarded only for creating tokens and transactions.

In the table below you will find the details of the available components. For more information on configuration, consult the corresponding reference in GitHub.

Component name	GitHub reference	Description
CardNumberTextField	Reference	Secure field for entering the card number.
ExpirationDateTextField	Reference	Secure field for entering the card expiration date.
SecurityTextField	Reference	Secure field for entering the security code (CVV).

Get payment methods

The Get payment methods method returns the list of payment methods available from the provided card BIN, considering the rules and financial institutions valid for the configured country. This method allows you to identify the card brand, correctly define the next checkout steps, and validate card acceptance.

kotlin
val coreMethods = MercadoPagoSDK.getInstance().coreMethods
coroutineScope {
   val result = coreMethods.getPaymentMethods(bin = bin)
   when (result) {
       is Result.Success -> {
           print("Request success: ${result.data}")
       }
       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   print("Request error: ${result.error}")
               }
               is ResultError.Validation -> {
                   print("Validation error: ${result.error}")
               }
           }
       }
   }
}

Parameter	Type	Description	Required
`bin`	String	The first 8 digits of the credit card, obtained via the `onBinChange` callback of `CardNumberTextFieldEvent`.	Required

For more information about the call response, consult the method documentation on GitHub.

Get installment conditions

The Get installment conditions method searches for all installment options available for a given card and transaction amount. It considers the rules of the issuer, payment method, and purchase amount, returning all valid installment options, including number of installments, interest, installment amount, total amount, and more.

The getInstallments method call must be made for all card types (debit and credit) to verify whether payment can be completed via that method.

kotlin
val coreMethods = MercadoPagoSDK.getInstance().coreMethods
coroutineScope {
   val result = coreMethods.getInstallments(
       bin = bin,
       amount = BigDecimal("100.00")
   )
   when (result) {
       is Result.Success -> {
           print("Request success: ${result.data}")
       }
       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   print("Request error: ${result.error}")
               }
               is ResultError.Validation -> {
                   print("Validation error: ${result.error}")
               }
           }
       }
   }
}

Use the Installment information to show the buyer all the details of the purchase amount and installments before finalizing the payment.

Parameter	Type	Description	Required
`bin`	String	The first 8 digits of the credit card, obtained via the `onBinChange` callback of `CardNumberTextFieldEvent`.	Required
`amount`	BigDecimal	Total transaction amount.	Required

For more information about the call response, consult the method documentation on GitHub.

Get card issuer

For certain payment methods and brands, Mercado Pago requires the identification of the card issuer. This method returns the list of available issuers for the provided BIN, allowing the buyer to select the correct issuer when necessary.

kotlin
val coreMethods = MercadoPagoSDK.getInstance().coreMethods
coroutineScope {
   val result = coreMethods.getCardIssuers(
       bin = bin,
       paymentMethodId = paymentMethodId,
   )
   when (result) {
       is Result.Success -> {
           print("Request success: ${result.data}")
       }
       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   print("Request error: ${result.error}")
               }
               is ResultError.Validation -> {
                   print("Validation error: ${result.error}")
               }
           }
       }
   }
}

Parameter	Type	Description	Required
`bin`	String	The first 8 digits of the credit card, obtained via the `onBinChange` callback of `CardNumberTextFieldEvent`.	Required
`paymentMethodId`	String	Payment method ID, normally obtained from the result of the `PaymentMethods` method.	Required

For more information about the call response, consult the method documentation on GitHub.

Get document types

Mercado Pago requires validation of the cardholder's identification document. Use this method to receive all accepted document types for the country configured in the integration.

kotlin
val coreMethods = MercadoPagoSDK.getInstance().coreMethods
coroutineScope {
   val result = coreMethods.getIdentificationTypes()
   when (result) {
       is Result.Success -> {
           print("Request success: ${result.data}")
       }
       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   print("Request error: ${result.error}")
               }
               is ResultError.Validation -> {
                   print("Validation error: ${result.error}")
               }
           }
       }
   }
}

For more information about the call response, consult the method documentation on GitHub.

Create card token

This method generates a temporary token from the provided card data. The generated token is required for the payment transaction via the Mercado Pago API, as it replaces the sensitive card data, ensuring greater security in the process.

This method call uses an instance of the secure fields previously configured in the checkout interface. Therefore, ensure that the secure fields are properly implemented and configured before using the generateCardToken method.

Create a token for a new card

To securely generate a token for a new card, use the class that protects the entered data and pass it to the generateCardToken method. Before executing the method, verify that all required fields are correctly filled.

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("Request success: ${result.data}")
       }
       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   print("Request error: ${result.error}")
               }
               is ResultError.Validation -> {
                   print("Validation error: ${result.error}")
               }
           }
       }
   }
}

Parameter	Type	Description	Required
`cardNumberState`	PCIFieldState	Card number field state.	Required
`expirationDateState`	PCIFieldState	Card expiration field state.	Required
`securityCodeState`	PCIFieldState	Card security code field state.	Required
`buyerIdentification`	BuyerIdentification	Buyer identification class.	Required

For more information about the call response, consult the method documentation on GitHub.

Create a token for an existing card

In Mercado Pago transactions, the card data registered by the buyer is stored securely and is not accessible from your backend. Only the card ID is provided to the application, which you must use to generate a temporary token. This protects sensitive information, as only the ID is handled, while the card number, CVV, and expiration date are not exposed and remain secure.

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("Request success: ${result.data}")
       }
       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   print("Request error: ${result.error}")
               }
               is ResultError.Validation -> {
                   print("Validation error: ${result.error}")
               }
           }
       }
   }
}

Parameter	Type	Description	Required
`cardId`	String	Existing generated card ID.	Required
`securityCodeState`	PCIFieldState	Card security code field state.	Required
`expirationDateState`	PCIFieldState	Card expiration field state.	Optional
`buyerIdentification`	BuyerIdentification	Buyer identification class.	Required

For more information about the call response, consult the method documentation on GitHub.

Submit payment

Payment submission must be done by creating an order that contains the associated payment transaction.

To do this, send a request with your test Access TokenPrivate key of the application created in Mercado Pago, used in the backend. You can access it through Your integrations > Integration data > Tests > Test credentials. The test Access Token starts with the prefix `APP_USR`. and the required parameters listed below to the /v1/ordersPOST endpoint.

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
                }
            }
        ]
    }
}'

Parameter	Type	Description	Required/Optional
`Authorization`	Header	Refers to your private key, the test Access TokenPrivate key of the application created in Mercado Pago, used in the backend. You can access it through Your integrations > Integration data > Tests > Test credentials. The test Access Token starts with the prefix `APP_USR`..	Required
`X-Idempotency-Key`	Header	Idempotency key. This key ensures each request is processed only once, avoiding duplicates. Use a unique value in the request `header`, such as a UUID V4 or a random string.	Required
`processing_mode`	Body. String	Order processing mode. Possible values are: - `automatic`: to create and process the order in automatic mode. - `manual`: to create the order and process it later. For more information, see the Integration model section.	Required
`total_amount`	Body. String	Total transaction amount.	Required
`transactions.payments.payment_method.id`	Body. String	Payment method identifier. In this case, it is the brand of each card. You can consult the full list of available identifiers by sending a request to the Get payment methodsGET endpoint.	Required
`transactions.payments.payment_method.type`	Body. String	Payment method type. For credit card payments use `credit_card`, and for debit card payments use `debit_card`.	Required
`transactions.payments.payment_method.token`	Body. String	Card token. Required field for credit and debit card payments.	Required

To see all parameters sent in this request in detail, consult our API ReferenceAPI. Also, if you receive an error when submitting the payment, consult our error list.

On success, the response will be similar to the example below.

json
{
  "id": "ORD01JS2V6CM8KJ0EC4H502TGK1WP",
  "type": "online",
  "processing_mode": "automatic",
  "external_reference": "ext_ref_1234",
  "total_amount": "50.00",
  "total_paid_amount": "50.00",
  "country_code": "PER",
  "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
        }
      }
    ]
  }
}

Parameter	Type	Description
`transactions.payments.status`	String	Transaction status. For example, `processed` indicates the payment was approved. See the Transaction status section for all possible values.
`transactions.payments.status_detail`	String	Transaction status detail. For example, `accredited` indicates the payment was approved and credited.
`transactions.payments.paid_amount`	String	Amount effectively paid in the transaction.

If you created the order in manual mode, payment processing requires an additional request to Process orderPOST. It is also possible to perform a reservation and capture of values. For more details, see Reserve, capture, and cancel values.

Once the order and payment are created, you can check the possible states in the Order status and Transaction status sections, respectively.

PreviousIntroductionLearn which payment methods you can offer using Checkout API in your mobile store.

NextConfigure orders notificationsConfigure orders notifications to receive alerts about your transactions with Checkout API.