How to integrate with Mercado Pago QR Code

[italopessoa]

Integrating Mercado Pago QR Code Payments

This guide provides a comprehensive overview of how to integrate with Mercado Pago QR code payments.

PUT https://api.mercadopago.com/instore/orders/qr/seller/collectors/{{user_id}}/pos/:pos_id/qrs

{
    "description": "order description",
    "expiration_date": "2024-06-03T20:05:00.000-03:00",
    "external_reference": "{EXTERNAL_ORDER_REFERENCE_ID}",
    "items": [
        {
            "sku_number": "A123K9191938",
            "category": "dessert",
            "title": "Coxinha",
            "description": "1 coxinha",
            "unit_price": 0.01,
            "quantity": 1,
            "unit_measure": "unit",
            "total_amount": 0.01
        }
    ],
    "notification_url": "{NOTIFICATION_WEBHOOK_URL}",//your webhook url
    "title": "order title",
    "total_amount": 0.01
}

webhook order created payload payload

The system will receive a notification about the newly created merchant order via webhook.

POST {NOTIFICATION_WEBHOOK_URL}?id={MERCHANT_ORDER_ID}&topic=merchant_order

{
  "resource": "https://api.mercadolibre.com/merchant_orders/{MERCHANT_ORDER_ID}",
  "topic": "merchant_order"
}

it can be used to query merchant_order details and get the the external_reference_id
use external_reference_id to find the current order on the system and save the association

GET https://api.mercadolibre.com/merchant_orders/{MERCHANT_ORDER_ID}

    var client = new MerchantOrderClient();
    var merchantOrder = client.Get(MERCHANT_ORDER_ID, new RequestOptions()
    {
        AccessToken = _accessToken
    });

"order_status": "payment_required" is the value we're looking for, use this to update the order status

{
    "id": {MERCHANT_ORDER_ID},
    "status": "opened",
    "external_reference": "{EXTERNAL_ORDER_REFERENCE_ID}",
    "payments": [],
    ...
    "items": [
        ...
    ],
    "cancelled": false,
    ...
    "order_status": "payment_required",
    ...
}

Payment notifications

The messages below will be triggered as soon as you make the payment on your bank account.

POST {NOTIFICATION_WEBHOOK_URL}?id={PAYMENT_ID}&topic=payment

{
  "resource": "https://api.mercadolibre.com/collections/notifications/{PAYMENT_ID}",
  "topic": "payment"
}

POST {NOTIFICATION_WEBHOOK_URL}?data.id={PAYMENT_ID}&type=payment

{
  "action": "payment.created",
  "api_version": "v1",
  "data": {
    "id": "{PAYMENT_ID}"
  },
  "date_created": "2024-06-03T23:01:13Z",
  "date_updated": "2024-06-03T23:01:13Z",
  "id": ********,
  "live_mode": true,
  "type": "payment",
  "user_id": "USER_ID"
}

merchant order updated webhook payload

POST {NOTIFICATION_WEBHOOK_URL}?id={MERCHANT_ORDER_ID}&topic=merchant_order

{
  "resource": "https://api.mercadolibre.com/merchant_orders/{MERCHANT_ORDER_ID}",
  "topic": "merchant_order"
}

when using the sdk to get the details the order_status is changed to paid

{
    "id": {ORDER_ID},
    "status": "closed",
    "external_reference": "{EXTERNAL_ORDER_REFERENCE_ID}",
    "payments": [
        {
            "id": 79704717558,
            "transaction_amount": 0.01,
            "total_paid_amount": 0.01,
            "shipping_cost": 0,
            "currency_id": "BRL",
            "status": "approved",
            "status_detail": "accredited",
            "operation_type": "regular_payment",
            "date_approved": "2024-06-03T14:56:55.000-04:00",
            "date_created": "2024-06-03T14:56:55.000-04:00",
            "last_modified": "2024-06-03T14:56:55.000-04:00",
            "amount_refunded": 0
        }
    ],
    "order_status": "paid",
}

Important

All requests must be verified. Check more details about how to validate webhook requests' origin

This is one way of validating whether the payment was accepted. might not be the more accurate but I'm going for simplicity on this first investigation.

[italopessoa]

header used to identify where the message comes from:
https://www.mercadopago.com.br/developers/en/docs/your-integrations/notifications/webhooks

[italopessoa]

website used for webhook integration testing https://webhook.site/

[italopessoa]

https://discord.com/channels/1078660903450464286/1247303239284559933/1247303239284559933

[italopessoa]

After some more investigation I figured there's another way to do the integration and that might fit better for my needs on the flow I'm planning for the application.

The steps I listed above is useful when you're integration with local stores. Which is in fact what this app is supposed to do, a self checkout totem. The problem with that approach is that I don't know in advance the payment Id to update on my system bringing some more complexity to the code since I'd have to filter events and fetch the payment Id if I really want it or could do less and only use the merchant order status and that's it.

Only wen I found this thread on MercadoPago discord server I realized the solution was right there.

you can create a Payment and set the payment method as pix this will create the QRCode for you and return the PaymentId which for integration purposes that's exactly what I need.

• Create Payment
• Save Payment Id on the database
• Return QRCode
• User executes the payment
• Webhook receives message with Payment Information
• Validate webhook hmac signature
• Get Payment by id
• Update Payment status on database