Integrate for mobile applications - Card - Mercado Pago Developers

Integration for mobile applications

The integration via the Native SDK Core Methods from Mercado Pago offers full control over the capture and processing of payment information, allowing you to create and customize forms according to your needs.

To integrate the Mercado Pago Native SDK using Core Methods, refer to the instructions specific to each technology:

Requirements

Before you start the integration, make sure your project meets the following requirements:

Requirement	Description
SDK	Version 23 or higher
Jetpack Compose BoM	Version 2024.12.01 or higher
Kotlin	Version 2.0 or higher
Public Key	The Public KeyPublic key used in the frontend to access information and encrypt data. You can access it through Your integrations > Application details > Production > Production credentials. is directly linked to the applicationEntity registered in Mercado Pago that acts as an identifier to manage your integrations. For more information, see the link below.Application details you created, so each one is unique for every integration.

Configure secure fields

Secure fields are components developed to ensure the privacy and protection of sensitive data typed by the buyer. Fully PCI-compliantSet of security rules designed to protect payment card data against fraud and data breaches., these fields ensure that the application never has direct access to the entered information, which is securely transmitted only for the creation of tokens and transactions.

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 there is a value change, without exposing the entered data, and also informs the result of the field validation according to PCI and card rules.

The data typed in the secure fields is never available to the integrating application. They are securely sent only for the creation of tokens and transactions.

In the table below, you will find the details of the available components. For more information about configuration, refer to the corresponding documentation for each component on GitHub.

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

Core Methods

Core Methods are essential for building a checkout flow integrated with Mercado Pago. They use information captured by the secure fields and enable the execution of the main payment operations.

Each method should be used according to the needs of your payment flow. To use them, start by creating an instance of Core Methods in your class with the following Kotlin code: val coreMethods = MercadoPagoSDK.getInstance().coreMethods.

This way, you will be able to use any of the methods listed below:

Get payment methods

The Get payment methods method returns the list of available payment methods based on the informed card BIN, considering the rules and valid financial institutions for the configured country. This step is essential to identify the card brand, correctly set the next steps of the checkout, and validate the card acceptance.

kotlin
val coreMethods = MercadoPagoSDK.getInstance().coreMethods
coroutineScope {
   // You should use the bin returned from CardNumberTextFieldEvent.OnBinChanged
   val result = coreMethods.getPaymentMethods(bin = bin)
   when (result) {
       is Result.Success -> {
           // Request succeeded
           print("Request success: ${result.data}")
       }

       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   // Request-type error
                   print("Request error: ${result.error}")
               }

               is ResultError.Validation -> {
                   // Validation-type error
                   print("Validation error: ${result.error}")
               }
           }
       }
   }
}

The parameters are listed in the table below.

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

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

Get installment options

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

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

kotlin
val coreMethods = MercadoPagoSDK.getInstance().coreMethods
coroutineScope { 
   // You should use the bin returned from CardNumberTextFieldEvent.OnBinChanged
   val result = coreMethods.getInstallments(
       bin = bin,
       amount = BigDecimal("100.00")
   )
   when (result) {
       is Result.Success -> {
           // Request succeeded
           print("Request success: ${result.data}")
       }

       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   // Request-type error
                   print("Request error: ${result.error}")
               }

               is ResultError.Validation -> {
                   // Validation-type error
                   print("Validation error: ${result.error}")
               }
           }
       }
   }
}

Use the information from the Installment to show the buyer all details of the purchase value and installment plan before completing the payment.

The parameters are listed in the table below.

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

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

Get card issuer

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

kotlin
val coreMethods = MercadoPagoSDK.getInstance().coreMethods
coroutineScope {
   // You should use the bin returned from CardNumberTextFieldEvent.OnBinChanged
   // You should use the paymentMethodId returned from the PaymentMethods request
   val result = coreMethods.getCardIssuers(
       bin = bin,
       paymentMethodId = paymentMethodId,
   )
   when (result) {
       is Result.Success -> {
           // Request succeeded
           print("Request success: ${result.data}")
       }

       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   // Request-type error
                   print("Request error: ${result.error}")
               }

               is ResultError.Validation -> {
                   // Validation-type error
                   print("Validation error: ${result.error}")
               }
           }
       }
   }
}

The parameters are listed in the table below.

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

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

Get document types

In some countries, Mercado Pago requires the validation of an identification document of the cardholder. This method returns all accepted document types, such as CPF, RG, DNI, for the country configured in the integration.

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

       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   // Request-type error
                   print("Request error: ${result.error}")
               }

               is ResultError.Validation -> {
                   // Validation-type error
                   print("Validation error: ${result.error}")
               }
           }
       }
   }
}

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

Create card token

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

The call to this method uses an instance of the secure fields previously configured in the checkout interface. Therefore, make sure 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, check if 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 -> {
           // Request succeeded
           print("Request success: ${result.data}")
       }

       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   // Request-type error
                   print("Request error: ${result.error}")
               }

               is ResultError.Validation -> {
                   // Validation-type error
                   print("Validation error: ${result.error}")
               }
           }
       }
   }
}

The parameters are listed in the table below.

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 response, check the method documentation on GitHub.

Create a token for an existing card

In the Mercado Pago flow, card data previously registered by the buyer is securely stored and not accessible to your backend. Only the card ID is available to the application. To process payments with saved cards, use this ID to generate a temporary token. This process ensures the protection of sensitive information, as only the card ID is handled by the application, while the card number, CVV, and expiration date are never exposed. Make sure the secure fields are properly configured and filled in.

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 -> {
           // Request succeeded
           print("Request success: ${result.data}")
       }

       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   // Request-type error
                   print("Request error: ${result.error}")
               }

               is ResultError.Validation -> {
                   // Validation-type error
                   print("Validation error: ${result.error}")
               }
           }
       }
   }
}

The parameters are listed in the table below.

Parameter	Type	Description	Required
`cardId`	String	Generated existing 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 response, check the method documentation on GitHub.

Make a payment

The request must be made by creating a payment that contains the associated transaction.
To do this, send a POST with your Production Access TokenPrivate key of the application created in Mercado Pago, used in the backend in development environments and for receiving real payments. You can access it via Your integrations > Application details > Production > Production credentials. and the required parameters listed below to the endpoint /v1/paymentsAPI and execute the request.

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_user_123@testuser.com",
    "identification": {
      "type": "CPF",
      "number": "95749019047"
    }
  },
  "payment_method_id": "master",
  "token": "ff8080814c11e237014c1ff593b57b4d",
  "transaction_amount": 58
}'

See the table below for the descriptions of parameters that have important particularities to highlight:

Attribute	Type	Description	Requirement
`Authorization`	Header	Refers to your private key, the Access Token.	Required
`X-Idempotency-Key`	Header	Idempotency key. This key ensures each request is processed only once, preventing duplicates. Use a unique value in the request header, such as a UUID V4 or a random string.	Required
`token`	Body.String	Card token identifier. The token is generated from the card data itself, providing greater security in the payment process. After being used in a purchase, the token is discarded, requiring the creation of a new token for each transaction.	Required
`transaction_amount`	Body.String	Product cost. For Chile, it must be an integer.	Required
`installments`	Body.String	Number of selected installments.	Required
`payment_method_id`	Body.String	Indicates the identifier of the payment method selected to make the payment. Retrieve all available payment methods by sending a GET to the `/v1/payment_methods` endpoint.	Required
`payer.email`	Body.String	Email associated with the payer.	Required

For detailed information on all parameters sent in this request, check the API Reference.

Examples and references

To deepen your understanding of the implementation and use of the SDK, check the GitHub repository.

The repository includes a complete sample module, demonstrating the integration of secure fields and Core Methods, as well as an integrated and secure checkout flow.

Integrar para websites

Saiba como configurar pagamentos com cartão em Checkout Transparente para websites.

Conta Mercado Pago

Permita o processamento automático de pagamentos através da carteira digital do Mercado Pago.