Cuenta

Inicio
Documentación
Referencia de API
Certificaciones
Tarjeta - Integrar medios de pago - Mercado Pago Developers

Integra Checkout API para pagos con tarjetas

La integración del Checkout API de Mercado Pago para tarjetas permite que puedas ofrecer una opción de pagos completa dentro de tu sitio. Toda la experiencia sucede en tu tienda para que los clientes no tengan que salir al momento de realizar la compra.

Importante
Tu integración con la API transparente de Mercado Pago puede ser elegible para PCI SAQ A . Esta categoría de PCI requiere menos requisitos del vendedor, lo que acelera el proceso de certificación. Para ser elegible para esta categoría, tu integración debe realizarse mediante campos de tarjeta en formato Iframe.

Fields utiliza componentes HTML iframe permite que los datos PCI (cardNumber, securityCode, y expirationDate) sean inaccesibles para terceros y procesados ​​por los servidores de Mercado Pago, aumentando la seguridad del comprador, vendedor y adquiriente.

Fields

Actualmente hay dos formas de implementar esta solución. La primera es mediante el uso de métodos core, donde el integrador es responsable de todo el flujo de pago, lo que permite una mayor flexibilidad para experiencias totalmente personalizadas. El segundo utiliza cardForm, un componente creado por nosotros que facilita la integración, realizando algunos pasos del proceso de forma automática.

Usa los ejemplos descargables para conocer la integración completa o para adaptarlos según lo que necesites.

¿Cómo funciona?

API-integration-flowchart

Si quieres realizar un flujo personalizado del pago, te compartimos todos los métodos disponibles para integrar de forma avanzada .

Al usar nuestro Checkout API de Mercado Pago, es importante tener en cuenta dos instancias: la de la captura de datos y la del envío de confirmación del pago.

  1. Primero, necesitas un frontend para que recolecte los datos de la tarjeta y que genere un token de seguridad con la información para poder crear el pago.
  2. Segundo, un backend que tome el token generado y los datos del pago, como por ejemplo monto e ítem, pueda confirmar y efectuar el pago.

Tanto para el frontend como para el backend, recomendamos utilizar nuestras librerías para poder recolectar los datos sensibles de tus usuarios de manera segura.

Nota
Puedes obtener más información en las Referencias de API .

Captura los datos de la tarjeta

Client-Side

Para crear un pago es necesario hacer la captura de los datos de la tarjeta a través del navegador del comprador. Por cuestiones de seguridad, es muy importante que los datos nunca lleguen a tus servidores.

Para capturar datos de la tarjeta, siga estos pasos:

  1. Incluye y configura la librería MercadoPago.js
  2. Agrega el formulario de pago
  3. Integra el formulario con la librería MercadoPago.js

1. Incluye y configura la librería MercadoPago.js

Usa nuestra librería oficial para acceder a la API de Mercado Pago desde tu frontend para recolectar los datos de forma segura y configura tu clave pública de la siguiente manera:

html

<body>
  <!-- Add step #2 -->
  <script src="https://sdk.mercadopago.com/js/v2"></script>
  <script>
      const mp = new MercadoPago('YOUR_PUBLIC_KEY');
      // Add step #3
  </script>
</body>

La información de la tarjeta será convertida en un token para que envíes los datos a tus servidores de modo seguro.

Si aún no tienes cuenta para ver tus credenciales, regístrate.

La información de la tarjeta se convertirá en un token para que puedas enviar los datos a tus servidores de forma segura.

2. Agrega el formulario de pago

Para capturar los datos de la tarjeta, primero tienes que brindar un formulario para cargar toda la información.

Con la funcionalidad CardForm de la librería MercadoPago.js, puedes obtener y validar todo los datos necesarios como identificar el tipo y nombre del medio de pago, el banco emisor, la cantidad de cuotas y más.

CardForm te permite tener una implementación segura y una correcta tokenización de la información de la tarjeta.

Para los campos PCI (Card Number, Expiration Date y Security Code) debes crear divs que servirán como contenedores para los iFrames.

Utiliza el siguiente formulario y agrega los estilos que desees.

html

<!-- Step #2 -->
<style>
  #form-checkout {
    display: flex;
    flex-direction: column;
    max-width: 600px;
  }

  .container {
    height: 18px;
    display: inline-block;
    border: 1px solid rgb(118, 118, 118);
    border-radius: 2px;
    padding: 1px 2px;
  }
</style>
<form id="form-checkout">
   <div id="form-checkout__cardNumber-container" class="container"></div>
   <div id="form-checkout__expirationDate-container" class="container"></div>
   <input type="text" name="cardholderName" id="form-checkout__cardholderName"/>
   <input type="email" name="cardholderEmail" id="form-checkout__cardholderEmail"/>
   <div id="form-checkout__securityCode-container" class="container"></div>
   <select name="issuer" id="form-checkout__issuer"></select>
   <select name="identificationType" id="form-checkout__identificationType"></select>
   <input type="text" name="identificationNumber" id="form-checkout__identificationNumber"/>
   <select name="installments" id="form-checkout__installments"></select>
   <button type="submit" id="form-checkout__submit">Pagar</button>
   <progress value="0" class="progress-bar">Cargando...</progress>
 </form>
Referencia técnica
Encuentra información sobre los distintos atributos en las referencias técnicas .

3. Integra el formulario con la librería MercadoPago.js

Ahora, para inicializar el CardForm, tienes que relacionar el ID de cada campo del formulario con los atributos correspondientes. La librería va a ser la responsable de completar, obtener y validar todos los datos necesarios al momento de confirmar el pago.

Para que el IFrame sea renderizado, es necesario pasar la opción iframe con el valor true en el objeto de parámetro recibido por cardForm. También es posible pasar el style a los elementos.

javascript

// Step #3
const cardForm = mp.cardForm({
   amount: '100.5',
   iframe: true,
   form: {
     id: 'form-checkout',
     cardholderName: {
       id: 'form-checkout__cardholderName',
       placeholder: "Titular de la tarjeta",
     },
     cardholderEmail: {
       id: 'form-checkout__cardholderEmail',
       placeholder: 'E-mail'
     },
     cardNumber: {
       id: 'form-checkout__cardNumber-container',
       placeholder: 'Número de la tarjeta',
     },
     securityCode: {
       id: 'form-checkout__securityCode-container',
       placeholder: 'Código de seguridad'
     },
     installments: {
       id: 'form-checkout__installments',
       placeholder: 'Cuotas'
     },
     expirationDate: {
       id: 'form-checkout__expirationDate-container',
       placeholder: 'Data de vencimiento (MM/YYYY)',
     },
     identificationType: {
       id: 'form-checkout__identificationType',
       placeholder: 'Tipo de documento'
     },
     identificationNumber: {
       id: 'form-checkout__identificationNumber',
       placeholder: 'Número de documento'
     },
     issuer: {
       id: 'form-checkout__issuer',
       placeholder: 'Banco emisor'
     }
   },
   callbacks: {
     onFormMounted: function (error) {
       if (error) return console.log('Callback para tratar o erro: montando o cardForm ', error)
     },
     onSubmit: function (event) {
       event.preventDefault();
 
       const {
         paymentMethodId: payment_method_id,
         issuerId: issuer_id,
         cardholderEmail: email,
         amount,
         token,
         installments,
         identificationNumber,
         identificationType
       } = cardForm.getCardFormData();
 
        fetch('/process_payment', {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            token,
            issuer_id,
            payment_method_id,
            transaction_amount: Number(amount),
            installments: Number(installments),
            description: 'product description',
            payer: {
              email,
              identification: {
                type: identificationType,
                number: identificationNumber
             }
           }
         })
       })
     },
     onFetching: function (resource) {
       console.log('fetching... ', resource)
       const progressBar = document.querySelector('.progress-bar')
       progressBar.removeAttribute('value')
 
       return () => {
         progressBar.setAttribute('value', '0')
       }
     }
   }
 });

La opción de callbacks acepta diferentes funciones que son activadas en diversos momentos del flujo.

Referencia técnica
Conoce más información sobre los callbacks en las referencias técnicas .

Al realizar el envío del formulario, generamos un token como una representación segura de los datos de la tarjeta. Podrás a acceder a este token utilizando la función getCardFormData, como mostramos en el ejemplo anterior en el callback onSubmit. También guardaremos el token en un input oculto dentro de tu formulario que denominaremos MPHiddenInputToken.

Importante
Ten en cuenta que el token tiene una validez de 7 días y solo se pueda usar una vez.

Envía el pago a Mercado Pago

Server-Side

Para continuar el proceso de pago hacia Mercado Pago, es necesario que tu backend sepa recibir la información del formulario con el token generado y los datos completados.

Según el ejemplo dado, tu backend debería disponibilizar un endpoint /process_payment, para recibir allí todos los datos luego de realizar la acción submit.

Ya estando en tu backend con toda la información recolectada, es momento de enviar la solicitud a Mercado Pago a través de nuestras APIs. Los campos mínimos requeridos a enviar son: token, transaction_amount, installments, payment_method_id y el payer.email.

Ten en cuenta que para que este paso funcione es necesario que configures tu clave privada y que para interactuar con nuestras APIs recomendamos utilizar la SDK oficial de Mercado Pago.

Encuentra el estado del pago en el campo status.

          
<?php
   require_once 'vendor/autoload.php';
 
   MercadoPago\SDK::setAccessToken("YOUR_ACCESS_TOKEN");
 
   $payment = new MercadoPago\Payment();
   $payment->transaction_amount = (float)$_POST['transactionAmount'];
   $payment->token = $_POST['token'];
   $payment->description = $_POST['description'];
   $payment->installments = (int)$_POST['installments'];
   $payment->payment_method_id = $_POST['paymentMethodId'];
   $payment->issuer_id = (int)$_POST['issuer'];
 
   $payer = new MercadoPago\Payer();
   $payer->email = $_POST['email'];
   $payer->identification = array(
       "type" => $_POST['identificationType'],
       "number" => $_POST['identificationNumber']
   );
   $payment->payer = $payer;
 
   $payment->save();
 
   $response = array(
       'status' => $payment->status,
       'status_detail' => $payment->status_detail,
       'id' => $payment->id
   );
   echo json_encode($response);
 
?>

Encuentra el estado del pago en el campo status.

          
 
var mercadopago = require('mercadopago');
mercadopago.configurations.setAccessToken("YOUR_ACCESS_TOKEN");
 
mercadopago.payment.save(req.body)
  .then(function(response) {
    const { status, status_detail, id } = response.body;
    res.status(response.status).json({ status, status_detail, id });
  })
  .catch(function(error) {
    console.error(error);
  });

Encuentra el estado del pago en el campo status.

          

PaymentClient client = new PaymentClient();

PaymentCreateRequest paymentCreateRequest =
   PaymentCreateRequest.builder()
       .transactionAmount(request.getTransactionAmount())
       .token(request.getToken())
       .description(request.getDescription())
       .installments(request.getInstallments())
       .paymentMethodId(request.getPaymentMethodId())
       .payer(
           PaymentPayerRequest.builder()
               .email(request.getPayer().getEmail())
               .firstName(request.getPayer().getFirstName())
               .identification(
                   IdentificationRequest.builder()
                       .type(request.getPayer().getIdentification().getType())
                       .number(request.getPayer().getIdentification().getNumber())
                       .build())
               .build())
       .build();

client.create(paymentCreateRequest);

Encuentra el estado del pago en el campo status.

          
require 'mercadopago'
sdk = Mercadopago::SDK.new('YOUR_ACCESS_TOKEN')
 
payment_data = {
 transaction_amount: params[:transactionAmount].to_f,
 token: params[:token],
 description: params[:description],
 installments: params[:installments].to_i,
 payment_method_id: params[:paymentMethodId],
 payer: {
   email: params[:email],
   identification: {
     type: params[:identificationType],
     number: params[:identificationNumber]
   }
 }
}
 
payment_response = sdk.payment.create(payment_data)
payment = payment_response[:response]
 
puts payment

Encuentra el estado del pago en el campo status.

          
using System;
using MercadoPago.Client.Common;
using MercadoPago.Client.Payment;
using MercadoPago.Config;
using MercadoPago.Resource.Payment;
 
MercadoPagoConfig.AccessToken = "YOUR_ACCESS_TOKEN";
 
var paymentRequest = new PaymentCreateRequest
{
   TransactionAmount = decimal.Parse(Request["transactionAmount"]),
   Token = Request["token"],
   Description = Request["description"],
   Installments = int.Parse(Request["installments"]),
   PaymentMethodId = Request["paymentMethodId"],
   Payer = new PaymentPayerRequest
   {
       Email = Request["email"],
       Identification = new IdentificationRequest
       {
           Type = Request["identificationType"],
           Number = Request["identificationNumber"],
       },
   },
};
 
var client = new PaymentClient();
Payment payment = await client.CreateAsync(paymentRequest);
 
Console.WriteLine(payment.Status);

Encuentra el estado del pago en el campo status.

          
import mercadopago
sdk = mercadopago.SDK("ACCESS_TOKEN")
 
payment_data = {
   "transaction_amount": float(request.POST.get("transaction_amount")),
   "token": request.POST.get("token"),
   "description": request.POST.get("description"),
   "installments": int(request.POST.get("installments")),
   "payment_method_id": request.POST.get("payment_method_id"),
   "payer": {
       "email": request.POST.get("email"),
       "identification": {
           "type": request.POST.get("type"), 
           "number": request.POST.get("number")
       }
   }
}
 
payment_response = sdk.payment().create(payment_data)
payment = payment_response["response"]
 
print(payment)

Encuentra el estado del pago en el campo status.

          
 
curl -X POST \
   -H 'accept: application/json' \
   -H 'content-type: application/json' \
   -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
   'https://api.mercadopago.com/v1/payments' \
   -d '{
         "transaction_amount": 100,
         "token": "ff8080814c11e237014c1ff593b57b4d",
         "description": "Blue shirt",
         "installments": 1,
         "payment_method_id": "visa",
         "issuer_id": 310,
         "payer": {
           "email": "test@test.com"
         }
   }'

Respuesta

json

{
   "status": "approved",
   "status_detail": "accredited",
   "id": 3055677,
   "date_approved": "2019-02-23T00:01:10.000-04:00",
   "payer": {
       ...
   },
   "payment_method_id": "visa",
   "payment_type_id": "credit_card",
   "refunds": [],
   ...
}
Conoce todos los campos disponibles para realizar un pago completo en las Referencias de API .

Mensajes de respuestas

Los posibles estados de un pago son:

payment-status

Para ayudar a mejorar la aprobación de tus pagos, es fundamental que puedas comunicar correctamente a tus clientes los resultados al realizar o crear un pago.

Esto ayudará a evitar casos de rechazos y contracargos en los casos de transacciones inicialmente aprobadas. Por ejemplo, permite que se puedan corregir los errores de carga de datos o ayudar a cambiar el medio de pago.

Te recomendamos usar los mensajes de respuesta y utilizar la comunicación sugerida en cada uno de los casos.

Nota

Recibe notificaciones de pago

Por último, es importante que estés siempre informado sobre la creación de nuevos pagos y las actualizaciones de sus estados. Por ejemplo si fueron aprobados, rechazados o si se encuentran pendientes.

Configura las notificaciones webhooks o notificaciones IPN.

Ejemplos descargables

Checkout API
Te dejamos ejemplos completos de integración para que puedas descargar al instante.

Navegá

Mercado Pago

Ayuda

País e idioma

Youtube

Suscribite a nuestro canal

Copyright © 1999-2022 MercadoLibre Perú S.R.L.