QR Payments in Point of Sale

Flow

Payment flow with QR at the point of sale Mercado Pago

Concepts

First, you must familiarize yourself with the following concepts since you will use them during the integration.

Attribute Description
ACCESS_TOKEN It is the access token of the Mercado Pago account to which the charges will be credited.
COLLECTOR_ID It is the user number of the Mercado Pago account, it is the last 9 digits of your access_token, after the middle script.

Objects

In addition to the previous concepts, you must also know the objects with which we will work.

POS Object

Json

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

Definitions

  • name: Descriptive name. It is a String of up to 45 characters.
  • external_id: It is the unique identifier of the point of sale. It is an alphanumeric code defined by you, it can not contain spaces or special characters and uppercase letters are not case sensitive. It is a String of up to 40 characters.
  • category : MCC code that indicates the point of sale item. The possible values are:
    • Gastronomy (Argentina): 621102
    • General: null
  • store_id: It is an identifier number of the branch to which the point of sale belongs. The id of the Store.
  • fixed_amount: Indicates if the user can enter any amount when reading the QR or will have to wait for an order to be available. It is a boolean.

Order Object

Json

{
    "external_reference": "internal reference id",
    "notification_url": "www.yourserver.com/endpoint",
      "items" :[{
        "title" : "Tacos",
        "currency_id" : "COP",
        "unit_price" : 16.0,
        "quantity" : 4
      },{
        "title" : "Soda",
        "currency_id" : "COP",
        "unit_price" : 15.0,
        "quantity" : 1
      }]
}

Definitions

  • external_reference: Alphanumeric string for external use, it is usually the ticket or order number.
  • notification_url: URI where the payment notification will be sent via POST.
  • items: Array of hashes of products to buy.
    • title: Item title.
    • currency_id: Currency id using ISO_4217 format.
    • unit_price: Unit price (maximum 2 decimals).
    • quantity: Product quantity.

Objeto Payment

Json

{
    "id": 420101010101,
    "external_reference": "internal id",
    "status": "approved",
    "status_detail": "accredited",
    ...
}

Definitions

  • id: Unique ID generated by Mercado Pago (you will need it to make refunds).

  • external_reference: Same alphanumeric string that you added when creating the order.

  • status: Payment status.

    • approved
    • rejected
    • refunded
    • charged_back
  • status_detail: Detailed information about the current status or the reason for rejection.

Consult the full documentation about this object in our API Reference.

Payments

Create QR

You must create a QR code for each POS with an external_id that identifies it.

API QR

Bash

curl -X POST https://api.mercadopago.com/pos?access_token=ACCESS_TOKEN -d
'{
    "name":"Principal POS",
    "fixed_amount": true,
    "category": 621102,
    "store_id": "123456",
    "external_id": "4lph4num3r1c"
}'

Order Creation

To create a payment through a QR code you must create an order with the detail of the pending payment.

API Orders

Bash

curl -X POST https://api.mercadopago.com/mpmobile/instore/qr/COLLECTOR_ID/EXTERNAL_ID?access_token=ACCESS_TOKEN -d
'{
    "external_reference": "internal id",
    "notification_url": "www.yourserver.com/endpoint",
      "items" :[{
        "title" : "Tacos",
        "currency_id" : "COP",
        "unit_price" : 16.0,
        "quantity" : 4
      }]
}'

The order expires 10 minutes after being created and automatically when paid. If a different expiration time is desired, you can send the header X-Ttl-Store-Preference with the desired time in seconds.

For example, if you want it to be available for 5 minutes you should send the header '' X-Ttl-Store-Preference: 300'`. Keep in mind that if a person pays that order before the set time, it will expire.

Get payment

After the user makes the payment you can obtain the data using any of the following ways:

  1. IPN: When the payment is created, we send a notification via webhook to the URL configured in the notification_url of the order, you will need to be subscribed to merchant_order's type notifications.
  2. Do the payment search using the external_reference as the search criteria.

Delete order

If you want to delete the order associated with a QR before the time expires (X-Ttl-Store-Preference) or be paid.

Bash

curl -X DELETE https://api.mercadopago.com/mpmobile/instore/qr/COLLECTOR_ID/EXTERNAL_ID?access_token=ACCESS_TOKEN

Refunds

There will be times when you will need to do a partial or total refund.

Total refund

Bash

curl -X POST https://api.mercadopago.com/v1/payments/PAYMENT_ID/refunds?access_token=ACCESS_TOKEN

Parcial refund

Bash

curl -X POST https://api.mercadopago.com/v1/payments/PAYMENT_ID/refunds?access_token=ACCESS_TOKEN -d '{ "amount": 10.50 }'

Testing

Two test users must be created: one buyer and another collector. With the billing user, the QR must be created and with the other, enter the Mercado Pago or Mercado Libre apps.

Consult the test data: test users and test cards that can be used.

Test cases Expected response
The user scans a valid QR code before placing the order. The app does not display an order.
The user scans a QR code with invalid parameters, meaning that it refers to a nonexistent account. The app reports that an error has occurred.
The user scans a valid code, once the order has been placed and the sales order has been created. La app muestra la orden.
The user generates an approved payment. The POS system receives the information of an approved payment.
The user generates an rejected payment. The POS system receives the information of an rejected payment.
A return of a payment is made from the POS. The return is impacted in the buyer's account.

Errors

Here you can find our error dictionary.

Reports

Consult the complete documentation about the Mercado Pago reports.

La búsqueda no arrojó ningún resultado.

Verifica la la ortografía de los términos de búsqueda o prueba con otras palabras clave.