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