> For the complete documentation index, see [llms.txt](https://docs.latam-payments.depay.us/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.latam-payments.depay.us/reference/api-reference.md).

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