# MD for: https://www.mercadopago.com.pe/developers/es/docs/checkout-api-orders/payment-integration/mobile/cards.md

\# 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. > WARNING > > 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. ::::::::AccordionComponent{title="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\](https://www.mercadopago.com.pe/developers/en/docs/security/pci) standards. To integrate the Card Payment, you must first have configured the Mercado Pago SDK Checkout in the \[development environment\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/development-environment) and, from there, follow the steps below according to the chosen operating system. > NOTE > > 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\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/additional-settings/mobile/behavior-customizations) documentation. :::::::TabsComponent ::::::TabComponent{title="Android"} 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+\*\*. > NOTE > > To deepen your understanding of the SDK implementation and usage, consult the \[GitHub repository\](https://github.com/mercadopago/sdk-android) for reference examples of both the Card Payment and Core Methods integrations, showcasing an integrated and secure checkout flow. :::::AccordionComponent{title="Create order" pill="server-side"} Before displaying the Card Payment, create an order in your backend through the :TagComponent{tag="POST" text="/v1/orders" href="/developers/en/reference/online-payments/checkout-api/create-order/post" color="green"} endpoint, using your :toolTipComponent\[test Access Token\]{content="Private 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. > NOTE > > 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\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/additional-settings/mobile/behavior-customizations#bookmark\_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 :toolTipComponent\[test Access Token\]{content="Private 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. > SUCCESS\_MESSAGE > > To learn about all available parameters, see the :TagComponent{tag="API" text="API Reference" href="/developers/en/reference/online-payments/checkout-api/create-order/post" color="accent"}. If you receive an error, see the \[error list\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/payment-management/integration-errors). ::::: :::::AccordionComponent{title="Configure and display the Card Payment" pill="client-side"} 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. > NOTE > > 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\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/additional-settings/mobile/behavior-customizations#bookmark\_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. | ::::: :::::: ::::::TabComponent{title="iOS"} The \*\*SDK Checkout for iOS\*\* is the native library for integrating card payments in iOS applications. Written in Swift and compatible with SwiftUI and UIKit, it abstracts card tokenization, installment selection, and communication with the Mercado Pago Orders API into a secure, managed flow. Distribution is done via Swift Package Manager from the official repository, supporting \*\*iOS 13.0+\*\*, \*\*Swift 5.5+\*\*, and \*\*Xcode 26.0+\*\*. > NOTE > > To deepen your understanding of the SDK implementation and usage, consult the \[GitHub repository\](https://github.com/mercadopago/sdk-ios) for reference examples of both the Card Payment and Core Methods integrations, showcasing an integrated and secure checkout flow. :::::AccordionComponent{title="Create order" pill="server-side"} Before displaying the Card Payment, create an order in your backend through the :TagComponent{tag="POST" text="/v1/orders" href="/developers/en/reference/online-payments/checkout-api/create-order/post" color="green"} endpoint, using your :toolTipComponent\[test Access Token\]{content="Private 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. > NOTE > > 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\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/additional-settings/mobile/behavior-customizations#bookmark\_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 :toolTipComponent\[test Access Token\]{content="Private 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. > SUCCESS\_MESSAGE > > To learn about all available parameters, see the :TagComponent{tag="API" text="API Reference" href="/developers/en/reference/online-payments/checkout-api/create-order/post" color="accent"}. If you receive an error, see the \[error list\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/payment-management/integration-errors). ::::: :::::AccordionComponent{title="Configure and display the Card Payment" pill="client-side"} In the SDK, 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. > NOTE > > 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\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/additional-settings/mobile/behavior-customizations#bookmark\_restrict\_payment\_methods\_and\_limit\_installments) section. ### Configure the checkout Build the checkout instance with \`MercadoPagoCheckout.Builder\`, specifying the \`cardTransaction\` type and the data of the order created in your backend. This instance holds the flow configuration and will be used in the display step. 

swift 

swift

```
let checkout = MercadoPagoCheckout.Builder(
    checkoutType: .cardTransaction(
        order: MPOrder(
            orderId: "ORD01JS2V6CM8KJ0EC4H502TGK1WP",
            clientToken: "order-client-token"
        )
    )
).build()
```

| 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. | ### Display the checkout With the instance created, display the checkout according to your application architecture and handle the flow return. The SDK returns the result in three situations: success, error, and cancellation by the buyer. ::::TabsComponent :::TabComponent{title="SwiftUI"} \`\`\`swift .fullScreenCover(isPresented: $showCheckout) { checkout.show { result in switch result { case .success(let paymentData): // Use paymentData.orderId, paymentData.orderStatus, etc. case .error(let error): // Show an error message or offer a new attempt case .userCancelled(let context): // Return to the cart or to the previous step } } } \`\`\` ::: :::TabComponent{title="UIKit — Modal"} \`\`\`swift checkout.present(from: self) { result in switch result { case .success(let paymentData): // Use paymentData.orderId, paymentData.orderStatus, etc. case .error(let error): // Show an error message or offer a new attempt case .userCancelled(let context): // Return to the cart or to the previous step } } \`\`\` ::: :::TabComponent{title="UIKit — Push"} \`\`\`swift checkout.push(to: navigationController) { result in switch result { case .success(let paymentData): // Use paymentData.orderId, paymentData.orderStatus, etc. case .error(let error): // Show an error message or offer a new attempt case .userCancelled(let context): // Return to the cart or to the previous step } } \`\`\` ::: :::: On success, the SDK will return the following information in \`MPPaymentData.cardTransaction\`: | Parameter | Type | Description | |---|---|---| | \`transactionAmount\` | \`Double?\` | Transaction amount. | | \`installment\` | \`Int?\` | Number of selected installments. | | \`paymentMethodId\` | \`String\` | Payment method identifier. | | \`paymentTypeId\` | \`String\` | Payment method type. | | \`issuerId\` | \`String?\` | Issuing bank identifier. | | \`payer\` | \`Payer?\` | Payer document data. | | \`orderId\` | \`String\` | Order identifier. | | \`orderStatus\` | \`String\` | Order status after processing. | ::::: :::::: ::::::: > SUCCESS\_MESSAGE > > 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\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/additional-settings/mobile/visual-customizations). :::::::: ::::::AccordionComponent{title="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. :::::TabsComponent ::::TabComponent{title="Android"} 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: :::AccordionComponent{title="Configure secure fields" pill="client-side"} Secure fields are components designed to ensure the privacy and protection of sensitive data entered by the buyer. In full compliance with :toolTipComponent\[PCI standards\]{content="Set 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. > NOTE > > 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\](https://mercadopago.github.io/sdk-android/core-methods/com.mercadopago.sdk.android.coremethods.ui.components.textfield.cardnumber/index.html) | Secure field for entering the card number. | | ExpirationDateTextField | \[Reference\](https://mercadopago.github.io/sdk-android/core-methods/com.mercadopago.sdk.android.coremethods.ui.components.textfield.expirationdate/index.html) | Secure field for entering the card expiration date. | | SecurityTextField | \[Reference\](https://mercadopago.github.io/sdk-android/core-methods/com.mercadopago.sdk.android.coremethods.ui.components.textfield.securitycode/index.html) | Secure field for entering the security code (CVV). | ::: :::AccordionComponent{title="Get payment methods" pill="client-side"} 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\](https://mercadopago.github.io/sdk-android/core-methods/com.mercadopago.sdk.android.coremethods.domain.interactor/-core-methods/get-payment-methods.html). ::: :::AccordionComponent{title="Get installment conditions" pill="client-side"} 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}") } } } } } \`\`\` > NOTE > > 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\](https://mercadopago.github.io/sdk-android/core-methods/com.mercadopago.sdk.android.coremethods.domain.interactor/-core-methods/get-installments.html). ::: :::AccordionComponent{title="Get card issuer" pill="client-side"} 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\](https://mercadopago.github.io/sdk-android/core-methods/com.mercadopago.sdk.android.coremethods.domain.interactor/-core-methods/get-card-issuers.html). ::: :::AccordionComponent{title="Get document types" pill="client-side"} 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\](https://mercadopago.github.io/sdk-android/core-methods/com.mercadopago.sdk.android.coremethods.domain.interactor/-core-methods/get-identification-types.html). ::: :::AccordionComponent{title="Create card token" pill="client-side"} 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. > WARNING > > This method call uses an instance of the \[secure fields\](#bookmark\_configure\_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\](https://mercadopago.github.io/sdk-android/core-methods/com.mercadopago.sdk.android.coremethods.ui.components.textfield.pcitextfield/-p-c-i-field-state/index.html) | Card number field state. | Required | | \`expirationDateState\` | \[PCIFieldState\](https://mercadopago.github.io/sdk-android/core-methods/com.mercadopago.sdk.android.coremethods.ui.components.textfield.pcitextfield/-p-c-i-field-state/index.html) | Card expiration field state. | Required | | \`securityCodeState\` | \[PCIFieldState\](https://mercadopago.github.io/sdk-android/core-methods/com.mercadopago.sdk.android.coremethods.ui.components.textfield.pcitextfield/-p-c-i-field-state/index.html) | Card security code field state. | Required | | \`buyerIdentification\` | \[BuyerIdentification\](https://mercadopago.github.io/sdk-android/core-methods/com.mercadopago.sdk.android.coremethods.domain.model/-buyer-identification/index.html) | Buyer identification class. | Required | For more information about the call response, consult the \[method documentation on GitHub\](https://mercadopago.github.io/sdk-android/core-methods/com.mercadopago.sdk.android.coremethods.domain.interactor/-core-methods/generate-card-token.html). ### 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\](https://mercadopago.github.io/sdk-android/core-methods/com.mercadopago.sdk.android.coremethods.ui.components.textfield.pcitextfield/-p-c-i-field-state/index.html) | Card security code field state. | Required | | \`expirationDateState\` | \[PCIFieldState\](https://mercadopago.github.io/sdk-android/core-methods/com.mercadopago.sdk.android.coremethods.ui.components.textfield.pcitextfield/-p-c-i-field-state/index.html) | Card expiration field state. | Optional | | \`buyerIdentification\` | \[BuyerIdentification\](https://mercadopago.github.io/sdk-android/core-methods/com.mercadopago.sdk.android.coremethods.domain.model/-buyer-identification/index.html) | Buyer identification class. | Required | For more information about the call response, consult the \[method documentation on GitHub\](https://mercadopago.github.io/sdk-android/core-methods/com.mercadopago.sdk.android.coremethods.domain.interactor/-core-methods/generate-card-token.html). ::: :::AccordionComponent{title="Submit payment" pill="server-side"} Payment submission must be done by creating an order that contains the associated payment transaction. To do this, send a request with your :toolTipComponent\[test Access Token\]{content="Private 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 :TagComponent{tag="POST" text="/v1/orders" href="/developers/en/reference/online-payments/checkout-api/create-order/post" color="green"} 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 :toolTipComponent\[test Access Token\]{content="Private 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\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/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 :TagComponent{tag="GET" text="Get payment methods" href="/developers/en/reference/online-payments/checkout-api/payment-methods/get" color="accent"} 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 | > SUCCESS\_MESSAGE > > To see all parameters sent in this request in detail, consult our :TagComponent{tag="API" text="API Reference" href="/developers/en/reference/online-payments/checkout-api/overview" color="accent"}. Also, if you receive an error when submitting the payment, consult our \[error list\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/payment-management/integration-errors). 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\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/payment-management/status/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. | > WARNING > > If you created the order in manual mode, payment processing requires an additional request to :TagComponent{tag="POST" text="Process order" href="/developers/en/reference/online-payments/checkout-api/process-order/post" color="green"}. It is also possible to perform a reservation and capture of values. For more details, see \[Reserve, capture, and cancel values\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/payment-management/reserve-capture-cancel). Once the order and payment are created, you can check the possible states in the \[Order status\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/payment-management/status/order-status) and \[Transaction status\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/payment-management/status/transaction-status) sections, respectively. ::: :::: ::::TabComponent{title="iOS"} In the Core Methods integration for iOS 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 Swift code: \`private let coreMethods = CoreMethods()\`. This way, you can use any of the methods listed below: :::AccordionComponent{title="Configure secure fields" pill="client-side"} Secure fields are components designed to ensure the privacy and protection of sensitive data entered by the buyer. In full compliance with :toolTipComponent\[PCI standards\]{content="Set 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 application whenever a value changes, without exposing the entered data, and also reports the validation result of the field according to PCI and card rules. > NOTE > > Data entered in secure fields is never available to the integrating application. It is securely forwarded only for creating tokens and transactions. See the available components in the table below. For more details on configuration, consult the corresponding reference in GitHub. | Component name | GitHub reference | Description | |---|---|---| | CardNumberTextField | \[Reference\](https://mercadopago.github.io/sdk-ios/latest/documentation/coremethods/cardnumbertextfield) | Secure field for entering the card number. | | ExpirationDateTextField | \[Reference\](https://mercadopago.github.io/sdk-ios/0.1.0/documentation/coremethods/expirationdatetextfield) | Secure field for entering the card expiration date. | | SecurityTextField | \[Reference\](https://mercadopago.github.io/sdk-ios/latest/documentation/coremethods/securitycodetextfield) | Secure field for entering the security code (CVV). | ::: :::AccordionComponent{title="Get payment methods" pill="client-side"} 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. \`\`\`swift Task { let paymentMethod = try await coreMethods.paymentMethods( bin: "50317557" ) } \`\`\` | Parameter | Type | Description | Required | |---|---|---|---| | \`bin\` | String | The first 8 digits of the credit card, obtained via the \`onBinChange\` callback of \`CardNumberTextField\`. | Required | For more information about the call response, consult the \[method documentation on GitHub\](https://mercadopago.github.io/sdk-ios/latest/documentation/coremethods/coremethods/paymentmethods(bin:mode:)). ::: :::AccordionComponent{title="Get installment conditions" pill="client-side"} 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. \`\`\`swift Task { let installments = try await coreMethods.installments( bin: "12345678", amount: "100" ) } \`\`\` > NOTE > > Use the selected \`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 | 8 digits of the credit card. | Required | | \`amount\` | String | Total transaction amount. | Required | For more information about the call response, consult the \[method documentation on GitHub\](https://mercadopago.github.io/sdk-ios/latest/documentation/coremethods/coremethods/paymentmethods(bin:mode:)). ::: :::AccordionComponent{title="Get card issuer" pill="client-side"} For certain payment methods and brands, Mercado Pago requires the identification of the card issuer. This method returns the list of available card issuers for the provided BIN, allowing the buyer to select the appropriate issuer when necessary. \`\`\`swift Task { let issuer = try await coreMethods.issuers( bin: "12345678", paymentMethodID: paymentMethodId ) } \`\`\` | Parameter | Type | Description | Required | |---|---|---|---| | \`bin\` | String | The first 8 digits of the credit card, obtained via the \`onBinChange\` callback of \`CardNumberTextField\`. | Required | | \`paymentMethodId\` | String | Payment method ID, obtained from the result of the \`PaymentMethods\` method. | Required | For more information about the call response, consult the \[method documentation on GitHub\](https://mercadopago.github.io/sdk-ios/latest/documentation/coremethods/coremethods/issuers(bin:paymentmethodid:)). ::: :::AccordionComponent{title="Get document types" pill="client-side"} 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. \`\`\`swift Task { let documents = await self.coreMethods.identificationTypes() } \`\`\` For more information about the call response, consult the \[method documentation on GitHub\](https://mercadopago.github.io/sdk-ios/latest/documentation/coremethods/coremethods/identificationtypes()). ::: :::AccordionComponent{title="Create card token" pill="client-side"} 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. > WARNING > > This method call uses an instance of the \[secure fields\](#bookmark\_configure\_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. \`\`\`swift Task { let token = try await coreMethods.createToken( cardNumber: cardNumber, expirationDate: expirationDate, securityCode: securityCode, documentType: IdentificationType(name: "CPF"), documentNumber: "1234567891", cardHolderName: "APRO" ) print("Token response => \\(token)") } \`\`\` | Parameter | Type | Description | Required | |---|---|---|---| | \`cardNumber\` | \[CardNumberTextField\](https://mercadopago.github.io/sdk-ios/latest/documentation/coremethods/cardnumbertextfield) | Card number field class. | Required | | \`expirationDate\` | \[ExpirationDateTextfield\](https://mercadopago.github.io/sdk-ios/latest/documentation/coremethods/expirationdatetextfield) | Card expiration field class. | Required | | \`securityCode\` | \[SecurityCodeTextField\](https://mercadopago.github.io/sdk-ios/latest/documentation/coremethods/securitycodetextfield) | Card security code field class. | Required | | \`documentType\` | \[IdentificationType\](https://mercadopago.github.io/sdk-ios/latest/documentation/coremethods/identificationtype) | Document type being submitted. | Optional | | \`documentNumber\` | String | Document number. | Optional | | \`cardHolderName\` | String | Full name of the cardholder. | Required | For more information about the call response, consult the \[method documentation on GitHub\](https://mercadopago.github.io/sdk-ios/latest/documentation/coremethods/coremethods/createtoken(cardnumber:expirationdate:securitycode:documenttype:documentnumber:cardholdername:)). ### 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. \`\`\`swift func generateTokenByCardID() { Task { let response = try await coreMethods.createToken( cardID: "123", securityCode: securityCodeField ) print("Token response => \\(response.token)") } } \`\`\` | Parameter | Type | Description | Required | |---|---|---|---| | \`cardID\` | String | Existing generated card ID. | Required | | \`securityCode\` | \[SecurityCodeTextField\](https://mercadopago.github.io/sdk-ios/latest/documentation/coremethods/securitycodetextfield) | Card security code field class. | Optional | For more information about the call response, consult the \[method documentation on GitHub\](https://mercadopago.github.io/sdk-ios/latest/documentation/coremethods/coremethods/createtoken(cardid:expirationdate:securitycode:)). ::: :::AccordionComponent{title="Submit payment" pill="server-side"} Payment submission must be done by creating an order that contains the associated payment transaction. To do this, send a request with your :toolTipComponent\[test Access Token\]{content="Private 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 :TagComponent{tag="POST" text="/v1/orders" href="/developers/en/reference/online-payments/checkout-api/create-order/post" color="green"} 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 | |---|---|---|---| | \`Authorization\` | Header | Refers to your private key, the :toolTipComponent\[test Access Token\]{content="Private 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\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/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 :TagComponent{tag="GET" text="Get payment methods" href="/developers/en/reference/online-payments/checkout-api/payment-methods/get" color="accent"} 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 | > SUCCESS\_MESSAGE > > To see all parameters sent in this request in detail, consult our :TagComponent{tag="API" text="API Reference" href="/developers/en/reference/online-payments/checkout-api/overview" color="accent"}. Also, if you receive an error when submitting the payment, consult our \[error list\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/payment-management/integration-errors). 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\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/payment-management/status/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. | > WARNING > > If you created the order in manual mode, payment processing requires an additional request to :TagComponent{tag="POST" text="/v1/orders/{order\_id}/process" href="/developers/en/reference/online-payments/checkout-api/process-order/post" color="green"}. It is also possible to perform a reservation and capture of values. For more details, see \[Reserve, capture, and cancel values\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/payment-management/reserve-capture-cancel). Once the order and payment are created, you can check the possible states in the \[Order status\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/payment-management/status/order-status) and \[Transaction status\](https://www.mercadopago.com.pe/developers/en/docs/checkout-api-orders/payment-management/status/transaction-status) sections, respectively. ::: :::: ::::: ::::::