Recursos para IA

Tarjetas

La integración de pagos con tarjeta de crédito y/o débito en Checkout API puede ser realizada de dos maneras. La integración recomendada se realiza por medio del Card Payment Brick, donde el Brick es el encargado de realizar la búsqueda por la información necesaria para realizar el pago. Pero, si deseas encargarte de definir cómo será buscada esta información, puedes realizar tu integración por medio de Core Methods, disponibles para sitios web y aplicaciones móviles Android e iOS.

En la integración por medio del Card Payment Brick para sitios web, la biblioteca de MercadoPago.js, incluída en tu proyecto durante la configuración del ambiente de desarrollo, se encarga de obtener la información requerida para la generación de un pago. Esto es, realiza una búsqueda de los tipos de documentos disponibles para el país correspondiente, así como, a medida que se introducen los datos de la tarjeta, de la información relativa al emisor y a las cuotas disponibles.

Toda la información involucrada en el procesamiento de la transacción es almacenada en el backend, en conformidad con los padrones de seguridad PCI.

Además, el componente brinda la posibilidad de orientar al usuario con alertas de campos incompletos o posibles errores al rellenar los datos, optimizando el proceso de compra.

Con esto, la implementación del flujo es transparente para quien realiza la integración, tal como muestra el diagrama a continuación.

  sequenceDiagram
      participant Navegador del comprador
      participant Front-end del integrador
      participant MercadoPago.js
      participant Back-end del integrador
      participant API Mercado Pago
      Navegador del comprador->>Front-end del integrador: 1. El Comprador accede a la pantalla de cobro.
      Front-end del integrador->>MercadoPago.js: 2. El front-end del integrador descarga e inicializa la SDK JS de Mercado Pago
      Front-end del integrador->>Navegador del comprador: 3. El front-end del integrador muestra el formulario de pago
      Navegador del comprador->>Front-end del integrador: 4. El comprador completa el formulario y finaliza el pago.
      Front-end del integrador->>MercadoPago.js: 5. El front-end del integrador utiliza la SDK JS para crear el token que contendrá los datos de la tarjeta de forma segura.
      Front-end del integrador->>Back-end del integrador: 6. El front-end del integrador envía el token de la tarjeta y los datos de pago a su back-end.
      Back-end del integrador->>API Mercado Pago: 7. Desde el back-end, se llama a los servicios de Mercado Pago para crear el pago.
      API Mercado Pago->>Navegador del comprador: 8. El front-end del integrador le muestra al comprador el resultado de la operación.
      API Mercado Pago->>Back-end del integrador: 9. Mercado Pago puede enviar notificaciones vía Webhook con actualizaciones del estado del pago.
      Back-end del integrador->>Navegador del comprador: 10. Si corresponde, se le avisa al comprador sobre la actualización del pago.

Para avanzar con la configuración de pagos con tarjeta de débito y/o crédito vía Card Payment Brick, sigue los pasos a continuación.

Recuerda: antes de configurar los medios de pago, elige el modo en que procesarás tus transacciones. La definición del modo de procesamiento, ya sea manual o automático, se realizará en el momento de la creación de la order, a través del parámetro processing_mode. Para más información, accede a la sección Modelo de integración.

Añadir formulario de pago

Para poder recibir pagos, es necesario que añadas en el frontend un formulario que permita capturar los datos del pagador de manera segura y permita la criptografía de la tarjeta. Esta inclusión debe realizarse por medio del Card Payment Brick, que ofrece un formulario optimizado con temas variados, e incluye los campos necesarios para pagos con tarjetas.

Para añadir el Card Payment Brick, realiza primero su configuración e inicialización desde el frontend, como muestran los ejemplos a continuación.

const renderCardPaymentBrick = async (bricksBuilder) => {
  const settings = {
    initialization: {
      amount: 100.99, // valor total a ser pago
    },
    callbacks: {
      onReady: () => {
        /*
         Callback llamado cuando el Brick esté listo.
         Aquí pueden ocultarse loadings del site, por ejemplo.
       */
      },
      onSubmit: (formData, additionalData) => {
        // callback llamado al hacer clic en el botón de envío de datos
        return new Promise((resolve, reject) => {
          const submitData = {
            type: "online",
            total_amount: String(formData.transaction_amount), // debe ser un string con formato 00.00
            external_reference: "ext_ref_1234", // identificador del origen de la transacción
            processing_mode: "automatic",
            transactions: {
              payments: [
                {
                  amount: String(formData.transaction_amount), // debe ser un string con formato 00.00 
                  payment_method: {
                    id: formData.payment_method_id,
                    type: additionalData.paymentTypeId,
                    token: formData.token,
                    installments: formData.installments,
                  },
                },
              ],
            },
            payer: {
              email: formData.payer.email,
              identification: formData.payer.identification,
            },
          };

          fetch("/process_order", {
            method: "POST",
            headers: {
              "Content-Type": "application/json",
            },
            body: JSON.stringify(submitData),
          })
            .then((response) => response.json())
            .then((response) => {
              // recibir el resultado del pago
              resolve();
            })
            .catch((error) => {
              // manejo de la respuesta de error al intentar crear el pago 
              reject();
            });
        });
      },
      onError: (error) => {
        // callback llamado para todos los casos de error del Brick 
        console.error(error);
      },
    },
  };
  window.cardPaymentBrickController = await bricksBuilder.create(
    "cardPayment",
    "cardPaymentBrick_container",
    settings
  );
};
renderCardPaymentBrick(bricksBuilder);

El callback onSubmit del Brick obtendrá los datos mínimos necesarios para la creación de un pago. Entre esos datos se encuentra el CardToken, que representa de forma segura los datos de la tarjeta. Este token solo puede ser usado una vez y expira dentro de los 7 días de su creación.

Además de la información mínima, recomendamos incluir detalles adicionales o que puedan facilitar el reconocimiento de la compra por parte del comprador, y aumentar así la tasa de aprobación de pagos. Consulta nuestra Referencia de API para conocer en detalle todos los parámetros a ser enviados al crear un pago, incluyendo aquellos que puedan mejorar tu aprobación, y verifica cuáles quieres incluir en esta etapa.

Luego, agrega los campos relevantes para el objeto enviado, que son retornados en la respuesta del callback.

Siempre que el usuario salga de la pantalla donde se exhibe el Brick, es necesario destruir la instancia actual con el comando window.cardPaymentBrickController.unmount(). Al volver a ingresar, una nueva instancia deberá ser generada. Finalmente, realiza el renderizado del Brick utilizando alguno de los ejemplos a continuación.

<div id="cardPaymentBrick_container"></div> // El id debe corresponder al valor enviado dentro del método create() en la etapa anterior

Como resultado, la renderización del Brick se verá similar a la imagen debajo.

cardform

Para avanzar a la etapa de envío del pago, será necesario que tu backend pueda recibir la información del formulario creado, junto con el token resultante de la criptografía de la tarjeta. Para eso, recomendamos disponibilizar un endpoint /Process_order que acoja los datos recolectados por el Brick después de realizar la acción submit.

Para configurar las cuotas exhibidas en el frontend, consulta la sección Configurar cuotas del Card Payment Brick. En caso de querer configurar cuotas sin intereses, accede a la documentación de Soporte.

Enviar pago

El envío del pago debe ser realizado mediante la creación de una order que contenga transacciones de pago asociadas.

La definición del modo de procesamiento se realizará al momento de crear la order, mediante el parámetro processing_mode. Su valor deberá ser automatic, para procesamientos automáticos, o manual, para procesar la order manualmente.

Para eso, envía un POST con tu Access Token de pruebaClave privada de la aplicación creada en Mercado Pago, 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`. y los parámetros requeridos al endpoint /v1/ordersAPI y ejecuta la requisición.

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

La creación de la order está sujeta a límites de solicitudes por cliente. Si recibes un error 429 Too Many Requests, espera el tiempo indicado en el header Retry-After de la respuesta antes de volver a intentarlo. Consulta Posibles errores para más detalles.

Consulta en la tabla a continuación las descripciones de los parámetros que poseen alguna particularidad importante que debe destacarse.

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, 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`..	Requerido
`X-Idempotency-Key`	Header	Llave de idempotencia. Esta llave garantiza que cada solicitud sea procesada una única vez, evitando duplicidades. Utiliza un valor exclusivo en el encabezado de tu solicitud, como un UUID V4 o strings aleatorias.	Requerido
`processing_mode`	Body. String	Modo de procesamiento de la order. Los valores posibles son: `automatic`, para crear y procesar la order en modo automático. `manual`, para crear la order y procesarla con posterioridad. Para más información, accede a Modelo de integración.	Requerido
`total_amount`	Body. String	Monto total de la transacción.	Requerido
`transaction.payments.payment_method.id`	Body. String	Identificador del método de pago. En este caso, es la bandera de cada tarjeta. Puedes consultar la lista completa de identificadores disponibles enviando una requisición al endpoint Obtener medios de pago.	Requerido
`transaction.payments.payment_method.type`	Body. String	Tipo de método de pago. Para pagos con tarjetas de crédito, debe ser `credit_card`, y para pagos con tarjeta de débito, debe ser `debit_card`.	Requerido.
`transaction.payments.payment_method.token`	Body. String	Token de la tarjeta. Obligatorio para pagos con tarjeta de crédito y débito.	Requerido

Para conocer en detalle todos los parámetros a ser enviados en esta requisición, consulta nuestra Referencia de API. Adicionalmente, si recibes un error al enviar el pago, puedes consultar nuestro listado de errores.

En caso de éxito, la respuesta se verá como el ejemplo a continuación.

json
{
  "id": "ORD01JS2V6CM8KJ0EC4H502TGK1WP",
  "type": "online",
  "processing_mode": "automatic",
  "external_reference": "ext_ref_1234",
  "total_amount": "50.00",
  "total_paid_amount": "200.00",
  "country_code": "BRA",
  "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": "47.28",
        "reference_id": "0002yjis6j",
        "status": "processed",
        "status_detail": "accredited",
        "payment_method": {
          "id": "elo",
          "type": "credit_card",
          "token": "519ada5ac7431ef6ce24ac19c38f6768",
          "installments": 1
        }
      }
    ]
  }
}

Entre los parámetros devueltos, se destacan los indicados en la tabla a continuación.

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.

En caso de haber creado la order en modo manual, recuerda que el procesamiento del pago requiere de una etapa adicional, el llamado a Procesar orderAPI. Adicionalmente, podrás realizar una reserva y captura de valores. Dirígete a la sección Reservar, capturar y cancelar fondos para más información. Una vez creada la order y el pago, puedes consultar los estados posibles dirigiéndote a 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 tiendas virtuales.

PróximoRapipago y Pago FácilDescubre cómo ofrecer pagos con Rapipago y Pago Fácil con Checkout API utilizando Orders API.