QR Code Payments

QR codes (Quick Response Codes) are two-dimensional barcodes that facilitate quick and efficient transactions when scanned with a mobile device equipped with a camera. QR codes are widely used for digital payments, allowing business applications to process payments securely and efficiently.

Types of QR Codes Supported by Our API

Our API supports two main types of QR codes, each defined by the type of payment amount it supports:

• Open amount: QR codes of this category do not specify a preset payment amount. Instead, they require that the business applications enable their clients to input the payment amount themselves, in the currency of the QR code's country.

• Closed amount: This QR contains a fixed amount and all the necessary information to complete the payment immediately.

Payment Process Flow

The payment process begins when users scan a QR code with their digital wallet. This initiates a series of interactions primarily handled between the wallet and Depay. Upon receiving the scan data, the wallet forwards this information to Depay for analysis. This crucial step determines the type of QR code—whether it represents a fixed or an open amount.

If the QR code is of a fixed amount, Depay quickly sends back all necessary payment information to the wallet. However, the process requires additional input if it's an open amount QR. In this scenario, Depay asks the wallet to have the user specify the amount they wish to pay. This involves the user entering the amount into their wallet application, and relaying this information back to Depay.

Once the amount is set and sent to Depay, whether it was pre-determined or user-specified, the next step involves preparing for the payment execution. The wallet presents all finalized payment details to the user for approval. After the user authorizes the transaction, the confirmed details are again passed to Depay by the wallet.

Depay then processes the authorized payment and sends the results back to the wallet. To conclude the transaction, the wallet communicates the outcome to the user. This final notification confirms the successful completion of the payment, or in some cases, details any issues that may have occurred, ensuring transparency and clarity for the user.

Payment Process Flow

Statuses of an Order

Key	Description
WAITING_AMOUNT	When the QR amount is open, the order remains waiting until the amount is sent.
PROCESS_LATER	This order status will only apply in Argentina. It occurs with static QRs where the merchant is expected to enter the QR amount. If the merchant has not provided the amount by the time the QR is scanned, the system will return this status.
CREATED	The order has been created.
PROCESSING	The payment was accepted and is being processed.
COMPLETED	The payment was successfully completed.
CANCELED	The preview was not accepted by the user or it expired.
REFUNDED	The order has been refunded.
PARTIALLY_REFUNDED	The order was partially refunded.
REJECTED	The payment has been rejected by the destination bank account.
FAILED	The payment failed due to an unexepcted error.

Retrieve QR Code Preview

POST https://stage.api.payments.depay.us/v2/payments/previews

This endpoint allows retrieving information from a QR code that conforms to the EMVCo standard, ensuring its applicability in an international payment interoperability context. Upon receiving a QR code, the system queries the QR owner's Resolve API to obtain the necessary payment details. This service uses the same standard structure as the Resolve API, ensuring consistency and compatibility in handling payment information across various systems and countries.

Headers

Name	Type	Description
Authorization*	String	Bearer Token
idempotency-key	String	An idempotent identifier provided by the client to ensure that a request is processed only once.

Request Body

Name	Type	Description
qr*	String	QR information
external_reference*	String	The user-defined identifier used to link and track the payment. Length (max): 100.
notification_url*	String	The provided URL is a POST endpoint where QR information will be received. If the QR code has a closed amount, the preview details will be sent directly. However, if the QR code has an open amount, a request for the payment amount will be made, and the operation amount must be provided via the PUT /payments/previews endpoint. After that, the preview details will be received. Length (max): 250.
user*	String	User information
full_name*	String	User name and surname
currency*	String	Represents the default currency the user will use to make the payment. It must be provided in ISO 4217 format
account_number*	String	User account from which the user wishes to make the payment
tax_id*	String	User tax identification number. Length (max): 50.

Request Body Example

{
    "qr": "00020101021102080000000041370012com.98113069226478599020143160012B000004538315015001130707101020512600220000532607300067079179520454115802AR5916Test Homo COELSA6015CABA - Ciudad A6107M5515AP53023262100706S0279981050001I63042A58",
    "external_reference": "e8a7a740-6f47-11ec-90d6-0242ac120003",
    "notification_url": "https://payments.depay.us/payments/webhook/",
    "user": {
        "full_name": "Juan Pedro",
        "currency": "ARS",
        "account_number": "234200234",
        "tax_id": "20125548964"
    }
}

Response

This response is to confirm that the request has been made. There are two types of responses: one for the open_amount QR code, which asks for the amount, and another for the closed_amount QR code, which provides the preview directly. When the preview reaches a success or missing_amount status, it is linked to a newly created order and notified through the configured webhook.

Name	Type	Description
status	String	A key that indicates the current status of the preview. This is different from the order status. When the preview is created you will receive status: succes or missing_amount
external_reference	String	This is the reference sent in the request, allowing the requester to internally identify the payment being performed. Length (max): 100.
message	String	A brief description of the current payment status.
local_currency	String	Currency of QR code (ISO 4217 format).

201: OK Closed Amount

{
      "status": "success",
      "external_reference": "e8a7a740-6f47-11ec-90d6-0242ac120003",
      "message": "Preview is being processed.",
      "local_currency": "ARS"     
}

201: OK Open Amount

201: OK PROCESS_LATER

400: Bad Request

401: Unauthorized Permission Denied

409: Conflict Error

Preview Callback Response

This response will be sent to the callback (notification_url). There are two possible responses: one for the open_amount QR code, which asks for the amount, and another for the closed_amount QR code, which sends the preview directly.

Name	Type	Description
payment_type	String	Payment method you are using.
external_reference	String	Reference sent to allow the requester to internally identify the payment. Length (max): 100.
collector	Object	Information object about the merchant (seller). This information is only available for successful read cases.
name	String	Name of the merchant.
identification_number	String	Unique Tax Identification Code of the administrator.
branch_office	String	Internal merchant or branch office number. Can be empty.
order	Object	Information object about the order to be paid. This information is only available for successful read cases.
id	String	Identifier of the order. This data is necessary when initiating the payment of this QR.
status	String	A key that indicates the current status of the order.
local_total_amount	Decimal	The total amount in the currency of the QR code's country. If it is an open amount QR (status: open_amount), the value will be null.
local_currency	String	Currency of the QR code's country. (ISO 4217 format).
user_total_amount	Decimal	The local_total_amount is converted into the user's currency. If it is an open amount QR (status: open_amount), the value will be null.
user_currency	String	User's currency. (ISO 4217 format).
qr_type	String	Type of the QR you are working with.
version	String	Version of the API you are working with.

Callback Body Example - Closed Amount

{
    "payment_type":"QR_CODE",
    "external_reference": "e8a7a740-6f47-11ec-90d6-0242ac120003",    
    "collector": {
        "name": "DEPAY MARKET",
        "identification_number": "20314691769",
        "branch_office": ""
    },
    "order": { 
        "id": "cd17fff7-ed31-47b7-948f-9fdec0cda9ce",
        "status":"CREATED",
        "local_total_amount": 22,
        "local_currency": "BRL",
        "user_total_amount": 3669,
        "user_currency": "ARS"
    },
    "qr_type":"closed_amount",
    "version":"2.0"
}

Callback Body Example - Open Amount

{
    "order_id": "cd17fff7-ed31-47b7-948f-9fdec0cda9ce",
    "order_status": "WAITING_AMOUNT",
    "local_currency": "ARS",
    "status": "OK",
    "external_reference": "e8a7a740-6f47-22ec-88d6-0242ac120003",
    "collector": {
        "name": "DEPAY MARKET",
        "identification_number": "20314691769",
        "branch_office": ""
    },
}

When working with OPEN AMOUNT QR codes, you will receive the preview notification in the next step of the flow.

Send Amount Information to Pay a QR Code

PUT https://stage.api.payments.depay.us/v2/payments/previews

This endpoint is exclusively for QR codes designated as 'open_amount.' It requires users to specify the payment amount, in the currency of the QR code's country, they wish to process. Once the amount is provided, the endpoint handles the currency conversion, ensuring a clear and seamless approval process before finalizing the payment.

Headers

Name	Type	Description
Authorization*	String	Bearer Token
idempotency-key	String	An idempotent identifier provided by the client to ensure that a request is processed only once.

Request Body

Name	Type	Description
order_id*	String	Order id provided in the callback notification_url
amount*	Decimal	Total amount to be paid in the currency of the QR code's country.

Request Body Example

{
    "order_id":"cd17fff7-ed31-47b7-948f-9fdec0cda9ce",
    "amount": 1000
}

Response

200: OK

{
    "status": "success",
    "message": "Preview is being processed."
}

400: Bad Request

409: Conflict Error

Name	Type	Description
payment_type	String	Payment method you are using.
external_reference	String	Reference sent to allow the requester to internally identify the payment. Length (max): 100.
collector	Object	Information object about the merchant (seller). This information is only available for successful read cases.
name	String	Name of the merchant.
identification_number	String	Unique Tax Identification Code of the administrator.
branch_office	String	Internal merchant or branch office number. Can be empty.
order	Object	Information object about the order to be paid. This information is only available for successful read cases.
id	String	Identifier of the order. This data is necessary when initiating the payment of this QR.
status	String	A key that indicates the current status of the order.
local_total_amount	Decimal	The total amount in the currency of the QR code's country. If it is an open amount QR (status: open_amount), the value will be null.
local_currency	String	Currency of the QR code's country. (ISO 4217 format).
user_total_amount	Decimal	The local_total_amount is converted into the user's currency. If it is an open amount QR (status: open_amount), the value will be null.
user_currency	String	User's currency. (ISO 4217 format).
qr_type	String	Type of the QR you are working with.
version	String	Version of the API you are working with.

Callback Body Example - Send Amount

{
    "payment_type":"QR_CODE",
    "external_reference": "e8a7a740-6f47-11ec-90d6-0242ac120003",    
    "collector": {
        "name": "DEPAY MARKET",
        "identification_number": "20314691769",
        "branch_office": ""
    },
    "order": { 
        "id": "cd17fff7-ed31-47b7-948f-9fdec0cda9ce",
        "status":"CREATED",
        "local_total_amount": 22,
        "local_currency": "BRL",
        "user_total_amount": 3669,
        "user_currency": "ARS"
    }
    "qr_type":"open_amount",
    "version":"2.0"
}

Pay a QR Code

POSThttps://stage.api.payments.depay.us/v2/payments

This endpoint initiates a transaction process through the system. It requires information obtained after querying through the QR information retrieval endpoint. In some cases, the final payment result may be available immediately in response to this endpoint if the system processes the transaction quickly. However, the final payment result is not always immediate, so it may be necessary to wait a few seconds to obtain it. The result can be accessed via a webhook that notifies the QR payment event or by directly querying the operation status.

Headers

Name	Type	Description
Authorization*	String	Bearer Token
idempotency-key	String	An idempotent identifier provided by the client to ensure that a request is processed only once.

Request Body

Name	Type	Description
order_id*	String	Order identifier. This field corresponds to the id field within the order object retrieved from the QR information retrieval endpoint. Required.
status*	String	This field is the value of the user's decision. The accepted values are 'accepted' or 'rejected'
notification_url*	String	The URL where notifications about QR payments events will be sent. Required. Length (max): 250.

Request Body Example

{
  "order_id": "cd17fff7-ed31-47b7-948f-9fdec0cda9ce",
  "status": "accepted",
  "notification_url": "https://api.payments.depay.us/payments/webhook/"
}

Response

201: OK Successful operation

{
    "status": "PROCESSING",
    "message": "Payment in process."
}

401: Unauthorized Permission denied

Name	Type	Description
order_id	String	Identifier of the order. This data is necessary when initiating the payment of this QR.
external_reference	String	This is the reference sent in the QR preview request, allowing the requester to internally identify the payment. Length (max): 100.
external_reference_id	String	This is the reference sent in the QR preview request, allowing the requester to internally identify the payment. Length (max): 100.
status	String	A key that indicates the current status of the order.
date	String	Date and time when the notification is created. Format: YYYY-MM-DDTHH:MM:SSZ (ISO 8601).
payment_date	String or Null	Date and time when the payment was processed. Format: YYYY-MM-DDTHH:MM:SSZ (ISO 8601).
merchant_identification_number	String	Unique identifier assigned to the merchant by the payment processor.
merchant_name	String	Display name of the merchant associated with the transaction.
error_code	String or Null	Error code returned in case the payment fails. Null if the transaction was successful.

Callback Body Example - Payment PROCESSING

{
    "order_id":"cd17fff7-ed31-47b7-948f-9fdec0cda9ce",
    "external_reference":"e8a7a740-6f47-11ec-90d6-0242ac120003",
    "external_reference_id":"e8a7a740-6f47-11ec-90d6-0242ac120003",
    "status":"PROCESSING",
    "date":"2025-05-30T11:14:25.115Z",
    "payment_date":null,
    "merchant_identification_number":"11111111111",
    "merchant_name":"MERCHANT01",
    "error_code":null
}

Callback Body Example - Payment CANCELED

{
    "order_id":"cd17fff7-ed31-47b7-948f-9fdec0cda9ce",
    "external_reference":"e8a7a740-6f47-11ec-90d6-0242ac120003",
    "external_reference_id":"e8a7a740-6f47-11ec-90d6-0242ac120003",
    "status":"CANCELED",
    "date":"2025-05-30T11:14:25.115Z",
    "payment_date":null,
    "merchant_identification_number":"111111111",
    "merchant_name":"MERCHANT01",
    "error_code":"Order expired"
}

Callback Body Example - Payment REJECTED

{
    "order_id":"cd17fff7-ed31-47b7-948f-9fdec0cda9ce",
    "external_reference":"e8a7a740-6f47-11ec-90d6-0242ac120003",
    "external_reference_id":"e8a7a740-6f47-11ec-90d6-0242ac120003",
    "status":"REJECTED",
    "date":"2025-05-30T11:14:25.115Z",
    "payment_date":null,
    "merchant_identification_number":"20322678275",
    "merchant_name":"MERCHANT01",
    "error_code":"VENCIDO | 0200 - AVISO ENVIADO"
}

Callback Body Example - Payment FAILED

{
    "order_id":"cd17fff7-ed31-47b7-948f-9fdec0cda9ce",
    "external_reference":"e8a7a740-6f47-11ec-90d6-0242ac120003",
    "external_reference_id":"e8a7a740-6f47-11ec-90d6-0242ac120003",
    "status":"FAILED",
    "date":"2025-05-29T13:16:30.452Z",
    "payment_date":null,
    "merchant_identification_number":"111111111111",
    "merchant_name":"MERCHANT01",
    "error_code":"ACCOUNT_BLOCKED The specified account is blocked."
}

Callback Body Example - Payment COMPLETED

{
    "order_id":"cd17fff7-ed31-47b7-948f-9fdec0cda9ce",
    "external_reference":"e8a7a740-6f47-11ec-90d6-0242ac120003",
    "external_reference_id":"e8a7a740-6f47-11ec-90d6-0242ac120003",
    "status":"COMPLETED",
    "date":"2025-05-30T11:14:25.115Z",
    "payment_date":"2025-05-30T11:14:25.115Z",
    "merchant_identification_number":"20322678275",
    "merchant_name":"MERCHANT01",
    "error_code":null
}

QR Refund

The refund can be either partial or full, as specified in the request. Depay will send updates regarding the refund status — such as whether it was successful or rejected — to the notification_url previously provided in the body of the Payment Request. The refunded amount will be credited to your pre-funded account to ensure uninterrupted service.

Status	Description	Is Final
REFUNDED	The refund has been successfully completed.	Yes
PARTIALLY_REFUNDED	The partial refund has been successfully completed.	No

Headers

Name	Type	Description
idempotency-key	String	An idempotent identifier provided to ensure that a request is processed only once.

Webhook Notification

This notification will be sent to notification_url.

Name	Type	Description
order_id	String	Order identifier. This field corresponds to the id field within the order object retrieved from the QR information retrieval endpoint.
external_reference	String	This is the reference sent in the QR preview request, allowing the requester to internally identify the payment. Length (max): 100.
status	String	A key that indicates the current status of the order.
date	String	Date and time when the notification is created. Format: YYYY-MM-DDTHH:MM:SSZ (ISO 8601).
payment_date	String	Date and time when the payment was processed. Format: YYYY-MM-DDTHH:MM:SSZ (ISO 8601).
merchant_identification_number	String	Unique identifier assigned to the merchant by the payment processor.
merchart_name	String	Display name of the merchant associated with the transaction.
error_code	String or null	Error code returned in case the payment fails. Null if the transaction was successful.
amount	Number	Transaction amount to be paid by the user.
currency	String	ISO 4217 currency code representing the transaction currency (e.g., USD, EUR, BRL).

Total Refund Notification Body Example

{
    "order_id":"cd17fff7-ed31-47b7-948f-9fdec0cda9ce",
    "external_reference":"12345678-1234-1234-1234-123456789876",
    "status":"REFUNDED",
    "date":"2025-05-26T15:30:56.842Z",
    "payment_date":"2025-05-26T15:30:56.842Z",
    "merchant_identification_number":"321664897",
    "merchant_name":"Depay",
    "error_code":null,
    "amount":0.2,
    "currency":"BRL"
}

Partial Refund Notification Body Example

{
    "order_id":"cd17fff7-ed31-47b7-948f-9fdec0cda9ce",
    "external_reference":"12345678-1234-1234-1234-123456789876",
    "status":"PARTIALLY_REFUNDED",
    "date":"2025-05-26T15:30:56.842Z",
    "payment_date":"2025-05-26T15:30:56.842Z",
    "merchant_identification_number":"1111111111",
    "merchant_name":"Depay",
    "error_code":null,
    "amount":0.1,
    "currency":"BRL"
}

Get Payment Status

GET https://stage.api.payments.depay.us/v2/payments/{order_id}/status

Allows users to inquire about the current status of their payments.

Headers

Name	Type	Description
Authorization*	String	Bearer Token

Query Parameters

Name	Type	Description
order_id*	String	Order identifier. This field corresponds to the id field within the order object retrieved from the QR information retrieval endpoint. Required.

Response

200: OK Successful operation

{
    "id": "cd17fff7-ed31-47b7-948f-9fdec0cda9ce",
    "status": "COMPLETED",
    "creation_date": "2023-05-15T11:45:38.2678234+00:00",
    "update_date": "2023-05-15T11:45:38.2678234+00:00",
    "local_amount": "7",
    "local_currency": "ARS",
    "user_amount": "7",
    "user_currency": "ARS",
    "external_reference": "123123123",
    "statuses":[
        {
            "status": "WAITING_AMOUNT",
            "created_at": "2024-11-01 20:01:30.948423"
        },
        {
            "status": "CREATED",
            "created_at": "2024-11-01 20:01:50.567650"
        },
        {
             "status": "COMPLETED",
            "created_at": "2024-11-01 20:02:00.343641"
        }
    ]
}

401: Unauthorized Premission Denied