Recursos para IA

Tarjetas

La integración de pagos con tarjeta de crédito y/o débito en Checkout API puede realizarse de dos maneras para aplicaciones móviles. La integración recomendada es a través del Card Payment Brick (vía Mercado Pago SDK Checkout), pero, si quieres ser responsable de definir cómo se obtendrá la información, puedes realizar tu integración a través de Core Methods (vía Mercado Pago SDK Core Methods), disponibles para aplicaciones Android e iOS.

La integración móvil vía Card Payment Brick usa internamente el módulo Core Methods para comunicarse con la API de Orders y enviar el pago. Al usar ambas integraciones en la misma aplicación, controla las versiones para evitar conflictos.

Consulta a continuación el flujo principal de la integración móvil vía Card Payment.

Card Payment

El Card Payment (vía Mercado Pago SDK Checkout) acelera la implementación de pagos con tarjeta en aplicaciones Android e iOS nativas. El SDK muestra el formulario, obtiene los datos necesarios de la tarjeta, permite la selección de cuotas, tokeniza la información de forma segura y procesa el pago contra una order creada previamente en el backend.

El flujo principal de esta integración con el SDK Checkout es el CardTransaction, donde el backend crea la order con el Access Token y envía a la aplicación únicamente el orderId y el clientToken. De esta forma, la credencial privada permanece protegida y los datos sensibles de la tarjeta se tratan en conformidad con los estándares de seguridad PCI.

Para integrar el Card Payment, primero deberás haber configurado el Mercado Pago SDK Checkout en el ambiente de desarrollo y, a partir de eso, seguir los pasos a continuación de acuerdo con el sistema operativo elegido.

Además del flujo principal presentado en esta sección, Mercado Pago SDK Checkout ofrece recursos adicionales para la integración móvil con Card Payment, como restringir los medios de pago aceptados, limitar el rango de cuotas, tokenizar una tarjeta sin realizar el cobro y gestionar la cancelación por parte del comprador. Para conocerlos, consulta la documentación Personalización de comportamiento del checkout.

El SDK Checkout para Android es la biblioteca nativa para integrar pagos con tarjeta en aplicaciones Android. Desarrollado en Kotlin con soporte a Jetpack Compose, encapsula toda la comunicación con la Orders API — tokenización de tarjeta, selección de cuotas, validación de marca y envío del pago — en un flujo gestionado, sin que el desarrollador necesite manipular datos sensibles directamente.

La distribución se realiza vía Jetpack Compose BoM para garantizar versiones coherentes entre los módulos, con requisitos mínimos de Android 6.0+ (versión 23 del SDK o superior) y Kotlin 2.0+.

Para profundizar en la implementación y el uso del SDK, consulta el repositorio en GitHub donde encontrarás ejemplos de referencia, tanto de la integración vía Card Payment como de Core Methods, presentando un flujo de checkout integrado y seguro.

Crear order

Antes de mostrar el Card Payment, crea una order en tu backend mediante el endpoint /v1/ordersPOST, utilizando tu Access Token de pruebaClave privada de la aplicación creada en Mercado Pago y utilizada en el backend. Puedes acceder a ella en Tus integraciones > Datos de integración > Pruebas > Credenciales de prueba..

En el flujo CardTransaction, crea la order en modo manual (processing_mode=manual) y no envíes la transacción de pago en ese momento. La respuesta proporcionará el id de la order y el client_token necesarios para que la SDK tokenice la tarjeta y procese el pago contra la order existente.

También es posible tokenizar una tarjeta sin realizar un cobro, útil para capturar los datos del comprador en un momento y efectuar el pago en otro. En ese caso, la SDK genera el token sin crear una order ni mover dinero. Para más información, consulta Tokenizar tarjeta sin realizar pago.

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

Parámetro	Tipo	Descripción	Obligatoriedad
`Authorization`	Header	Hace referencia a tu clave privada, el Access Token de pruebaClave privada de la aplicación creada en Mercado Pago y que es utilizada en el backend. Puedes acceder a ella a través de Tus integraciones > Datos de integración > Pruebas > Credenciales de prueba. El Access Token de prueba comienza con el prefijo `APP_USR`..	Obligatorio
`X-Idempotency-Key`	Header	Clave de idempotencia. Esta clave garantiza que cada solicitud se procese una única vez, evitando duplicidades. Usa un valor exclusivo en el `header` de la solicitud, como un UUID V4 o un string aleatorio.	Obligatorio
`processing_mode`	Body. String	Modo de procesamiento de la order. Los valores posibles son: - `automatic`: para crear y procesar la orden en modo automático. - `manual`: para crear la order y procesarla posteriormente. En este caso, usa `manual` para permitir que la SDK complete y procese la transacción mediante el `client_token`.	Obligatorio
`total_amount`	Body. String	Monto total de la transacción.	Obligatorio
`payer.email`	Body. String	E-mail del pagador.	Obligatorio

En caso de éxito, la API devolverá la order creada y el token de autenticación para el procesamiento en la aplicación.

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

Usa el valor de id como orderId y el valor de client_token como clientToken en la configuración de la SDK.

Para conocer todos los parámetros disponibles, consulta la Referencia de APIAPI. Si recibes un error, consulta la lista de errores.

Configurar y mostrar el Card Payment

En la SDK Checkout, pasa a MPOrder los datos de la order creada en tu backend. La SDK mostrará el formulario, permitirá la selección de cuotas, tokenizará la tarjeta y procesará el pago contra esa order.

Si tu integración necesita restringir algún tipo de tarjeta, las marcas aceptadas o el rango de cuotas, esa configuración debe aplicarse antes de iniciar la tokenización. Las reglas se evalúan en el momento en que se muestra el formulario, por lo que una tarjeta fuera de las restricciones es rechazada sin que se genere ningún token. Para más información, consulta la sección Restringir medios de pago y limitar cuotas.

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

checkout.show { result ->
    when (result) {
        is MercadoPagoCheckoutResult.Success -> {
            val data = result.paymentData // MPPaymentData.CardTransaction
            // Usa data.orderId, data.orderStatus, etc.
        }
        is MercadoPagoCheckoutResult.Error -> {
            // Muestra un mensaje de error u ofrece un nuevo intento
        }
        is MercadoPagoCheckoutResult.UserCancelled -> {
            // Vuelve al carrito o al paso anterior
        }
    }
}

Parámetro	Tipo	Descripción
`orderId`	`String`	Identificador de la order (`id`) devuelto en su creación.
`clientToken`	`String`	Token (`client_token`) devuelto en la creación de la order y que representa las credenciales del usuario.

En caso de éxito, la SDK devolverá en MPPaymentData.CardTransaction la siguiente información:

Parámetro	Tipo	Descripción
`orderId`	`String`	Identificador de la order.
`orderStatus`	`String`	Status de la order tras el procesamiento.
`paymentMethodId`	`String`	Identificador del medio de pago.
`paymentTypeId`	`String`	Tipo del medio de pago.

Con el Card Payment también es posible alinear la apariencia del checkout con la identidad visual de tu aplicación. El Mercado Pago SDK Checkout usa componentes tokenizados en design atómico, de modo que alterar un token repercute automáticamente en componentes, pantallas y estados. Para más información, consulta Personalizaciones visuales del Card Payment.

Core Methods

En la integración mediante Core Methods (a través del Mercado Pago SDK Core Methods) para aplicaciones móviles, el desarrollador es responsable de definir cómo se obtendrá la información necesaria para completar el pago, incluyendo el tipo de documento y los datos de la tarjeta (emisor y cuotas ). Con esto, tiene total flexibilidad en la construcción de la experiencia del flujo de checkout, a diferencia de la integración mediante Card Payment, donde la búsqueda de la información se realiza automáticamente y la interfaz es preestablecida.

El SDK Core Methods utiliza información capturada por los campos seguros, viabilizando la ejecución de las principales operaciones de pago.

En la integración mediante Core Methods para aplicaciones Android, cada método debe utilizarse según las necesidades de tu flujo de pago. Para utilizarlos, comienza creando una instancia de Core Methods en tu clase con el siguiente código Kotlin: val coreMethods = MercadoPagoSDK.getInstance().coreMethods.

De esa forma, podrás utilizar cualquiera de los métodos listados a continuación:

Configurar campos seguros

Los campos seguros son componentes desarrollados para garantizar la privacidad y protección de los datos sensibles ingresados por el comprador. En total conformidad con los estándares PCIConjunto de reglas de seguridad que buscan proteger los datos de las tarjetas de pago contra fraudes y filtraciones de datos., estos campos aseguran que la aplicación nunca tenga acceso directo a la información ingresada, que se transmite de forma segura solo para la creación de tokens y transacciones.

Todas las interacciones con estos campos ocurren mediante callbacks, lo que permite capturar eventos relevantes sin exponer los datos del usuario. Los métodos descritos a continuación utilizan instancias de estos campos seguros, por lo que es esencial que estén configurados correctamente en la interfaz del checkout antes de usarlos.

Cada componente notifica a la aplicación integradora cuando hay un cambio de valor, sin exponer los datos ingresados, e informa el resultado de la validación del campo según las reglas del PCI y de la tarjeta.

Los datos ingresados en los campos seguros nunca están disponibles para la aplicación integradora. Se transmiten de forma segura solo para la creación de tokens y transacciones.

En la tabla a continuación encontrarás el detalle de los componentes disponibles. Para más información sobre la configuración, consulta la referencia correspondiente en GitHub.

Nombre del componente	Referencia en GitHub	Descripción
CardNumberTextField	Referencia	Campo seguro para ingresar el número de tarjeta.
ExpirationDateTextField	Referencia	Campo seguro para ingresar la fecha de vencimiento de la tarjeta.
SecurityTextField	Referencia	Campo seguro para ingresar el código de seguridad (CVV).

Obtener medios de pago

El método Obtener medios de pago devuelve la lista de medios de pago disponibles a partir del BIN de la tarjeta informado, considerando las reglas e instituciones financieras válidas para el país configurado. Mediante este método es posible identificar la marca de la tarjeta, definir correctamente los próximos pasos del checkout y validar la aceptación de la tarjeta.

kotlin
val coreMethods = MercadoPagoSDK.getInstance().coreMethods
coroutineScope {
   val result = coreMethods.getPaymentMethods(bin = bin)
   when (result) {
       is Result.Success -> {
           print("Éxito de request: ${result.data}")
       }
       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   print("Error de request: ${result.error}")
               }
               is ResultError.Validation -> {
                   print("Error de validación: ${result.error}")
               }
           }
       }
   }
}

Parámetro	Tipo	Descripción	Obligatorio
`bin`	String	Los 8 primeros dígitos de la tarjeta de crédito, obtenidos mediante el callback `onBinChange` del `CardNumberTextFieldEvent`.	Obligatorio

Para más información sobre la respuesta de la llamada, consulta la documentación del método en GitHub.

Obtener condiciones de cuotas

El método Obtener condiciones de cuotas realiza la búsqueda de todas las opciones de cuotas disponibles para una tarjeta y monto de transacción determinados. Considera las reglas del emisor, del medio de pago y del monto de la compra, devolviendo todas las opciones válidas, incluyendo cantidad de cuotas, intereses, valor de cada cuota, valor total, entre otros.

La llamada al método getInstallments debe realizarse para todos los tipos de tarjeta (débito y crédito) para verificar si el pago puede completarse mediante ese medio.

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

Utiliza la información del Installment para mostrar al comprador todos los detalles del monto y de las cuotas de la compra, antes de finalizar el pago.

Parámetro	Tipo	Descripción	Obligatorio
`bin`	String	Los 8 primeros dígitos de la tarjeta de crédito, obtenidos mediante el callback `onBinChange` del `CardNumberTextFieldEvent`.	Obligatorio
`amount`	BigDecimal	Monto total de la transacción.	Obligatorio

Para más información sobre la respuesta de la llamada, consulta la documentación del método en GitHub.

Obtener emisor de la tarjeta

En determinados medios de pago y marcas, Mercado Pago requiere la identificación del emisor de la tarjeta (issuer). Este método devuelve la lista de emisores disponibles para el BIN informado, permitiendo al comprador seleccionar el emisor correcto cuando sea necesario.

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

Parámetro	Tipo	Descripción	Obligatorio
`bin`	String	Los 8 primeros dígitos de la tarjeta de crédito, obtenidos mediante el callback `onBinChange` del `CardNumberTextFieldEvent`.	Obligatorio
`paymentMethodId`	String	ID del medio de pago, normalmente obtenido desde el resultado del método `PaymentMethods`.	Obligatorio

Para más información sobre la respuesta de la llamada, consulta la documentación del método en GitHub.

Obtener tipos de documento

Mercado Pago requiere la validación de un documento de identificación del titular de la tarjeta. Utiliza este método para recibir todos los tipos de documentos aceptados para el país configurado en la integración.

kotlin
val coreMethods = MercadoPagoSDK.getInstance().coreMethods
coroutineScope {
   val result = coreMethods.getIdentificationTypes()
   when (result) {
       is Result.Success -> {
           print("Éxito de request: ${result.data}")
       }
       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   print("Error de request: ${result.error}")
               }
               is ResultError.Validation -> {
                   print("Error de validación: ${result.error}")
               }
           }
       }
   }
}

Para más información sobre la respuesta de la llamada, consulta la documentación del método en GitHub.

Crear token de la tarjeta

Este método es responsable de generar un token temporal a partir de los datos de la tarjeta informada. El token generado es obligatorio para realizar la transacción de pago mediante la API de Mercado Pago, ya que reemplaza los datos sensibles de la tarjeta, garantizando mayor seguridad en el proceso.

La llamada a este método utiliza una instancia de los campos seguros previamente configurados en la interfaz del checkout. Por lo tanto, asegúrate de que los campos seguros estén correctamente implementados y configurados antes de utilizar el método generateCardToken.

Crear un token para una tarjeta nueva

Para generar un token para una tarjeta nueva de forma segura, utiliza la clase que protege los datos ingresados y pásala al método generateCardToken. Antes de ejecutar el método, verifica que todos los campos obligatorios estén completados correctamente.

kotlin
val coreMethods = MercadoPagoSDK.getInstance().coreMethods
coroutineScope {
   val result = coreMethods.generateCardToken(
      cardNumberState = cardNumberPCIFieldState,
      expirationDateState = expirationDatePCIFieldState,
      securityCodeState = securityCodePCIFieldState,
      buyerIdentification = BuyerIdentification(
          name = "APRO",
          number = "12345678",
          type = "DNI"
      )
   )
   when (result) {
       is Result.Success -> {
           print("Éxito de request: ${result.data}")
       }
       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   print("Error de request: ${result.error}")
               }
               is ResultError.Validation -> {
                   print("Error de validación: ${result.error}")
               }
           }
       }
   }
}

Parámetro	Tipo	Descripción	Obligatorio
`cardNumberState`	PCIFieldState	Estado del campo de número de tarjeta.	Obligatorio
`expirationDateState`	PCIFieldState	Estado del campo de vencimiento de la tarjeta.	Obligatorio
`securityCodeState`	PCIFieldState	Estado del campo de código de seguridad de la tarjeta.	Obligatorio
`buyerIdentification`	BuyerIdentification	Clase de identificación del comprador.	Obligatorio

Para más información sobre la respuesta de la llamada, consulta la documentación del método en GitHub.

Crear un token para una tarjeta existente

En las transacciones con Mercado Pago, los datos de las tarjetas registradas por el comprador se almacenan de forma segura y no son accesibles desde tu backend. Solo el ID de la tarjeta se proporciona a la aplicación, que deberás utilizar para generar un token temporal. Esto protege la información sensible, ya que solo el ID se manipula, mientras que el número de tarjeta, CVV y fecha de vencimiento no se exponen y permanecen seguros.

kotlin
val coreMethods = MercadoPagoSDK.getInstance().coreMethods
coroutineScope {
   val result = coreMethods.generateCardToken(
      cardId = cardId,
      expirationDateState = expirationDatePCIFieldState,
      securityCodeState = securityCodePCIFieldState,
      buyerIdentification = BuyerIdentification(
          name = "APRO",
          number = "12345678",
          type = "DNI"
      )
   )
   when (result) {
       is Result.Success -> {
           print("Éxito de request: ${result.data}")
       }
       is Result.Error -> {
           when (result.error) {
               is ResultError.Request -> {
                   print("Error de request: ${result.error}")
               }
               is ResultError.Validation -> {
                   print("Error de validación: ${result.error}")
               }
           }
       }
   }
}

Parámetro	Tipo	Descripción	Obligatorio
`cardId`	String	ID de la tarjeta existente generada.	Obligatorio
`securityCodeState`	PCIFieldState	Estado del campo de código de seguridad de la tarjeta.	Obligatorio
`expirationDateState`	PCIFieldState	Estado del campo de vencimiento de la tarjeta.	Opcional
`buyerIdentification`	BuyerIdentification	Clase de identificación del comprador.	Obligatorio

Para más información sobre la respuesta de la llamada, consulta la documentación del método en GitHub.

Realizar pago

El envío del pago debe realizarse mediante la creación de una order que contenga la transacción de pago asociada.

Para eso, envía una solicitud con tu Access Token de pruebaClave privada de la aplicación creada en Mercado Pago que se utiliza en el backend. Puedes acceder a ella a través de Tus integraciones > Datos de integración > Pruebas > Credenciales de prueba. El Access Token de prueba comienza con el prefijo `APP_USR`. y los parámetros requeridos que se enumeran a continuación al endpoint /v1/ordersPOST.

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

Parámetro	Tipo	Descripción	Obligatorio/Opcional
`Authorization`	Header	Hace referencia a tu clave privada, el Access Token de pruebaClave privada de la aplicación creada en Mercado Pago que se utiliza en el backend. Puedes acceder a ella a través de Tus integraciones > Datos de integración > Pruebas > Credenciales de prueba. El Access Token de prueba comienza con el prefijo `APP_USR`..	Obligatorio
`X-Idempotency-Key`	Header	Clave de idempotencia. Esta clave garantiza que cada solicitud se procese solo una vez, evitando duplicidades. Usa un valor exclusivo en el `header` de la solicitud, como un UUID V4 o un string aleatorio.	Obligatorio
`processing_mode`	Body. String	Modo de procesamiento de la order. Los valores posibles son: - `automatic`: para crear y procesar la orden en modo automático. - `manual`: para crear la order y procesarla posteriormente. Para más información, consulta la sección Modelo de integración.	Obligatorio
`total_amount`	Body. String	Monto total de la transacción.	Obligatorio
`transactions.payments.payment_method.id`	Body. String	Identificador del medio de pago. En este caso, es la marca de cada tarjeta. Puedes consultar la lista completa de identificadores disponibles enviando una solicitud al endpoint Obtener medios de pagoGET.	Obligatorio
`transactions.payments.payment_method.type`	Body. String	Tipo de medio de pago. Para pagos con tarjeta de crédito debe ser `credit_card`, y para pagos con tarjeta de débito debe ser `debit_card`.	Obligatorio
`transactions.payments.payment_method.token`	Body. String	Token de la tarjeta. Campo obligatorio para pagos con tarjeta de crédito y débito.	Obligatorio

Para conocer en detalle todos los parámetros enviados en esta solicitud, consulta nuestra Referencia de APIAPI. Además, si recibes un error al enviar el pago, consulta nuestra lista de errores.

En caso de éxito, la respuesta será similar al ejemplo a continuación.

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

Parámetro	Tipo	Descripción
`transactions.payments.status`	String	Estado de la transacción. Por ejemplo, `processed` indica que el pago fue aprobado. Consulta la sección Estado de la transacción para ver todos los valores posibles.
`transactions.payments.status_detail`	String	Detalle del estado de la transacción. Por ejemplo, `accredited` indica que el pago fue aprobado y acreditado.
`transactions.payments.paid_amount`	String	Monto efectivamente pagado en la transacción.

Si creaste la order en modo manual, recuerda que el procesamiento del pago requiere un paso adicional: la solicitud al endpoint Procesar orderPOST. Además, es posible realizar una reserva y captura de valores. Dirígete a la sección Reservar, capturar y cancelar valores para más información.

Una vez creada la order y el pago, puedes consultar los estados posibles en las secciones Estado de la order y Estado de la transacción, respectivamente.

AnteriorIntroducciónConoce qué medios de pago puedes ofrecer con Checkout API en tu tienda online en entorno móvil.

PróximoConfigurar notificaciones de ordersConfigura notificaciones de orders para recibir alertas sobre tus transacciones con Checkout API.