Pagos QR en Punto de Venta

Primero debes familiarizarte con los siguiente conceptos ya que los usarás durante la integración.

Además de los conceptos anteriores, también debes conocer los objetos con los que trabajaremos.

{
    "name":"Caja Principal",
    "fixed_amount": true,
    "category": 621102,
    "store_id": "123456",
    "external_id": "4lph4num3r1c"
}

Definiciones

• name: Nombre descriptivo. Es un String de hasta 45 caracteres.
• external_id: es el identificador único del punto de venta. Es un código alfanumérico definido por ti, no puede contener espacios ni caracteres especiales y no se distinguen las mayúsculas de las minúsculas. Es un String de hasta 40 caracteres.
• category : Código MCC que indica el rubro del punto de venta. Los valores posibles son
  • Gastronomía Argentina: 621102
  • General: null
• store_id: Es un número identificador de la sucursal a la que pertenece el punto de venta. El el id del Store.
• fixed_amount: Indica si el usuario podrá ingresar algún monto al leer el QR o tendrá que esperar a que esté una orden disponible. Es un booleano.

{
    "external_reference": "id de transacción interno",
	"notification_url": "www.yourserver.com/endpoint",
      "items" :[{
        "title" : "Tacos",
        "currency_id" : "CLP",
        "unit_price" : 16.0,
        "quantity" : 4
      },{
        "title" : "Refresco",
        "currency_id" : "CLP",
        "unit_price" : 15.0,
        "quantity" : 1
      }]
}

Definiciones

• external_reference: String alfanumérico para uso externo, normalmente es el número de ticket o de pedido.
• notification_url: URI donde se enviará vía POST la notificación de pago.
• items: Arreglo de hashes de productos a comprar.
  • title: Título del producto.
  • currency_id: Identificador de moneda en formato ISO_4217.
  • unit_price: Precio unitario (máximo 2 decimales).
  • quantity: Cantidad del producto.

{
    "id": 420101010101,
    "external_reference": "id de transacción interno",
    "status": "approved",
    "status_detail": "accredited",
    ...
}

Definiciones

• id: Id único generado por Mercado Pago (lo necesitarás para realizar devoluciones).

• external_reference: Mismo string alfanumérico que añadiste al crear la orden.

• status: Estatus del pago.

  • approved: El pago fue aprobado y acreditado.

  • rejected: El pago fue rechazado. El usuario podría reintentar el pago.

  • refunded: El pago fue devuelto al usuario.

  • charged_back: Se ha realizado un contracargo en la tarjeta de crédito del comprador.

• status_detail: Información detallada del estado actual o el motivo de rechazo.

Consultar la documentación completa sobre este objeto en nuestra Referencia API.

Deberás crear un código QR para cada caja con un external_id que identifique la misma.

API de creación de QRs

curl -X POST \
-H 'Authorization: Bearer ACCESS_TOKEN' \
https://api.mercadopago.com/pos \ 
-d \
'{
    "name":"Caja Principal",
    "fixed_amount": true,
    "category": 621102,
    "store_id": "123456",
    "external_id": "4lph4num3r1c"
}'

Para realizar un cobro a través de un código QR de Mercado Pago deberás crear una orden con el detalle del cobro pendiente.

API de creación de órdenes

curl -X POST \
-H 'Authorization: Bearer ACCESS_TOKEN' \
https://api.mercadopago.com/mpmobile/instore/qr/COLLECTOR_ID/EXTERNAL_ID \
-d \
'{
    "external_reference": "id de transacción interno",
	"notification_url": "www.yourserver.com/endpoint",
      "items" :[{
        "title" : "Tacos",
        "currency_id" : "CLP",
        "unit_price" : 16.0,
        "quantity" : 4
      }]
}'

La orden expira a los 10 minutos de ser creada y automáticamente al ser pagada. Si se desea un tiempo de expiración diferente, puedes enviar el header X-Ttl-Store-Preference con el tiempo deseado en segundos.

Por ejemplo si deseas que esté disponible durante 5 minutos se debe enviar el header 'X-Ttl-Store-Preference: 300'. Hay que tener presente que si una persona paga esa orden antes del tiempo configurado, expirará.

Luego de que el usuario realiza el pago podrás obtener los datos usando cualquiera de las siguientes formas:

1. IPN: Cuando el pago es creado, enviamos una notificación vía webhook a la URL configurada en la notification_url de la orden, deberás estar suscrito a las notificaciones tipo merchant_order.
2. Hacer la búsqueda del pago utilizando el external_reference como criterio de búsqueda.

Si quieres eliminar la orden asociada a un QR antes de que expire el tiempo (X-Ttl-Store-Preference) o sea pagada.

curl -X DELETE \
-H 'Authorization: Bearer ACCESS_TOKEN' \
https://api.mercadopago.com/mpmobile/instore/qr/COLLECTOR_ID/EXTERNAL_ID

Habrán ocasiones en las que necesitarás realizar una devolución parcial o total de un pago.

Devolución total

curl -X POST \
-H 'Authorization: Bearer ACCESS_TOKEN' \
https://api.mercadopago.com/v1/payments/PAYMENT_ID/refunds

Devolución parcial

curl -X POST \
-H 'Authorization: Bearer ACCESS_TOKEN' \
https://api.mercadopago.com/v1/payments/PAYMENT_ID/refunds \
-d '{ "amount": 10.50 }'

Se deben crear dos usuarios de prueba: uno comprador y otro cobrador. Con el usuario cobrador se debe crear el QR y con el otro ingresar en las apps de Mercado Pago o Mercado Libre.

Consultar los datos de prueba: usuarios de prueba y tarjetas de prueba que se pueden utilizar.

Aquí podrás encontrar nuestro diccionario de errores.

Consultar la documentación completa sobre los reportes de Mercado Pago.