# Welcome!

Our solution generates interoperable QR codes across different countries, enabling payment processors to request QR codes for merchants from any supported region. This allows, for example, a merch

Our solution generates interoperable QR codes across different countries, enabling payment processors to request QR codes for merchants from any supported region. This feature enhances cross-border payment capabilities, providing a smoother transaction experience for both merchants and customers, and supports a more integrated international payment ecosystem.

## Welcome to Depay API

Welcome to Depay API! Here you'll find all the documentation you need to get up and running with the API.

## Want to jump right in?

Feeling like an eager beaver? Jump in to the quick start docs and get making your first request:

{% content-ref url="/pages/i3nE5Ls872ovbhQvU7WG" %}
[Quick Start](/quick-start)
{% endcontent-ref %}

## Want to deep dive?

Dive a little deeper and start exploring our API reference to get an idea of everything that's possible with the API:

{% content-ref url="/pages/G8WwSgROP4rzDqzbLqOy" %}
[API Reference](/reference/api-reference)
{% endcontent-ref %}


# Quick Start

## Get your API keys

Your API requests are authenticated using Bearer Tokens. Any request that doesn't include an Bearer Tokens will return an error.

You can generate a Bearer Token using the Authentication methods.

{% content-ref url="/pages/8FhhWpLUfUbJF9wOEDcC" %}
[Authentication](/reference/api-reference/authentication)
{% endcontent-ref %}

## Make your first request

To make your first request, send an authenticated request to the orders endpoint. This will return an `order`, which is nice.

## Get Order details by UUID

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

> Get an existing order by UUID

#### Query Parameters

| Name                                   | Type   | Description             |
| -------------------------------------- | ------ | ----------------------- |
| uuid<mark style="color:red;">\*</mark> | string | Order unique identifier |

#### Headers

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

{% tabs %}
{% tab title="200 Successfull operation" %}

```json
{
    "order_uuid": "64579618-7013-455b-b525-5ff9d5d2b8f5",
    "total": "10",
    "destination_wallet": "0x7f533b5fbf6ef86c3b7df76cc27fc67744a9a760",
    "status": "in_progress"
}
```

{% endtab %}

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

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

{% endtab %}

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

```json
{
    "statusCode": 404,
    "message": "Not Found"
}
```

{% endtab %}
{% endtabs %}


# API Reference

The Depay Latam Payments API enables merchants and PSPs to generate interoperable QR codes for cross-border payments across Latin America. Customers pay using their local wallet in their own currency; merchants receive funds in their local currency. This is a **collections (cobros) API** — it is the merchant-side counterpart to the wallet integrator API.

***

### Base URLs

All API endpoints are prefixed with the base URL for your environment.

| Environment | Base URL                              |
| ----------- | ------------------------------------- |
| Staging     | `https://stage.api.payments.depay.us` |
| Production  | `https://api.payments.depay.us`       |

All examples throughout this documentation use the **staging** base URL. Replace it with the production URL before going live.

> **Note:** Most endpoints use a `/v2/` path prefix. The exception is the authentication endpoint (`/auth/token`).

***

### Authentication

All endpoints require a Bearer Token in the `Authorization` header.

http

```http
Authorization: Bearer <ACCESS_TOKEN>
```

Obtain a token by calling `GET /auth/token` with your API Key:

http

```http
GET https://stage.api.payments.depay.us/auth/token
x-api-key: <YOUR_API_KEY>
```

json

```json
{
    "expiresIn": "3600",
    "accessToken": "<ACCESS_TOKEN>",
    "refreshToken": "<REFRESH_TOKEN>"
}
```

Tokens expire after **3600 seconds**. Refresh before expiry to avoid interruptions. See Authentication for full details.

***

### Common Headers

| Header          | Required | Description                               |
| --------------- | -------- | ----------------------------------------- |
| `Authorization` | Yes      | Bearer Token. Required on all endpoints.  |
| `Content-Type`  | Yes      | `application/json` for all POST requests. |

***

### Available Resources

| Resource             | Method   | Path                                              | Description                                                                              |
| -------------------- | -------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Authentication       | `GET`    | `/auth/token`                                     | Obtain a Bearer Token using your API Key.                                                |
| Create QR            | `POST`   | `/v2/qr`                                          | Generate a QR code for a Point of Sale. Triggers an async webhook on payment completion. |
| Cancel QR            | `DELETE` | `/v2/payins/qr/{order_id}`                        | Cancel an active QR code and invalidate any pending payment.                             |
| QR Refund            | `POST`   | `/v2/qr/refund`                                   | Request a full or partial refund for a completed QR payment.                             |
| Get Payment Status   | `GET`    | `/v2/payins/orders/{order_id}`                    | Query the current status and status history of an order.                                 |
| Exchange Rates       | `GET`    | `/v2/exchange-rates/rates/payins/{base}/{target}` | Retrieve the real-time exchange rate between two supported currencies.                   |
| Reconciliation Files | `GET`    | `/v2/reports/conciliation/payins`                 | Download a CSV or TXT report of all transactions for a given period.                     |
| Callbacks            | —        | —                                                 | Validate the HMAC-SHA256 signature included in every webhook notification.               |

***

### Webhooks

Endpoints that accept a `notification_url` parameter send asynchronous POST callbacks to that URL when the payment or refund status changes.

The notifications you will receive:

* **QR Creation** — sent after the QR is created, confirming the order and returning amounts and exchange rate.
* **Payment Completion** — sent when the QR is paid, canceled, rejected, or failed.
* **QR Expiration** — sent if the QR expires without being paid (10-minute timeout).
* **Refund Update** — sent after a refund is initiated, with intermediate and final statuses.

Your endpoint must return HTTP `200` to acknowledge receipt. Unacknowledged callbacks will be retried.

To verify that a callback originated from Depay and was not tampered with, validate the `signature` header included in every notification. See Callbacks for implementation details.

***

### The `message` Field

Several API responses and webhook payloads include a `message` field (e.g., `"message": "QR generated successfully."`).

> **Important:** The `message` field is **informational only**. Do not use its value in application logic — it may change without notice and may be in Spanish. Always base your logic on the `status` field.


# Authentication

To initiate use of the API, the first step is to acquire an API Key from Depay. This key uniquely identifies and grants you access to our services. After receiving your API Key, you must then obtain a JWT (JSON Web Token), which is essential for authenticating and authorizing your subsequent interactions with the API. This process ensures that access is both secure and tailored to your specific needs.

## Get access token

<mark style="color:blue;">`GET`</mark> `https://stage.api.payments.depay.us/auth/token`

> Retrieves Bearer Token needed to authenticate throughout the API Endpoints.

#### Headers

| Name                                        | Type   | Description       |
| ------------------------------------------- | ------ | ----------------- |
| x-api-key<mark style="color:red;">\*</mark> | String | \<YOUR\_API\_KEY> |

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

```json
{
    "expiresIn": "3600",
    "accessToken": "<ACCESS_TOKEN>",
    "refreshToken": "<REFRESH_TOKEN>"
}
```

{% endtab %}

{% tab title="403: Forbidden Invalid API-Key supplied" %}

```json
{
    "statusCode": 403,
    "message": "Forbidden resource"
}
```

{% endtab %}
{% endtabs %}

Once obtained your `accessToken` you should use it to authenticate  subsequent requests across all API endpoints. In order to do so, it should be included in the Authorization header of each request.

For example:

<pre class="language-http"><code class="lang-http">GET https://stage.api.payments.depay.us/payins/orders/{uuid}
<strong>Host: https://stage.api.payments.depay.us
</strong>Authorization: Bearer &#x3C;ACCESS_TOKEN>
</code></pre>


# Merchant Onboarding and Payment Flow

The Merchant Onboarding process and Payment Flow is not required for this integration.\
All necessary configurations and credentials are already managed internally by Depay, which means you do not need to implement any onboarding.

This simplifies the integration process, allowing you to focus solely on initiating and handling payment requests through the provided API endpoints.

For broader context, in the standard Depay cross-border payment system, merchants typically follow a structured onboarding process to prepare their accounts for international transactions. This workflow begins with the creation of a **Collector**, which represents the primary merchant entity. The **Collector** acts as the umbrella account under which all business activities are managed.

Once the Collector is set up, **Stores** are added to represent each specific business location or service point under that merchant. Stores allow for better organization, helping merchants track sales and transactions across multiple locations. Each Store is then equipped with **Point of Sale (POS)** terminals, which act as individual points where sales are processed.

With the complete setup of Collectors, Stores, and POS terminals, the merchant is ready to begin processing payments through Depay's cross-border QR code system. At this stage, **international QR codes** can be requested to facilitate transactions, enabling customers to make seamless payments from their local wallets, regardless of geographic boundaries.

This end-to-end setup not only ensures that merchants have a well-organized structure for managing their operations but also simplifies the payment experience for customers by offering a familiar, convenient way to make purchases using interoperable QR codes. The steps provide a complete journey from onboarding to the point where the merchant can actively engage in cross-border payments using Depay’s technology.

**Key Steps in the Onboarding Process:**

1. **Create a Collector**: Establish the primary merchant account.
2. **Add Stores**: Represent each physical or digital business outlet under the Collector.
3. **Set Up POS Terminals**: Configure the number of POS units required for each Store.
4. **Request QR Codes**: Begin facilitating payments by generating interoperable QR codes for transactions.


# Collectors

In the Depay ecosystem, a **Collector** refers to a merchant or business that utilizes our payment gateway services to process transactions. **Collector** integrate Depay's technology into their operations to offer seamless QR code-based payment options from different countries, simplifying and securing their sales processes. Essentially, **Collectors** are businesses looking to enhance the convenience of cross-border payments, ensuring that tourists or users from other regions can easily complete transactions using their local wallets.

Our API provides a suite of endpoints designed to manage **Collector** accounts efficiently, allowing for actions such as creating new **Collector** records, retrieving details about specific **Collectors**, listing all **Collectors**, and updating existing **Collector** information.&#x20;

## Create a new **Collector**

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

This endpoint allows you to create a new Collector within the Depay ecosystem. A Collector represents a merchant or business that integrates our payment gateway to facilitate QR code-based cross-border payments. This is the first step in managing a Collector's payment operations and making them accessible for future transactions through our API.

#### Headers

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

#### Request Body

<table><thead><tr><th width="195">Name</th><th width="101">Type</th><th>Description</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>Internal identifier generated by the system for the collector.</td></tr><tr><td>external_reference<mark style="color:red;">*</mark></td><td>String</td><td>An external identifier provided by the user that uniquely references the collector in their own system.</td></tr><tr><td>name<mark style="color:red;">*</mark></td><td>String</td><td>The name of the collector or business being registered.</td></tr><tr><td>fantasy_name</td><td>String</td><td>The trade name or informal name of the collector or business.</td></tr><tr><td>legal_address</td><td>String</td><td>The physical address of the collector or business.</td></tr><tr><td>regular_contact_email<mark style="color:red;">*</mark></td><td>String</td><td>The email address of the collector or business, used for communication and notifications.</td></tr><tr><td>regular_contact_phone</td><td>String</td><td>Contact phone number for the collector or business.</td></tr><tr><td>country_code</td><td>String</td><td>ISO 3166-1 alpha-2 country code representing the business location (e.g., AR, BR, US).</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>A brief description of the collector or business being registered.</td></tr></tbody></table>

<details>

<summary>Request Body Example</summary>

```json
{
    "code": "123",
    "external_reference": "7688391d-d967-4f61-93e6-13fb594dbc0f",
    "name": "Collector Test",
    "fantasy_name": "Collector Test",
    "tax_id": "213123123",
    "legal_address": "Fake Street 432",
    "regular_contact_email": "test1@depay.us",
    "regular_contact_phone": "12313123",
    "country_code": "AR",
    "description": "Collector de prueba"
}
```

</details>

{% tabs %}
{% tab title="201: Created Collector" %}

```json
{
    "collector_uuid": "188f08fc-80c6-4d62-b723-06008c55Ce"
}
```

{% endtab %}

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

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

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

## Get an existing Collector

<mark style="color:blue;">`GET`</mark> `https://stage.api.payments.depay.us/collectors/{uuid}`

This endpoint allows you to retrieve the details of an existing Collector using its unique identifier (UUID).

#### Query Parameters

| Name                                   | Type   | Description          |
| -------------------------------------- | ------ | -------------------- |
| uuid<mark style="color:red;">\*</mark> | string | Collector identifier |

#### Headers

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

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

```json
{
    "uuid": "188f08fc-80c6-4d62-b723-06008c55Ce",
    "createdAt": "2025-06-06T15:37:16.358Z",
    "updatedAt": "2025-06-06T15:37:16.358Z",
    "externalReference": "c2594bb7-c27a-47b3-8a6b-29f7cf023886",
    "name": "Collector Test",
    "fantasty_name": "Collector Test",
    "description": "Collector de prueba",
    "tax_id": "213123123",
    "image": null,
    "regular_contact_email": "test0@depay.us",
    "regular_contact_phone": "12313123",
    "country_code": "AR",
    "address": "Av. Siempreviva 432",
    "code": "123",
    "company": null,
    "category": null,
    "color": null,
    "store": []
}
```

{% endtab %}

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

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

{% endtab %}

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

```json
{
    "statusCode": 404,
    "message": "Collector not found"
}
```

{% endtab %}
{% endtabs %}

## Get all Collectors

<mark style="color:blue;">`GET`</mark> `https://stage.api.payments.depay.us/collectors`

This endpoint allows you to retrieve a list of all existing Collectors in the Depay ecosystem.

#### Headers

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

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

```json
[
    {
        "uuid": "763f5d43-0730-4c82-bc61-2958b589c8d6",
        "createdAt": "2025-04-28T14:06:58.329Z",
        "updatedAt": "2025-05-06T14:36:35.499Z",
        "externalReference": "892b2d92-ffd0-4c8f-9b74-8b42c5a3d5d7",
        "name": "Collector Test Endpoint",
        "fantasty_name": "Collector Test",
        "description": "Collector de prueba",
        "tax_id": "213123123",
        "image": null,
        "regular_contact_email": "test2@depay.us",
        "regular_contact_phone": "12313123",
        "country_code": "AR",
        "address": "Av. Siempreviva 432",
        "code": "123",
        "company": null,
        "category": null,
        "color": null
    },
    {
        "uuid": "188f08fc-80c6-4d62-b723-06007c974efe",
        "createdAt": "2025-06-06T15:37:16.358Z",
        "updatedAt": "2025-06-06T15:37:16.358Z",
        "externalReference": "c2594bb7-c27a-47b3-8a6b-29f7cf023886",
        "name": "Collector Test",
        "fantasty_name": "Collector Test",
        "description": "Collector de prueba",
        "tax_id": "213123123",
        "image": null,
        "regular_contact_email": "test60@depay.us",
        "regular_contact_phone": "12313123",
        "country_code": "AR",
        "address": "Av. Siempreviva 432",
        "code": "123",
        "company": null,
        "category": null,
        "color": null
    }
]
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

## Update a Collector

<mark style="color:purple;">`PATCH`</mark> `https://stage.api.payments.depay.us/collectors/{uuid}`

This endpoint allows you to update the details of an existing Collector in the Depay ecosystem.

#### Query Parameters

<table><thead><tr><th width="232">Name</th><th width="139">Type</th><th>Description</th></tr></thead><tbody><tr><td>uuid<mark style="color:red;">*</mark></td><td>String</td><td>Collector identifier</td></tr></tbody></table>

#### Request Body

<table><thead><tr><th width="236">Name</th><th width="139">Type</th><th>Description</th></tr></thead><tbody><tr><td>name</td><td>String</td><td>The name of the collector or business being registered.</td></tr><tr><td>email</td><td>String</td><td>The email address of the collector or business, used for communication and notifications.</td></tr><tr><td>description</td><td>String</td><td>A brief description of the collector or business being registered</td></tr><tr><td>external_reference</td><td>String</td><td>An external identifier provided by the user that uniquely references the collector in their own system.</td></tr><tr><td>address</td><td>String</td><td>The physical address of the collector or business, used for reference or notifications.</td></tr><tr><td>phone</td><td>String</td><td>Contact phone number for the collector or business.</td></tr><tr><td>manager</td><td>String</td><td>The person in charge of the business location.</td></tr></tbody></table>

{% tabs %}
{% tab title="204: No Content Customer updated" %}

```json
{
    "status": 201,
    "message": "Collector updated"
}
```

{% endtab %}

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

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

{% endtab %}

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

```json
{
    "statusCode": 404,
    "message": "Collector not found"
}
```

{% endtab %}
{% endtabs %}

## Disable a Collector

<mark style="color:orange;">`PUT`</mark> `https://stage.api.payments.depay.us/collectors/disable/{collector_uuid}`

This endpoint allows you to disable an existing Collector in the Depay ecosystem.

#### Query Parameters

| Name                                   | Type   | Description          |
| -------------------------------------- | ------ | -------------------- |
| uuid<mark style="color:red;">\*</mark> | String | Collector identifier |

#### Headers

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

{% tabs %}
{% tab title="204: No Content Collector disabled" %}

{% endtab %}

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

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

{% endtab %}

{% tab title="404: Not Found Collector not found" %}

```json
{
    "statusCode": 404,
    "message": "Collector not found"
}
```

{% endtab %}

{% tab title="409: Conflict Error disabling Customer" %}

{% endtab %}
{% endtabs %}


# Store

Within the Depay system, a **Store** represents the physical or digital retail outlet operated by a **customer** (merchant). It is where the customer’s transactions occur using i**nteroperable QR codes** and where our payment integration is implemented. Each Store is a unique entity under a customer account, enabling detailed management and analysis of transactions specific to that location. Whether a customer operates a single store or multiple shops across different locations, each is treated as a distinct **Store** within our platform, facilitating effective cross-border payment management.

Our API includes various endpoints to manage Stores effectively, facilitating operations such as adding new Stores, retrieving information about specific Stores, and updating Store details. This allows customers to tailor their payment processing setup to each Store's needs, ensuring a seamless and efficient payment experience.

## Create a new Store for a Collector

<mark style="color:green;">`POST`</mark> `https://stage.api.payments.depay.us/collectors/{collector_uuid}/stores`

This endpoint allows you to create a new **Store,** within the Depay ecosystem, for a specific Collector.

#### Query Parameters

<table><thead><tr><th width="217">Name</th><th width="140">Type</th><th>Description</th></tr></thead><tbody><tr><td>collector_uuid</td><td>String</td><td>collector identifiier</td></tr></tbody></table>

#### Headers

<table><thead><tr><th width="220">Name</th><th width="144">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="229">Name</th><th width="142">Type</th><th>Description</th></tr></thead><tbody><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>A brief description of the store being registered</td></tr><tr><td>external_reference<mark style="color:red;">*</mark></td><td>String</td><td>An external identifier provided by the user to uniquely reference the store in their own system.</td></tr><tr><td>address<mark style="color:red;">*</mark></td><td>String</td><td>The physical address of the store, used for reference and location purposes.</td></tr><tr><td>phone<mark style="color:red;">*</mark></td><td>String</td><td>The contact phone number for the store, useful for communications and inquiries.</td></tr><tr><td>manager<mark style="color:red;">*</mark></td><td>String</td><td>The name of the person responsible for managing the store.</td></tr></tbody></table>

<details>

<summary>Request Body Example</summary>

```json
{
    "description": "Retail store specializing in electronics",
    "external_reference": "store_12345",
    "address": "123 Tech Street, Cityville",
    "phone": "123-456-7890",
    "manager": "Jane Doe"
}
```

</details>

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

```json
{
    "status": 201,
    "message": "Store created",
    "uuid": "16146fd1-aee2-444e-916d-586e7debb9e7"
}
```

{% endtab %}

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

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

{% endtab %}

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

```json
{
    "statusCode": 404,
    "message": "Error creating the store. Collector not found"
}
```

{% endtab %}

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

```json
{
    "response": {
        "message": "Error description",
    }
}
```

{% endtab %}
{% endtabs %}

## Get an existing Store

<mark style="color:blue;">`GET`</mark> `https://stage.api.payments.depay.us/stores/{uuid}`

This endpoint allows you to retrieve the details of an existing **Store** using its unique identifier (UUID).

#### Query Parameters

| Name                                   | Type   | Description      |
| -------------------------------------- | ------ | ---------------- |
| uuid<mark style="color:red;">\*</mark> | string | Store identifier |

#### Headers

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

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

```json
{
    "uuid": "eb3550e7-92ea-4a15-9990-13a95c52600e",
    "createdAt": "2025-06-06T17:56:37.642Z",
    "updatedAt": "2025-06-06T17:56:37.642Z",
    "description": "123",
    "externalReference": "d97c884a-aebc-451f-a375-b6061afcf582",
    "address": "Av. Siempreviva 432",
    "phone": "test1@depay.us",
    "manager": "John Doe",
    "point_of_sales": []
}

```

{% endtab %}

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

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

{% endtab %}

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

```json
{
    "statusCode": 404,
    "message": "Store not found"
}
```

{% endtab %}
{% endtabs %}

## Get all Stores

<mark style="color:blue;">`GET`</mark> `https://stage.api.payments.depay.us/collectors/{collector_uuid}/stores`

This endpoint allows you to retrieve a list of all existing Stores in the Depay ecosystem, for a specific Collector.

#### Query Parameters

| Name            | Type   | Description         |
| --------------- | ------ | ------------------- |
| collector\_uuid | String | customer identifier |

#### Headers

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

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

```json
[
    {
        "uuid": "fa036507-ca23-4426-94a4-746ca3bc18cb",
        "createdAt": "2025-06-06T17:50:16.551Z",
        "updatedAt": "2025-06-06T17:50:16.551Z",
        "description": "123",
        "externalReference": "09124d3a-3f46-40a1-9aee-d41f9623dd31",
        "address": "Av. Siempreviva 432",
        "phone": "test8@depay.us",
        "manager": "John Doe"
    },
    {
        "uuid": "eb3550e7-92ea-4a15-9990-13a95c52600e",
        "createdAt": "2025-06-06T17:56:37.642Z",
        "updatedAt": "2025-06-06T17:56:37.642Z",
        "description": "123",
        "externalReference": "d97c884a-aebc-451f-a375-b6061afcf582",
        "address": "Av. Siempreviva 432",
        "phone": "test1@depay.us",
        "manager": "John Doe"
    }
]
```

{% endtab %}

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

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

{% endtab %}

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

```json
{
    "statusCode": 404,
    "message": "Collector not found"
}
```

{% endtab %}
{% endtabs %}

## Update an existing Store

<mark style="color:purple;">`PATCH`</mark> `https://stage.api.payments.depay.us/stores/{uuid}`

This endpoint allows you to update the details of an existing **Store** in the Depay ecosystem.

#### Query Parameters

| Name                                   | Type   | Description      |
| -------------------------------------- | ------ | ---------------- |
| uuid<mark style="color:red;">\*</mark> | String | Store identifier |

#### Request Body

<table><thead><tr><th width="229">Name</th><th width="142">Type</th><th>Description</th></tr></thead><tbody><tr><td>description<mark style="color:red;">*</mark></td><td>String</td><td>A brief description of the store being registered</td></tr><tr><td>external_reference<mark style="color:red;">*</mark></td><td>String</td><td>An external identifier provided by the user to uniquely reference the store in their own system.</td></tr><tr><td>address<mark style="color:red;">*</mark></td><td>String</td><td>The physical address of the store, used for reference and location purposes.</td></tr><tr><td>phone<mark style="color:red;">*</mark></td><td>String</td><td>The contact phone number for the store, useful for communications and inquiries.</td></tr><tr><td>manager<mark style="color:red;">*</mark></td><td>String</td><td>The name of the person responsible for managing the store.</td></tr></tbody></table>

{% tabs %}
{% tab title="201: Store updated" %}

```json
{
    "status": 201,
    "message": "Store updated"
}
```

{% endtab %}

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

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

{% endtab %}

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

```json
{
    "statusCode": 404,
    "message": "Store not found"
}
```

{% endtab %}
{% endtabs %}

## Disable a Store

<mark style="color:orange;">`PUT`</mark> `https://stage.api.payments.depay.us/stores/{uuid}/disable`

This endpoint allows you to disable an existing Store in the Depay ecosystem.

#### Query Parameters

| Name                                   | Type   | Description       |
| -------------------------------------- | ------ | ----------------- |
| uuid<mark style="color:red;">\*</mark> | String | Branch identifier |

#### Headers

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

{% tabs %}
{% tab title="204: No Content Branch disabled" %}

{% endtab %}

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

{% endtab %}

{% tab title="404: Not Found Branch not found" %}

{% endtab %}

{% tab title="409: Conflict Error disabling Branch" %}

{% endtab %}
{% endtabs %}


# Point of Sales

In the context of Depay's ecosystem, a **POS (Point of Sale)** refers to a specific point, either digital or physical, where payment transactions are processed using interoperable QR codes. Each store, belonging to a customer (merchant), can operate multiple **POS** terminals, all integrated into the Depay system to handle cross-border payments seamlessly. These points allow merchants to accept payments from tourists or foreign customers using their local wallets, facilitating seamless cross-border sales.

Our API facilitates the comprehensive management of each POS, allowing Customers to add, update, retrieve, and manage multiple **Points Of Sale** under a single Store. This flexibility supports varied business models and operational scales, ensuring that whether a Store operates a single POS or several, each can be efficiently integrated and managed through Depay's system.

## Create a new Point of Sales

<mark style="color:green;">`POST`</mark> `https://stage.api.payments.depay.us/stores/{store_uuid}/pos`

This endpoint allows you to create a new POS for the specified Store

#### Query Parameters

| Name        | Type   | Description      |
| ----------- | ------ | ---------------- |
| store\_uuid | String | Store identifier |

#### Headers

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

#### Request Body

| Name                                                  | Type   | Description                                                                                       |
| ----------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------- |
| name<mark style="color:red;">\*</mark>                | String | The name of the pos being registered.                                                             |
| external\_reference<mark style="color:red;">\*</mark> | String | An external identifier provided by the user that uniquely references the pos in their own system. |
| description                                           | String | A brief description of the pos.                                                                   |

<details>

<summary>Request Body Example</summary>

```json
{
    "name": "testing",
    "external_reference": "94c4631f-0480-4da3-8cc0-170a9ea402a1",
    "description": "Test collector"
}
```

</details>

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

{% endtab %}

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

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

{% endtab %}

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

```json
{
    "statusCode": 404,
    "message": "Store not found"
}
```

{% endtab %}
{% endtabs %}

## Get an existing POS

<mark style="color:blue;">`GET`</mark> `https://stage.api.payments.depay.us/pos/{uuid}`

This endpoint allows you to retrieve the details of an existing POS using its unique identifier (UUID).

#### Query Parameters

| Name                                   | Type   | Description       |
| -------------------------------------- | ------ | ----------------- |
| uuid<mark style="color:red;">\*</mark> | string | Branch identifier |

#### Headers

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

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

```json
{
    "uuid": "bc1b79ce-2528-4039-9c08-37836400ab80",
    "createdAt": "2025-06-06T18:11:24.111Z",
    "updatedAt": "2025-06-06T18:11:24.111Z",
    "externalReference": "f1609d5f-7a84-4f54-bb6d-c420bd630451",
    "description": "Test collector",
    "category": 0,
    "store": {
        "uuid": "eb3550e7-92ea-4a15-9990-13a95c52600e",
        "createdAt": "2025-06-06T17:56:37.642Z",
        "updatedAt": "2025-06-06T18:04:33.000Z",
        "description": "123",
        "externalReference": "5e5e18f6-d4b9-4f94-9f83-7877c859015c",
        "address": "Av. Siempreviva 432",
        "phone": "test1@depay.us",
        "manager": "John Dou",
        "collector": {
            "uuid": "188f08fc-80c6-4d62-b723-06007c974efe",
            "createdAt": "2025-06-06T15:37:16.358Z",
            "updatedAt": "2025-06-06T15:37:16.358Z",
            "externalReference": "c2594bb7-c27a-47b3-8a6b-29f7cf023886",
            "name": "Collector Test",
            "fantasty_name": "Collector Test",
            "description": "Collector de prueba",
            "tax_id": "213123123",
            "image": null,
            "regular_contact_email": "test60@depay.us",
            "regular_contact_phone": "12313123",
            "country_code": "AR",
            "address": "Av. Siempreviva 432",
            "code": "123",
            "company": null,
            "category": null,
            "color": null
        }
    }
}
```

{% endtab %}

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

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

{% endtab %}

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

```json
{
    "statusCode": 404,
    "message": "POS not found"
}
```

{% endtab %}
{% endtabs %}

## Get All POS

<mark style="color:blue;">`GET`</mark> `https://stage.api.payments.depay.us/stores/{store_uuid}/pos`

This endpoint allows you to retrieve a list of all existing POS in the Depay ecosystem

#### Query Parameters

| Name                                          | Type   | Description      |
| --------------------------------------------- | ------ | ---------------- |
| store\_uuid<mark style="color:red;">\*</mark> | String | Store identifier |

#### Headers

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

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

```json
{[
    {
       "name": "POS Name",
       "description": "POS Description",
       "external_reference": "external_reference_pos",
       "uuid": "271f9b3f-49b0-4183-9b1a-f4e98287d2b4",
       "enabled": "true"
    },
    {
       "name": "POS Name"
       "description": "POS 2 Description",
       "external_reference": "external_reference_pos_2",
       "uuid": "271f9b3f-49b0-4183-9b1a-f4e98287d2b5",
       "enabled": "true"
    }
]}
```

{% endtab %}

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

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

{% endtab %}

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

```json
{
    "statusCode": 404,
    "message": "Store not found"
}
```

{% endtab %}
{% endtabs %}

## Update POS

<mark style="color:purple;">`PATCH`</mark> `https://stage.api.payments.depay.us/pos/{uuid}`

This endpoint allows you to update the details of an existing POS in the Depay ecosystem.

#### Query Parameters

| Name                                   | Type   | Description    |
| -------------------------------------- | ------ | -------------- |
| uuid<mark style="color:red;">\*</mark> | String | POS identifier |

#### Request Body

| Name                                          | Type   | Description                                                                                       |
| --------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------- |
| name<mark style="color:red;">\*</mark>        | String | The name of the pos being registered.                                                             |
| description<mark style="color:red;">\*</mark> | String | A brief description of the pos                                                                    |
| external\_reference                           | String | An external identifier provided by the user that uniquely references the pos in their own system. |

<details>

<summary>Request Body Example</summary>

```json
{
    "name": "testing",
    "external_reference": "{{external_reference}}",
    "description": "Test collector2"
}
```

</details>

{% tabs %}
{% tab title="201: POS updated" %}

```json
{
    "status": 201,
    "message": "PointOfSales updated",
    "data": {
        "uuid": "bc1b79ce-2528-4039-9c08-37836400ab80",
        "createdAt": "2025-06-06T18:11:24.111Z",
        "updatedAt": "2025-06-06T18:30:38.000Z",
        "externalReference": "e32f7151-3bd2-42ad-a37c-be8668a6a3b5",
        "description": "Test collector2"
    }
}
```

{% endtab %}

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

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

{% endtab %}

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

```json
{
    "statusCode": 404,
    "message": "POS not found"
}
```

{% endtab %}
{% endtabs %}

## Disable POS

<mark style="color:orange;">`PUT`</mark> `https://stage.api.payments.depay.us/pos/disable/{uuid}`

This endpoint allows you to disable an existing Collector in the Depay ecosystem.

#### Query Parameters

| Name                                   | Type   | Description    |
| -------------------------------------- | ------ | -------------- |
| uuid<mark style="color:red;">\*</mark> | String | POS identifier |

#### Headers

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

{% tabs %}
{% tab title="204: No Content POs disabled" %}

{% endtab %}

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

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

{% endtab %}

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

```json
{
    "statusCode": 404,
    "message": "POS not found"
}
```

{% endtab %}
{% endtabs %}


# 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="/files/XkuyKq6koiW25zGJE0Sd" alt=""><figcaption></figcaption></figure>

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

| Key                 | Description                                                    |
| ------------------- | -------------------------------------------------------------- |
| 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 unexpected 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>

> **Important:** `local_country` is the merchant's country; `qr_from` is the country whose QR network will process the payment.

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

#### Path Parameters

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

#### Headers

| Name                                            | Type   | Description  |
| ----------------------------------------------- | ------ | ------------ |
| Authorization<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

> `message` is informational only. Do not use its value in application logic; it may change without notice and may be in Spanish.

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

> `message` is informational only. Do not use its value in application logic; it may change without notice and may be in Spanish.

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>

Path 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": "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 %}


# Exchange Rates

In the context of our API, exchange rates refer to the conversion values between different currency pairs. This feature allows users to retrieve real-time exchange rates to facilitate cross-border transactions.

Our API provides an endpoint to fetch the latest exchange rates, ensuring accurate and up-to-date currency conversion. The available currency pairs at the moment are:

* USD/ARS
* ARS/USD
* USD/BRL
* BRL/USD
* ARS/BRL
* BRL/ARS

These rates are periodically updated based on market conditions.

### Retrieve exchange rate

This endpoint allows you to retrieve the latest exchange rate between two supported currencies. It returns both conversion directions for the requested currency pair.

<mark style="color:blue;">`GET`</mark> `https://stage.api.payments.depay.us/v2/exchange-rates/rates/payins-fiat/{base}/{target}`

#### Headers

| Name            | Type   | Description   |
| --------------- | ------ | ------------- |
| Authorization\* | String | Bearer Token. |

#### **Query Parameters**

| Name      | Type   | Description                                                             |
| --------- | ------ | ----------------------------------------------------------------------- |
| precision | String | Number of decimal places used in the exchange rate returned by the API. |

#### **Path Parameters**

| Name     | Type   | Description                                               |
| -------- | ------ | --------------------------------------------------------- |
| base\*   | String | The currency code you want to convert from (e.g., `USD`). |
| target\* | String | The currency code you want to convert to (e.g., `BRL`).   |

#### **Response**

| Name               | Type   | Description                                                      |
| ------------------ | ------ | ---------------------------------------------------------------- |
| exchangeRate\_1    | String | Conversion rate from **target\_currency** to **base\_currency.** |
| description\_xr\_1 | String | Description of the exchange rate.                                |
| exchangeRate\_2    | String | Conversion rate from **base\_currency** to **target\_currency.** |
| description\_xr\_2 | String | Description of the exchange rate.                                |

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

```json
{
    "exchangeRate_1": "0.17",
    "description_xr_1": "1 BRL = 0.17 USD",
    "exchangeRate_2": "5.86",
    "description_xr_2": "1 USD = 5.86 BRL"
}
```

{% endtab %}

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

```json
{
    "eventId": "BadRequest",
    "detail": "One or more validation errors occurred.",
    "correlationId": "e9119b1b-07ee-4734-8fb4-ceac60ecabc4",
    "errores": [{
        "code": "400",
        "title": "",
        "detail": "The X field is required."
    }]
}
```

{% endtab %}

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

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

{% endtab %}

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

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

{% endtab %}
{% endtabs %}


# Reconciliation Files

This endpoint allows you to download a reconciliation file containing all transactions for a specific period and status. The file can be exported in CSV or TXT format, and includes detailed information for backend validation, accounting, or audits.

## Retrieve files

Returns a reconciliation file with a list of all transactions filtered by date range and status. The file includes key data fields such as UUID, amounts, currencies, statuses, and timestamps.

<mark style="color:blue;">`GET`</mark> `https://stage.api.payments.depay.us/reports/conciliation/payins`

#### Headers

<table><thead><tr><th width="251.4375">Name</th><th width="170.609375">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="252.9765625">Name</th><th width="82.125">Type</th><th width="85.8203125">Required</th><th>Description</th></tr></thead><tbody><tr><td>start_date</td><td>String</td><td>No</td><td>Start date for the report (format: YYYY-MM-DD).</td></tr><tr><td>end_date</td><td>String</td><td>No</td><td>End date for the report (format: YYYY-MM-DD).</td></tr><tr><td>status</td><td>String</td><td>No</td><td>Filter by transaction status (e.g., CREATED, COMPLETED, CANCELED).</td></tr><tr><td>format</td><td>String</td><td>Yes</td><td>File format: <code>csv</code> (default) or <code>txt</code>.</td></tr></tbody></table>

#### **Fields in the reconciliation file:**

| Field                           | Type     | Description                                                                   |
| ------------------------------- | -------- | ----------------------------------------------------------------------------- |
| Status                          | String   | Status of the transaction (e.g., COMPLETED, FAILED, CANCELED).                |
| External Reference              | String   | Custom reference provided by the merchant for internal tracking.              |
| POS External Reference          | String   | Reference used by the merchant’s POS system to link the payment.              |
| Order Id                        | String   | Unique identifier assigned by Depay to the order.                             |
| Customer                        | String   | Unique identifier assigned by Depay to the customer.                          |
| Collector Name                  | String   | Registered name of the collector receiving the payment.                       |
| Collector Identification Number | String   | Tax ID or legal identifier of the collector or business.                      |
| User Amount                     | Decimal  | Amount paid by the user in their original currency.                           |
| User Currency                   | String   | Currency code representing the user’s payment currency (e.g., ARS, BRL).      |
| User Country                    | String   | ISO 3166-1 alpha-2 country code of the user's country (e.g., AR, BR, US).     |
| User Name                       | String   | Full name of the user making the payment.                                     |
| User Account Number             | String   | Bank or virtual account number used by the user.                              |
| User Tax ID                     | String   | Tax identifier or document number of the user (e.g., CPF, CUIT, SSN).         |
| Amount USD                      | Decimal  | Payment amount expressed in USD for reference.                                |
| Local Amount                    | Decimal  | Amount to be received by the merchant in the local currency.                  |
| Local Currency                  | String   | Currency code representing the local currency (e.g., ARS, BRL).               |
| Local Country                   | String   | ISO 3166-1 alpha-2 country code of the merchant’s country (e.g., AR, BR, US). |
| Payment Date                    | Datetime | Date and time the payment was processed (ISO 8601 format).                    |

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

```json
File: 2025-04-07-conciliation.csv
Content-Type: text/csv
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}


# Callbacks

To ensure the authenticity and security of callback notifications sent from our API to your systems, each notification includes a **signature** in the HTTP headers under the key `signature`. This signature allows you to validate that the notification originated from us and was not tampered with during transmission.

## Signature Generation

#### 1. Payload and Customer Identification     &#x20;

Each notification has a unique payload (`payload`) and is associated with a specific customer (`customerUuid`).   &#x20;

#### 2. Data to Be Signed     &#x20;

We concatenate the payload and customer UUID in the following format:      \
`{payload}+{customerUuid}`  &#x20;

• **payload**: The JSON stringified body of the callback notification.\
• **customerUuid**: The unique identifier of your account.

**3. Key for Signing**

We use a secret API key (api\_key) associated with your account to generate the signature. This key is securely stored and unique for each customer.&#x20;

#### 4. Hash Algorithm

We use the HMAC (Hash-Based Message Authentication Code) algorithm with SHA-256 to compute the signature. The formula is:&#x20;

`signature = HMAC_SHA256(api_key, "{payload}+{customerUuid}")`&#x20;

#### 5. Output:&#x20;

The resulting HMAC digest is converted to a hexadecimal string and sent as the signature header.&#x20;

**Example Notification Header**

```
http
POST /callback-endpoint HTTP/1.1
Content-Type: application/json
signature: 3d2e4a5b6c7d8e9f10g11h12i13j14k15l16m17n18o19p20q21r22s23t24u25
```

## Validating the Signature on Your Side

To validate the authenticity of a callback notification follow this steps:&#x20;

#### 1. Retrieve the Header Signature

Extract the signature from the headers of the received notification.&#x20;

#### 2. Recreate the Signature

Using your API key (shared during account setup), and your customer UUID recreate the signature following the same process we use:&#x20;

• JSON stringify the payload exactly as received. \
• Concatenate the payload and customer UUID with a +. \
• Compute the HMAC using the SHA-256 algorithm and your API key. <br>

Example in **Node.js**:

```
const crypto = require('crypto');

const apiKey = 'your-api-key'; // The secret API key we provided
const payload = '{"event":"payment","amount":100}'; // The callback payload (JSON stringified)
const customerUuid = 'abc123'; // Your customer UUID

const dataToSign = `${payload}+${customerUuid}`;
const hmac = crypto.createHmac('sha256', apiKey);
hmac.update(dataToSign);
const recreatedSignature = hmac.digest('hex');

console.log('Recreated Signature:', recreatedSignature);
```

#### 3. Compare Signatures

• Compare the `recreatedSignature` with the signature header value.\
• If they match, the notification is valid and originated from our API. If not, reject the notification. <br>

Example in Node.js

```
const crypto = require('crypto');

const apiKey = Buffer.from('your-api-key', 'utf-8'); // The secret API key
const payload = '{"event":"payment","amount":100}'; // The callback payload (JSON stringified)
const customerUuid = 'abc123'; // The customer UUID

const dataToSign = ${payload}+${customerUuid};
const recreatedSignature = crypto
  .createHmac('sha256', apiKey) // Create an HMAC using the SHA-256 algorithm and the API key
  .update(dataToSign, 'utf-8') // Specify the data to sign
  .digest('hex'); // Generate the hash in hexadecimal format

// Assume header.signature is the signature sent in the request headers
const header = { signature: 'signature-sent-in-header' }; // Placeholder for the header

const isValidSignature = recreatedSignature === header.signature; // Validate the signature

console.log('Is the signature valid?', isValidSignature);
```

## **Security Notes**

• **API Key Confidentiality**: Keep your API key secure and never expose it publicly or hard-code it into client-side code.

• **Validate Payload Integrity**: If the signature does not match, reject the notification and log the attempt.

By following these steps, you can ensure that the callback notifications you receive are authentic and trustworthy. If you have any issues or questions, please contact our support team.