QR Payments in Gas Stations

1. The user scans the QR code from the Mercado Pago or Mercado Libre app. The QR contains your POS_ID with the information of the position where the sale was made.

2. Our server consults your server for the last pending sale for that position in that branch.

3. Our server searches for the last outstanding order and, if it exists, return the order body.

4. Your server returns the order to our server and we create the purchase order on the user's smartphone.

5. The user follows the purchase flow and confirms the payment.

6. Immediately after the payment is processed, we send to your server a notification INP informing that there is a novelty.

7. With the payment identifier, you can search the payment and continue with your internal processes.

   If the status is approved, the payment must be accredited. On the other hand, if it is rejected, the app will retry the payment requesting another means of payment.

8. That is all! Inform your customer that the payment was processed correctly.

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

Within to the previous concepts, you must also know the objects with which we gonna work.

{
    "name":"Pump 1",
    "external_id": "pos_1",
    "category": 473000,
    "store_id": "123456",
    "url": "api.integration.com?apies=1&pos=1"   
}

Definitions

• name: 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 cannot contain spaces or special characters and uppercase letters are not case sensitive. A string of up to 40 characters.
• category : MCC code of the POS. The possible values are
  • Gastronomy: 621102
  • Gas Station: 473000
  • General: null
• store_id: It is an identifier number of the branch where the POS belongs. The id of the Store.
• url: Server URL of the management system that returns the pump data of a specific station.

{
   "collector_id": 178106235,
   "sponsor_id": 334249281,
   "items":[
      {
         "title":" $500.00 Premium",
         "currency_id": "PEN",
         "description":"$500.00 Premium",
         "quantity": 1.0,
         "unit_price": 500.00
      }
   ],
   "external_reference":"internal id",
   "notification_url":"https://www.mycompany.com/notification",
   "loyalty":{
      "program":"payback",
      "transaction_id":"45ea80da",
      "invoice_number":"3592",
      "transaction_date":"2018-09-21T12:33:13.000+00:00",
      "transaction_amount":500.00,
      "store_id":"802",
      "products":[
         {
            "code":"1",
            "quantity":1.0,
            "unit":"litre",
            "unit_price":500.00
         }
      ],
      "cashier_identification":{
         "type":"INE",
         "number":"00000000"
      },
      "period":"0000",
      "shift":"1",
      "affinity_plan":"7"
   }
}

Definitions

• collector_id: Long. Identifier of the MercadoPago account where the payments will be accredited.
• sponsor_id: Long. Identifier of a Mercado Pago account that develops the solution.
• external_reference: String. Reference to synchronize with your system.
• notification_url: String. URL that will receive the notifications sent, defined by the developer.
• items: Array. List of products, where each item is an object with the following fields:
  • title: String. Product name.
  • quantity: Integer.
  • unit_price: Decimal.
• loyalty: Objeto. Data needed to score points in a specific loyalty program:
  • program: String. Loyalty program (serviclub, payback, etc.)
  • transaction_id: String.
  • invoice_number: String.
  • transaction_date: String with ISO 8601 format.
  • transaction_amount: Decimal. Total amount.
  • store_id: String. Unique identifier of the business (identifier of the service station or APIES).
  • products: Array. List of products purchased with the following attributes
    • code: String. Product code.
    • quantity: Integer or decimal.
    • unit_price: Decimal.
    • unit: String. Metric unit.
  • cashier_identification: Object. Employee data.
    • type: String. Document type.
    • number: String. ID number.
  • period: String. Period number.
  • shift: String. Shift number.
  • affinity_plan: String.

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

Definitions

• id: Unique ID generated by Mercado Pago (you will need it to refund a payment).

• 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.

It is necessary that you have a URL in your management software that returns the pump data of a certain station. Also, should contain the additional parameters that are desired in the query (APIES of the station, supplier or pump identifier, etc.). For example: https://www.mycompany.com/pay-mp?apies=6232&pos=1

This URL (or endpoint) should return the information with which the body order where we will create the QR.

We recommend using the external_reference attribute to be able to associate the order (and its eventual payment) with the purchase. It is an alphanumeric code of up to 256 characters defined by the developer, cannot contain spaces or special characters and is not case sensitive.

If your system has a loyalty program, you must add the loyalty hash that provides the necessary information to credit the points to the buyer once the payment is approved.

The expected response of this endpoint contains the header Content-Type: application/json and should respond with anHTTP 200 (OK)status; In addition, you must include in the body a JSON corresponding to the order object.

In case of error, the URL should return a status code HTTP 400 (Bad Request), and in the response body a JSON with the following format:

{
	"error": {
		"type": "XXX",
		"message": "YYYY"
	}
}

Definitions

The message is optional, corresponds to a plain text explanation of the cause of the problem.

Whether in the testing or production phase, you must inform the URL to Mercado Pago to set it up and start testing.

You must create a QR code for each POS with an url.

API QR

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

1. Receive 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.

There will be times when you will need to refund a payment totally or partially.

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 }'

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.

Here you can find our error dictionary.

Consult the complete documentation about the Mercado Pago reports.