QR Payments in Point of Sale

Flow

Concepts

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

Objects

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

POS Object

{
    "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

{
    "external_reference": "internal reference id",
    "notification_url": "www.yourserver.com/endpoint",
      "items" :[{
        "title" : "Tacos",
        "currency_id" : "MXN",
        "unit_price" : 16.0,
        "quantity" : 4
      },{
        "title" : "Soda",
        "currency_id" : "MXN",
        "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

{
    "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

curl -X POST \
-H 'Authorization: Bearer ACCESS_TOKEN' \
https://api.mercadopago.com/pos \
-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

curl -X POST \
-H 'Authorization: Bearer ACCESS_TOKEN' \
https://api.mercadopago.com/mpmobile/instore/qr/COLLECTOR_ID/EXTERNAL_ID \
-d \
'{
    "external_reference": "internal id",
    "notification_url": "www.yourserver.com/endpoint",
      "items" :[{
        "title" : "Tacos",
        "currency_id" : "MXN",
        "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.

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

Refunds

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

Total refund

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

Parcial refund

curl -X POST \
-H 'Authorization: Bearer ACCESS_TOKEN' \
https://api.mercadopago.com/v1/payments/PAYMENT_ID/refunds \
-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.

Errors

Here you can find our error dictionary.

Reports

Consult the complete documentation about the Mercado Pago reports.