Tarjetas

Antes de mostrar el Card Payment, crea una order en tu backend mediante el endpoint /v1/ordersPOST, utilizando tu Access Token de pruebaClave privada vinculada a una aplicación, utilizada en el backend para autenticar operaciones en el entorno de prueba. Puedes consultarla en la sección Credenciales de la aplicación, dentro del entorno de prueba. No permite procesar pagos reales y nunca debe exponerse en el frontend.Ver 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.

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",
    "expiration_time": "PT2H",
    "total_amount": "100.00",
    "external_reference": "ext_ref_1234",
    "payer": {
        "email": "test_payer@example.com"
    },
    "items": [
        {
            "title": "Producto",
            "quantity": 1,
            "unit_price": "100.00"
        }
    ],
    "config": {
        "location": {
            "state_id": "PE-LIM"
        }
    }
}'

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...",
  "expiration_time": "PT2H",
  "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.

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.

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

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

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.

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.

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}")
               }
           }
       }
   }
}

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

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}")
               }
           }
       }
   }
}

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

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}")
               }
           }
       }
   }
}

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

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.

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.

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}")
               }
           }
       }
   }
}

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}")
               }
           }
       }
   }
}

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

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 vinculada a una aplicación, utilizada en el backend para autenticar operaciones en el entorno de prueba. Puedes consultarla en la sección Credenciales de la aplicación, dentro del entorno de prueba. No permite procesar pagos reales y nunca debe exponerse en el frontend.Ver credenciales de prueba 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_payer@example.com"
    },
    "config": {
        "location": {
            "state_id": "PE-LIM"
        }
    },
    "transactions": {
        "payments": [
            {
                "amount": "50.00",
                "payment_method": {
                    "id": "master",
                    "type": "credit_card",
                    "token": "1223123",
                    "installments": 1
                }
            }
        ]
    }
}'

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

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.