# QR

In the Depay ecosystem, **QR codes** are a powerful tool for enabling international payments. Each **QR code** generated represents a "sales order" with all the necessary transaction information, including the specific payment amount, currency, and store details. Customers simply provide the essential purchase details, and Depay generates an interoperable **QR code** that can be used across borders. This makes it easier for merchants to accept payments from customers with local wallets, ensuring a seamless and secure payment experience without any complexity for the user.

## QR Payments Flow

When a user wants to make a purchase in a different country, the merchant sends the purchase details to their local Payment Service Provider (PSP). The PSP forwards the request to Depay, which calculates the currency conversion and generates a QR code compatible with the user's currency. The merchant presents the QR code to the customer, who scans it, accepts the conversion, and completes the payment. Once the payment is credited, Depay notifies the PSP via a webhook, who in turn informs the merchant of the payment outcome.

This process provides a seamless and cross-border payment experience, allowing customers to pay in their local currency while ensuring merchants receive funds in theirs, thus simplifying international transactions for all parties involved.

<figure><img src="https://2097770310-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7SNWmdpaEP4mpq9N9KRP%2Fuploads%2FAVSI42znfhvBbtSQFn55%2FLatam-Payments-Secuence.png?alt=media&#x26;token=e3c32dd1-60bb-4124-b3f9-fc446e69775e" alt=""><figcaption></figcaption></figure>

### **Statuses of a Payment** <a href="#statuses-of-a-payment" id="statuses-of-a-payment"></a>

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

## Create a new QR for a Point of Sales

<mark style="color:green;">`POST`</mark> `https://stage.api.payments.depay.us/v2/qr`

This endpoint allows you to create a new QR code for a specific point of sale (POS) and payment amount. By providing the necessary details, such as the POS identifier, local amount, and currencies, a QR code will be generated to facilitate the payment process. Once the QR code is scanned and the payment is either successfully completed or rejected, a notification will be sent to the provided "notification\_url", keeping the customer updated on the status of the transaction. This enables a seamless cross-border payment experience.

#### Headers

<table><thead><tr><th width="206">Name</th><th width="132">Type</th><th>Description</th></tr></thead><tbody><tr><td>Authorization<mark style="color:red;">*</mark></td><td>String</td><td>Bearer Token</td></tr></tbody></table>

#### Request Body

<table><thead><tr><th width="237">Name</th><th width="133">Type</th><th>Description</th></tr></thead><tbody><tr><td>local_currency<mark style="color:red;">*</mark></td><td>String</td><td>Represents the default currency of the merchant’s country. It must be provided in ISO 4217 format</td></tr><tr><td>local_country<mark style="color:red;">*</mark></td><td>String</td><td>Merchant’s country. It must be provided in ISO 3166-1 alpha-2 format (e.g., "AR" for Argentina).</td></tr><tr><td>qr_from<mark style="color:red;">*</mark></td><td>String</td><td>Represents the country of origin of the QR by its country code. It must be provided in ISO 3166-1 alpha-2 format (e.g., "AR" for Argentina).</td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td>Decimal</td><td>The total amount in the currency of the merchant’s currency.</td></tr><tr><td>pos_external_reference<mark style="color:red;">*</mark></td><td>String</td><td>The identifier of the point of sale (POS) used when associating a POS to a store during the merchant onboarding process.</td></tr><tr><td>external_reference<mark style="color:red;">*</mark></td><td>String</td><td>The identifier used to link and track the operation.</td></tr><tr><td>notification_url<mark style="color:red;">*</mark></td><td>String</td><td>The provided URL is a POST endpoint used to receive notifications about changes in the payment status.</td></tr><tr><td>tax_id</td><td>String</td><td>Merchant tax identification number</td></tr><tr><td>items</td><td>Object</td><td>Items of the order</td></tr><tr><td>   sku_number</td><td>String</td><td>Unique Identifier of the item</td></tr><tr><td>   category</td><td>String</td><td>Category of the item</td></tr><tr><td>   name</td><td>String</td><td>Name of the item</td></tr><tr><td>   quantity</td><td>Decimal</td><td>Quantity of purchased items</td></tr><tr><td>   unit_price</td><td>Decimal</td><td>Unit price of the item</td></tr><tr><td>   total_amount</td><td>Decimal</td><td>Total amount of the purchased item</td></tr></tbody></table>

<details>

<summary>Request Body Example</summary>

```json
{
    "local_currency": "BRL",
    "local_country": "BR",
    "qr_from": "AR",
    "amount": 10,
    "pos_external_reference":"ABC1s23",
    "external_reference": "ref_qr_1738847080464_uxv7qyvixc",
    "notification_url": "https://webhook.site/82457e1d-8d96-4d00-8ef9-3df6c62a4950",
    "tax_id": "123456789"     
}
```

</details>

{% tabs %}
{% tab title="201: Created QR created" %}

```json
{   
    "status": "success",  
    "order_id": "7478bd70-87ad-49d0-9143-9b148d776fc7",  
    "qr_data": "00020101021102080000000041370012com.TEST98113069226478599020143160012B000004551965015001130707101020512600220000531909000067076630520454115802AR5918GRANJAS CARNAVE SA6012BUENOS AIRES61041000530303262100706S0282581050001Z63040F00",
    "message": "QR generated successfully.",
    "user_amount": 2883.9085042893075,
    "user_currency": "ARS",
    "exchange_rate": 0.0035
}
```

{% endtab %}

{% tab title="400: Bad Request" %}

```json
{
    "statusCode": 400,
    "message": [
        "notification_url is required"
    ]
}
```

{% endtab %}

{% tab title="401: Unauthorized Permission Denied" %}

```json
{   
    "statusCode": 401,
    "message": "Unauthorized"
}
```

{% endtab %}

{% tab title="409: Conflict Error creating QR" %}

```json
{
    "statusCode": 409,
    "message": "Conflict error"
}
```

{% endtab %}
{% endtabs %}

### QR creation Callback Response

This response will be sent to the callback `(notification_url)`.

```json
{
  "order_id": "7478bd70-87ad-49d0-9143-9b148d776fc7",
  "external_reference": "ref_qr_1738847080464_uxv7qyvixc",
  "order_status": "CREATED",
  "local_amount": 10,
  "local_currency": "BRL",
  "user_amount": 2139.1682999216637,
  "user_currency": "ARS",
  "exchange_rate": 0.0035,
  "qr_code": "00020101021102080000000041370012com.TESTbind98114668759911499020143360032B00000515988OD000002114079ETA0545015001120322678275512600220000531905054067220517520457345802AR5905Depay6014CABA - Almagro6108C1006ACT530303262100706S1740981080004A0546304924D"
}
```

### QR Expiration Time

A QR code will expire **10 minutes** after its creation in both **Stage** and **Production** environments.

### **How can we simulate QR authorization in the Stage environment?**

To simulate QR authorization in the Stage environment:

**Closed QR codes**, the final digit of the amount determines the simulated response:

* If the amount ends in **9**, the QR will return status: **FAILED**.
* If the amount ends in **8**, it will return status: **CREATED**, followed by **CANCELED**.
* For any other ending digit (not 8 or 9), the QR will return status: **COMPLETED**.

**Examples:**

* `amount: 1000` → **COMPLETED**
* `amount: 1008` → **CREATED** then **CANCELED**
* `amount: 1009` → **FAILED**

## Cancel an existing QR

<mark style="color:red;">`DELETE`</mark> `https://stage.api.payments.depay.us/v2/payins/qr/{order_id}`

This endpoint allows you to cancel an existing QR code for a given point of sale (POS) identifier. By using this DELETE method, the corresponding QR code is invalidated, and any **Pending Payment** requests are effectively canceled.

#### Query Parameters

| Name                                        | Type   | Description       |
| ------------------------------------------- | ------ | ----------------- |
| order\_id<mark style="color:red;">\*</mark> | string | Uuid of the order |

#### Headers

| Name                                             | Type   | Description  |
| ------------------------------------------------ | ------ | ------------ |
| Authentication<mark style="color:red;">\*</mark> | String | Bearer Token |

{% tabs %}
{% tab title="200: OK Successful operation" %}

{% endtab %}

{% tab title="401: Unauthorized Permission denied" %}

```json
{
    "statusCode": 401,
    "message": "Unauthorized"
}
```

{% endtab %}

{% tab title="404: Not Found" %}

```json
{
    "statusCode": 404,
    "message": "ORDER_NOT_FOUND"
}
```

{% endtab %}

{% tab title="409: Conflict" %}

```json
{
    "statusCode": 409,
    "message": "The order has already been canceled."
}
```

{% endtab %}
{% endtabs %}

## QR Expiration Notification

If a QR code is canceled due to 10 minutes passing since its creation, you will receive the following notification:

```json
{
    "order_id": "7478bd70-87ad-49d0-9143-9b148d776fc7",
    "type": "PAYMENT",
    "status": "CANCELED",
    "message": "New payment status: canceled. Order Expired",
    "external_reference": "ref_qr_1738847080464_uxv7qyvixc"
}
```

## QR Payment Notification

When a QR code is successfully paid, you will receive the following notification:

```json
{
    "order_id": "7478bd70-87ad-49d0-9143-9b148d776fc7",
    "type": "PAYMENT",
    "status": "COMPLETED",
    "message": "Payment acreditado",
    "external_reference": "ref_qr_1738847080464_uxv7qyvixc",
    "user_tax_id": "304658985",
    "user_account": "31111111111111111112"
}
```

## QR Refund

<mark style="color:green;">`POST`</mark> `https://stage.api.payments.depay.us/v2/qr/refund`

This endpoint allows you to request a refund for an existing QR payment using the order identifier. The refund can be either partial or full, as specified in the request.  Additionally, a `notification_url` must be provided, where Depay will send updates regarding the refund status, such as whether it was successful or rejected.

| Status               | Description                                                                                         | Is Final |
| -------------------- | --------------------------------------------------------------------------------------------------- | -------- |
| `PENDING`            | The refund is still being processed.                                                                | No       |
| `REJECTED`           | The refund encountered an error.                                                                    | No       |
| `PARTIALLY_REFUNDED` | The funds have been deducted from the merchant, but the refund to the customer is not yet complete. | No       |
| `REFUNDED`           | The refund has been successfully completed.                                                         | Yes      |

#### Headers

<table><thead><tr><th width="205">Name</th><th width="134">Type</th><th>Description</th></tr></thead><tbody><tr><td>Authentication<mark style="color:red;">*</mark></td><td>String</td><td>Bearer Token</td></tr></tbody></table>

#### Request Body

<table><thead><tr><th width="207">Name</th><th width="133">Type</th><th>Description</th></tr></thead><tbody><tr><td>order_id<mark style="color:red;">*</mark></td><td>String</td><td>The order identifier</td></tr><tr><td>partial<mark style="color:red;">*</mark></td><td>Boolean</td><td><p><code>true</code> = Partial refund </p><p><code>false</code> = Full refund</p></td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td>Decimal</td><td>The total amount to be refunded. The gross amount must be entered without deductions.</td></tr><tr><td>notification_url</td><td>String</td><td>The provided URL is a POST endpoint used to receive notifications about changes in the refund status.</td></tr><tr><td>reason<mark style="color:red;">*</mark></td><td>String</td><td>Description of the refund reason.</td></tr></tbody></table>

<details>

<summary>Request Body Example</summary>

```json
{
    "order_id": "7478bd70-87ad-49d0-9143-9b148d776fc7",
    "partial": false,
    "amount": 1000,
    "reason": "refund reason",
    "notification_url": "https://qrpayments.depay.us/webhook/"
}
```

</details>

{% tabs %}
{% tab title="200: OK Successful Operation" %}

```json
{
    "id": "e8a7a740-6f47-11ec-90d6-0242ac120003",     
    "status": "PENDING"
}
```

{% endtab %}

{% tab title="401: Unauthorized" %}

```json
{
    "statusCode": 401,
    "message": "Unauthorized"
}
```

{% endtab %}

{% tab title="404: Not Found" %}

```json
{
    "statusCode": 404,
    "message": "ORDER_NOT_FOUND"
}
```

{% endtab %}

{% tab title="409: Conflict" %}

```json
{
    "statusCode": 409,
    "message": "The order is totally refunded."
}
```

{% endtab %}
{% endtabs %}

### Refund Callback Response

This response will be sent to the callback `(notification_url)`.

Total Refund - Callback Body Example

```json
{
    "order_id":"7478bd70-87ad-49d0-9143-9b148d776fc7",
    "type":"REFUND",
    "status":"REFUNDED",
    "message":"Refund DEVUELTA",
    "external_reference":"d8044af9-7559-50b3-agf2-b256ed3ag14f"
}
```

Partial Refund - Callback Body Example

```json
{
  "order_id": "7478bd70-87ad-49d0-9143-9b148d776fc7",
  "type": "REFUND",
  "status": "PARTIALLY_REFUNDED",
  "message": "Refund DEVUELTA",
  "external_reference": "refqr1749216815792_nxf1whwc5of"
}
```

## **Get Payment Statuses**

<mark style="color:blue;">`GET`</mark> `https://stage.api.payments.depay.us/v2/payins/orders/{order_id}`

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

#### Headers

<table><thead><tr><th width="226">Name</th><th width="115">Type</th><th>Description</th></tr></thead><tbody><tr><td>Authorization<mark style="color:red;">*</mark></td><td>String</td><td>Bearer Token</td></tr></tbody></table>

Query Parameters

<table><thead><tr><th width="238">Name</th><th width="111">Type</th><th>Description</th></tr></thead><tbody><tr><td>order_id<mark style="color:red;">*</mark></td><td>String</td><td>Order identifier. This field corresponds to the <code>id</code> field within the <code>order</code> object retrieved from the QR information retrieval endpoint. Required.</td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK Successful operation" %}

```json
{
    "id": "7478bd70-87ad-49d0-9143-9b148d776fc7",
    "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": "CREATED",
            "created_at": "2024-11-01 20:01:30.948423"
        },
        {
             "status": "WAITING_AMOUNT",
            "created_at": "2024-11-01 20:01:50.567650"
        },
        {
             "status": "COMPLETED",
            "created_at": "2024-11-01 20:02:00.343641"
        }
    ]
}
```

{% endtab %}

{% tab title="401: Unauthorized" %}

```json
{
    "statusCode": 401,
    "message": "Unauthorized"
}
```

{% endtab %}

{% tab title="404: Not Found" %}

```json
{
    "statusCode": 404,
    "message": "ORDER_NOT_FOUND"
}
```

{% endtab %}
{% endtabs %}