---
url: /api/account.md
description: 'Balances, sub-accounts and transfers between them, and transaction history.'
---

# Account

Your business has a primary account and can have sub-accounts, each with its own balances, history, deposit details
and bank accounts. Use sub-accounts to keep funds apart, for example by desk, product or client, and move funds
between them with a transfer.

## Choosing the account a request acts on

Every signed request acts on one account:

* Without `X-VALR-SUB-ACCOUNT-ID`, it acts on your primary account, whose ID is `0`.
* With `X-VALR-SUB-ACCOUNT-ID` set to a sub-account's `id`, it acts on that sub-account. Include the ID in the
  signature too; see [Authentication](/guides/authentication).

A key limited to specific sub-accounts can only act on those, so it must always send the header. Endpoints that
manage sub-accounts, or that cover your whole business, such as balances for all accounts, are called on your primary
account by a key that isn't limited to sub-accounts.

## Common tasks

* **See every balance at once:** [Get balances for all accounts](/operations/getV1AccountBalancesAll) returns each
  account's balances in one call. Balances of your payments accounts are under [Payouts](/api/payouts).
* **Create a sub-account:** [Create a sub-account](/operations/postV1AccountSubaccount) returns its ID. Mark accounts
  that hold your clients' money with the `CLIENT_FUNDS` tag.
* **Move funds:** [Transfer between accounts](/operations/postV1AccountSubaccountsTransfer) moves funds between your
  primary account and sub-accounts. It's processed asynchronously, so confirm it from balances or transaction history.
* **Reconcile:** transaction history is per account, newest first. An account's history doesn't include
  its sub-accounts' transactions; list them together with
  [List transactions for all sub-accounts](/operations/getV1AccountTransactionhistorySubaccounts).

## Before you start

| Bundle | Allows |
|---|---|
| `TREASURY_READ` | Read balances, history, deposit details, sub-accounts and withdrawals |
| `TREASURY_WRITE` | Everything in `TREASURY_READ`, plus create, rename and delete sub-accounts and transfer between accounts |

## Endpoints

### Balances

Account balances.

| Endpoint | Request | Needs |
|---|---|---|
| [Get balances](/operations/getV1AccountBalances) | `GET /v1/account/balances` | `ACCOUNT_BALANCES_READ` |
| [Get balances for all accounts](/operations/getV1AccountBalancesAll) | `GET /v1/account/balances/all` | `ACCOUNT_BALANCES_READ` |

### Sub-accounts

Your business's primary account and its sub-accounts: list, create, rename and delete sub-accounts, and move funds between your accounts. Your primary account's ID is `0`. To call another endpoint on a sub-account, send the sub-account's `id` in the `X-VALR-SUB-ACCOUNT-ID` header; without it, requests act on your primary account. A key limited to some sub-accounts can only act on those, so it must always send the header.

| Endpoint | Request | Needs |
|---|---|---|
| [List sub-accounts](/operations/getV1AccountSubaccounts) | `GET /v1/account/subaccounts` | `SUB_ACCOUNTS_READ` |
| [Get a sub-account](/operations/getV1AccountSubaccountByAccountPublicId) | `GET /v1/account/subaccount/{accountPublicId}` | `SUB_ACCOUNTS_READ` |
| [Create a sub-account](/operations/postV1AccountSubaccount) | `POST /v1/account/subaccount` | `SUB_ACCOUNTS_MANAGE` |
| [Rename a sub-account](/operations/putV1AccountSubaccount) | `PUT /v1/account/subaccount` | `SUB_ACCOUNTS_MANAGE` |
| [Delete a sub-account](/operations/deleteV1AccountSubaccount) | `DELETE /v1/account/subaccount` | `SUB_ACCOUNTS_MANAGE` |
| [Transfer between accounts](/operations/postV1AccountSubaccountsTransfer) | `POST /v1/account/subaccounts/transfer` | `TRANSFERS_CREATE` |

### Transaction history

Transactions and trades on your accounts, newest first. Unless an endpoint says otherwise, it reads the account you call it on: your primary account, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`. An account's history doesn't include its sub-accounts' transactions.

| Endpoint | Request | Needs |
|---|---|---|
| [List transactions](/operations/getV1AccountTransactionhistory) | `GET /v1/account/transactionhistory` | `TRANSACTION_HISTORY_READ` |
| [List transactions for all sub-accounts](/operations/getV1AccountTransactionhistorySubaccounts) | `GET /v1/account/transactionhistory/subaccounts` | `TRANSACTION_HISTORY_READ` |

---

---
url: /guides/ai-support.md
description: >-
  Ask questions about the API with AI-powered support, and machine-readable docs
  for coding assistants
---

# AI support

![Ask AI](/img/ask-ai.png)

To explore our docs with AI support, [open the VALR support centre's AI assistant](https://support.valr.com/hc/en-us?askai=true).

## Docs for coding assistants and agents

This site publishes its documentation in forms that coding assistants and AI agents can read directly:

| | |
|---|---|
| [`/llms.txt`](/llms.txt) | An index of every page, with a short description of each |
| [`/llms-full.txt`](/llms-full.txt) | All the documentation in one markdown file |
| [`/openapi.json`](/openapi.json) | The OpenAPI specification for every endpoint on this site |

Point your assistant at `llms-full.txt` for the full context, or at `llms.txt` to let it fetch only the pages it needs.
Every endpoint's page there includes the permission it needs, its errors and a ready-to-run example request.

---

---
url: /api.md
description: VALR Business API reference for institution API keys
---

# API Reference

| | |
|---|---|
| **Base URL** | `https://api.valr.com` |
| **Protocol** | HTTPS only |
| **Content-Type** | `application/json` |
| **Authentication** | Signed requests with an institution API key ([guide](/guides/authentication)) |
| **Permissions** | Each endpoint needs one permission, granted by your key's bundles ([bundles](/guides/permissions)) |
| **Errors** | Listed per endpoint ([errors](/guides/errors)) |
| **OpenAPI spec** | [Download openapi.json](/openapi.json) |

Each endpoint page shows the permission it needs, the bundles that grant it, its request and response, the errors
it can return, and code samples that sign the request when they run.

## Categories

| Category | |
|---|---|
| [Account](/api/account) | Balances, sub-accounts and transfers between them, and transaction history. |
| [Wallets](/api/wallets) | Receive and send crypto and fiat, manage saved crypto addresses and linked bank accounts, and track every deposit and withdrawal. |
| [Collections](/api/collections) | Collect bank deposits from your payers with unique deposit references, then follow each payment to settlement. |
| [Payouts](/api/payouts) | Pay many bank beneficiaries in one batch from your payout account, and track every payout to completion. |
| [Webhooks](/api/webhooks) | Get an HTTPS notification when something happens on your business's accounts, instead of polling the API. |
| [Public data](/api/public-data) | Exchange status, server time, currencies and pairs, and market prices, with no API key needed. |

---

---
url: /api-docs/deleteV2PaymentsBulkWithdrawalsBeneficiariesById.md
description: 'DELETE /v2/payments/bulk-withdrawals/beneficiaries/{id}'
---

# Archive a beneficiary

`DELETE /v2/payments/bulk-withdrawals/beneficiaries/{id}`

Archives a beneficiary so it no longer appears in the active list. Its bank and account number stay reserved: creating or paying the same recipient again restores it.

**Requires** `DISBURSEMENTS_DELETE`, granted by `DISBURSEMENTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | Yes | Beneficiary ID. |

## Responses

### 204

No content

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=DELETE
REQUEST_PATH='/v2/payments/bulk-withdrawals/beneficiaries/{id}'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "DELETE"
path = "/v2/payments/bulk-withdrawals/beneficiaries/{id}"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | The beneficiary ID isn't a valid UUID. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No active beneficiary with this ID exists on your account; it may already be archived. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /guides/authentication.md
description: Institution API keys and how to sign requests
---

# Authentication

## Institution API keys

Your business creates institution API keys in VALR Business. Creating a key needs a team member with permission to
manage API keys, and confirmation by email and two-factor authentication. When you create a key you choose:

* **Bundles**: what the key can do ([permissions & bundles](/guides/permissions)).
* **Sub-accounts** (optional): limit the key to specific sub-accounts. Without a limit, the key can act on your primary
  account and any sub-account.
* **IP addresses** (optional): only accept requests from these addresses or ranges.
* **Endpoints** (optional): only allow these endpoints.

The API key and secret are shown once. Keys don't expire; revoke a key in VALR Business when you no longer need it.

::: danger Keep the secret secret
Anyone with your API secret can sign requests as your business. Never send it in a request, commit it to source
control or paste it into a web page.
:::

## Signing a request

Every request is signed with HMAC-SHA512, using your API secret as the key, over this string:

```
timestamp + METHOD + path + body + subAccountId
```

| Part | Value |
|---|---|
| `timestamp` | Current time in Unix milliseconds; the same value you send in `X-VALR-TIMESTAMP` |
| `METHOD` | HTTP method in upper case, e.g. `POST` |
| `path` | Path including the query string, e.g. `/v1/account/balances?excludeZeroBalances=true` |
| `body` | The exact JSON string you send, or an empty string |
| `subAccountId` | The sub-account ID you send in `X-VALR-SUB-ACCOUNT-ID`, or an empty string |

Send these headers:

| Header | Value |
|---|---|
| `X-VALR-API-KEY` | Your API key |
| `X-VALR-SIGNATURE` | The signature, as lower-case hex |
| `X-VALR-TIMESTAMP` | The timestamp you signed |
| `X-VALR-SUB-ACCOUNT-ID` | Optional: act on this sub-account |

Sign each request just before you send it: requests with an old timestamp are rejected, and each signature can only
be used once. Every endpoint's code samples sign the request for you; set `VALR_API_KEY` and `VALR_API_SECRET` in your
environment and run them.

## Primary account and sub-accounts

Without `X-VALR-SUB-ACCOUNT-ID`, a request acts on your primary account. Some endpoints, such as payments and deposit
references, only work on the primary account and with a key that isn't limited to sub-accounts. Those endpoints say so,
and return `401` with code `-93` otherwise.

## Verify your implementation

| | GET example | POST example |
|---|---|---|
| Secret | `4961b74efac86b25cce8fbe4c9811c4c7a787b7a5996660afcc2e287ad864363` | same |
| Timestamp | `1558014486185` | `1558017528946` |
| Method | `GET` | `POST` |
| Path | `/v1/account/balances` | `/v1/orders/market` |
| Body | *(empty)* | `{"customerOrderId":"ORDER-000001","pair":"BTCUSDC","side":"BUY","quoteAmount":"80000"}` |
| Signature | `9d52c181ed69460b49307b7891f04658e938b21181173844b5018b2fe783a6d4c62b8e67a03de4d099e7437ebfabe12c56233b73c6a0cc0f7ae87e05f6289928` | `09f536e3dfdad58443f16010a97a0a21ad27486b7b8d6d4103170d885410ed77f037f1fa628474190d4f5c08ca12c1acc850901f1c2e75c6d906ec3b32b008d0` |

---

---
url: /api-docs/postV2PaymentsBulkWithdrawalsBatchesByIdCancel.md
description: 'POST /v2/payments/bulk-withdrawals/batches/{id}/cancel'
---

# Cancel a disbursement batch

`POST /v2/payments/bulk-withdrawals/batches/{id}/cancel`

Cancels a batch that is pending approval or approved, and marks its withdrawals that haven't been submitted as `SKIPPED`. Batches created with an API key are executed immediately, so they usually can't be cancelled.

**Requires** `DISBURSEMENTS_UPDATE`, granted by `DISBURSEMENTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | Yes | Batch ID. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | - |
| label | string | Yes | - |
| currency | string | Yes | - |
| totalAmount | string | Yes | Sum of the withdrawal amounts, as a decimal string. |
| withdrawalCount | integer (int32) | Yes | - |
| status | string | Yes | Batch status: `PENDING_APPROVAL`, `APPROVED`, `PROCESSING`, `COMPLETED`, `PARTIALLY_COMPLETED`, `FAILED` or `CANCELLED`. |
| uploadedBy | string | Yes | ID of the user or API key that created the batch. |
| uploadedByName | object | Yes | - |
| approvedBy | string | Yes | ID of the user or API key that approved the batch (for a batch created with an API key, that key); `null` until approved. |
| approvedByName | object | Yes | - |
| approvedAt | string (date-time) | Yes | - |
| createdAt | string (date-time) | Yes | - |
| updatedAt | string (date-time) | Yes | - |
| completedAt | string (date-time) | Yes | - |
| feeQuote | object | Yes | Fee for the batch's pending withdrawals, or the fee charged once none are pending. Only returned by `GET /v2/payments/bulk-withdrawals/batches/{id}`; `null` elsewhere, and when the fee can't be quoted. |

**`uploadedByName` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | - |
| surname | string | Yes | - |

**`approvedByName` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | - |
| surname | string | Yes | - |

**`feeQuote` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| fee | string | Yes | Fee as a decimal string. `null` means the fee is unknown, which isn't the same as no fee. |
| currency | string | Yes | - |
| withdrawalCount | integer (int32) | Yes | Number of withdrawals the fee covers. |
| grossTotal | string | Yes | Sum of those withdrawals' amounts. |
| requiredTotal | string | Yes | Gross total plus fee: the available balance your payout account needs. |
| feeGroups | DisbursementFeeGroupForDisplay\[] | Yes | Breakdown by fee type; `null` when the quote is the fee already charged. |

**`feeGroups` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| actionType | string | Yes | `FAST_WITHDRAWAL` for banks that take real-time payments, otherwise `REGULAR_WITHDRAWAL`. |
| withdrawalCount | integer (int32) | Yes | - |
| grossTotal | string | Yes | - |

**Example:**

```json
{
  "id": "7c1e9a3b-5d2f-4b6a-8e0c-2a4b6c8d0e1f",
  "label": "November rent",
  "currency": "ZAR",
  "totalAmount": "45000.00",
  "withdrawalCount": 3,
  "status": "CANCELLED",
  "uploadedBy": "2e4a6c8e-0b1d-4f3a-9c5e-7a9b1d3f5a7c",
  "uploadedByName": {
    "name": "Lerato",
    "surname": "Mokoena"
  },
  "approvedBy": null,
  "approvedByName": null,
  "approvedAt": null,
  "createdAt": "2026-10-22T14:03:11.250Z",
  "updatedAt": "2026-10-23T08:40:27.733Z",
  "completedAt": null,
  "feeQuote": null
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=POST
REQUEST_PATH='/v2/payments/bulk-withdrawals/batches/{id}/cancel'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "POST"
path = "/v2/payments/bulk-withdrawals/batches/{id}/cancel"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | The batch ID isn't a valid UUID. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No batch with this ID exists on your account. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api/collections.md
description: >-
  Collect bank deposits from your payers with unique deposit references, then
  follow each payment to settlement.
---

# Collections

Collections let your payers pay you by bank transfer, with each deposit matched to the payer who made it. You give
every payer a unique deposit reference; when a deposit quoting that reference arrives, it's credited to your
collections account, matched to the reference and recorded as a payment. Collected funds are then settled to your
business, either in scheduled payout runs or instantly.

## How a collection works

1. **Create a deposit reference** for each payer, one at a time or in bulk, and give it to them. You can record the
   amount you expect and the payer's name and email to help you reconcile.
2. **The payer deposits**, quoting the reference. The deposit is credited and matched to the reference. If a payer
   quotes the wrong reference, link the deposit to the right one yourself.
3. **Follow the payment.** Each deposit becomes a payment with a step-by-step timeline: received, converted where your
   business converts collected funds, and settled.
4. **Settlement.** Collected funds are paid out to your business's settlement wallet, either in runs on a payout
   schedule set up with VALR or as instant payouts. Each settlement lists the payments it carried.

To hear about deposits as they're credited, subscribe a [webhook](/api/webhooks) to `FIAT_DEPOSIT_CREDITED`: its
`reference` is the deposit reference the deposit matched.

## Before you start

* **API key:** the `COLLECTIONS_WRITE` bundle creates, updates and deletes deposit references and reads collections.
  `PAYMENTS_READ` reads collections without changing anything.
* **Account:** collections work on your business as a whole. Call these endpoints without `X-VALR-SUB-ACCOUNT-ID`,
  with a key that isn't limited to specific sub-accounts; otherwise they return `401` with code `-93`.
* **Formats:** amounts are decimal strings. Paged lists return `items`, `total`, `limit` and `offset`. Page through
  payments and settlements with `limit` and `offset`, and through deposit references and deposits with `limit` and
  `skip`.

## Endpoints

### Getting paid

Deposits your business receives, from payers or to fund disbursements, and how each one is converted and paid out.

| Endpoint | Request | Needs |
|---|---|---|
| [List payments](/operations/getV2Payments) | `GET /v2/payments` | `COLLECTIONS_READ` |
| [Get a payment](/operations/getV2PaymentsById) | `GET /v2/payments/{id}` | `COLLECTIONS_READ` |
| [List collection activity](/operations/getV2PaymentsCollectionsHistory) | `GET /v2/payments/collections/history` | `COLLECTIONS_READ` |

### Deposit references

Unique references your payers quote when they deposit, so each deposit can be matched to a payer.

| Endpoint | Request | Needs |
|---|---|---|
| [Get a deposit reference](/operations/getV2WalletFiatByCurrencyPaymentReferencesByReferenceCode) | `GET /v2/wallet/fiat/{currency}/payment/references/{referenceCode}` | `COLLECTIONS_READ` |
| [Delete a deposit reference](/operations/deleteV2WalletFiatByCurrencyPaymentReferencesByReferenceCode) | `DELETE /v2/wallet/fiat/{currency}/payment/references/{referenceCode}` | `COLLECTIONS_DELETE` |
| [Update a deposit reference](/operations/putV2WalletFiatByCurrencyPaymentReferencesByReferenceCode) | `PUT /v2/wallet/fiat/{currency}/payment/references/{referenceCode}` | `COLLECTIONS_UPDATE` |
| [Create a deposit reference](/operations/postV2WalletFiatByCurrencyPaymentReferences) | `POST /v2/wallet/fiat/{currency}/payment/references` | `COLLECTIONS_CREATE` |
| [List deposit references](/operations/getV2WalletFiatByCurrencyPaymentReferences) | `GET /v2/wallet/fiat/{currency}/payment/references` | `COLLECTIONS_READ` |
| [Create deposit references in bulk](/operations/postV2WalletFiatByCurrencyPaymentBulkReferences) | `POST /v2/wallet/fiat/{currency}/payment/bulk-references` | `COLLECTIONS_CREATE` |
| [Get a bulk reference job](/operations/getV2WalletFiatByCurrencyPaymentBulkReferencesByJobId) | `GET /v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}` | `COLLECTIONS_READ` |
| [List bulk reference job items](/operations/getV2WalletFiatByCurrencyPaymentBulkReferencesByJobIdItems) | `GET /v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}/items` | `COLLECTIONS_READ` |
| [List credited deposits](/operations/getV2WalletFiatByCurrencyPaymentDeposits) | `GET /v2/wallet/fiat/{currency}/payment/deposits` | `COLLECTIONS_READ` |
| [Unlink a deposit from its reference](/operations/deleteV2WalletFiatByCurrencyPaymentDepositsByPublicIdReference) | `DELETE /v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference` | `COLLECTIONS_DELETE` |
| [Link a deposit to a reference](/operations/putV2WalletFiatByCurrencyPaymentDepositsByPublicIdReference) | `PUT /v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference` | `COLLECTIONS_UPDATE` |

### Collection schedules

Schedules that pay collected funds out at set times, the payments queued for each run, and the runs themselves.

| Endpoint | Request | Needs |
|---|---|---|
| [List queued scheduled payments](/operations/getV2PaymentsCollectEvents) | `GET /v2/payments/collect/events` | `COLLECTIONS_READ` |
| [Get a scheduled payment](/operations/getV2PaymentsCollectEventsById) | `GET /v2/payments/collect/events/{id}` | `COLLECTIONS_READ` |
| [List processed scheduled payments](/operations/getV2PaymentsCollectHistory) | `GET /v2/payments/collect/history` | `COLLECTIONS_READ` |
| [Get a payout run](/operations/getV2PaymentsCollectRunsById) | `GET /v2/payments/collect/runs/{id}` | `COLLECTIONS_READ` |
| [List a payout run's payments](/operations/getV2PaymentsCollectRunsByIdPayments) | `GET /v2/payments/collect/runs/{id}/payments` | `COLLECTIONS_READ` |
| [List payout runs](/operations/getV2PaymentsCollectRunsHistory) | `GET /v2/payments/collect/runs/history` | `COLLECTIONS_READ` |
| [List payout schedules](/operations/getV2PaymentsCollectSchedules) | `GET /v2/payments/collect/schedules` | `COLLECTIONS_READ` |
| [Get upcoming scheduled payouts](/operations/getV2PaymentsCollectUpcoming) | `GET /v2/payments/collect/upcoming` | `COLLECTIONS_READ` |

### Settlements

Payouts of collected funds, made instantly or by a scheduled run, and the payments each one paid out.

| Endpoint | Request | Needs |
|---|---|---|
| [List settlements](/operations/getV2PaymentsCollectSettlements) | `GET /v2/payments/collect/settlements` | `COLLECTIONS_READ` |
| [Get a settlement](/operations/getV2PaymentsCollectSettlementsById) | `GET /v2/payments/collect/settlements/{id}` | `COLLECTIONS_READ` |
| [List a settlement's payments](/operations/getV2PaymentsCollectSettlementsByIdPayments) | `GET /v2/payments/collect/settlements/{id}/payments` | `COLLECTIONS_READ` |
| [Get the settlement wallet](/operations/getV2PaymentsCollectSettlementsWallet) | `GET /v2/payments/collect/settlements/wallet` | `COLLECTIONS_READ` |

---

---
url: /api-docs/postV2PaymentsBulkWithdrawalsBeneficiaries.md
description: POST /v2/payments/bulk-withdrawals/beneficiaries
---

# Create a beneficiary

`POST /v2/payments/bulk-withdrawals/beneficiaries`

Saves a beneficiary you can pay out to. If an archived beneficiary has the same bank and account number, it's restored with these details and keeps its original ID.

**Requires** `DISBURSEMENTS_CREATE`, granted by `DISBURSEMENTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Request Body

**Content-Type:** `application/json`

| Property | Type | Required | Description |
|---|---|---|---|
| bank | string | Yes | Bank code from `GET /v2/payments/bulk-withdrawals/banks`, e.g. `FNB`. Case-insensitive. |
| accountHolder | string | No | - |
| accountNumber | string | No | - |
| branchCode | string | No | - |
| accountType | string | No | Account type: `CHEQUE`, `SAVINGS`, `BOND` or `TRANSMISSION`. Case-insensitive. |
| email | string | No | - |
| type | string | No | `INDIVIDUAL` or `BUSINESS`. Case-insensitive. |
| tradingName | string | No | - |
| reference | string | No | Default payment reference for this beneficiary. It isn't applied to payouts automatically: send it as the withdrawal's `reference`. |
| country | string | No | Country of registration as an ISO 3166 alpha-2 code, e.g. `ZA`. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | - |
| bank | string | Yes | - |
| bankDisplayName | string | Yes | - |
| accountHolder | string | Yes | - |
| accountNumberMasked | string | Yes | Account number with all but the last four digits masked. |
| accountNumber | string | Yes | - |
| branchCode | string | Yes | - |
| accountType | string | Yes | - |
| email | string | Yes | - |
| type | string | Yes | `INDIVIDUAL`, `BUSINESS`, or `null` if never set, which is possible for beneficiaries saved from a batch. |
| tradingName | string | Yes | - |
| reference | string | Yes | Default payment reference for this beneficiary. It isn't applied to payouts automatically. |
| country | string | Yes | - |
| createdAt | string (date-time) | Yes | - |
| updatedAt | string (date-time) | Yes | - |
| lastPaidAt | string (date-time) | Yes | When a payout to this beneficiary was last attempted; `null` if never. |
| deletedAt | string (date-time) | Yes | When the beneficiary was archived; `null` if it's active. |
| deletedBy | string | Yes | ID of the user or API key that archived the beneficiary. |

**Example:**

```json
{
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "bank": "FNB",
  "bankDisplayName": "FNB/RMB",
  "accountHolder": "Thandi Nkosi",
  "accountNumberMasked": "*******0327",
  "accountNumber": "62845190327",
  "branchCode": "250655",
  "accountType": "CHEQUE",
  "email": "thandi@example.com",
  "type": "INDIVIDUAL",
  "tradingName": null,
  "reference": "SALARY",
  "country": "ZA",
  "createdAt": "2026-09-01T10:12:30.004Z",
  "updatedAt": "2026-09-01T10:12:30.004Z",
  "lastPaidAt": null,
  "deletedAt": null,
  "deletedBy": null
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=POST
REQUEST_PATH='/v2/payments/bulk-withdrawals/beneficiaries'
BODY='{"bank":"<bank>","accountHolder":"<accountHolder>","accountNumber":"<accountNumber>","branchCode":"<branchCode>","accountType":"<accountType>","email":"<email>","type":"<type>","tradingName":"<tradingName>","reference":"<reference>","country":"<country>"}'
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}" -H "Content-Type: application/json" --data "$BODY"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "POST"
path = "/v2/payments/bulk-withdrawals/beneficiaries"
body = "{\"bank\":\"<bank>\",\"accountHolder\":\"<accountHolder>\",\"accountNumber\":\"<accountNumber>\",\"branchCode\":\"<branchCode>\",\"accountType\":\"<accountType>\",\"email\":\"<email>\",\"type\":\"<type>\",\"tradingName\":\"<tradingName>\",\"reference\":\"<reference>\",\"country\":\"<country>\"}"  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID
headers["Content-Type"] = "application/json"

response = requests.request(method, "https://api.valr.com" + path, headers=headers, data=body.encode())
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation; `validationErrors` lists each failing field. |
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 409 | `CONFLICT` | `CONFLICT` | An active beneficiary with this bank and account number already exists; update it instead. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/postV2WalletFiatByCurrencyPaymentReferences.md
description: 'POST /v2/wallet/fiat/{currency}/payment/references'
---

# Create a deposit reference

`POST /v2/wallet/fiat/{currency}/payment/references`

Creates a unique deposit reference for a payer. Give the reference to the payer; deposits that quote it are matched to it. You can record the amount you expect and the payer's name and email to help you reconcile deposits.

**Requires** `COLLECTIONS_CREATE`, granted by `COLLECTIONS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Fiat currency of the reference, e.g. `ZAR`. |

## Request Body

**Content-Type:** `application/json`

| Property | Type | Required | Description |
|---|---|---|---|
| expectedAmount | string | No | Amount you expect the payer to deposit, as a decimal string greater than zero. |
| name | string | No | Payer's name. |
| email | string | No | Payer's email address. |

## Responses

### 201

Created

| Property | Type | Required | Description |
|---|---|---|---|
| referenceCode | string | Yes | The reference your payer quotes when depositing. |
| currency | string | Yes | - |
| expectedAmount | string | No | - |
| createdAt | integer (int64) | Yes | When the reference was created, in Unix milliseconds. |
| name | string | No | - |
| email | string | No | - |
| matchedDeposits | UserMatchedDepositInfo\[] | Yes | Deposits matched to this reference. |
| matchedDepositCount | integer (int32) | Yes | - |

**`matchedDeposits` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| publicId | string (uuid) | Yes | - |
| amount | string | Yes | - |
| effectiveDate | string | Yes | - |
| creditedAt | integer (int64) | Yes | - |
| isOverride | boolean | Yes | `true` if this deposit is set as the reference's override deposit. |

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=POST
REQUEST_PATH='/v2/wallet/fiat/{currency}/payment/references'
BODY='{"expectedAmount":"<expectedAmount>","name":"<name>","email":"<email>"}'
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}" -H "Content-Type: application/json" --data "$BODY"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "POST"
path = "/v2/wallet/fiat/{currency}/payment/references"
body = "{\"expectedAmount\":\"<expectedAmount>\",\"name\":\"<name>\",\"email\":\"<email>\"}"  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID
headers["Content-Type"] = "application/json"

response = requests.request(method, "https://api.valr.com" + path, headers=headers, data=body.encode())
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation; `validationErrors` lists each failing field. |
| 400 | `-15721` | `SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH` | Your collections account doesn't support this currency. |
| 429 | `-15116` | `UNIQUE_DEPOSIT_REFERENCE_RATE_LIMIT_EXCEEDED` | You've reached the daily limit for creating references. |
| 429 | `-15119` | `UNIQUE_DEPOSIT_REFERENCE_OVERALL_LIMIT_EXCEEDED` | You've reached the maximum number of references. |
| 503 | `-15117` | `UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED` | Deposit references are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/postV2PaymentsBulkWithdrawalsBatches.md
description: POST /v2/payments/bulk-withdrawals/batches
---

# Create a disbursement batch

`POST /v2/payments/bulk-withdrawals/batches`

Creates a batch of ZAR payouts and executes it straight away: batches created with an API key skip the approval step, so the fee is charged and the payouts are submitted immediately, and the key needs the `DISBURSEMENTS_APPROVE` permission as well (the `DISBURSEMENTS_WRITE` bundle includes it). Your payout account must have enough available balance for the payouts plus the fee. `X-VALR-Idempotency-Key` is optional. Send one to make retries safe: repeating a key returns the original batch's ID with status 200. Without it, every request creates a new batch.

**Requires** `DISBURSEMENTS_CREATE` (granted by `DISBURSEMENTS_WRITE`) and `DISBURSEMENTS_APPROVE` (granted by `DISBURSEMENTS_WRITE`) ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| X-VALR-Idempotency-Key | header | string | No | Your unique key for this batch: up to 128 letters, digits, `:`, `_`, `.` or `-`. Reuse it only to retry the same request. |

## Request Body

**Content-Type:** `application/json`

| Property | Type | Required | Description |
|---|---|---|---|
| withdrawals | BulkWithdrawalItemRequest\[] | Yes | The payouts to make, one per recipient. |
| label | string | No | Your label for the batch, up to 64 characters. Defaults to the creation time in South African time, e.g. `23-10-26-10:15`. |

**`withdrawals` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| bank | string | Yes | Bank code from `GET /v2/payments/bulk-withdrawals/banks`, e.g. `FNB`. Case-insensitive. |
| accountHolder | string | No | Name on the recipient's bank account, 4 to 64 characters. |
| accountNumber | string | No | Recipient's account number, 4 to 18 digits. |
| branchCode | string | No | Recipient's branch code, 6 digits. |
| accountType | string | No | Account type: `CHEQUE`, `SAVINGS`, `BOND` or `TRANSMISSION`. Case-insensitive. |
| amount | number | No | Amount to pay in ZAR, greater than zero with at most two decimal places. |
| reference | string | No | Payment reference for this payout: up to 35 letters, digits, spaces, `/`, `'` or `-`. |
| email | string | No | Recipient's email address. Saved on their beneficiary, not sent with the payout. |
| type | string | No | `INDIVIDUAL` or `BUSINESS`. Saved on the recipient's beneficiary. Case-insensitive. |
| tradingName | string | No | Recipient's trading name. Saved on their beneficiary, not sent with the payout. |
| country | string | No | Recipient's country of registration as an ISO 3166 alpha-2 code, e.g. `ZA`. Saved on their beneficiary. |

## Responses

### 200

A batch with this idempotency key already exists. Its ID is returned and nothing new is created.

| Property | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | Batch ID. |

**Example:**

```json
{
  "id": "5b9a3c1e-2f4d-4a7b-9c8e-1d2f3a4b5c6d"
}
```

### 202

Batch created and executed. Check its progress with `GET /v2/payments/bulk-withdrawals/batches/{id}`; individual payouts can still fail.

| Property | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | Batch ID. |

**Example:**

```json
{
  "id": "5b9a3c1e-2f4d-4a7b-9c8e-1d2f3a4b5c6d"
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=POST
REQUEST_PATH='/v2/payments/bulk-withdrawals/batches'
BODY='{"withdrawals":"<withdrawals>","label":"<label>"}'
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}" -H "Content-Type: application/json" --data "$BODY"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "POST"
path = "/v2/payments/bulk-withdrawals/batches"
body = "{\"withdrawals\":\"<withdrawals>\",\"label\":\"<label>\"}"  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID
headers["Content-Type"] = "application/json"

response = requests.request(method, "https://api.valr.com" + path, headers=headers, data=body.encode())
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or has no `withdrawals` array, or `X-VALR-Idempotency-Key` isn't valid, in which case `validationErrors` names the header. |
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 409 | `CONFLICT` | `CONFLICT` | The idempotency key belongs to a batch that was cancelled, so retry with a new key, or to one that failed after its fee was charged, so contact support instead of retrying. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/postV1AccountSubaccount.md
description: POST /v1/account/subaccount
---

# Create a sub-account

`POST /v1/account/subaccount`

Creates a sub-account and returns its ID. Set `accountTags` to `["CLIENT_FUNDS"]` to mark it as an account for your clients' funds. Call it on your primary account (don't send `X-VALR-SUB-ACCOUNT-ID`); keys limited to some sub-accounts can't use it.

**Requires** `SUB_ACCOUNTS_MANAGE`, granted by `TREASURY_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| isProprietarySubAccount | query | boolean | No | Only matters if VALR has made KYC details mandatory for your sub-accounts: then `true` creates a sub-account with just a name, and with `false` the body must also include the account holder's KYC details. |

## Request Body

**Content-Type:** `application/json`

| Property | Type | Required | Description |
|---|---|---|---|
| label | string | Yes | Name for the sub-account: 1 to 64 letters, digits, spaces or hyphens. It must differ from your other sub-accounts' names, ignoring case, and can't be `Primary` or `Main`. |
| accountTags | string\[] | No | Tags to set on the new sub-account. The only tag you can set is `CLIENT_FUNDS`, which marks it as an account for your clients' funds; values VALR doesn't recognise are ignored. |

## Responses

### 200

Created. The body holds the new sub-account's ID as a string in `id`.

**Example:**

```json
{
  "id": "7339876125413376"
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=POST
REQUEST_PATH='/v1/account/subaccount'
BODY='{"label":"<label>","accountTags":"<accountTags>"}'
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}" -H "Content-Type: application/json" --data "$BODY"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "POST"
path = "/v1/account/subaccount"
body = "{\"label\":\"<label>\",\"accountTags\":\"<accountTags>\"}"  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID
headers["Content-Type"] = "application/json"

response = requests.request(method, "https://api.valr.com" + path, headers=headers, data=body.encode())
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation (`validationErrors` lists each failing field), or `isProprietarySubAccount` isn't `true` or `false`. |
| 400 | `-17214` | `INVALID_ACCOUNT_TAG_COMBINATION` | `accountTags` contains a tag other than `CLIENT_FUNDS`. |
| 403 | `-11132` | `SUB_ACCOUNT_ALREADY_EXISTS` | Another of your sub-accounts already has this name (ignoring case), or the name is `Primary` or `Main`. |
| 403 | `-11136` | `SUB_ACCOUNT_LIMIT_EXCEEDED` | Your business already has the maximum number of sub-accounts. |
| 409 | `-11423` | `SUB_ACCOUNT_PROFILE_INFO_ALREADY_EXISTS` | Only when KYC details are mandatory for your sub-accounts: another of your sub-accounts already has this email address, ID number or cell number. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/postV1Webhooks.md
description: POST /v1/webhooks
---

# Create a webhook

`POST /v1/webhooks`

Creates a webhook that sends the chosen event types to your URL. The response includes the webhook's signing secret, which you need to verify deliveries: it's shown only once and can't be retrieved later, so store it securely. The URL must use HTTPS and resolve to a public IP address, and a key restricted to sub-accounts can't manage webhooks.

**Requires** `WEBHOOKS_MANAGE`, granted by `WEBHOOKS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Request Body

**Content-Type:** `application/json`

| Property | Type | Required | Description |
|---|---|---|---|
| url | string | Yes | HTTPS URL to deliver events to, up to 2,048 characters. It must resolve to a public IP address and mustn't contain a username or password. Redirects aren't followed. |
| eventTypes | string\[] | Yes | Event types to send, from 1 to 20 `name` values returned by `GET /v1/webhooks/event-types`. |
| description | string | No | Your label for the webhook, up to 256 characters of letters, digits, spaces and punctuation. |

## Responses

### 201

Created

| Property | Type | Required | Description |
|---|---|---|---|
| subscription | object | Yes | The new webhook. |
| signingSecret | string | Yes | Secret for verifying deliveries. It's shown only in this response and can't be retrieved later, so store it securely. |

**`subscription` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| identifier | string | Yes | Webhook ID. |
| scopeKind | string | Yes | What the webhook is attached to. Always `ENTITY` for webhooks managed with an institution key: the webhook receives events for every account in your business. |
| scopeLabel | string | Yes | Readable label for `scopeKind`. |
| url | string | Yes | URL events are delivered to. |
| eventTypes | string\[] | Yes | Event types delivered to this webhook. |
| active | boolean | Yes | Whether events are delivered. An inactive webhook receives nothing until it's reactivated. |
| description | string | No | Your label for the webhook. Absent if you didn't set one. |
| signingSecretFingerprint | string | Yes | First 8 hex characters of the SHA-256 hash of the signing secret, so you can check which secret the webhook uses. The secret itself is only returned when the webhook is created. |
| createdAt | string | Yes | When the webhook was created, as an ISO 8601 timestamp in UTC. |
| updatedAt | string | Yes | When the webhook was last changed, as an ISO 8601 timestamp in UTC. |

**Example:**

```json
{
  "subscription": {
    "identifier": "0b8f5d2e-7a41-4c3b-9e6d-2f1a8c7b5e90",
    "scopeKind": "ENTITY",
    "scopeLabel": "Entity",
    "url": "https://hooks.example.com/valr",
    "eventTypes": [
      "FIAT_DEPOSIT_CREDITED",
      "FIAT_WITHDRAWAL_STATUS_UPDATE"
    ],
    "active": true,
    "description": "Treasury reconciliation",
    "signingSecretFingerprint": "7477002c",
    "createdAt": "2026-10-23T08:00:00.214367Z",
    "updatedAt": "2026-10-23T08:00:00.214367Z"
  },
  "signingSecret": "EXAMPLE-SIGNING-SECRET-do-not-use-000000000"
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=POST
REQUEST_PATH='/v1/webhooks'
BODY='{"url":"<url>","eventTypes":"<eventTypes>","description":"<description>"}'
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}" -H "Content-Type: application/json" --data "$BODY"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "POST"
path = "/v1/webhooks"
body = "{\"url\":\"<url>\",\"eventTypes\":\"<eventTypes>\",\"description\":\"<description>\"}"  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID
headers["Content-Type"] = "application/json"

response = requests.request(method, "https://api.valr.com" + path, headers=headers, data=body.encode())
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation; `validationErrors` lists each failing field. |
| 400 | `-18122` | `WEBHOOK_SUBSCRIPTION_LIMIT_REACHED` | Your business already has the maximum number of webhooks. Delete one you no longer need, then try again. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/postV2PaymentsBulkWithdrawalsBeneficiariesBulk.md
description: POST /v2/payments/bulk-withdrawals/beneficiaries/bulk
---

# Create beneficiaries in bulk

`POST /v2/payments/bulk-withdrawals/beneficiaries/bulk`

Saves a list of beneficiaries in one all-or-nothing request and returns them in the order sent. A beneficiary with the same bank and account number as an existing one updates it, restoring it if archived, instead of failing.

**Requires** `DISBURSEMENTS_CREATE`, granted by `DISBURSEMENTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Request Body

**Content-Type:** `application/json`

| Property | Type | Required | Description |
|---|---|---|---|
| beneficiaries | CreateBeneficiaryRequest\[] | Yes | The beneficiaries to save, each validated as for `POST /v2/payments/bulk-withdrawals/beneficiaries`. |

**`beneficiaries` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| bank | string | Yes | Bank code from `GET /v2/payments/bulk-withdrawals/banks`, e.g. `FNB`. Case-insensitive. |
| accountHolder | string | No | - |
| accountNumber | string | No | - |
| branchCode | string | No | - |
| accountType | string | No | Account type: `CHEQUE`, `SAVINGS`, `BOND` or `TRANSMISSION`. Case-insensitive. |
| email | string | No | - |
| type | string | No | `INDIVIDUAL` or `BUSINESS`. Case-insensitive. |
| tradingName | string | No | - |
| reference | string | No | Default payment reference for this beneficiary. It isn't applied to payouts automatically: send it as the withdrawal's `reference`. |
| country | string | No | Country of registration as an ISO 3166 alpha-2 code, e.g. `ZA`. |

## Responses

### 200

OK

Array of objects:

| Property | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | - |
| bank | string | Yes | - |
| bankDisplayName | string | Yes | - |
| accountHolder | string | Yes | - |
| accountNumberMasked | string | Yes | Account number with all but the last four digits masked. |
| accountNumber | string | Yes | - |
| branchCode | string | Yes | - |
| accountType | string | Yes | - |
| email | string | Yes | - |
| type | string | Yes | `INDIVIDUAL`, `BUSINESS`, or `null` if never set, which is possible for beneficiaries saved from a batch. |
| tradingName | string | Yes | - |
| reference | string | Yes | Default payment reference for this beneficiary. It isn't applied to payouts automatically. |
| country | string | Yes | - |
| createdAt | string (date-time) | Yes | - |
| updatedAt | string (date-time) | Yes | - |
| lastPaidAt | string (date-time) | Yes | When a payout to this beneficiary was last attempted; `null` if never. |
| deletedAt | string (date-time) | Yes | When the beneficiary was archived; `null` if it's active. |
| deletedBy | string | Yes | ID of the user or API key that archived the beneficiary. |

**Example:**

```json
[
  {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "bank": "FNB",
    "bankDisplayName": "FNB/RMB",
    "accountHolder": "Thandi Nkosi",
    "accountNumberMasked": "*******0327",
    "accountNumber": "62845190327",
    "branchCode": "250655",
    "accountType": "CHEQUE",
    "email": "thandi@example.com",
    "type": "INDIVIDUAL",
    "tradingName": null,
    "reference": "SALARY",
    "country": "ZA",
    "createdAt": "2026-09-01T10:12:30.004Z",
    "updatedAt": "2026-10-23T10:20:15.380Z",
    "lastPaidAt": null,
    "deletedAt": null,
    "deletedBy": null
  },
  {
    "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
    "bank": "STANDARD",
    "bankDisplayName": "Standard Bank",
    "accountHolder": "Karoo Fresh Produce (Pty) Ltd",
    "accountNumberMasked": "*****4058",
    "accountNumber": "271934058",
    "branchCode": "051001",
    "accountType": "CHEQUE",
    "email": "accounts@example.com",
    "type": "BUSINESS",
    "tradingName": "Karoo Fresh",
    "reference": null,
    "country": "ZA",
    "createdAt": "2026-10-23T10:20:15.380Z",
    "updatedAt": "2026-10-23T10:20:15.380Z",
    "lastPaidAt": null,
    "deletedAt": null,
    "deletedBy": null
  }
]
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=POST
REQUEST_PATH='/v2/payments/bulk-withdrawals/beneficiaries/bulk'
BODY='{"beneficiaries":"<beneficiaries>"}'
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}" -H "Content-Type: application/json" --data "$BODY"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "POST"
path = "/v2/payments/bulk-withdrawals/beneficiaries/bulk"
body = "{\"beneficiaries\":\"<beneficiaries>\"}"  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID
headers["Content-Type"] = "application/json"

response = requests.request(method, "https://api.valr.com" + path, headers=headers, data=body.encode())
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation; `validationErrors` lists each failing field. |
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/postV2WalletFiatByCurrencyPaymentBulkReferences.md
description: 'POST /v2/wallet/fiat/{currency}/payment/bulk-references'
---

# Create deposit references in bulk

`POST /v2/wallet/fiat/{currency}/payment/bulk-references`

Starts a background job that creates a deposit reference for each payer in `senders` and returns its `jobId`; if any payer is invalid or the batch would take you past your reference limits, the whole batch is rejected. Poll Get a bulk reference job until `status` is no longer `PROCESSING`, then list the job's items to get each payer's reference code.

**Requires** `COLLECTIONS_CREATE`, granted by `COLLECTIONS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Fiat currency of the references, e.g. `ZAR`. |

## Request Body

**Content-Type:** `application/json`

| Property | Type | Required | Description |
|---|---|---|---|
| senders | BulkSenderInput\[] | Yes | Payers to create references for, one reference each. |

**`senders` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Payer's name. |
| email | string | Yes | Payer's email address. |
| expectedAmount | string | No | Amount you expect the payer to deposit, as a decimal string greater than zero. |

## Responses

### 201

Created

| Property | Type | Required | Description |
|---|---|---|---|
| jobId | integer (int64) | Yes | ID of the job. Use it to check the job's status and read its items. |
| totalItems | integer (int32) | Yes | - |
| acceptedItems | integer (int32) | Yes | Number of payers accepted into the job. |

**Example:**

```json
{
  "jobId": 4182,
  "totalItems": 2,
  "acceptedItems": 2
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=POST
REQUEST_PATH='/v2/wallet/fiat/{currency}/payment/bulk-references'
BODY='{"senders":"<senders>"}'
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}" -H "Content-Type: application/json" --data "$BODY"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "POST"
path = "/v2/wallet/fiat/{currency}/payment/bulk-references"
body = "{\"senders\":\"<senders>\"}"  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID
headers["Content-Type"] = "application/json"

response = requests.request(method, "https://api.valr.com" + path, headers=headers, data=body.encode())
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation; `validationErrors` lists each failing field. |
| 400 | `-15121` | `BULK_DEPOSIT_REFERENCE_BATCH_TOO_LARGE` | `senders` has more payers than a single batch allows. Split them into smaller batches. |
| 400 | `-15721` | `SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH` | Your collections account doesn't support this currency. |
| 400 | `-15123` | `BULK_DEPOSIT_REFERENCE_INVALID_SENDER` | An entry in `senders` is `null`, a payer's name or email is missing or invalid, or their expected amount isn't a number greater than zero; the message identifies up to three such payers by their position in `senders`, and no job is created. |
| 409 | `-15124` | `BULK_DEPOSIT_REFERENCE_JOB_IN_PROGRESS` | An earlier bulk job is still processing. Wait for it to finish, then try again. |
| 429 | `-15119` | `UNIQUE_DEPOSIT_REFERENCE_OVERALL_LIMIT_EXCEEDED` | The batch would take you past the maximum number of references. Delete references you no longer need or submit fewer payers. |
| 429 | `-15116` | `UNIQUE_DEPOSIT_REFERENCE_RATE_LIMIT_EXCEEDED` | The batch would take you past the daily limit for creating references. Submit fewer payers or try again tomorrow. |
| 503 | `-15120` | `BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED` | Bulk deposit references are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/deleteV1WalletFiatByCurrencyAccountsById.md
description: 'DELETE /v1/wallet/fiat/{currency}/accounts/{id}'
---

# Delete a bank account

`DELETE /v1/wallet/fiat/{currency}/accounts/{id}`

Deletes a bank account linked to the account (the primary, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`) so it can't receive withdrawals any more. Send a `Content-Type: application/json` header even though the request has no body.

**Requires** `BANK_ACCOUNTS_MANAGE`, granted by `BANK_ACCOUNTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Fiat currency, e.g. `ZAR`. |
| id | path | string | Yes | Bank account ID: the `id` returned when it was linked or listed. |

## Responses

### 204

No content

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=DELETE
REQUEST_PATH='/v1/wallet/fiat/{currency}/accounts/{id}'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "DELETE"
path = "/v1/wallet/fiat/{currency}/accounts/{id}"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The bank account ID isn't a valid UUID, or the `Content-Type: application/json` header is missing. |
| 404 | `-14203` | `COULD_NOT_GET_LINKED_ACCOUNT` | No bank account with this ID is linked to the account. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/deleteV2WalletFiatByCurrencyPaymentReferencesByReferenceCode.md
description: 'DELETE /v2/wallet/fiat/{currency}/payment/references/{referenceCode}'
---

# Delete a deposit reference

`DELETE /v2/wallet/fiat/{currency}/payment/references/{referenceCode}`

Deletes a deposit reference, so it no longer appears in your list or search results and can't be retrieved or updated. Deleted references don't count towards your maximum number of references.

**Requires** `COLLECTIONS_DELETE`, granted by `COLLECTIONS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Fiat currency of the reference, e.g. `ZAR`. |
| referenceCode | path | string | Yes | The reference code returned when the reference was created. |

## Responses

### 204

No content

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=DELETE
REQUEST_PATH='/v2/wallet/fiat/{currency}/payment/references/{referenceCode}'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "DELETE"
path = "/v2/wallet/fiat/{currency}/payment/references/{referenceCode}"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 404 | `-15114` | `UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND` | No reference with this code exists on your account. |
| 503 | `-15117` | `UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED` | Deposit references are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/deleteV1AccountSubaccount.md
description: DELETE /v1/account/subaccount
---

# Delete a sub-account

`DELETE /v1/account/subaccount`

Deletes a sub-account, so it no longer appears in your account lists, and responds with 204. The sub-account must be empty first: no balances, reserved amounts or debt. Call it on your primary account (don't send `X-VALR-SUB-ACCOUNT-ID`); keys limited to some sub-accounts can't use it.

**Requires** `SUB_ACCOUNTS_MANAGE`, granted by `TREASURY_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Request Body

**Content-Type:** `application/json`

| Property | Type | Required | Description |
|---|---|---|---|
| id | integer (int64) | Yes | ID of the sub-account to delete. You can also send it as a string, which avoids losing precision in languages whose numbers are 64-bit floats. |

## Responses

### 204

No content

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=DELETE
REQUEST_PATH='/v1/account/subaccount'
BODY='{"id":0}'
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}" -H "Content-Type: application/json" --data "$BODY"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "DELETE"
path = "/v1/account/subaccount"
body = "{\"id\":0}"  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID
headers["Content-Type"] = "application/json"

response = requests.request(method, "https://api.valr.com" + path, headers=headers, data=body.encode())
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation; `validationErrors` lists each failing field. |
| 400 | `-11134` | `SUB_ACCOUNT_NOT_FOUND` | None of your business's sub-accounts has this `id`. |
| 400 | `-11163` | `CANNOT_DISABLE_SUB_ACCOUNT_WITH_BALANCES` | The sub-account still holds funds, reserved amounts or debt. Cancel its open orders, transfer its funds out and repay any borrowing, then try again. |
| 400 | `-17217` | `CANNOT_DISABLE_SYSTEM_PROVISIONED_SUB_ACCOUNT` | VALR set this sub-account up for you, so it can't be deleted. |
| 400 | `-17216` | `CANNOT_DISABLE_SHARED_SUB_ACCOUNT` | The sub-account is shared with another VALR user. Stop sharing it, then try again. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/deleteV1WebhooksById.md
description: 'DELETE /v1/webhooks/{id}'
---

# Delete a webhook

`DELETE /v1/webhooks/{id}`

Deletes a webhook so new events are no longer sent to it. Send a `Content-Type: application/json` header even though the request has no body. A key restricted to sub-accounts can't manage webhooks.

**Requires** `WEBHOOKS_MANAGE`, granted by `WEBHOOKS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | Yes | Webhook ID: the `identifier` returned when the webhook was created. |

## Responses

### 200

OK

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=DELETE
REQUEST_PATH='/v1/webhooks/{id}'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "DELETE"
path = "/v1/webhooks/{id}"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The webhook ID isn't a valid UUID, or the `Content-Type: application/json` header is missing. |
| 404 | `-18121` | `WEBHOOK_SUBSCRIPTION_NOT_FOUND` | No webhook with this ID exists for your business. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /guides/errors.md
description: >-
  Error responses for each endpoint, plus an index of every documented error
  code
---

# Errors

Errors return a JSON body with a `code` and a `message`, and an HTTP status that matches the code. Most endpoints use a numeric code:

```json
{ "code": -93, "message": "Unauthorized" }
```

When a request body fails validation, `validationErrors.errors` lists each failing `field` with a `message`. Endpoints under `/v2/payments` can also return errors from the payments service, which use a text code:

```json
{ "code": "NOT_FOUND", "message": "Resource not found." }
```

An unexpected failure returns HTTP 500 with `"message": "Unknown Error"`; quote the `code` to VALR support. Codes shown with `{placeholders}` in their message include a value that depends on your account or configuration.

## Common to all signed endpoints {#common-to-all-endpoints}

Authentication and authorisation. Any endpoint that takes an API key can return these; public endpoints can't.

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11268` | `API_KEY_API_KEY_HEADER_MISSING` | The `X-VALR-API-KEY` header is missing. |
| 400 | `-11269` | `API_KEY_SIGNATURE_HEADER_MISSING` | The `X-VALR-SIGNATURE` header is missing. |
| 400 | `-11270` | `API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID` | The `X-VALR-TIMESTAMP` header is missing or isn't a Unix timestamp in milliseconds. |
| 400 | `-11258` | `API_KEY_REQUEST_TIMESTAMP_TOO_EARLY` | The timestamp is too far in the past. Sign each request just before sending it. |
| 400 | `-11259` | `API_KEY_MESSAGE_TIMESTAMP_EXPIRED` | The timestamp is too far in the future. Check your clock. |
| 401 | `-11264` | `API_KEY_INVALID` | The API key doesn't exist or has been revoked. |
| 401 | `-11252` | `API_KEY_INVALID_SIGNATURE` | The signature doesn't match the request. Check the signed string: timestamp, method, path with query, body and sub-account ID. |
| 401 | `-11272` | `API_KEY_IP_NOT_WHITELISTED` | The request came from an IP address outside the key's allowed list. |
| 401 | `-93` | `UNAUTHORIZED` | The key isn't allowed to make this request: none of its bundles grants this endpoint's permission, the account isn't in the key's scope, the endpoint must be called on the primary account (don't send `X-VALR-SUB-ACCOUNT-ID`) or with a key that isn't restricted to sub-accounts, or institution keys are temporarily unavailable. |
| 403 | `-11277` | `API_KEY_ENDPOINT_NOT_ALLOWED` | The key's allowed-endpoints list doesn't include this endpoint. |
| 500 | `-11257` | `API_KEY_REQUEST_BLACKLISTED` | This exact signed request has already been used. Each signature is accepted once. |

## `GET /v2/wallet/fiat/{currency}/payment/references/{referenceCode}`

Get a deposit reference. [Endpoint reference](/operations/getV2WalletFiatByCurrencyPaymentReferencesByReferenceCode)

| HTTP | Code | Name | When |
|---|---|---|---|
| 404 | `-15114` | `UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND` | No reference with this code exists on your account. |
| 503 | `-15117` | `UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED` | Deposit references are temporarily unavailable. |

## `DELETE /v2/wallet/fiat/{currency}/payment/references/{referenceCode}`

Delete a deposit reference. [Endpoint reference](/operations/deleteV2WalletFiatByCurrencyPaymentReferencesByReferenceCode)

| HTTP | Code | Name | When |
|---|---|---|---|
| 404 | `-15114` | `UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND` | No reference with this code exists on your account. |
| 503 | `-15117` | `UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED` | Deposit references are temporarily unavailable. |

## `PUT /v2/wallet/fiat/{currency}/payment/references/{referenceCode}`

Update a deposit reference. [Endpoint reference](/operations/putV2WalletFiatByCurrencyPaymentReferencesByReferenceCode)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation; `validationErrors` lists each failing field. |
| 404 | `-15114` | `UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND` | No reference with this code exists on your account. |
| 503 | `-15117` | `UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED` | Deposit references are temporarily unavailable. |

## `POST /v2/wallet/fiat/{currency}/payment/references`

Create a deposit reference. [Endpoint reference](/operations/postV2WalletFiatByCurrencyPaymentReferences)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation; `validationErrors` lists each failing field. |
| 400 | `-15721` | `SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH` | Your collections account doesn't support this currency. |
| 429 | `-15116` | `UNIQUE_DEPOSIT_REFERENCE_RATE_LIMIT_EXCEEDED` | You've reached the daily limit for creating references. |
| 429 | `-15119` | `UNIQUE_DEPOSIT_REFERENCE_OVERALL_LIMIT_EXCEEDED` | You've reached the maximum number of references. |
| 503 | `-15117` | `UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED` | Deposit references are temporarily unavailable. |

## `GET /v2/wallet/fiat/{currency}/payment/references`

List deposit references. [Endpoint reference](/operations/getV2WalletFiatByCurrencyPaymentReferences)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `matched` isn't `true` or `false`, `skip` or `limit` isn't a whole number, `query`, `name` or `email` is empty or too long, or the currency isn't recognised. |
| 400 | `-15721` | `SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH` | Your collections account doesn't support this currency. |
| 503 | `-15117` | `UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED` | Deposit references are temporarily unavailable. |

## `GET /v1/account/balances`

Get balances. [Endpoint reference](/operations/getV1AccountBalances)

No endpoint-specific errors; see the common errors above.

## `GET /v2/payments/bulk-withdrawals/batches/{id}`

Get a disbursement batch. [Endpoint reference](/operations/getV2PaymentsBulkWithdrawalsBatchesById)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | The batch ID isn't a valid UUID. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No batch with this ID exists on your account. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `GET /v1/webhooks`

List webhooks. [Endpoint reference](/operations/getV1Webhooks)

No endpoint-specific errors; see the common errors above.

## `POST /v1/webhooks`

Create a webhook. [Endpoint reference](/operations/postV1Webhooks)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation; `validationErrors` lists each failing field. |
| 400 | `-18122` | `WEBHOOK_SUBSCRIPTION_LIMIT_REACHED` | Your business already has the maximum number of webhooks. Delete one you no longer need, then try again. |

## `DELETE /v1/webhooks/{id}`

Delete a webhook. [Endpoint reference](/operations/deleteV1WebhooksById)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The webhook ID isn't a valid UUID, or the `Content-Type: application/json` header is missing. |
| 404 | `-18121` | `WEBHOOK_SUBSCRIPTION_NOT_FOUND` | No webhook with this ID exists for your business. |

## `GET /v1/webhooks/{id}`

Get a webhook. [Endpoint reference](/operations/getV1WebhooksById)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The webhook ID isn't a valid UUID. |
| 404 | `-18121` | `WEBHOOK_SUBSCRIPTION_NOT_FOUND` | No webhook with this ID exists for your business. |

## `PUT /v1/webhooks/{id}`

Update a webhook. [Endpoint reference](/operations/putV1WebhooksById)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation; `validationErrors` lists each failing field. |
| 404 | `-18121` | `WEBHOOK_SUBSCRIPTION_NOT_FOUND` | No webhook with this ID exists for your business. |

## `GET /v1/webhooks/{id}/deliveries`

List webhook delivery attempts. [Endpoint reference](/operations/getV1WebhooksByIdDeliveries)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The webhook ID isn't a valid UUID, `skip` or `limit` isn't an integer, or `limit` is more than 100. |
| 404 | `-18121` | `WEBHOOK_SUBSCRIPTION_NOT_FOUND` | No webhook with this ID exists for your business. |

## `GET /v1/webhooks/{id}/events/{eventId}`

Get a webhook event. [Endpoint reference](/operations/getV1WebhooksByIdEventsByEventId)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The webhook ID or event ID isn't a valid UUID. |
| 404 | `-18121` | `WEBHOOK_SUBSCRIPTION_NOT_FOUND` | No webhook with this ID exists for your business. |
| 404 | `-18123` | `WEBHOOK_EVENT_NOT_FOUND` | This webhook hasn't sent an event with this ID. |

## `GET /v1/webhooks/event-types`

List webhook event types. [Endpoint reference](/operations/getV1WebhooksEventTypes)

No endpoint-specific errors; see the common errors above.

## `POST /v2/wallet/fiat/{currency}/payment/bulk-references`

Create deposit references in bulk. [Endpoint reference](/operations/postV2WalletFiatByCurrencyPaymentBulkReferences)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation; `validationErrors` lists each failing field. |
| 400 | `-15121` | `BULK_DEPOSIT_REFERENCE_BATCH_TOO_LARGE` | `senders` has more payers than a single batch allows. Split them into smaller batches. |
| 400 | `-15721` | `SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH` | Your collections account doesn't support this currency. |
| 400 | `-15123` | `BULK_DEPOSIT_REFERENCE_INVALID_SENDER` | An entry in `senders` is `null`, a payer's name or email is missing or invalid, or their expected amount isn't a number greater than zero; the message identifies up to three such payers by their position in `senders`, and no job is created. |
| 409 | `-15124` | `BULK_DEPOSIT_REFERENCE_JOB_IN_PROGRESS` | An earlier bulk job is still processing. Wait for it to finish, then try again. |
| 429 | `-15119` | `UNIQUE_DEPOSIT_REFERENCE_OVERALL_LIMIT_EXCEEDED` | The batch would take you past the maximum number of references. Delete references you no longer need or submit fewer payers. |
| 429 | `-15116` | `UNIQUE_DEPOSIT_REFERENCE_RATE_LIMIT_EXCEEDED` | The batch would take you past the daily limit for creating references. Submit fewer payers or try again tomorrow. |
| 503 | `-15120` | `BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED` | Bulk deposit references are temporarily unavailable. |

## `GET /v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}`

Get a bulk reference job. [Endpoint reference](/operations/getV2WalletFiatByCurrencyPaymentBulkReferencesByJobId)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The job ID isn't a whole number, or the currency isn't recognised. |
| 400 | `-15721` | `SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH` | Your collections account doesn't support this currency. |
| 404 | `-15122` | `BULK_DEPOSIT_REFERENCE_JOB_NOT_FOUND` | No bulk job with this ID exists on your account for this currency. |
| 503 | `-15120` | `BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED` | Bulk deposit references are temporarily unavailable. |

## `GET /v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}/items`

List bulk reference job items. [Endpoint reference](/operations/getV2WalletFiatByCurrencyPaymentBulkReferencesByJobIdItems)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The job ID, `skip` or `limit` isn't a whole number, `status` isn't `PENDING`, `SUCCESS` or `FAILED`, or the currency isn't recognised. |
| 400 | `-15721` | `SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH` | Your collections account doesn't support this currency. |
| 404 | `-15122` | `BULK_DEPOSIT_REFERENCE_JOB_NOT_FOUND` | No bulk job with this ID exists on your account for this currency. |
| 503 | `-15120` | `BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED` | Bulk deposit references are temporarily unavailable. |

## `GET /v2/wallet/fiat/{currency}/payment/deposits`

List credited deposits. [Endpoint reference](/operations/getV2WalletFiatByCurrencyPaymentDeposits)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `skip` or `limit` isn't a whole number, or the currency isn't recognised. |
| 400 | `-15721` | `SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH` | Your collections account doesn't support this currency. |
| 503 | `-15117` | `UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED` | Deposit references are temporarily unavailable. |

## `DELETE /v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference`

Unlink a deposit from its reference. [Endpoint reference](/operations/deleteV2WalletFiatByCurrencyPaymentDepositsByPublicIdReference)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The deposit ID isn't a valid UUID. |
| 404 | `-15118` | `FIAT_DEPOSIT_NOT_FOUND` | No deposit with this ID exists on your collections account. |

## `PUT /v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference`

Link a deposit to a reference. [Endpoint reference](/operations/putV2WalletFiatByCurrencyPaymentDepositsByPublicIdReference)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation; `validationErrors` lists each failing field. |
| 400 | `-15115` | `UNIQUE_DEPOSIT_REFERENCE_INVALID_OVERRIDE` | The deposit hasn't been fully credited yet. |
| 404 | `-15118` | `FIAT_DEPOSIT_NOT_FOUND` | No deposit with this ID exists on your collections account. |
| 404 | `-15114` | `UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND` | No reference with this code exists on your account. |

## `GET /v2/payments`

List payments. [Endpoint reference](/operations/getV2Payments)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `GET /v2/payments/{id}`

Get a payment. [Endpoint reference](/operations/getV2PaymentsById)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | The payment ID isn't a valid UUID. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No payment with this ID exists in your business. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `GET /v2/payments/collect/events`

List queued scheduled payments. [Endpoint reference](/operations/getV2PaymentsCollectEvents)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `GET /v2/payments/collect/events/{id}`

Get a scheduled payment. [Endpoint reference](/operations/getV2PaymentsCollectEventsById)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | The scheduled payment ID isn't a valid UUID. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No scheduled payment with this ID exists on your business's payout schedules. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `GET /v2/payments/collect/history`

List processed scheduled payments. [Endpoint reference](/operations/getV2PaymentsCollectHistory)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `GET /v2/payments/collect/runs/{id}`

Get a payout run. [Endpoint reference](/operations/getV2PaymentsCollectRunsById)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | The run ID isn't a valid UUID. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No payout run with this ID exists on your business's payout schedules. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `GET /v2/payments/collect/runs/{id}/payments`

List a payout run's payments. [Endpoint reference](/operations/getV2PaymentsCollectRunsByIdPayments)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | The run ID isn't a valid UUID. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `GET /v2/payments/collect/runs/history`

List payout runs. [Endpoint reference](/operations/getV2PaymentsCollectRunsHistory)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `GET /v2/payments/collect/schedules`

List payout schedules. [Endpoint reference](/operations/getV2PaymentsCollectSchedules)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `GET /v2/payments/collect/settlements`

List settlements. [Endpoint reference](/operations/getV2PaymentsCollectSettlements)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `GET /v2/payments/collect/settlements/{id}`

Get a settlement. [Endpoint reference](/operations/getV2PaymentsCollectSettlementsById)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | The settlement ID is longer than 64 characters, contains characters other than letters, digits, `.`, `_` and `-`, or is only dots. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No settlement with this ID exists in your business. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `GET /v2/payments/collect/settlements/{id}/payments`

List a settlement's payments. [Endpoint reference](/operations/getV2PaymentsCollectSettlementsByIdPayments)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | The settlement ID is longer than 64 characters, contains characters other than letters, digits, `.`, `_` and `-`, or is only dots. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No settlement with this ID exists in your business. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `GET /v2/payments/collect/settlements/wallet`

Get the settlement wallet. [Endpoint reference](/operations/getV2PaymentsCollectSettlementsWallet)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No settlement wallet is set up for your business. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `GET /v2/payments/collect/upcoming`

Get upcoming scheduled payouts. [Endpoint reference](/operations/getV2PaymentsCollectUpcoming)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `GET /v2/payments/collections/history`

List collection activity. [Endpoint reference](/operations/getV2PaymentsCollectionsHistory)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `GET /v2/payments/account/balances/{type}`

Get payments account balances. [Endpoint reference](/operations/getV2PaymentsAccountBalancesByType)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | `type` isn't one of `PAYOUT`, `COLLECTIONS`, `FUNDING` or `HOLD`. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | Your business has no account of this type set up for `currency`. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `GET /v2/payments/bulk-withdrawals/banks`

List supported banks. [Endpoint reference](/operations/getV2PaymentsBulkWithdrawalsBanks)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `GET /v2/payments/bulk-withdrawals/batches`

List disbursement batches. [Endpoint reference](/operations/getV2PaymentsBulkWithdrawalsBatches)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `POST /v2/payments/bulk-withdrawals/batches`

Create a disbursement batch. [Endpoint reference](/operations/postV2PaymentsBulkWithdrawalsBatches)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or has no `withdrawals` array, or `X-VALR-Idempotency-Key` isn't valid, in which case `validationErrors` names the header. |
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 409 | `CONFLICT` | `CONFLICT` | The idempotency key belongs to a batch that was cancelled, so retry with a new key, or to one that failed after its fee was charged, so contact support instead of retrying. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `POST /v2/payments/bulk-withdrawals/batches/{id}/cancel`

Cancel a disbursement batch. [Endpoint reference](/operations/postV2PaymentsBulkWithdrawalsBatchesByIdCancel)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | The batch ID isn't a valid UUID. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No batch with this ID exists on your account. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `GET /v2/payments/bulk-withdrawals/batches/{id}/fee-quote`

Get a batch's fee quote. [Endpoint reference](/operations/getV2PaymentsBulkWithdrawalsBatchesByIdFeeQuote)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | The batch ID isn't a valid UUID. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No batch with this ID exists on your account. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `PUT /v2/payments/bulk-withdrawals/batches/{id}/label`

Rename a disbursement batch. [Endpoint reference](/operations/putV2PaymentsBulkWithdrawalsBatchesByIdLabel)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation; `validationErrors` lists each failing field. |
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No batch with this ID exists on your account. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `GET /v2/payments/bulk-withdrawals/batches/{id}/withdrawals`

List a batch's withdrawals. [Endpoint reference](/operations/getV2PaymentsBulkWithdrawalsBatchesByIdWithdrawals)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | The batch ID isn't a valid UUID. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No batch with this ID exists on your account. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `GET /v2/payments/bulk-withdrawals/beneficiaries`

List beneficiaries. [Endpoint reference](/operations/getV2PaymentsBulkWithdrawalsBeneficiaries)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `POST /v2/payments/bulk-withdrawals/beneficiaries`

Create a beneficiary. [Endpoint reference](/operations/postV2PaymentsBulkWithdrawalsBeneficiaries)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation; `validationErrors` lists each failing field. |
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 409 | `CONFLICT` | `CONFLICT` | An active beneficiary with this bank and account number already exists; update it instead. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `DELETE /v2/payments/bulk-withdrawals/beneficiaries/{id}`

Archive a beneficiary. [Endpoint reference](/operations/deleteV2PaymentsBulkWithdrawalsBeneficiariesById)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | The beneficiary ID isn't a valid UUID. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No active beneficiary with this ID exists on your account; it may already be archived. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `GET /v2/payments/bulk-withdrawals/beneficiaries/{id}`

Get a beneficiary. [Endpoint reference](/operations/getV2PaymentsBulkWithdrawalsBeneficiariesById)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | The beneficiary ID isn't a valid UUID. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No beneficiary with this ID exists on your account. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `PUT /v2/payments/bulk-withdrawals/beneficiaries/{id}`

Update a beneficiary. [Endpoint reference](/operations/putV2PaymentsBulkWithdrawalsBeneficiariesById)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation; `validationErrors` lists each failing field. |
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No active beneficiary with this ID exists on your account; archived beneficiaries can't be updated. |
| 409 | `CONFLICT` | `CONFLICT` | Another beneficiary, active or archived, already has this bank and account number. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `POST /v2/payments/bulk-withdrawals/beneficiaries/bulk`

Create beneficiaries in bulk. [Endpoint reference](/operations/postV2PaymentsBulkWithdrawalsBeneficiariesBulk)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation; `validationErrors` lists each failing field. |
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `POST /v2/payments/bulk-withdrawals/fee-quote`

Quote fees for withdrawals. [Endpoint reference](/operations/postV2PaymentsBulkWithdrawalsFeeQuote)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation; `validationErrors` lists each failing field. |
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `GET /v2/payments/bulk-withdrawals/withdrawals`

List withdrawals. [Endpoint reference](/operations/getV2PaymentsBulkWithdrawalsWithdrawals)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `GET /v2/payments/payout/history`

List payout account transactions. [Endpoint reference](/operations/getV2PaymentsPayoutHistory)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `GET /v2/payments/payout/history/{id}`

Get a payout account transaction. [Endpoint reference](/operations/getV2PaymentsPayoutHistoryById)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | The transaction ID isn't a valid UUID. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No payout account transaction with this ID exists on your account. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

## `GET /v1/wallet/crypto/{currency}/deposit/address`

Get a crypto deposit address. [Endpoint reference](/operations/getV1WalletCryptoByCurrencyDepositAddress)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The currency or `destinationCurrency` isn't recognised, or `accountType` is blank or isn't `COLLECTIONS`, `FUNDING` or `PAYOUTS`. |
| 400 | `-112` | `CURRENCY_NOT_SUPPORTED` | `networkType` wasn't sent and the currency can't be deposited on a blockchain, for example a fiat currency. |
| 400 | `-15721` | `SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH` | Your business has no account of the requested `accountType` set up for `destinationCurrency`. |
| 400 | `-13105` | `RECEIVE_ADDRESS_NOT_SUPPORTED_FOR_CURRENCY_NETWORK_TYPE` | The account has no address for this currency and network yet, and deposits on this network are disabled or not supported for this currency. |
| 403 | `-13104` | `RECEIVE_ADDRESS_NOT_SUPPORTED_IN_REGION` | The account has no address for this currency and network yet, and crypto deposits are restricted for your business, so a new one can't be created. |
| 500 | `-30` | `COULD_NOT_GET_RECEIVE_ADDRESS` | A new deposit address couldn't be created. Try again later. |

## `GET /v1/wallet/crypto/{currency}/deposit/history`

List crypto deposits for a currency. [Endpoint reference](/operations/getV1WalletCryptoByCurrencyDepositHistory)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `skip` or `limit` isn't a whole number, `limit` is more than 100, `startTime` or `endTime` isn't an ISO 8601 timestamp, or the currency isn't recognised. |

## `GET /v1/wallet/crypto/{currency}/withdraw`

Get crypto withdrawal settings. [Endpoint reference](/operations/getV1WalletCryptoByCurrencyWithdraw)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The currency isn't recognised. |
| 400 | `-112` | `CURRENCY_NOT_SUPPORTED` | `networkType` wasn't sent and the currency can't be withdrawn on a blockchain, for example a fiat currency. |

## `POST /v1/wallet/crypto/{currency}/withdraw`

Withdraw crypto. [Endpoint reference](/operations/postV1WalletCryptoByCurrencyWithdraw)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The currency isn't recognised, or the body fails validation, for example `amount` isn't a positive decimal, both or neither of `address` and `addressBookId` are sent, or the recipient's details are missing; `validationErrors` lists each failing field. |
| 400 | `-13427` | `NON_ADDRESS_BOOK_WITHDRAWALS_DISABLED` | Withdrawals are restricted to address-book entries, and the address isn't saved in the account's address book. |
| 400 | `-13428` | `ADDRESS_BOOK_ENTRY_STILL_WARMING_UP` | Withdrawals are restricted to address-book entries, and this entry was added or changed too recently. Try again once its waiting period has passed. |
| 400 | `-13415` | `WITHDRAWALS_TEMPORARILY_SUSPENDED` | Withdrawals are paused after a recent security change on your account; the message says when they resume. Withdrawals to address-book entries may still be allowed. |
| 400 | `-112` | `CURRENCY_NOT_SUPPORTED` | The currency can't be withdrawn on a blockchain, for example a fiat currency. |
| 400 | `-13018` | `BLOCKCHAIN_INVALID_NETWORK_FOR_CURRENCY` | The network isn't available for this currency. |
| 400 | `-13402` | `CURRENCY_DOES_NOT_SUPPORT_PAYMENT_REFERENCE` | A `paymentReference` was sent, but this currency and network don't use one. |
| 400 | `-13410` | `PAYMENT_REFERENCE_MISSING` | The address needs a payment reference, such as a memo or tag; send it in `paymentReference`. |
| 400 | `-13405` | `INVALID_WITHDRAW_TRANSACTION_REFERENCE` | The `paymentReference` isn't valid for this network. |
| 400 | `-50` | `INVALID_WITHDRAW_ADDRESS` | The address isn't valid for this currency and network. |
| 400 | `-13411` | `WITHDRAW_AMOUNT_BELOW_MINIMUM` | The amount is below the network's minimum, which the message gives. |
| 400 | `-13404` | `INVALID_WITHDRAW_AMOUNT` | The network rejected the amount, for example because it has too many decimal places. |
| 400 | `-13419` | `NETWORK_FEE_FOR_TRANSACTION_EXCEEDED` | Sending to this address would need more network fee than is allowed, so it can't receive withdrawals. |
| 400 | `-13017` | `BLOCKCHAIN_SEND_TRUSTLINE_NOT_VALID` | The destination address has no active trustline for this asset. |
| 400 | `-13019` | `BLOCKCHAIN_SEND_MISSING_KYC_PERMIT` | The token issuer hasn't whitelisted the destination address. |
| 400 | `-30071` | `SERVICE_PROVIDER_NOT_FOUND` | `serviceProviderId` isn't in the list from `GET /v1/wallet/crypto/service-providers`. |
| 400 | `-6` | `INSUFFICIENT_BALANCE` | The account's available balance doesn't cover the amount plus the network fee. |
| 400 | `-108` | `WITHDRAW_LIMIT_REACHED` | The withdrawal would exceed your business's withdrawal limit; see `GET /v1/wallet/crypto/{currency}/withdraw/limits`. |
| 400 | `-32765` | `WITHDRAWAL_RESTRICTION_APPLIED` | Your business must keep a minimum portfolio value, and this withdrawal would take it below that. |
| 400 | `-19213` | `MARGIN_NOT_ENABLED_FOR_ACCOUNT` | `allowBorrow` is `true`, but margin isn't enabled on the account. |
| 400 | `-19243` | `BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE` | `allowBorrow` is `true`, but borrowing for withdrawals is currently unavailable. |
| 400 | `-19244` | `BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY` | `allowBorrow` is `true`, but this currency can't be borrowed for withdrawals. |
| 404 | `-13422` | `ADDRESS_BOOK_ENTRY_NOT_FOUND` | No entry with this `addressBookId` exists in the account's address book. |
| 500 | `-13423` | `ADDRESS_BOOK_ENTRY_CURRENCY_WRONG` | The address-book entry is saved for a different currency. |
| 500 | `-19502` | `CURRENCY_UNDER_MAINTENANCE` | The currency is under maintenance. Try again in a few minutes. |
| 500 | `-46` | `WITHDRAW_UNAVAILABLE` | Withdrawals of this currency on this network are currently disabled, or the withdrawal couldn't be recorded. Try again later. |
| 500 | `-29` | `BLOCKCHAIN_SEND_FAILURE` | The withdrawal couldn't be checked with the network. Try again later. |
| 500 | `-19202` | `INSUFFICIENT_LIQUIDITY_FOR_BORROW` | `allowBorrow` is `true`, but the amount can't be borrowed right now. Try again later. |
| 503 | `-12015` | `WITHDRAWALS_NOT_AVAILABLE` | Withdrawals are temporarily unavailable. |

## `GET /v1/wallet/crypto/{currency}/withdraw/{id}`

Get a crypto withdrawal. [Endpoint reference](/operations/getV1WalletCryptoByCurrencyWithdrawById)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The currency isn't recognised or the withdrawal ID isn't a valid UUID. |
| 404 | `-13403` | `SEND_NOT_FOUND` | No withdrawal with this ID exists on the account, or it's in a different currency. |

## `GET /v1/wallet/crypto/{currency}/withdraw/history`

List crypto withdrawals for a currency. [Endpoint reference](/operations/getV1WalletCryptoByCurrencyWithdrawHistory)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `skip` or `limit` isn't a whole number, `limit` is more than 100, `startTime` or `endTime` isn't an ISO 8601 timestamp, or the currency isn't recognised. |

## `GET /v1/wallet/crypto/{currency}/withdraw/limits`

Get crypto withdrawal limits. [Endpoint reference](/operations/getV1WalletCryptoByCurrencyWithdrawLimits)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The currency isn't recognised. |

## `GET /v1/wallet/crypto/address-book`

List address-book entries. [Endpoint reference](/operations/getV1WalletCryptoAddressBook)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `skip` or `limit` isn't a whole number, `limit` is more than 100, or `networkType` is blank. |

## `GET /v1/wallet/crypto/address-book/{currency}`

List address-book entries for a currency. [Endpoint reference](/operations/getV1WalletCryptoAddressBookByCurrency)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The currency isn't recognised, `skip` or `limit` isn't a whole number, `limit` is more than 100, or `networkType` is blank. |

## `GET /v1/wallet/crypto/deposit/history`

List crypto deposits. [Endpoint reference](/operations/getV1WalletCryptoDepositHistory)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `skip` or `limit` isn't a whole number, `limit` is more than 100, `startTime` or `endTime` isn't an ISO 8601 timestamp, or the currency isn't recognised. |

## `GET /v1/wallet/crypto/service-providers`

List service providers. [Endpoint reference](/operations/getV1WalletCryptoServiceProviders)

No endpoint-specific errors; see the common errors above.

## `GET /v1/wallet/crypto/withdraw/history`

List crypto withdrawals. [Endpoint reference](/operations/getV1WalletCryptoWithdrawHistory)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `skip` or `limit` isn't a whole number, `limit` is more than 100, `startTime` or `endTime` isn't an ISO 8601 timestamp, or the currency isn't recognised. |

## `GET /v1/wallet/fiat/{currency}/accounts`

List bank accounts. [Endpoint reference](/operations/getV1WalletFiatByCurrencyAccounts)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The currency isn't recognised. |
| 451 | `-15320` | `FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY` | Your business's region doesn't allow withdrawals in this currency. |

## `POST /v1/wallet/fiat/{currency}/accounts`

Link a bank account. [Endpoint reference](/operations/postV1WalletFiatByCurrencyAccounts)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation, including a `bank` that isn't in the country's bank list or a branch code, account number or account type that doesn't fit the country, or the currency isn't recognised; `validationErrors` lists each failing field. |
| 400 | `-15875` | `FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED` | Withdrawals to this branch code aren't supported. Use another branch or contact support. |
| 400 | `-13418` | `BANK_ACCOUNT_LINKING_TEMPORARILY_DISABLED` | Linking bank accounts is paused for a while after a security change on your account, such as a password reset or a new device; the message says when it's re-enabled. |
| 400 | `-115` | `INVALID_COUNTRY_ALPHA_2` | No banks are available for the bank account's country. |
| 451 | `-15320` | `FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY` | Your business's region doesn't allow withdrawals in this currency. |
| 500 | `-15317` | `BANK_REMOTE_FETCH_FAILURE` | The bank list for the bank account's country couldn't be loaded. Try again later. |

## `DELETE /v1/wallet/fiat/{currency}/accounts/{id}`

Delete a bank account. [Endpoint reference](/operations/deleteV1WalletFiatByCurrencyAccountsById)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The bank account ID isn't a valid UUID, or the `Content-Type: application/json` header is missing. |
| 404 | `-14203` | `COULD_NOT_GET_LINKED_ACCOUNT` | No bank account with this ID is linked to the account. |

## `GET /v1/wallet/fiat/{currency}/accounts/{id}`

Get a bank account. [Endpoint reference](/operations/getV1WalletFiatByCurrencyAccountsById)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The currency isn't recognised or the bank account ID isn't a valid UUID. |
| 404 | `-14203` | `COULD_NOT_GET_LINKED_ACCOUNT` | No bank account with this ID is linked to the account. |
| 451 | `-15320` | `FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY` | Your business's region doesn't allow withdrawals in this currency. |

## `GET /v1/wallet/fiat/{currency}/banks`

List banks for a currency. [Endpoint reference](/operations/getV1WalletFiatByCurrencyBanks)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The currency isn't recognised. |
| 400 | `-112` | `CURRENCY_NOT_SUPPORTED` | Bank accounts can't be linked in this currency. |
| 451 | `-15320` | `FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY` | Your business's region doesn't allow withdrawals in this currency. |
| 500 | `-15317` | `BANK_REMOTE_FETCH_FAILURE` | The bank list couldn't be loaded. Try again later. |

## `GET /v1/wallet/fiat/{currency}/deposit/reference`

Get the account deposit reference. [Endpoint reference](/operations/getV1WalletFiatByCurrencyDepositReference)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The currency isn't recognised. |
| 451 | `-15111` | `FIAT_DEPOSITS_NOT_ALLOWED_FOR_CURRENCY` | Your business's region doesn't allow deposits in this currency. |

## `GET /v1/wallet/fiat/{currency}/deposit/reference/{buyCurrencySymbol}`

Get an auto-buy deposit reference. [Endpoint reference](/operations/getV1WalletFiatByCurrencyDepositReferenceByBuyCurrencySymbol)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `currency` or `buyCurrencySymbol` isn't a recognised currency. |
| 400 | `-21` | `INVALID_CURRENCY_PAIR` | There's no market for buying `buyCurrencySymbol` with `currency`. |
| 400 | `-32` | `CURRENCY_PAIR_NOT_ACTIVE` | The market for buying `buyCurrencySymbol` with `currency` isn't active. |
| 400 | `-15132` | `CURRENCY_NOT_ENABLED_FOR_FIAT_DEPOSIT_AUTO_BUY` | `buyCurrencySymbol` can't be auto-bought with `currency`; list the currencies that can with List auto-buy currencies. |
| 451 | `-15134` | `CURRENCY_NOT_ALLOWED_FOR_FIAT_DEPOSIT_AUTO_BUY` | Auto-buy into `buyCurrencySymbol` with `currency` isn't available for your business. |
| 451 | `-15111` | `FIAT_DEPOSITS_NOT_ALLOWED_FOR_CURRENCY` | Your business's region doesn't allow deposits in `currency`. |

## `GET /v1/wallet/fiat/{currency}/auto-buy`

List auto-buy currencies. [Endpoint reference](/operations/getV1WalletFiatByCurrencyAutoBuy)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The currency isn't recognised. |

## `GET /v1/wallet/fiat/{currency}/withdraw/estimate-fee`

Estimate a fiat withdrawal fee. [Endpoint reference](/operations/getV1WalletFiatByCurrencyWithdrawEstimateFee)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `linkedBankAccountId` is missing or isn't a UUID, `amount` is missing or isn't a number, `fast` isn't `true` or `false`, or the currency isn't recognised. |
| 404 | `-14203` | `COULD_NOT_GET_LINKED_ACCOUNT` | No bank account with this ID exists. |

## `POST /v1/wallet/fiat/{currency}/withdraw`

Withdraw fiat to a bank account. [Endpoint reference](/operations/postV1WalletFiatByCurrencyWithdraw)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation, or `reference` was rejected, or the currency isn't recognised; `validationErrors` lists each failing field. |
| 400 | `-13415` | `WITHDRAWALS_TEMPORARILY_SUSPENDED` | Withdrawals are paused for a while after a security change on your account, such as a password reset or a new device; the message says when they're re-enabled. |
| 400 | `-32765` | `WITHDRAWAL_RESTRICTION_APPLIED` | The withdrawal would take your portfolio below the minimum value it must keep. |
| 400 | `-15875` | `FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED` | Withdrawals to the bank account's branch code aren't supported. Use another bank account or contact support. |
| 400 | `-15307` | `FIAT_WITHDRAWAL_AMOUNT_BELOW_MINIMUM` | `amount` is below the minimum withdrawal for this currency. |
| 400 | `-15318` | `FIAT_WITHDRAWAL_CURRENCY_MISMATCH` | The bank account was linked for a different currency. |
| 400 | `-6` | `INSUFFICIENT_BALANCE` | The account's available balance doesn't cover `amount` plus the fee. |
| 400 | `-15322` | `CAN_NOT_WITHDRAW_TO_A_DELETED_BANK_ACCOUNT` | The bank account has been deleted. Link it again to withdraw to it. |
| 400 | `-15321` | `CAN_NOT_WITHDRAW_TO_AN_UNCONFIRMED_BANK_ACCOUNT` | The bank account was never confirmed. |
| 400 | `-15309` | `CAN_NOT_WITHDRAW_TO_AN_UNVERIFIED_BANK_ACCOUNT` | This currency only pays out to verified bank accounts, and this one hasn't been verified yet or failed verification. |
| 400 | `-19243` | `BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE` | `allowBorrow` was set, but borrowing for withdrawals is unavailable at the moment. |
| 400 | `-19244` | `BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY` | `allowBorrow` was set, but this currency can't be borrowed for a withdrawal. |
| 400 | `-19213` | `MARGIN_NOT_ENABLED_FOR_ACCOUNT` | `allowBorrow` was set, but margin isn't enabled on the account. |
| 400 | `-11533` | `CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING` | Borrowing the shortfall would exceed the account's borrow limit for this currency. |
| 400 | `-11534` | `ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING` | Borrowing the shortfall would exceed the account's total borrow limit. |
| 404 | `-14203` | `COULD_NOT_GET_LINKED_ACCOUNT` | No bank account with `linkedBankAccountId` exists. |
| 451 | `-15320` | `FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY` | Your business's region doesn't allow withdrawals in this currency. |
| 500 | `-19202` | `INSUFFICIENT_LIQUIDITY_FOR_BORROW` | `allowBorrow` was set, but the amount to borrow isn't available right now. Try again later. |
| 503 | `-12015` | `WITHDRAWALS_NOT_AVAILABLE` | Withdrawals are unavailable at the moment. Try again later. |

## `GET /v1/wallet/fiat/{currency}/withdrawals`

List fiat withdrawals. [Endpoint reference](/operations/getV1WalletFiatByCurrencyWithdrawals)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `status` is empty or isn't one of the listed values, `limit` or `offset` isn't a whole number, `includeAllSubAccounts` isn't `true` or `false`, or the currency isn't recognised. |

## `GET /v1/wallet/fiat/{currency}/withdrawals/{id}`

Get a fiat withdrawal. [Endpoint reference](/operations/getV1WalletFiatByCurrencyWithdrawalsById)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The withdrawal ID isn't a valid UUID, `includeAllSubAccounts` isn't `true` or `false`, or the currency isn't recognised. |
| 404 | `-15300` | `COULD_NOT_FIND_FIAT_WITHDRAWAL` | No withdrawal in this currency with this ID exists on the account, or on any of your business's visible accounts when `includeAllSubAccounts` applies. |

## `POST /v2/fiat/payments`

Pay a bank beneficiary. [Endpoint reference](/operations/postV2FiatPayments)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation, including a `newBeneficiary` field or a `newBeneficiary.bank` that isn't in the country's bank list, or `reference` was rejected; `validationErrors` lists each failing field. |
| 400 | `-109` | `INVALID_CURRENCY_SYMBOL` | `currency` isn't a recognised currency. |
| 400 | `-18104` | `PAYMENT_BENEFICIARY_DETAILS_REQUIRED` | Neither `beneficiaryId` nor `newBeneficiary` was sent. |
| 400 | `-115` | `INVALID_COUNTRY_ALPHA_2` | No banks are available for `newBeneficiary`'s country. |
| 400 | `-13418` | `BANK_ACCOUNT_LINKING_TEMPORARILY_DISABLED` | Adding a beneficiary is paused for a while after a security change on your account; the message says when it's re-enabled. You can still pay an existing beneficiary. |
| 400 | `-15875` | `FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED` | Payments to the beneficiary's branch code aren't supported. Use another bank account or contact support. |
| 400 | `-13415` | `WITHDRAWALS_TEMPORARILY_SUSPENDED` | Withdrawals are paused for a while after a security change on your account, such as a password reset or a new device; the message says when they're re-enabled. |
| 400 | `-32765` | `WITHDRAWAL_RESTRICTION_APPLIED` | The payment would take your portfolio below the minimum value it must keep. |
| 400 | `-15307` | `FIAT_WITHDRAWAL_AMOUNT_BELOW_MINIMUM` | `amount` is below the minimum withdrawal for this currency. |
| 400 | `-15318` | `FIAT_WITHDRAWAL_CURRENCY_MISMATCH` | The beneficiary's bank account was linked for a different currency from `currency`. |
| 400 | `-6` | `INSUFFICIENT_BALANCE` | The account's available balance doesn't cover `amount` plus the fee. |
| 400 | `-15309` | `CAN_NOT_WITHDRAW_TO_AN_UNVERIFIED_BANK_ACCOUNT` | This currency only pays out to verified bank accounts, and the beneficiary hasn't been verified yet or failed verification. |
| 404 | `-18106` | `PAYMENTS_API_DISABLED` | This endpoint isn't available yet. |
| 404 | `-14203` | `COULD_NOT_GET_LINKED_ACCOUNT` | No bank account with `beneficiaryId` exists. |
| 409 | `-18103` | `PAYMENT_BENEFICIARY_NOT_ACTIVE` | The beneficiary with `beneficiaryId` was never confirmed or has been deleted. |
| 451 | `-15320` | `FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY` | Your business's region doesn't allow withdrawals in this currency. |
| 500 | `-15317` | `BANK_REMOTE_FETCH_FAILURE` | The bank list for `newBeneficiary`'s country couldn't be loaded. Try again later. |
| 503 | `-12015` | `WITHDRAWALS_NOT_AVAILABLE` | Withdrawals are unavailable at the moment. Try again later. |

## `POST /v2/crypto/payments`

Pay a crypto beneficiary. [Endpoint reference](/operations/postV2CryptoPayments)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation, including a `newBeneficiary` field or missing travel-rule details (`beneficiaryName`, `isCorporate`, `isSelfHosted`, and a service provider for a hosted wallet) for an address outside VALR; `validationErrors` lists each failing field. |
| 400 | `-109` | `INVALID_CURRENCY_SYMBOL` | `currency` isn't a recognised currency. |
| 400 | `-18104` | `PAYMENT_BENEFICIARY_DETAILS_REQUIRED` | Neither `beneficiaryId` nor `newBeneficiary` was sent. |
| 400 | `-13426` | `ADDRESS_BOOK_ENTRY_LABEL_IN_USE` | Another address-book entry on the account already uses `newBeneficiary.label`. |
| 400 | `-50` | `INVALID_WITHDRAW_ADDRESS` | The beneficiary's address isn't valid for this currency and network. |
| 400 | `-13410` | `PAYMENT_REFERENCE_MISSING` | The beneficiary's address needs a payment reference, such as a memo or tag. |
| 400 | `-13405` | `INVALID_WITHDRAW_TRANSACTION_REFERENCE` | The beneficiary's payment reference isn't valid for this address. |
| 400 | `-13402` | `CURRENCY_DOES_NOT_SUPPORT_PAYMENT_REFERENCE` | The beneficiary has a payment reference, but this currency and network don't use one. |
| 400 | `-13415` | `WITHDRAWALS_TEMPORARILY_SUSPENDED` | Withdrawals are paused for a while after a security change on your account, such as a password reset or a new device; the message says when they're re-enabled. |
| 400 | `-13411` | `WITHDRAW_AMOUNT_BELOW_MINIMUM` | `amount` is below the minimum withdrawal for this currency and network. |
| 400 | `-13404` | `INVALID_WITHDRAW_AMOUNT` | `amount` isn't valid for this currency and network, for example it has too many decimal places. |
| 400 | `-13419` | `NETWORK_FEE_FOR_TRANSACTION_EXCEEDED` | Withdrawals to the beneficiary's address aren't allowed because sending to it would cost too much in network fees. |
| 400 | `-6` | `INSUFFICIENT_BALANCE` | The account's available balance doesn't cover `amount` plus the network fee. |
| 400 | `-108` | `WITHDRAW_LIMIT_REACHED` | The payment would exceed your daily withdrawal limit. |
| 400 | `-32765` | `WITHDRAWAL_RESTRICTION_APPLIED` | The payment would take your portfolio below the minimum value it must keep. |
| 400 | `-19243` | `BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE` | `allowBorrow` was set, but borrowing for withdrawals is unavailable at the moment. |
| 400 | `-19244` | `BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY` | `allowBorrow` was set, but this currency can't be borrowed for a withdrawal. |
| 400 | `-19213` | `MARGIN_NOT_ENABLED_FOR_ACCOUNT` | `allowBorrow` was set, but margin isn't enabled on the account. |
| 400 | `-11533` | `CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING` | Borrowing the shortfall would exceed the account's borrow limit for this currency. |
| 400 | `-11534` | `ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING` | Borrowing the shortfall would exceed the account's total borrow limit. |
| 404 | `-18106` | `PAYMENTS_API_DISABLED` | This endpoint isn't available yet. |
| 404 | `-18101` | `PAYMENT_BENEFICIARY_NOT_FOUND` | No address-book entry with `beneficiaryId` exists on the account. |
| 409 | `-18103` | `PAYMENT_BENEFICIARY_NOT_ACTIVE` | The address-book entry with `beneficiaryId` hasn't been activated. |
| 500 | `-19502` | `CURRENCY_UNDER_MAINTENANCE` | Withdrawals of this currency are paused for maintenance. Try again in a few minutes. |
| 500 | `-46` | `WITHDRAW_UNAVAILABLE` | Withdrawals of this currency on this network are unavailable at the moment. Try again later. |
| 500 | `-19202` | `INSUFFICIENT_LIQUIDITY_FOR_BORROW` | `allowBorrow` was set, but the amount to borrow isn't available right now. Try again later. |
| 503 | `-12015` | `WITHDRAWALS_NOT_AVAILABLE` | Withdrawals are unavailable at the moment. Try again later. |

## `GET /v1/account/transactionhistory`

List transactions. [Endpoint reference](/operations/getV1AccountTransactionhistory)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `skip` or `limit` isn't a whole number, `limit` is more than 200, `startTime` or `endTime` isn't an ISO 8601 timestamp, `endTime` is before `startTime`, `currency` isn't a currency VALR supports, `transactionTypes` contains an unknown type, or `beforeId` isn't a valid UUID. |

## `GET /v1/account/transactionhistory/subaccounts`

List transactions for all sub-accounts. [Endpoint reference](/operations/getV1AccountTransactionhistorySubaccounts)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `beforeId` was sent (it isn't supported here), `skip` or `limit` isn't a whole number, `limit` is more than 200, `startTime` or `endTime` isn't an ISO 8601 timestamp, `endTime` is before `startTime` or more than 7 days after it, `currency` isn't a currency VALR supports, or `transactionTypes` contains an unknown type. |

## `GET /v1/account/balances/all`

Get balances for all accounts. [Endpoint reference](/operations/getV1AccountBalancesAll)

No endpoint-specific errors; see the common errors above.

## `GET /v1/account/subaccounts`

List sub-accounts. [Endpoint reference](/operations/getV1AccountSubaccounts)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `includeTags` or `includePayoutAccounts` isn't `true` or `false`. |

## `GET /v1/account/subaccount/{accountPublicId}`

Get a sub-account. [Endpoint reference](/operations/getV1AccountSubaccountByAccountPublicId)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The sub-account ID isn't a whole number. |
| 400 | `-11134` | `SUB_ACCOUNT_NOT_FOUND` | None of your business's sub-accounts has this ID. Your primary account (`0`) isn't a sub-account. |

## `POST /v1/account/subaccount`

Create a sub-account. [Endpoint reference](/operations/postV1AccountSubaccount)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation (`validationErrors` lists each failing field), or `isProprietarySubAccount` isn't `true` or `false`. |
| 400 | `-17214` | `INVALID_ACCOUNT_TAG_COMBINATION` | `accountTags` contains a tag other than `CLIENT_FUNDS`. |
| 403 | `-11132` | `SUB_ACCOUNT_ALREADY_EXISTS` | Another of your sub-accounts already has this name (ignoring case), or the name is `Primary` or `Main`. |
| 403 | `-11136` | `SUB_ACCOUNT_LIMIT_EXCEEDED` | Your business already has the maximum number of sub-accounts. |
| 409 | `-11423` | `SUB_ACCOUNT_PROFILE_INFO_ALREADY_EXISTS` | Only when KYC details are mandatory for your sub-accounts: another of your sub-accounts already has this email address, ID number or cell number. |

## `PUT /v1/account/subaccount`

Rename a sub-account. [Endpoint reference](/operations/putV1AccountSubaccount)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation (`validationErrors` lists each failing field), or `isProprietarySubAccount` isn't `true` or `false`. |
| 400 | `-11134` | `SUB_ACCOUNT_NOT_FOUND` | None of your business's sub-accounts has this `id`. |
| 403 | `-11132` | `SUB_ACCOUNT_ALREADY_EXISTS` | Another of your sub-accounts already has this name (ignoring case), or the name is `Primary` or `Main`. |
| 409 | `-11423` | `SUB_ACCOUNT_PROFILE_INFO_ALREADY_EXISTS` | Only when KYC details are mandatory for your sub-accounts: another of your sub-accounts already has this email address, ID number or cell number. |

## `DELETE /v1/account/subaccount`

Delete a sub-account. [Endpoint reference](/operations/deleteV1AccountSubaccount)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation; `validationErrors` lists each failing field. |
| 400 | `-11134` | `SUB_ACCOUNT_NOT_FOUND` | None of your business's sub-accounts has this `id`. |
| 400 | `-11163` | `CANNOT_DISABLE_SUB_ACCOUNT_WITH_BALANCES` | The sub-account still holds funds, reserved amounts or debt. Cancel its open orders, transfer its funds out and repay any borrowing, then try again. |
| 400 | `-17217` | `CANNOT_DISABLE_SYSTEM_PROVISIONED_SUB_ACCOUNT` | VALR set this sub-account up for you, so it can't be deleted. |
| 400 | `-17216` | `CANNOT_DISABLE_SHARED_SUB_ACCOUNT` | The sub-account is shared with another VALR user. Stop sharing it, then try again. |

## `POST /v1/account/subaccounts/transfer`

Transfer between accounts. [Endpoint reference](/operations/postV1AccountSubaccountsTransfer)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation; `validationErrors` lists each failing field. |
| 400 | `-109` | `INVALID_CURRENCY_SYMBOL` | `currencyCode` isn't a currency VALR supports. |
| 400 | `-19213` | `MARGIN_NOT_ENABLED_FOR_ACCOUNT` | `allowBorrow` is `true`, but the source account isn't enabled for margin. |
| 400 | `-6` | `INSUFFICIENT_BALANCE` | `allowBorrow` is `true`, but the source account doesn't have enough collateral to borrow the shortfall. |
| 400 | `-19243` | `BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE` | Borrowing for transfers is temporarily unavailable. Transfer no more than the available balance, or try again later. |
| 400 | `-19244` | `BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY` | This currency can't be borrowed for a transfer. |
| 400 | `-11533` | `CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING` | Borrowing the shortfall would take the source account past its borrow limit for this currency. |
| 400 | `-11534` | `ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING` | Borrowing the shortfall would take the source account past its total borrow limit. |
| 403 | `-11133` | `SUB_ACCOUNT_INTERNAL_TRANSFER_NOT_ALLOWED` | The transfer was refused, and the message says why: `fromId` and `toId` are the same, one of them isn't an account in your business, the source account doesn't have enough available balance and `allowBorrow` is `false`, you called it on a sub-account and `fromId` isn't that sub-account, or your key is limited to sub-accounts and one of the accounts isn't among them. |
| 500 | `-19202` | `INSUFFICIENT_LIQUIDITY_FOR_BORROW` | Not enough of this currency is available to borrow right now. Try again later. |
| 500 | `-19502` | `CURRENCY_UNDER_MAINTENANCE` | The currency is under maintenance. Try again in a few minutes. |
| 503 | `-11652` | `INTERNAL_TRANSFERS_NOT_AVAILABLE` | Transfers between accounts are temporarily unavailable. |

## `GET /v1/public/time`

Get the server time. [Endpoint reference](/operations/getV1PublicTime)

No endpoint-specific errors; see the common errors above.

## `GET /v1/public/status`

Get the exchange status. [Endpoint reference](/operations/getV1PublicStatus)

No endpoint-specific errors; see the common errors above.

## `GET /v1/public/marketsummary`

List market summaries. [Endpoint reference](/operations/getV1PublicMarketsummary)

No endpoint-specific errors; see the common errors above.

## `GET /v1/public/{currencyPair}/marketsummary`

Get a pair's market summary. [Endpoint reference](/operations/getV1PublicByCurrencyPairMarketsummary)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-21` | `INVALID_CURRENCY_PAIR` | `currencyPair` isn't a currency pair VALR supports. |
| 404 | `-111` | `MARKET_SUMMARY_NOT_FOUND` | VALR has no market summary for the pair yet, which can happen for a pair that isn't trading. |

## `GET /v1/public/{currencyPair}/buckets`

List price buckets. [Endpoint reference](/operations/getV1PublicByCurrencyPairBuckets)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-21` | `INVALID_CURRENCY_PAIR` | `currencyPair` isn't a currency pair VALR supports. |
| 400 | `-11` | `INVALID_REQUEST` | `periodSeconds` isn't one of the supported periods, `skip` or `limit` isn't a whole number, `limit` is more than 400, or `includeEmpty` isn't `true` or `false`. |

## `GET /v1/public/currencies`

List currencies. [Endpoint reference](/operations/getV1PublicCurrencies)

No endpoint-specific errors; see the common errors above.

## `GET /v1/public/pairs`

List currency pairs. [Endpoint reference](/operations/getV1PublicPairs)

No endpoint-specific errors; see the common errors above.

## `GET /v1/public/pairs/{type}`

List currency pairs by type. [Endpoint reference](/operations/getV1PublicPairsByType)

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `type` isn't `SPOT` or `FUTURE`. |

## Index

Every documented code, with the endpoints that return it.

| Code | Name | HTTP | Message | Returned by |
|---|---|---|---|---|
| `-108` | `WITHDRAW_LIMIT_REACHED` | 400 | Amount exceeds daily limit | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments) |
| `-109` | `INVALID_CURRENCY_SYMBOL` | 400 | Invalid currency symbol | [`POST /v2/fiat/payments`](/operations/postV2FiatPayments)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments)[`POST /v1/account/subaccounts/transfer`](/operations/postV1AccountSubaccountsTransfer) |
| `-11` | `INVALID_REQUEST` | 400 | Invalid Request, please check your request and try again | [`PUT /v2/wallet/fiat/{currency}/payment/references/{referenceCode}`](/operations/putV2WalletFiatByCurrencyPaymentReferencesByReferenceCode)[`POST /v2/wallet/fiat/{currency}/payment/references`](/operations/postV2WalletFiatByCurrencyPaymentReferences)[`GET /v2/wallet/fiat/{currency}/payment/references`](/operations/getV2WalletFiatByCurrencyPaymentReferences)[`GET /v2/payments/bulk-withdrawals/batches/{id}`](/operations/getV2PaymentsBulkWithdrawalsBatchesById)[`POST /v1/webhooks`](/operations/postV1Webhooks)[`DELETE /v1/webhooks/{id}`](/operations/deleteV1WebhooksById)[`GET /v1/webhooks/{id}`](/operations/getV1WebhooksById)[`PUT /v1/webhooks/{id}`](/operations/putV1WebhooksById)[`GET /v1/webhooks/{id}/deliveries`](/operations/getV1WebhooksByIdDeliveries)[`GET /v1/webhooks/{id}/events/{eventId}`](/operations/getV1WebhooksByIdEventsByEventId)[`POST /v2/wallet/fiat/{currency}/payment/bulk-references`](/operations/postV2WalletFiatByCurrencyPaymentBulkReferences)[`GET /v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}`](/operations/getV2WalletFiatByCurrencyPaymentBulkReferencesByJobId)[`GET /v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}/items`](/operations/getV2WalletFiatByCurrencyPaymentBulkReferencesByJobIdItems)[`GET /v2/wallet/fiat/{currency}/payment/deposits`](/operations/getV2WalletFiatByCurrencyPaymentDeposits)[`DELETE /v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference`](/operations/deleteV2WalletFiatByCurrencyPaymentDepositsByPublicIdReference)[`PUT /v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference`](/operations/putV2WalletFiatByCurrencyPaymentDepositsByPublicIdReference)[`GET /v2/payments/{id}`](/operations/getV2PaymentsById)[`GET /v2/payments/collect/events/{id}`](/operations/getV2PaymentsCollectEventsById)[`GET /v2/payments/collect/runs/{id}`](/operations/getV2PaymentsCollectRunsById)[`GET /v2/payments/collect/runs/{id}/payments`](/operations/getV2PaymentsCollectRunsByIdPayments)[`GET /v2/payments/collect/settlements/{id}`](/operations/getV2PaymentsCollectSettlementsById)[`GET /v2/payments/collect/settlements/{id}/payments`](/operations/getV2PaymentsCollectSettlementsByIdPayments)[`GET /v2/payments/account/balances/{type}`](/operations/getV2PaymentsAccountBalancesByType)[`POST /v2/payments/bulk-withdrawals/batches`](/operations/postV2PaymentsBulkWithdrawalsBatches)[`POST /v2/payments/bulk-withdrawals/batches/{id}/cancel`](/operations/postV2PaymentsBulkWithdrawalsBatchesByIdCancel)[`GET /v2/payments/bulk-withdrawals/batches/{id}/fee-quote`](/operations/getV2PaymentsBulkWithdrawalsBatchesByIdFeeQuote)[`PUT /v2/payments/bulk-withdrawals/batches/{id}/label`](/operations/putV2PaymentsBulkWithdrawalsBatchesByIdLabel)[`GET /v2/payments/bulk-withdrawals/batches/{id}/withdrawals`](/operations/getV2PaymentsBulkWithdrawalsBatchesByIdWithdrawals)[`POST /v2/payments/bulk-withdrawals/beneficiaries`](/operations/postV2PaymentsBulkWithdrawalsBeneficiaries)[`DELETE /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/deleteV2PaymentsBulkWithdrawalsBeneficiariesById)[`GET /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/getV2PaymentsBulkWithdrawalsBeneficiariesById)[`PUT /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/putV2PaymentsBulkWithdrawalsBeneficiariesById)[`POST /v2/payments/bulk-withdrawals/beneficiaries/bulk`](/operations/postV2PaymentsBulkWithdrawalsBeneficiariesBulk)[`POST /v2/payments/bulk-withdrawals/fee-quote`](/operations/postV2PaymentsBulkWithdrawalsFeeQuote)[`GET /v2/payments/payout/history/{id}`](/operations/getV2PaymentsPayoutHistoryById)[`GET /v1/wallet/crypto/{currency}/deposit/address`](/operations/getV1WalletCryptoByCurrencyDepositAddress)[`GET /v1/wallet/crypto/{currency}/deposit/history`](/operations/getV1WalletCryptoByCurrencyDepositHistory)[`GET /v1/wallet/crypto/{currency}/withdraw`](/operations/getV1WalletCryptoByCurrencyWithdraw)[`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw)[`GET /v1/wallet/crypto/{currency}/withdraw/{id}`](/operations/getV1WalletCryptoByCurrencyWithdrawById)[`GET /v1/wallet/crypto/{currency}/withdraw/history`](/operations/getV1WalletCryptoByCurrencyWithdrawHistory)[`GET /v1/wallet/crypto/{currency}/withdraw/limits`](/operations/getV1WalletCryptoByCurrencyWithdrawLimits)[`GET /v1/wallet/crypto/address-book`](/operations/getV1WalletCryptoAddressBook)[`GET /v1/wallet/crypto/address-book/{currency}`](/operations/getV1WalletCryptoAddressBookByCurrency)[`GET /v1/wallet/crypto/deposit/history`](/operations/getV1WalletCryptoDepositHistory)[`GET /v1/wallet/crypto/withdraw/history`](/operations/getV1WalletCryptoWithdrawHistory)[`GET /v1/wallet/fiat/{currency}/accounts`](/operations/getV1WalletFiatByCurrencyAccounts)[`POST /v1/wallet/fiat/{currency}/accounts`](/operations/postV1WalletFiatByCurrencyAccounts)[`DELETE /v1/wallet/fiat/{currency}/accounts/{id}`](/operations/deleteV1WalletFiatByCurrencyAccountsById)[`GET /v1/wallet/fiat/{currency}/accounts/{id}`](/operations/getV1WalletFiatByCurrencyAccountsById)[`GET /v1/wallet/fiat/{currency}/banks`](/operations/getV1WalletFiatByCurrencyBanks)[`GET /v1/wallet/fiat/{currency}/deposit/reference`](/operations/getV1WalletFiatByCurrencyDepositReference)[`GET /v1/wallet/fiat/{currency}/deposit/reference/{buyCurrencySymbol}`](/operations/getV1WalletFiatByCurrencyDepositReferenceByBuyCurrencySymbol)[`GET /v1/wallet/fiat/{currency}/auto-buy`](/operations/getV1WalletFiatByCurrencyAutoBuy)[`GET /v1/wallet/fiat/{currency}/withdraw/estimate-fee`](/operations/getV1WalletFiatByCurrencyWithdrawEstimateFee)[`POST /v1/wallet/fiat/{currency}/withdraw`](/operations/postV1WalletFiatByCurrencyWithdraw)[`GET /v1/wallet/fiat/{currency}/withdrawals`](/operations/getV1WalletFiatByCurrencyWithdrawals)[`GET /v1/wallet/fiat/{currency}/withdrawals/{id}`](/operations/getV1WalletFiatByCurrencyWithdrawalsById)[`POST /v2/fiat/payments`](/operations/postV2FiatPayments)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments)[`GET /v1/account/transactionhistory`](/operations/getV1AccountTransactionhistory)[`GET /v1/account/transactionhistory/subaccounts`](/operations/getV1AccountTransactionhistorySubaccounts)[`GET /v1/account/subaccounts`](/operations/getV1AccountSubaccounts)[`GET /v1/account/subaccount/{accountPublicId}`](/operations/getV1AccountSubaccountByAccountPublicId)[`POST /v1/account/subaccount`](/operations/postV1AccountSubaccount)[`PUT /v1/account/subaccount`](/operations/putV1AccountSubaccount)[`DELETE /v1/account/subaccount`](/operations/deleteV1AccountSubaccount)[`POST /v1/account/subaccounts/transfer`](/operations/postV1AccountSubaccountsTransfer)[`GET /v1/public/{currencyPair}/buckets`](/operations/getV1PublicByCurrencyPairBuckets)[`GET /v1/public/pairs/{type}`](/operations/getV1PublicPairsByType) |
| `-11134` | `SUB_ACCOUNT_NOT_FOUND` | 400 | Subaccount not found | [`GET /v1/account/subaccount/{accountPublicId}`](/operations/getV1AccountSubaccountByAccountPublicId)[`PUT /v1/account/subaccount`](/operations/putV1AccountSubaccount)[`DELETE /v1/account/subaccount`](/operations/deleteV1AccountSubaccount) |
| `-11163` | `CANNOT_DISABLE_SUB_ACCOUNT_WITH_BALANCES` | 400 | Cannot disable sub account with balances | [`DELETE /v1/account/subaccount`](/operations/deleteV1AccountSubaccount) |
| `-112` | `CURRENCY_NOT_SUPPORTED` | 400 | Currency not supported | [`GET /v1/wallet/crypto/{currency}/deposit/address`](/operations/getV1WalletCryptoByCurrencyDepositAddress)[`GET /v1/wallet/crypto/{currency}/withdraw`](/operations/getV1WalletCryptoByCurrencyWithdraw)[`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw)[`GET /v1/wallet/fiat/{currency}/banks`](/operations/getV1WalletFiatByCurrencyBanks) |
| `-11258` | `API_KEY_REQUEST_TIMESTAMP_TOO_EARLY` | 400 | Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past | All signed endpoints |
| `-11259` | `API_KEY_MESSAGE_TIMESTAMP_EXPIRED` | 400 | Timestamp cannot be more than {ApiKeyMessageClockSkewBufferSeconds} seconds in the past | All signed endpoints |
| `-11268` | `API_KEY_API_KEY_HEADER_MISSING` | 400 | API key header missing: X-VALR-API-KEY | All signed endpoints |
| `-11269` | `API_KEY_SIGNATURE_HEADER_MISSING` | 400 | API key header missing: X-VALR-SIGNATURE | All signed endpoints |
| `-11270` | `API_KEY_TIMESTAMP_HEADER_MISSING_OR_INVALID` | 400 | API key header missing or is invalid: X-VALR-TIMESTAMP | All signed endpoints |
| `-113` | `INVALID_JSON` | 400 | Invalid JSON payload | [`PUT /v2/wallet/fiat/{currency}/payment/references/{referenceCode}`](/operations/putV2WalletFiatByCurrencyPaymentReferencesByReferenceCode)[`POST /v2/wallet/fiat/{currency}/payment/references`](/operations/postV2WalletFiatByCurrencyPaymentReferences)[`POST /v1/webhooks`](/operations/postV1Webhooks)[`PUT /v1/webhooks/{id}`](/operations/putV1WebhooksById)[`POST /v2/wallet/fiat/{currency}/payment/bulk-references`](/operations/postV2WalletFiatByCurrencyPaymentBulkReferences)[`PUT /v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference`](/operations/putV2WalletFiatByCurrencyPaymentDepositsByPublicIdReference)[`POST /v2/payments/bulk-withdrawals/batches`](/operations/postV2PaymentsBulkWithdrawalsBatches)[`PUT /v2/payments/bulk-withdrawals/batches/{id}/label`](/operations/putV2PaymentsBulkWithdrawalsBatchesByIdLabel)[`POST /v2/payments/bulk-withdrawals/beneficiaries`](/operations/postV2PaymentsBulkWithdrawalsBeneficiaries)[`PUT /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/putV2PaymentsBulkWithdrawalsBeneficiariesById)[`POST /v2/payments/bulk-withdrawals/beneficiaries/bulk`](/operations/postV2PaymentsBulkWithdrawalsBeneficiariesBulk)[`POST /v2/payments/bulk-withdrawals/fee-quote`](/operations/postV2PaymentsBulkWithdrawalsFeeQuote)[`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw)[`POST /v1/wallet/fiat/{currency}/accounts`](/operations/postV1WalletFiatByCurrencyAccounts)[`POST /v1/wallet/fiat/{currency}/withdraw`](/operations/postV1WalletFiatByCurrencyWithdraw)[`POST /v2/fiat/payments`](/operations/postV2FiatPayments)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments)[`POST /v1/account/subaccount`](/operations/postV1AccountSubaccount)[`PUT /v1/account/subaccount`](/operations/putV1AccountSubaccount)[`DELETE /v1/account/subaccount`](/operations/deleteV1AccountSubaccount)[`POST /v1/account/subaccounts/transfer`](/operations/postV1AccountSubaccountsTransfer) |
| `-115` | `INVALID_COUNTRY_ALPHA_2` | 400 | Invalid country alpha 2 | [`POST /v1/wallet/fiat/{currency}/accounts`](/operations/postV1WalletFiatByCurrencyAccounts)[`POST /v2/fiat/payments`](/operations/postV2FiatPayments) |
| `-11533` | `CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING` | 400 | Account borrow limit for requested currency would be exceeded and is therefore not allowed. | [`POST /v1/wallet/fiat/{currency}/withdraw`](/operations/postV1WalletFiatByCurrencyWithdraw)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments)[`POST /v1/account/subaccounts/transfer`](/operations/postV1AccountSubaccountsTransfer) |
| `-11534` | `ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING` | 400 | Account total borrow limit would be exceeded and is therefore not allowed. | [`POST /v1/wallet/fiat/{currency}/withdraw`](/operations/postV1WalletFiatByCurrencyWithdraw)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments)[`POST /v1/account/subaccounts/transfer`](/operations/postV1AccountSubaccountsTransfer) |
| `-13017` | `BLOCKCHAIN_SEND_TRUSTLINE_NOT_VALID` | 400 | Unable to verify trustline. Please confirm that your address has an active trustline for this asset. | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw) |
| `-13018` | `BLOCKCHAIN_INVALID_NETWORK_FOR_CURRENCY` | 400 | Unable to validate network type for provided currency | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw) |
| `-13019` | `BLOCKCHAIN_SEND_MISSING_KYC_PERMIT` | 400 | Contact token issuer for whitelisting. | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw) |
| `-13105` | `RECEIVE_ADDRESS_NOT_SUPPORTED_FOR_CURRENCY_NETWORK_TYPE` | 400 | Deposit address is not supported for the specified currency and network type | [`GET /v1/wallet/crypto/{currency}/deposit/address`](/operations/getV1WalletCryptoByCurrencyDepositAddress) |
| `-13402` | `CURRENCY_DOES_NOT_SUPPORT_PAYMENT_REFERENCE` | 400 | This currency does not support a payment reference field | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments) |
| `-13404` | `INVALID_WITHDRAW_AMOUNT` | 400 | Invalid withdraw amount, please ensure amount is larger than minimum | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments) |
| `-13405` | `INVALID_WITHDRAW_TRANSACTION_REFERENCE` | 400 | Invalid transaction reference | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments) |
| `-13410` | `PAYMENT_REFERENCE_MISSING` | 400 | This withdrawal address requires a  | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments) |
| `-13411` | `WITHDRAW_AMOUNT_BELOW_MINIMUM` | 400 | Please ensure withdrawal amount is larger than  | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments) |
| `-13415` | `WITHDRAWALS_TEMPORARILY_SUSPENDED` | 400 | Withdrawals have been suspended | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw)[`POST /v1/wallet/fiat/{currency}/withdraw`](/operations/postV1WalletFiatByCurrencyWithdraw)[`POST /v2/fiat/payments`](/operations/postV2FiatPayments)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments) |
| `-13418` | `BANK_ACCOUNT_LINKING_TEMPORARILY_DISABLED` | 400 | Bank account linking has been temporarily suspended | [`POST /v1/wallet/fiat/{currency}/accounts`](/operations/postV1WalletFiatByCurrencyAccounts)[`POST /v2/fiat/payments`](/operations/postV2FiatPayments) |
| `-13419` | `NETWORK_FEE_FOR_TRANSACTION_EXCEEDED` | 400 | Withdrawals to this address are not allowed | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments) |
| `-13426` | `ADDRESS_BOOK_ENTRY_LABEL_IN_USE` | 400 | The label provided is already in use. | [`POST /v2/crypto/payments`](/operations/postV2CryptoPayments) |
| `-13427` | `NON_ADDRESS_BOOK_WITHDRAWALS_DISABLED` | 400 | Withdrawals to addresses not in your address book are disabled. Please contact support to change | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw) |
| `-13428` | `ADDRESS_BOOK_ENTRY_STILL_WARMING_UP` | 400 | Address book entry too new. Withdrawals not allowed yet | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw) |
| `-15115` | `UNIQUE_DEPOSIT_REFERENCE_INVALID_OVERRIDE` | 400 | Deposit override is invalid | [`PUT /v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference`](/operations/putV2WalletFiatByCurrencyPaymentDepositsByPublicIdReference) |
| `-15121` | `BULK_DEPOSIT_REFERENCE_BATCH_TOO_LARGE` | 400 | Batch size exceeds maximum allowed | [`POST /v2/wallet/fiat/{currency}/payment/bulk-references`](/operations/postV2WalletFiatByCurrencyPaymentBulkReferences) |
| `-15123` | `BULK_DEPOSIT_REFERENCE_INVALID_SENDER` | 400 | Invalid sender information | [`POST /v2/wallet/fiat/{currency}/payment/bulk-references`](/operations/postV2WalletFiatByCurrencyPaymentBulkReferences) |
| `-15132` | `CURRENCY_NOT_ENABLED_FOR_FIAT_DEPOSIT_AUTO_BUY` | 400 | Currency not enabled for Auto-Buy | [`GET /v1/wallet/fiat/{currency}/deposit/reference/{buyCurrencySymbol}`](/operations/getV1WalletFiatByCurrencyDepositReferenceByBuyCurrencySymbol) |
| `-15307` | `FIAT_WITHDRAWAL_AMOUNT_BELOW_MINIMUM` | 400 | Amount is lower than the minimum | [`POST /v1/wallet/fiat/{currency}/withdraw`](/operations/postV1WalletFiatByCurrencyWithdraw)[`POST /v2/fiat/payments`](/operations/postV2FiatPayments) |
| `-15309` | `CAN_NOT_WITHDRAW_TO_AN_UNVERIFIED_BANK_ACCOUNT` | 400 | This bank account is not verified. Please withdraw to a verified account. | [`POST /v1/wallet/fiat/{currency}/withdraw`](/operations/postV1WalletFiatByCurrencyWithdraw)[`POST /v2/fiat/payments`](/operations/postV2FiatPayments) |
| `-15318` | `FIAT_WITHDRAWAL_CURRENCY_MISMATCH` | 400 | Withdrawal currency does not match the currency of selected bank account | [`POST /v1/wallet/fiat/{currency}/withdraw`](/operations/postV1WalletFiatByCurrencyWithdraw)[`POST /v2/fiat/payments`](/operations/postV2FiatPayments) |
| `-15321` | `CAN_NOT_WITHDRAW_TO_AN_UNCONFIRMED_BANK_ACCOUNT` | 400 | This bank account is not confirmed. Please complete our verification process to withdraw. | [`POST /v1/wallet/fiat/{currency}/withdraw`](/operations/postV1WalletFiatByCurrencyWithdraw) |
| `-15322` | `CAN_NOT_WITHDRAW_TO_A_DELETED_BANK_ACCOUNT` | 400 | This bank account has been deleted. Please add the account and try again. | [`POST /v1/wallet/fiat/{currency}/withdraw`](/operations/postV1WalletFiatByCurrencyWithdraw) |
| `-15721` | `SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH` | 400 | No scoped deposit account exists for the requested currency. | [`POST /v2/wallet/fiat/{currency}/payment/references`](/operations/postV2WalletFiatByCurrencyPaymentReferences)[`GET /v2/wallet/fiat/{currency}/payment/references`](/operations/getV2WalletFiatByCurrencyPaymentReferences)[`POST /v2/wallet/fiat/{currency}/payment/bulk-references`](/operations/postV2WalletFiatByCurrencyPaymentBulkReferences)[`GET /v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}`](/operations/getV2WalletFiatByCurrencyPaymentBulkReferencesByJobId)[`GET /v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}/items`](/operations/getV2WalletFiatByCurrencyPaymentBulkReferencesByJobIdItems)[`GET /v2/wallet/fiat/{currency}/payment/deposits`](/operations/getV2WalletFiatByCurrencyPaymentDeposits)[`GET /v1/wallet/crypto/{currency}/deposit/address`](/operations/getV1WalletCryptoByCurrencyDepositAddress) |
| `-15875` | `FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED` | 400 | Withdrawals using the selected branch code are not supported. Please try a valid branch in your region or contact support. | [`POST /v1/wallet/fiat/{currency}/accounts`](/operations/postV1WalletFiatByCurrencyAccounts)[`POST /v1/wallet/fiat/{currency}/withdraw`](/operations/postV1WalletFiatByCurrencyWithdraw)[`POST /v2/fiat/payments`](/operations/postV2FiatPayments) |
| `-17214` | `INVALID_ACCOUNT_TAG_COMBINATION` | 400 | Invalid account tag combination | [`POST /v1/account/subaccount`](/operations/postV1AccountSubaccount) |
| `-17216` | `CANNOT_DISABLE_SHARED_SUB_ACCOUNT` | 400 | Cannot disable shared sub account | [`DELETE /v1/account/subaccount`](/operations/deleteV1AccountSubaccount) |
| `-17217` | `CANNOT_DISABLE_SYSTEM_PROVISIONED_SUB_ACCOUNT` | 400 | Cannot disable a system-provisioned sub account | [`DELETE /v1/account/subaccount`](/operations/deleteV1AccountSubaccount) |
| `-18104` | `PAYMENT_BENEFICIARY_DETAILS_REQUIRED` | 400 | Provide either an existing beneficiary id or full beneficiary details. | [`POST /v2/fiat/payments`](/operations/postV2FiatPayments)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments) |
| `-18122` | `WEBHOOK_SUBSCRIPTION_LIMIT_REACHED` | 400 | Webhook subscription limit reached: | [`POST /v1/webhooks`](/operations/postV1Webhooks) |
| `-19213` | `MARGIN_NOT_ENABLED_FOR_ACCOUNT` | 400 | Margin not enabled for account | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw)[`POST /v1/wallet/fiat/{currency}/withdraw`](/operations/postV1WalletFiatByCurrencyWithdraw)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments)[`POST /v1/account/subaccounts/transfer`](/operations/postV1AccountSubaccountsTransfer) |
| `-19243` | `BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE` | 400 | Borrowing for withdrawal and internal transfers currently not available | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw)[`POST /v1/wallet/fiat/{currency}/withdraw`](/operations/postV1WalletFiatByCurrencyWithdraw)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments)[`POST /v1/account/subaccounts/transfer`](/operations/postV1AccountSubaccountsTransfer) |
| `-19244` | `BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY` | 400 | Borrowing for withdrawal and internal transfers currently not available for selected currency | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw)[`POST /v1/wallet/fiat/{currency}/withdraw`](/operations/postV1WalletFiatByCurrencyWithdraw)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments)[`POST /v1/account/subaccounts/transfer`](/operations/postV1AccountSubaccountsTransfer) |
| `-21` | `INVALID_CURRENCY_PAIR` | 400 | Unsupported Currency Pair | [`GET /v1/wallet/fiat/{currency}/deposit/reference/{buyCurrencySymbol}`](/operations/getV1WalletFiatByCurrencyDepositReferenceByBuyCurrencySymbol)[`GET /v1/public/{currencyPair}/marketsummary`](/operations/getV1PublicByCurrencyPairMarketsummary)[`GET /v1/public/{currencyPair}/buckets`](/operations/getV1PublicByCurrencyPairBuckets) |
| `-30071` | `SERVICE_PROVIDER_NOT_FOUND` | 400 | Service provider not found. | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw) |
| `-32` | `CURRENCY_PAIR_NOT_ACTIVE` | 400 | The given currency pair is not active | [`GET /v1/wallet/fiat/{currency}/deposit/reference/{buyCurrencySymbol}`](/operations/getV1WalletFiatByCurrencyDepositReferenceByBuyCurrencySymbol) |
| `-32765` | `WITHDRAWAL_RESTRICTION_APPLIED` | 400 | Withdrawal denied. Minimum portfolio value would not be met after this withdrawal. | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw)[`POST /v1/wallet/fiat/{currency}/withdraw`](/operations/postV1WalletFiatByCurrencyWithdraw)[`POST /v2/fiat/payments`](/operations/postV2FiatPayments)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments) |
| `-50` | `INVALID_WITHDRAW_ADDRESS` | 400 | Invalid Withdraw address. | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments) |
| `-6` | `INSUFFICIENT_BALANCE` | 400 | Insufficient Balance | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw)[`POST /v1/wallet/fiat/{currency}/withdraw`](/operations/postV1WalletFiatByCurrencyWithdraw)[`POST /v2/fiat/payments`](/operations/postV2FiatPayments)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments)[`POST /v1/account/subaccounts/transfer`](/operations/postV1AccountSubaccountsTransfer) |
| `BAD_REQUEST` | `BAD_REQUEST` | 400 | Bad request. | [`GET /v2/payments/bulk-withdrawals/batches/{id}`](/operations/getV2PaymentsBulkWithdrawalsBatchesById)[`GET /v2/payments`](/operations/getV2Payments)[`GET /v2/payments/{id}`](/operations/getV2PaymentsById)[`GET /v2/payments/collect/events`](/operations/getV2PaymentsCollectEvents)[`GET /v2/payments/collect/events/{id}`](/operations/getV2PaymentsCollectEventsById)[`GET /v2/payments/collect/history`](/operations/getV2PaymentsCollectHistory)[`GET /v2/payments/collect/runs/{id}`](/operations/getV2PaymentsCollectRunsById)[`GET /v2/payments/collect/runs/{id}/payments`](/operations/getV2PaymentsCollectRunsByIdPayments)[`GET /v2/payments/collect/runs/history`](/operations/getV2PaymentsCollectRunsHistory)[`GET /v2/payments/collect/schedules`](/operations/getV2PaymentsCollectSchedules)[`GET /v2/payments/collect/settlements`](/operations/getV2PaymentsCollectSettlements)[`GET /v2/payments/collect/settlements/{id}`](/operations/getV2PaymentsCollectSettlementsById)[`GET /v2/payments/collect/settlements/{id}/payments`](/operations/getV2PaymentsCollectSettlementsByIdPayments)[`GET /v2/payments/collect/settlements/wallet`](/operations/getV2PaymentsCollectSettlementsWallet)[`GET /v2/payments/collect/upcoming`](/operations/getV2PaymentsCollectUpcoming)[`GET /v2/payments/collections/history`](/operations/getV2PaymentsCollectionsHistory)[`GET /v2/payments/account/balances/{type}`](/operations/getV2PaymentsAccountBalancesByType)[`GET /v2/payments/bulk-withdrawals/banks`](/operations/getV2PaymentsBulkWithdrawalsBanks)[`GET /v2/payments/bulk-withdrawals/batches`](/operations/getV2PaymentsBulkWithdrawalsBatches)[`POST /v2/payments/bulk-withdrawals/batches`](/operations/postV2PaymentsBulkWithdrawalsBatches)[`POST /v2/payments/bulk-withdrawals/batches/{id}/cancel`](/operations/postV2PaymentsBulkWithdrawalsBatchesByIdCancel)[`GET /v2/payments/bulk-withdrawals/batches/{id}/fee-quote`](/operations/getV2PaymentsBulkWithdrawalsBatchesByIdFeeQuote)[`PUT /v2/payments/bulk-withdrawals/batches/{id}/label`](/operations/putV2PaymentsBulkWithdrawalsBatchesByIdLabel)[`GET /v2/payments/bulk-withdrawals/batches/{id}/withdrawals`](/operations/getV2PaymentsBulkWithdrawalsBatchesByIdWithdrawals)[`GET /v2/payments/bulk-withdrawals/beneficiaries`](/operations/getV2PaymentsBulkWithdrawalsBeneficiaries)[`POST /v2/payments/bulk-withdrawals/beneficiaries`](/operations/postV2PaymentsBulkWithdrawalsBeneficiaries)[`DELETE /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/deleteV2PaymentsBulkWithdrawalsBeneficiariesById)[`GET /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/getV2PaymentsBulkWithdrawalsBeneficiariesById)[`PUT /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/putV2PaymentsBulkWithdrawalsBeneficiariesById)[`POST /v2/payments/bulk-withdrawals/beneficiaries/bulk`](/operations/postV2PaymentsBulkWithdrawalsBeneficiariesBulk)[`POST /v2/payments/bulk-withdrawals/fee-quote`](/operations/postV2PaymentsBulkWithdrawalsFeeQuote)[`GET /v2/payments/bulk-withdrawals/withdrawals`](/operations/getV2PaymentsBulkWithdrawalsWithdrawals)[`GET /v2/payments/payout/history`](/operations/getV2PaymentsPayoutHistory)[`GET /v2/payments/payout/history/{id}`](/operations/getV2PaymentsPayoutHistoryById) |
| `-11252` | `API_KEY_INVALID_SIGNATURE` | 401 | Request has an invalid signature | All signed endpoints |
| `-11264` | `API_KEY_INVALID` | 401 | API key or secret is invalid | All signed endpoints |
| `-11272` | `API_KEY_IP_NOT_WHITELISTED` | 401 | The originating IP Address has not been whitelisted. | All signed endpoints |
| `-93` | `UNAUTHORIZED` | 401 | Unauthorized | All signed endpoints |
| `-11132` | `SUB_ACCOUNT_ALREADY_EXISTS` | 403 | A subaccount with that label already exists | [`POST /v1/account/subaccount`](/operations/postV1AccountSubaccount)[`PUT /v1/account/subaccount`](/operations/putV1AccountSubaccount) |
| `-11133` | `SUB_ACCOUNT_INTERNAL_TRANSFER_NOT_ALLOWED` | 403 | Internal transfer did not succeed | [`POST /v1/account/subaccounts/transfer`](/operations/postV1AccountSubaccountsTransfer) |
| `-11136` | `SUB_ACCOUNT_LIMIT_EXCEEDED` | 403 | New subaccount limit exceeded | [`POST /v1/account/subaccount`](/operations/postV1AccountSubaccount) |
| `-11277` | `API_KEY_ENDPOINT_NOT_ALLOWED` | 403 | This API key does not have permission to access this endpoint | All signed endpoints |
| `-13104` | `RECEIVE_ADDRESS_NOT_SUPPORTED_IN_REGION` | 403 | Deposit address is not supported in your region | [`GET /v1/wallet/crypto/{currency}/deposit/address`](/operations/getV1WalletCryptoByCurrencyDepositAddress) |
| `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | 403 | Payments access is not configured for this user. | [`GET /v2/payments/bulk-withdrawals/batches/{id}`](/operations/getV2PaymentsBulkWithdrawalsBatchesById)[`GET /v2/payments`](/operations/getV2Payments)[`GET /v2/payments/{id}`](/operations/getV2PaymentsById)[`GET /v2/payments/collect/events`](/operations/getV2PaymentsCollectEvents)[`GET /v2/payments/collect/events/{id}`](/operations/getV2PaymentsCollectEventsById)[`GET /v2/payments/collect/history`](/operations/getV2PaymentsCollectHistory)[`GET /v2/payments/collect/runs/{id}`](/operations/getV2PaymentsCollectRunsById)[`GET /v2/payments/collect/runs/{id}/payments`](/operations/getV2PaymentsCollectRunsByIdPayments)[`GET /v2/payments/collect/runs/history`](/operations/getV2PaymentsCollectRunsHistory)[`GET /v2/payments/collect/schedules`](/operations/getV2PaymentsCollectSchedules)[`GET /v2/payments/collect/settlements`](/operations/getV2PaymentsCollectSettlements)[`GET /v2/payments/collect/settlements/{id}`](/operations/getV2PaymentsCollectSettlementsById)[`GET /v2/payments/collect/settlements/{id}/payments`](/operations/getV2PaymentsCollectSettlementsByIdPayments)[`GET /v2/payments/collect/settlements/wallet`](/operations/getV2PaymentsCollectSettlementsWallet)[`GET /v2/payments/collect/upcoming`](/operations/getV2PaymentsCollectUpcoming)[`GET /v2/payments/collections/history`](/operations/getV2PaymentsCollectionsHistory)[`GET /v2/payments/account/balances/{type}`](/operations/getV2PaymentsAccountBalancesByType)[`GET /v2/payments/bulk-withdrawals/banks`](/operations/getV2PaymentsBulkWithdrawalsBanks)[`GET /v2/payments/bulk-withdrawals/batches`](/operations/getV2PaymentsBulkWithdrawalsBatches)[`POST /v2/payments/bulk-withdrawals/batches`](/operations/postV2PaymentsBulkWithdrawalsBatches)[`POST /v2/payments/bulk-withdrawals/batches/{id}/cancel`](/operations/postV2PaymentsBulkWithdrawalsBatchesByIdCancel)[`GET /v2/payments/bulk-withdrawals/batches/{id}/fee-quote`](/operations/getV2PaymentsBulkWithdrawalsBatchesByIdFeeQuote)[`PUT /v2/payments/bulk-withdrawals/batches/{id}/label`](/operations/putV2PaymentsBulkWithdrawalsBatchesByIdLabel)[`GET /v2/payments/bulk-withdrawals/batches/{id}/withdrawals`](/operations/getV2PaymentsBulkWithdrawalsBatchesByIdWithdrawals)[`GET /v2/payments/bulk-withdrawals/beneficiaries`](/operations/getV2PaymentsBulkWithdrawalsBeneficiaries)[`POST /v2/payments/bulk-withdrawals/beneficiaries`](/operations/postV2PaymentsBulkWithdrawalsBeneficiaries)[`DELETE /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/deleteV2PaymentsBulkWithdrawalsBeneficiariesById)[`GET /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/getV2PaymentsBulkWithdrawalsBeneficiariesById)[`PUT /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/putV2PaymentsBulkWithdrawalsBeneficiariesById)[`POST /v2/payments/bulk-withdrawals/beneficiaries/bulk`](/operations/postV2PaymentsBulkWithdrawalsBeneficiariesBulk)[`POST /v2/payments/bulk-withdrawals/fee-quote`](/operations/postV2PaymentsBulkWithdrawalsFeeQuote)[`GET /v2/payments/bulk-withdrawals/withdrawals`](/operations/getV2PaymentsBulkWithdrawalsWithdrawals)[`GET /v2/payments/payout/history`](/operations/getV2PaymentsPayoutHistory)[`GET /v2/payments/payout/history/{id}`](/operations/getV2PaymentsPayoutHistoryById) |
| `-111` | `MARKET_SUMMARY_NOT_FOUND` | 404 | Market summary not found | [`GET /v1/public/{currencyPair}/marketsummary`](/operations/getV1PublicByCurrencyPairMarketsummary) |
| `-13403` | `SEND_NOT_FOUND` | 404 | Could not find send | [`GET /v1/wallet/crypto/{currency}/withdraw/{id}`](/operations/getV1WalletCryptoByCurrencyWithdrawById) |
| `-13422` | `ADDRESS_BOOK_ENTRY_NOT_FOUND` | 404 | Could not find address book entry. | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw) |
| `-14203` | `COULD_NOT_GET_LINKED_ACCOUNT` | 404 | The requested bank account does not exist | [`DELETE /v1/wallet/fiat/{currency}/accounts/{id}`](/operations/deleteV1WalletFiatByCurrencyAccountsById)[`GET /v1/wallet/fiat/{currency}/accounts/{id}`](/operations/getV1WalletFiatByCurrencyAccountsById)[`GET /v1/wallet/fiat/{currency}/withdraw/estimate-fee`](/operations/getV1WalletFiatByCurrencyWithdrawEstimateFee)[`POST /v1/wallet/fiat/{currency}/withdraw`](/operations/postV1WalletFiatByCurrencyWithdraw)[`POST /v2/fiat/payments`](/operations/postV2FiatPayments) |
| `-15114` | `UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND` | 404 | Deposit reference not found | [`GET /v2/wallet/fiat/{currency}/payment/references/{referenceCode}`](/operations/getV2WalletFiatByCurrencyPaymentReferencesByReferenceCode)[`DELETE /v2/wallet/fiat/{currency}/payment/references/{referenceCode}`](/operations/deleteV2WalletFiatByCurrencyPaymentReferencesByReferenceCode)[`PUT /v2/wallet/fiat/{currency}/payment/references/{referenceCode}`](/operations/putV2WalletFiatByCurrencyPaymentReferencesByReferenceCode)[`PUT /v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference`](/operations/putV2WalletFiatByCurrencyPaymentDepositsByPublicIdReference) |
| `-15118` | `FIAT_DEPOSIT_NOT_FOUND` | 404 | Deposit not found | [`DELETE /v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference`](/operations/deleteV2WalletFiatByCurrencyPaymentDepositsByPublicIdReference)[`PUT /v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference`](/operations/putV2WalletFiatByCurrencyPaymentDepositsByPublicIdReference) |
| `-15122` | `BULK_DEPOSIT_REFERENCE_JOB_NOT_FOUND` | 404 | Bulk deposit job not found | [`GET /v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}`](/operations/getV2WalletFiatByCurrencyPaymentBulkReferencesByJobId)[`GET /v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}/items`](/operations/getV2WalletFiatByCurrencyPaymentBulkReferencesByJobIdItems) |
| `-15300` | `COULD_NOT_FIND_FIAT_WITHDRAWAL` | 404 | The requested withdrawal does not exist | [`GET /v1/wallet/fiat/{currency}/withdrawals/{id}`](/operations/getV1WalletFiatByCurrencyWithdrawalsById) |
| `-18101` | `PAYMENT_BENEFICIARY_NOT_FOUND` | 404 | Payment beneficiary not found. | [`POST /v2/crypto/payments`](/operations/postV2CryptoPayments) |
| `-18106` | `PAYMENTS_API_DISABLED` | 404 | API payments are not enabled. | [`POST /v2/fiat/payments`](/operations/postV2FiatPayments)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments) |
| `-18121` | `WEBHOOK_SUBSCRIPTION_NOT_FOUND` | 404 | Webhook subscription not found | [`DELETE /v1/webhooks/{id}`](/operations/deleteV1WebhooksById)[`GET /v1/webhooks/{id}`](/operations/getV1WebhooksById)[`PUT /v1/webhooks/{id}`](/operations/putV1WebhooksById)[`GET /v1/webhooks/{id}/deliveries`](/operations/getV1WebhooksByIdDeliveries)[`GET /v1/webhooks/{id}/events/{eventId}`](/operations/getV1WebhooksByIdEventsByEventId) |
| `-18123` | `WEBHOOK_EVENT_NOT_FOUND` | 404 | Webhook event not found | [`GET /v1/webhooks/{id}/events/{eventId}`](/operations/getV1WebhooksByIdEventsByEventId) |
| `NOT_FOUND` | `NOT_FOUND` | 404 | Resource not found. | [`GET /v2/payments/bulk-withdrawals/batches/{id}`](/operations/getV2PaymentsBulkWithdrawalsBatchesById)[`GET /v2/payments/{id}`](/operations/getV2PaymentsById)[`GET /v2/payments/collect/events/{id}`](/operations/getV2PaymentsCollectEventsById)[`GET /v2/payments/collect/runs/{id}`](/operations/getV2PaymentsCollectRunsById)[`GET /v2/payments/collect/settlements/{id}`](/operations/getV2PaymentsCollectSettlementsById)[`GET /v2/payments/collect/settlements/{id}/payments`](/operations/getV2PaymentsCollectSettlementsByIdPayments)[`GET /v2/payments/collect/settlements/wallet`](/operations/getV2PaymentsCollectSettlementsWallet)[`GET /v2/payments/account/balances/{type}`](/operations/getV2PaymentsAccountBalancesByType)[`POST /v2/payments/bulk-withdrawals/batches/{id}/cancel`](/operations/postV2PaymentsBulkWithdrawalsBatchesByIdCancel)[`GET /v2/payments/bulk-withdrawals/batches/{id}/fee-quote`](/operations/getV2PaymentsBulkWithdrawalsBatchesByIdFeeQuote)[`PUT /v2/payments/bulk-withdrawals/batches/{id}/label`](/operations/putV2PaymentsBulkWithdrawalsBatchesByIdLabel)[`GET /v2/payments/bulk-withdrawals/batches/{id}/withdrawals`](/operations/getV2PaymentsBulkWithdrawalsBatchesByIdWithdrawals)[`DELETE /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/deleteV2PaymentsBulkWithdrawalsBeneficiariesById)[`GET /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/getV2PaymentsBulkWithdrawalsBeneficiariesById)[`PUT /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/putV2PaymentsBulkWithdrawalsBeneficiariesById)[`GET /v2/payments/payout/history/{id}`](/operations/getV2PaymentsPayoutHistoryById) |
| `-11423` | `SUB_ACCOUNT_PROFILE_INFO_ALREADY_EXISTS` | 409 | Sub account with Id, E-mail or Cell number already exists | [`POST /v1/account/subaccount`](/operations/postV1AccountSubaccount)[`PUT /v1/account/subaccount`](/operations/putV1AccountSubaccount) |
| `-15124` | `BULK_DEPOSIT_REFERENCE_JOB_IN_PROGRESS` | 409 | A bulk deposit job is already being processed | [`POST /v2/wallet/fiat/{currency}/payment/bulk-references`](/operations/postV2WalletFiatByCurrencyPaymentBulkReferences) |
| `-18103` | `PAYMENT_BENEFICIARY_NOT_ACTIVE` | 409 | The selected payment beneficiary is not active. | [`POST /v2/fiat/payments`](/operations/postV2FiatPayments)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments) |
| `CONFLICT` | `CONFLICT` | 409 | Resource conflict. | [`POST /v2/payments/bulk-withdrawals/batches`](/operations/postV2PaymentsBulkWithdrawalsBatches)[`POST /v2/payments/bulk-withdrawals/beneficiaries`](/operations/postV2PaymentsBulkWithdrawalsBeneficiaries)[`PUT /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/putV2PaymentsBulkWithdrawalsBeneficiariesById) |
| `-15116` | `UNIQUE_DEPOSIT_REFERENCE_RATE_LIMIT_EXCEEDED` | 429 | Daily deposit reference generation limit exceeded | [`POST /v2/wallet/fiat/{currency}/payment/references`](/operations/postV2WalletFiatByCurrencyPaymentReferences)[`POST /v2/wallet/fiat/{currency}/payment/bulk-references`](/operations/postV2WalletFiatByCurrencyPaymentBulkReferences) |
| `-15119` | `UNIQUE_DEPOSIT_REFERENCE_OVERALL_LIMIT_EXCEEDED` | 429 | Total deposit reference limit reached | [`POST /v2/wallet/fiat/{currency}/payment/references`](/operations/postV2WalletFiatByCurrencyPaymentReferences)[`POST /v2/wallet/fiat/{currency}/payment/bulk-references`](/operations/postV2WalletFiatByCurrencyPaymentBulkReferences) |
| `-15111` | `FIAT_DEPOSITS_NOT_ALLOWED_FOR_CURRENCY` | 451 | Deposits in the selected currency are not supported in your region | [`GET /v1/wallet/fiat/{currency}/deposit/reference`](/operations/getV1WalletFiatByCurrencyDepositReference)[`GET /v1/wallet/fiat/{currency}/deposit/reference/{buyCurrencySymbol}`](/operations/getV1WalletFiatByCurrencyDepositReferenceByBuyCurrencySymbol) |
| `-15134` | `CURRENCY_NOT_ALLOWED_FOR_FIAT_DEPOSIT_AUTO_BUY` | 451 | Auto-buys in the selected currency are not supported in your region | [`GET /v1/wallet/fiat/{currency}/deposit/reference/{buyCurrencySymbol}`](/operations/getV1WalletFiatByCurrencyDepositReferenceByBuyCurrencySymbol) |
| `-15320` | `FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY` | 451 | Withdrawals in the selected currency are not supported in your region | [`GET /v1/wallet/fiat/{currency}/accounts`](/operations/getV1WalletFiatByCurrencyAccounts)[`POST /v1/wallet/fiat/{currency}/accounts`](/operations/postV1WalletFiatByCurrencyAccounts)[`GET /v1/wallet/fiat/{currency}/accounts/{id}`](/operations/getV1WalletFiatByCurrencyAccountsById)[`GET /v1/wallet/fiat/{currency}/banks`](/operations/getV1WalletFiatByCurrencyBanks)[`POST /v1/wallet/fiat/{currency}/withdraw`](/operations/postV1WalletFiatByCurrencyWithdraw)[`POST /v2/fiat/payments`](/operations/postV2FiatPayments) |
| `-11257` | `API_KEY_REQUEST_BLACKLISTED` | 500 | Duplicate message received | All signed endpoints |
| `-13423` | `ADDRESS_BOOK_ENTRY_CURRENCY_WRONG` | 500 | Address book entry not valid for specified currency | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw) |
| `-15317` | `BANK_REMOTE_FETCH_FAILURE` | 500 | Unable to fetch remote list of banks | [`POST /v1/wallet/fiat/{currency}/accounts`](/operations/postV1WalletFiatByCurrencyAccounts)[`GET /v1/wallet/fiat/{currency}/banks`](/operations/getV1WalletFiatByCurrencyBanks)[`POST /v2/fiat/payments`](/operations/postV2FiatPayments) |
| `-19202` | `INSUFFICIENT_LIQUIDITY_FOR_BORROW` | 500 | The borrow amount is unavailable currently, please try again later | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw)[`POST /v1/wallet/fiat/{currency}/withdraw`](/operations/postV1WalletFiatByCurrencyWithdraw)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments)[`POST /v1/account/subaccounts/transfer`](/operations/postV1AccountSubaccountsTransfer) |
| `-19502` | `CURRENCY_UNDER_MAINTENANCE` | 500 | Currency currently under maintenance. Please try again in a few minutes. | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments)[`POST /v1/account/subaccounts/transfer`](/operations/postV1AccountSubaccountsTransfer) |
| `-29` | `BLOCKCHAIN_SEND_FAILURE` | 500 | Unknown Blockchain Send Failure | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw) |
| `-30` | `COULD_NOT_GET_RECEIVE_ADDRESS` | 500 | Could not get deposit address | [`GET /v1/wallet/crypto/{currency}/deposit/address`](/operations/getV1WalletCryptoByCurrencyDepositAddress) |
| `-46` | `WITHDRAW_UNAVAILABLE` | 500 | Withdrawal currently unavailable. | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments) |
| `INTERNAL_ERROR` | `INTERNAL_ERROR` | 500 | An internal error occurred. | [`GET /v2/payments/bulk-withdrawals/batches/{id}`](/operations/getV2PaymentsBulkWithdrawalsBatchesById)[`GET /v2/payments`](/operations/getV2Payments)[`GET /v2/payments/{id}`](/operations/getV2PaymentsById)[`GET /v2/payments/collect/events`](/operations/getV2PaymentsCollectEvents)[`GET /v2/payments/collect/events/{id}`](/operations/getV2PaymentsCollectEventsById)[`GET /v2/payments/collect/history`](/operations/getV2PaymentsCollectHistory)[`GET /v2/payments/collect/runs/{id}`](/operations/getV2PaymentsCollectRunsById)[`GET /v2/payments/collect/runs/{id}/payments`](/operations/getV2PaymentsCollectRunsByIdPayments)[`GET /v2/payments/collect/runs/history`](/operations/getV2PaymentsCollectRunsHistory)[`GET /v2/payments/collect/schedules`](/operations/getV2PaymentsCollectSchedules)[`GET /v2/payments/collect/settlements`](/operations/getV2PaymentsCollectSettlements)[`GET /v2/payments/collect/settlements/{id}`](/operations/getV2PaymentsCollectSettlementsById)[`GET /v2/payments/collect/settlements/{id}/payments`](/operations/getV2PaymentsCollectSettlementsByIdPayments)[`GET /v2/payments/collect/settlements/wallet`](/operations/getV2PaymentsCollectSettlementsWallet)[`GET /v2/payments/collect/upcoming`](/operations/getV2PaymentsCollectUpcoming)[`GET /v2/payments/collections/history`](/operations/getV2PaymentsCollectionsHistory)[`GET /v2/payments/account/balances/{type}`](/operations/getV2PaymentsAccountBalancesByType)[`GET /v2/payments/bulk-withdrawals/banks`](/operations/getV2PaymentsBulkWithdrawalsBanks)[`GET /v2/payments/bulk-withdrawals/batches`](/operations/getV2PaymentsBulkWithdrawalsBatches)[`POST /v2/payments/bulk-withdrawals/batches`](/operations/postV2PaymentsBulkWithdrawalsBatches)[`POST /v2/payments/bulk-withdrawals/batches/{id}/cancel`](/operations/postV2PaymentsBulkWithdrawalsBatchesByIdCancel)[`GET /v2/payments/bulk-withdrawals/batches/{id}/fee-quote`](/operations/getV2PaymentsBulkWithdrawalsBatchesByIdFeeQuote)[`PUT /v2/payments/bulk-withdrawals/batches/{id}/label`](/operations/putV2PaymentsBulkWithdrawalsBatchesByIdLabel)[`GET /v2/payments/bulk-withdrawals/batches/{id}/withdrawals`](/operations/getV2PaymentsBulkWithdrawalsBatchesByIdWithdrawals)[`GET /v2/payments/bulk-withdrawals/beneficiaries`](/operations/getV2PaymentsBulkWithdrawalsBeneficiaries)[`POST /v2/payments/bulk-withdrawals/beneficiaries`](/operations/postV2PaymentsBulkWithdrawalsBeneficiaries)[`DELETE /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/deleteV2PaymentsBulkWithdrawalsBeneficiariesById)[`GET /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/getV2PaymentsBulkWithdrawalsBeneficiariesById)[`PUT /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/putV2PaymentsBulkWithdrawalsBeneficiariesById)[`POST /v2/payments/bulk-withdrawals/beneficiaries/bulk`](/operations/postV2PaymentsBulkWithdrawalsBeneficiariesBulk)[`POST /v2/payments/bulk-withdrawals/fee-quote`](/operations/postV2PaymentsBulkWithdrawalsFeeQuote)[`GET /v2/payments/bulk-withdrawals/withdrawals`](/operations/getV2PaymentsBulkWithdrawalsWithdrawals)[`GET /v2/payments/payout/history`](/operations/getV2PaymentsPayoutHistory)[`GET /v2/payments/payout/history/{id}`](/operations/getV2PaymentsPayoutHistoryById) |
| `-16097` | `EXCHANGE_API_ERROR` | 502 | Upstream service error. | [`GET /v2/payments/bulk-withdrawals/batches/{id}`](/operations/getV2PaymentsBulkWithdrawalsBatchesById)[`GET /v2/payments`](/operations/getV2Payments)[`GET /v2/payments/{id}`](/operations/getV2PaymentsById)[`GET /v2/payments/collect/events`](/operations/getV2PaymentsCollectEvents)[`GET /v2/payments/collect/events/{id}`](/operations/getV2PaymentsCollectEventsById)[`GET /v2/payments/collect/history`](/operations/getV2PaymentsCollectHistory)[`GET /v2/payments/collect/runs/{id}`](/operations/getV2PaymentsCollectRunsById)[`GET /v2/payments/collect/runs/{id}/payments`](/operations/getV2PaymentsCollectRunsByIdPayments)[`GET /v2/payments/collect/runs/history`](/operations/getV2PaymentsCollectRunsHistory)[`GET /v2/payments/collect/schedules`](/operations/getV2PaymentsCollectSchedules)[`GET /v2/payments/collect/settlements`](/operations/getV2PaymentsCollectSettlements)[`GET /v2/payments/collect/settlements/{id}`](/operations/getV2PaymentsCollectSettlementsById)[`GET /v2/payments/collect/settlements/{id}/payments`](/operations/getV2PaymentsCollectSettlementsByIdPayments)[`GET /v2/payments/collect/settlements/wallet`](/operations/getV2PaymentsCollectSettlementsWallet)[`GET /v2/payments/collect/upcoming`](/operations/getV2PaymentsCollectUpcoming)[`GET /v2/payments/collections/history`](/operations/getV2PaymentsCollectionsHistory)[`GET /v2/payments/account/balances/{type}`](/operations/getV2PaymentsAccountBalancesByType)[`GET /v2/payments/bulk-withdrawals/banks`](/operations/getV2PaymentsBulkWithdrawalsBanks)[`GET /v2/payments/bulk-withdrawals/batches`](/operations/getV2PaymentsBulkWithdrawalsBatches)[`POST /v2/payments/bulk-withdrawals/batches`](/operations/postV2PaymentsBulkWithdrawalsBatches)[`POST /v2/payments/bulk-withdrawals/batches/{id}/cancel`](/operations/postV2PaymentsBulkWithdrawalsBatchesByIdCancel)[`GET /v2/payments/bulk-withdrawals/batches/{id}/fee-quote`](/operations/getV2PaymentsBulkWithdrawalsBatchesByIdFeeQuote)[`PUT /v2/payments/bulk-withdrawals/batches/{id}/label`](/operations/putV2PaymentsBulkWithdrawalsBatchesByIdLabel)[`GET /v2/payments/bulk-withdrawals/batches/{id}/withdrawals`](/operations/getV2PaymentsBulkWithdrawalsBatchesByIdWithdrawals)[`GET /v2/payments/bulk-withdrawals/beneficiaries`](/operations/getV2PaymentsBulkWithdrawalsBeneficiaries)[`POST /v2/payments/bulk-withdrawals/beneficiaries`](/operations/postV2PaymentsBulkWithdrawalsBeneficiaries)[`DELETE /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/deleteV2PaymentsBulkWithdrawalsBeneficiariesById)[`GET /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/getV2PaymentsBulkWithdrawalsBeneficiariesById)[`PUT /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/putV2PaymentsBulkWithdrawalsBeneficiariesById)[`POST /v2/payments/bulk-withdrawals/beneficiaries/bulk`](/operations/postV2PaymentsBulkWithdrawalsBeneficiariesBulk)[`POST /v2/payments/bulk-withdrawals/fee-quote`](/operations/postV2PaymentsBulkWithdrawalsFeeQuote)[`GET /v2/payments/bulk-withdrawals/withdrawals`](/operations/getV2PaymentsBulkWithdrawalsWithdrawals)[`GET /v2/payments/payout/history`](/operations/getV2PaymentsPayoutHistory)[`GET /v2/payments/payout/history/{id}`](/operations/getV2PaymentsPayoutHistoryById) |
| `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | 502 | Upstream service error. | [`GET /v2/payments/bulk-withdrawals/batches/{id}`](/operations/getV2PaymentsBulkWithdrawalsBatchesById)[`GET /v2/payments`](/operations/getV2Payments)[`GET /v2/payments/{id}`](/operations/getV2PaymentsById)[`GET /v2/payments/collect/events`](/operations/getV2PaymentsCollectEvents)[`GET /v2/payments/collect/events/{id}`](/operations/getV2PaymentsCollectEventsById)[`GET /v2/payments/collect/history`](/operations/getV2PaymentsCollectHistory)[`GET /v2/payments/collect/runs/{id}`](/operations/getV2PaymentsCollectRunsById)[`GET /v2/payments/collect/runs/{id}/payments`](/operations/getV2PaymentsCollectRunsByIdPayments)[`GET /v2/payments/collect/runs/history`](/operations/getV2PaymentsCollectRunsHistory)[`GET /v2/payments/collect/schedules`](/operations/getV2PaymentsCollectSchedules)[`GET /v2/payments/collect/settlements`](/operations/getV2PaymentsCollectSettlements)[`GET /v2/payments/collect/settlements/{id}`](/operations/getV2PaymentsCollectSettlementsById)[`GET /v2/payments/collect/settlements/{id}/payments`](/operations/getV2PaymentsCollectSettlementsByIdPayments)[`GET /v2/payments/collect/settlements/wallet`](/operations/getV2PaymentsCollectSettlementsWallet)[`GET /v2/payments/collect/upcoming`](/operations/getV2PaymentsCollectUpcoming)[`GET /v2/payments/collections/history`](/operations/getV2PaymentsCollectionsHistory)[`GET /v2/payments/account/balances/{type}`](/operations/getV2PaymentsAccountBalancesByType)[`GET /v2/payments/bulk-withdrawals/banks`](/operations/getV2PaymentsBulkWithdrawalsBanks)[`GET /v2/payments/bulk-withdrawals/batches`](/operations/getV2PaymentsBulkWithdrawalsBatches)[`POST /v2/payments/bulk-withdrawals/batches`](/operations/postV2PaymentsBulkWithdrawalsBatches)[`POST /v2/payments/bulk-withdrawals/batches/{id}/cancel`](/operations/postV2PaymentsBulkWithdrawalsBatchesByIdCancel)[`GET /v2/payments/bulk-withdrawals/batches/{id}/fee-quote`](/operations/getV2PaymentsBulkWithdrawalsBatchesByIdFeeQuote)[`PUT /v2/payments/bulk-withdrawals/batches/{id}/label`](/operations/putV2PaymentsBulkWithdrawalsBatchesByIdLabel)[`GET /v2/payments/bulk-withdrawals/batches/{id}/withdrawals`](/operations/getV2PaymentsBulkWithdrawalsBatchesByIdWithdrawals)[`GET /v2/payments/bulk-withdrawals/beneficiaries`](/operations/getV2PaymentsBulkWithdrawalsBeneficiaries)[`POST /v2/payments/bulk-withdrawals/beneficiaries`](/operations/postV2PaymentsBulkWithdrawalsBeneficiaries)[`DELETE /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/deleteV2PaymentsBulkWithdrawalsBeneficiariesById)[`GET /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/getV2PaymentsBulkWithdrawalsBeneficiariesById)[`PUT /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/putV2PaymentsBulkWithdrawalsBeneficiariesById)[`POST /v2/payments/bulk-withdrawals/beneficiaries/bulk`](/operations/postV2PaymentsBulkWithdrawalsBeneficiariesBulk)[`POST /v2/payments/bulk-withdrawals/fee-quote`](/operations/postV2PaymentsBulkWithdrawalsFeeQuote)[`GET /v2/payments/bulk-withdrawals/withdrawals`](/operations/getV2PaymentsBulkWithdrawalsWithdrawals)[`GET /v2/payments/payout/history`](/operations/getV2PaymentsPayoutHistory)[`GET /v2/payments/payout/history/{id}`](/operations/getV2PaymentsPayoutHistoryById) |
| `-11652` | `INTERNAL_TRANSFERS_NOT_AVAILABLE` | 503 | Internal transfers are currently not available. | [`POST /v1/account/subaccounts/transfer`](/operations/postV1AccountSubaccountsTransfer) |
| `-12015` | `WITHDRAWALS_NOT_AVAILABLE` | 503 | Withdrawals are currently not available. | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw)[`POST /v1/wallet/fiat/{currency}/withdraw`](/operations/postV1WalletFiatByCurrencyWithdraw)[`POST /v2/fiat/payments`](/operations/postV2FiatPayments)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments) |
| `-15117` | `UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED` | 503 | Unique deposit references are not available at this time | [`GET /v2/wallet/fiat/{currency}/payment/references/{referenceCode}`](/operations/getV2WalletFiatByCurrencyPaymentReferencesByReferenceCode)[`DELETE /v2/wallet/fiat/{currency}/payment/references/{referenceCode}`](/operations/deleteV2WalletFiatByCurrencyPaymentReferencesByReferenceCode)[`PUT /v2/wallet/fiat/{currency}/payment/references/{referenceCode}`](/operations/putV2WalletFiatByCurrencyPaymentReferencesByReferenceCode)[`POST /v2/wallet/fiat/{currency}/payment/references`](/operations/postV2WalletFiatByCurrencyPaymentReferences)[`GET /v2/wallet/fiat/{currency}/payment/references`](/operations/getV2WalletFiatByCurrencyPaymentReferences)[`GET /v2/wallet/fiat/{currency}/payment/deposits`](/operations/getV2WalletFiatByCurrencyPaymentDeposits) |
| `-15120` | `BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED` | 503 | Bulk deposit references are not available at this time | [`POST /v2/wallet/fiat/{currency}/payment/bulk-references`](/operations/postV2WalletFiatByCurrencyPaymentBulkReferences)[`GET /v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}`](/operations/getV2WalletFiatByCurrencyPaymentBulkReferencesByJobId)[`GET /v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}/items`](/operations/getV2WalletFiatByCurrencyPaymentBulkReferencesByJobIdItems) |
| `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | 503 | Payments backend is not available. | [`GET /v2/payments/bulk-withdrawals/batches/{id}`](/operations/getV2PaymentsBulkWithdrawalsBatchesById)[`GET /v2/payments`](/operations/getV2Payments)[`GET /v2/payments/{id}`](/operations/getV2PaymentsById)[`GET /v2/payments/collect/events`](/operations/getV2PaymentsCollectEvents)[`GET /v2/payments/collect/events/{id}`](/operations/getV2PaymentsCollectEventsById)[`GET /v2/payments/collect/history`](/operations/getV2PaymentsCollectHistory)[`GET /v2/payments/collect/runs/{id}`](/operations/getV2PaymentsCollectRunsById)[`GET /v2/payments/collect/runs/{id}/payments`](/operations/getV2PaymentsCollectRunsByIdPayments)[`GET /v2/payments/collect/runs/history`](/operations/getV2PaymentsCollectRunsHistory)[`GET /v2/payments/collect/schedules`](/operations/getV2PaymentsCollectSchedules)[`GET /v2/payments/collect/settlements`](/operations/getV2PaymentsCollectSettlements)[`GET /v2/payments/collect/settlements/{id}`](/operations/getV2PaymentsCollectSettlementsById)[`GET /v2/payments/collect/settlements/{id}/payments`](/operations/getV2PaymentsCollectSettlementsByIdPayments)[`GET /v2/payments/collect/settlements/wallet`](/operations/getV2PaymentsCollectSettlementsWallet)[`GET /v2/payments/collect/upcoming`](/operations/getV2PaymentsCollectUpcoming)[`GET /v2/payments/collections/history`](/operations/getV2PaymentsCollectionsHistory)[`GET /v2/payments/account/balances/{type}`](/operations/getV2PaymentsAccountBalancesByType)[`GET /v2/payments/bulk-withdrawals/banks`](/operations/getV2PaymentsBulkWithdrawalsBanks)[`GET /v2/payments/bulk-withdrawals/batches`](/operations/getV2PaymentsBulkWithdrawalsBatches)[`POST /v2/payments/bulk-withdrawals/batches`](/operations/postV2PaymentsBulkWithdrawalsBatches)[`POST /v2/payments/bulk-withdrawals/batches/{id}/cancel`](/operations/postV2PaymentsBulkWithdrawalsBatchesByIdCancel)[`GET /v2/payments/bulk-withdrawals/batches/{id}/fee-quote`](/operations/getV2PaymentsBulkWithdrawalsBatchesByIdFeeQuote)[`PUT /v2/payments/bulk-withdrawals/batches/{id}/label`](/operations/putV2PaymentsBulkWithdrawalsBatchesByIdLabel)[`GET /v2/payments/bulk-withdrawals/batches/{id}/withdrawals`](/operations/getV2PaymentsBulkWithdrawalsBatchesByIdWithdrawals)[`GET /v2/payments/bulk-withdrawals/beneficiaries`](/operations/getV2PaymentsBulkWithdrawalsBeneficiaries)[`POST /v2/payments/bulk-withdrawals/beneficiaries`](/operations/postV2PaymentsBulkWithdrawalsBeneficiaries)[`DELETE /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/deleteV2PaymentsBulkWithdrawalsBeneficiariesById)[`GET /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/getV2PaymentsBulkWithdrawalsBeneficiariesById)[`PUT /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/putV2PaymentsBulkWithdrawalsBeneficiariesById)[`POST /v2/payments/bulk-withdrawals/beneficiaries/bulk`](/operations/postV2PaymentsBulkWithdrawalsBeneficiariesBulk)[`POST /v2/payments/bulk-withdrawals/fee-quote`](/operations/postV2PaymentsBulkWithdrawalsFeeQuote)[`GET /v2/payments/bulk-withdrawals/withdrawals`](/operations/getV2PaymentsBulkWithdrawalsWithdrawals)[`GET /v2/payments/payout/history`](/operations/getV2PaymentsPayoutHistory)[`GET /v2/payments/payout/history/{id}`](/operations/getV2PaymentsPayoutHistoryById) |

---

---
url: /api-docs/getV1WalletFiatByCurrencyWithdrawEstimateFee.md
description: 'GET /v1/wallet/fiat/{currency}/withdraw/estimate-fee'
---

# Estimate a fiat withdrawal fee

`GET /v1/wallet/fiat/{currency}/withdraw/estimate-fee`

Returns the fee for withdrawing `amount` to a bank account linked to the account (the primary, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`). The fee is charged on top, so the account is debited `fullAmount` plus `feeAmount`.

**Requires** `WITHDRAWALS_READ`, granted by `TREASURY_READ` or `TREASURY_WRITE` or `WITHDRAWALS_WRITE` or `BANK_ACCOUNTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Fiat currency to withdraw, e.g. `ZAR`. |
| linkedBankAccountId | query | string | Yes | ID of the bank account to withdraw to. |
| amount | query | string | Yes | Amount to withdraw, as a decimal string. |
| fast | query | boolean | No | `true` to price a fast (RTC or RTGS) withdrawal. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| feeAmount | string | Yes | - |
| fullAmount | string | Yes | - |
| fast | boolean | Yes | - |

**Example:**

```json
{
  "feeAmount": "8.50",
  "fullAmount": "1500.00",
  "fast": false
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/wallet/fiat/{currency}/withdraw/estimate-fee'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/wallet/fiat/{currency}/withdraw/estimate-fee"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `linkedBankAccountId` is missing or isn't a UUID, `amount` is missing or isn't a number, `fast` isn't `true` or `false`, or the currency isn't recognised. |
| 404 | `-14203` | `COULD_NOT_GET_LINKED_ACCOUNT` | No bank account with this ID exists. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1WalletFiatByCurrencyAccountsById.md
description: 'GET /v1/wallet/fiat/{currency}/accounts/{id}'
---

# Get a bank account

`GET /v1/wallet/fiat/{currency}/accounts/{id}`

Returns a bank account linked to the account (the primary, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`).

**Requires** `WITHDRAWALS_READ`, granted by `TREASURY_READ` or `TREASURY_WRITE` or `WITHDRAWALS_WRITE` or `BANK_ACCOUNTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Fiat currency, e.g. `ZAR`. |
| id | path | string | Yes | Bank account ID: the `id` returned when it was linked or listed. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | - |
| bank | string | Yes | - |
| accountHolder | string | Yes | - |
| accountNumber | string | Yes | - |
| branchCode | string | Yes | - |
| accountType | string | Yes | - |
| createdAt | string | Yes | - |
| country | string | Yes | - |

**Example:**

```json
{
  "id": "3c9e1f42-7d5b-4a8e-9f21-6b0d8c4e7a15",
  "bank": "FNB/RMB",
  "accountHolder": "Acme Trading (Pty) Ltd",
  "accountNumber": "62792461544",
  "branchCode": "250655",
  "accountType": "Current/Cheque",
  "createdAt": "2026-08-14T09:21:37.408215Z",
  "country": "ZA"
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/wallet/fiat/{currency}/accounts/{id}'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/wallet/fiat/{currency}/accounts/{id}"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The currency isn't recognised or the bank account ID isn't a valid UUID. |
| 404 | `-14203` | `COULD_NOT_GET_LINKED_ACCOUNT` | No bank account with this ID is linked to the account. |
| 451 | `-15320` | `FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY` | Your business's region doesn't allow withdrawals in this currency. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV2PaymentsBulkWithdrawalsBatchesByIdFeeQuote.md
description: 'GET /v2/payments/bulk-withdrawals/batches/{id}/fee-quote'
---

# Get a batch's fee quote

`GET /v2/payments/bulk-withdrawals/batches/{id}/fee-quote`

Returns the fee for the batch's withdrawals that are still pending or, once none are pending, the fee that was charged. Unlike `GET /v2/payments/bulk-withdrawals/batches/{id}`, this returns an error rather than `null` when the fee can't be quoted.

**Requires** `DISBURSEMENTS_READ`, granted by `PAYMENTS_READ` or `DISBURSEMENTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | Yes | Batch ID. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| fee | string | Yes | Fee as a decimal string. `null` means the fee is unknown, which isn't the same as no fee. |
| currency | string | Yes | - |
| withdrawalCount | integer (int32) | Yes | Number of withdrawals the fee covers. |
| grossTotal | string | Yes | Sum of those withdrawals' amounts. |
| requiredTotal | string | Yes | Gross total plus fee: the available balance your payout account needs. |
| feeGroups | DisbursementFeeGroupForDisplay\[] | Yes | Breakdown by fee type; `null` when the quote is the fee already charged. |

**`feeGroups` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| actionType | string | Yes | `FAST_WITHDRAWAL` for banks that take real-time payments, otherwise `REGULAR_WITHDRAWAL`. |
| withdrawalCount | integer (int32) | Yes | - |
| grossTotal | string | Yes | - |

**Example:**

```json
{
  "fee": "25.00",
  "currency": "ZAR",
  "withdrawalCount": 2,
  "grossTotal": "20501.00",
  "requiredTotal": "20526.00",
  "feeGroups": null
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/payments/bulk-withdrawals/batches/{id}/fee-quote'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/payments/bulk-withdrawals/batches/{id}/fee-quote"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | The batch ID isn't a valid UUID. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No batch with this ID exists on your account. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV2PaymentsBulkWithdrawalsBeneficiariesById.md
description: 'GET /v2/payments/bulk-withdrawals/beneficiaries/{id}'
---

# Get a beneficiary

`GET /v2/payments/bulk-withdrawals/beneficiaries/{id}`

Returns a beneficiary, active or archived.

**Requires** `DISBURSEMENTS_READ`, granted by `PAYMENTS_READ` or `DISBURSEMENTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | Yes | Beneficiary ID. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | - |
| bank | string | Yes | - |
| bankDisplayName | string | Yes | - |
| accountHolder | string | Yes | - |
| accountNumberMasked | string | Yes | Account number with all but the last four digits masked. |
| accountNumber | string | Yes | - |
| branchCode | string | Yes | - |
| accountType | string | Yes | - |
| email | string | Yes | - |
| type | string | Yes | `INDIVIDUAL`, `BUSINESS`, or `null` if never set, which is possible for beneficiaries saved from a batch. |
| tradingName | string | Yes | - |
| reference | string | Yes | Default payment reference for this beneficiary. It isn't applied to payouts automatically. |
| country | string | Yes | - |
| createdAt | string (date-time) | Yes | - |
| updatedAt | string (date-time) | Yes | - |
| lastPaidAt | string (date-time) | Yes | When a payout to this beneficiary was last attempted; `null` if never. |
| deletedAt | string (date-time) | Yes | When the beneficiary was archived; `null` if it's active. |
| deletedBy | string | Yes | ID of the user or API key that archived the beneficiary. |

**Example:**

```json
{
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "bank": "FNB",
  "bankDisplayName": "FNB/RMB",
  "accountHolder": "Thandi Nkosi",
  "accountNumberMasked": "*******0327",
  "accountNumber": "62845190327",
  "branchCode": "250655",
  "accountType": "CHEQUE",
  "email": "thandi@example.com",
  "type": "INDIVIDUAL",
  "tradingName": null,
  "reference": "SALARY",
  "country": "ZA",
  "createdAt": "2026-09-01T10:12:30.004Z",
  "updatedAt": "2026-10-23T08:15:02.010Z",
  "lastPaidAt": "2026-10-23T08:15:03.204Z",
  "deletedAt": null,
  "deletedBy": null
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/payments/bulk-withdrawals/beneficiaries/{id}'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/payments/bulk-withdrawals/beneficiaries/{id}"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | The beneficiary ID isn't a valid UUID. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No beneficiary with this ID exists on your account. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV2WalletFiatByCurrencyPaymentBulkReferencesByJobId.md
description: 'GET /v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}'
---

# Get a bulk reference job

`GET /v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}`

Returns the status of a bulk reference job. `completedItems` and `failedItems` are filled in when the job finishes; while it's `PROCESSING`, list the job's items to follow its progress.

**Requires** `COLLECTIONS_READ`, granted by `PAYMENTS_READ` or `COLLECTIONS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Fiat currency of the references, e.g. `ZAR`. |
| jobId | path | integer | Yes | The `jobId` returned when the bulk job was created. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| jobId | integer (int64) | Yes | - |
| status | string (PROCESSING, COMPLETED, PARTIALLY\_FAILED) | Yes | `PROCESSING` while references are being created, then `COMPLETED` if every reference was created or `PARTIALLY_FAILED` if any failed. |
| totalItems | integer (int32) | Yes | - |
| acceptedItems | integer (int32) | Yes | - |
| completedItems | integer (int32) | Yes | Number of references created. Filled in when the job finishes. |
| failedItems | integer (int32) | Yes | Number of payers whose reference couldn't be created. Filled in when the job finishes. |
| createdAt | string | Yes | When the job was created, in Unix milliseconds. |
| completedAt | string | No | When the job finished, in Unix milliseconds. Absent until the job finishes. |

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The job ID isn't a whole number, or the currency isn't recognised. |
| 400 | `-15721` | `SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH` | Your collections account doesn't support this currency. |
| 404 | `-15122` | `BULK_DEPOSIT_REFERENCE_JOB_NOT_FOUND` | No bulk job with this ID exists on your account for this currency. |
| 503 | `-15120` | `BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED` | Bulk deposit references are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1WalletCryptoByCurrencyDepositAddress.md
description: 'GET /v1/wallet/crypto/{currency}/deposit/address'
---

# Get a crypto deposit address

`GET /v1/wallet/crypto/{currency}/deposit/address`

Returns the deposit address for a currency on one network for the account the request acts on (your primary account, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`), creating one if the account doesn't have one yet. To get the address of one of your business's payments accounts instead, send `accountType` and `destinationCurrency` together; a key restricted to sub-accounts can't do this.

**Requires** `DEPOSITS_READ`, granted by `TREASURY_READ` or `TREASURY_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Crypto currency to deposit, e.g. `USDT`. |
| networkType | query | string | No | Network to deposit on, e.g. `Ethereum`. Defaults to the currency's default network. |
| accountType | query | string | No | Payments account to get the address for, instead of the account the request acts on: `COLLECTIONS`, `FUNDING` or `PAYOUTS` (case-insensitive). Only takes effect together with `destinationCurrency`; if you send just one of the two, both are ignored. |
| destinationCurrency | query | string | No | Currency the payments account chosen with `accountType` is set up for, e.g. `ZAR` for a funding account whose deposits are converted to rand. Only takes effect together with `accountType`. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| currency | string | Yes | - |
| address | string | Yes | - |
| networkType | string | Yes | - |
| paymentReference | string | No | Memo, tag or reference that deposits to this address must include, on networks that use one. |
| legacy | boolean | No | `true` if this is an older address that still works; left out otherwise. |

**Example:**

```json
{
  "currency": "USDT",
  "address": "0x5b3f9a1c2e7d48a6b0c4e9f1a2d3b4c5e6f70812",
  "networkType": "Ethereum"
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/wallet/crypto/{currency}/deposit/address'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/wallet/crypto/{currency}/deposit/address"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The currency or `destinationCurrency` isn't recognised, or `accountType` is blank or isn't `COLLECTIONS`, `FUNDING` or `PAYOUTS`. |
| 400 | `-112` | `CURRENCY_NOT_SUPPORTED` | `networkType` wasn't sent and the currency can't be deposited on a blockchain, for example a fiat currency. |
| 400 | `-15721` | `SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH` | Your business has no account of the requested `accountType` set up for `destinationCurrency`. |
| 400 | `-13105` | `RECEIVE_ADDRESS_NOT_SUPPORTED_FOR_CURRENCY_NETWORK_TYPE` | The account has no address for this currency and network yet, and deposits on this network are disabled or not supported for this currency. |
| 403 | `-13104` | `RECEIVE_ADDRESS_NOT_SUPPORTED_IN_REGION` | The account has no address for this currency and network yet, and crypto deposits are restricted for your business, so a new one can't be created. |
| 500 | `-30` | `COULD_NOT_GET_RECEIVE_ADDRESS` | A new deposit address couldn't be created. Try again later. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1WalletCryptoByCurrencyWithdrawById.md
description: 'GET /v1/wallet/crypto/{currency}/withdraw/{id}'
---

# Get a crypto withdrawal

`GET /v1/wallet/crypto/{currency}/withdraw/{id}`

Returns one withdrawal from the account the request acts on (your primary account, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`), with its status, network fee and, once it has been broadcast, its transaction hash and confirmations.

**Requires** `WITHDRAWALS_READ`, granted by `TREASURY_READ` or `TREASURY_WRITE` or `WITHDRAWALS_WRITE` or `BANK_ACCOUNTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Currency of the withdrawal, e.g. `USDC`. It must match the withdrawal's currency. |
| id | path | string | Yes | Withdrawal ID returned when the withdrawal was created (`uniqueId` in responses). |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| currency | string | Yes | - |
| address | string | Yes | - |
| amount | string | Yes | - |
| feeAmount | string | Yes | Network fee, charged on top of `amount`. |
| transactionHash | string | No | Network transaction hash, once the withdrawal has been broadcast. |
| confirmations | integer (int32) | Yes | - |
| lastConfirmationAt | string | No | Time of the latest network confirmation, in UTC but without a time-zone designator. |
| uniqueId | string (uuid) | Yes | Withdrawal ID. |
| createdAt | string | Yes | When the withdrawal was created. `startTime` and `endTime` filter on this. |
| verified | boolean | Yes | - |
| status | string | Yes | `Pending`, `Awaiting approval`, `Processing`, `Complete`, `Failed` or `Cancelled`. Withdrawal lists leave out cancelled withdrawals. |
| networkType | string | No | - |
| paymentReference | string | No | - |
| paymentReferenceFieldName | string | No | - |

**Example:**

```json
{
  "currency": "USDC",
  "address": "0x8d3f2b6a91c04e7fa1b2c3d4e5f60718293a4b5c",
  "amount": "250",
  "feeAmount": "1.5",
  "transactionHash": "0x5901a831de792a71a309438bd8ada659952c7662f1c130a74dd1852906971a84",
  "confirmations": 12,
  "lastConfirmationAt": "2026-10-23T08:21:47.318205",
  "uniqueId": "7c1d9e42-5a3b-4f6e-9d8c-2b1a0f3e4d5c",
  "createdAt": "2026-10-23T08:15:02.441Z",
  "verified": true,
  "status": "Complete",
  "networkType": "Ethereum"
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/wallet/crypto/{currency}/withdraw/{id}'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/wallet/crypto/{currency}/withdraw/{id}"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The currency isn't recognised or the withdrawal ID isn't a valid UUID. |
| 404 | `-13403` | `SEND_NOT_FOUND` | No withdrawal with this ID exists on the account, or it's in a different currency. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV2WalletFiatByCurrencyPaymentReferencesByReferenceCode.md
description: 'GET /v2/wallet/fiat/{currency}/payment/references/{referenceCode}'
---

# Get a deposit reference

`GET /v2/wallet/fiat/{currency}/payment/references/{referenceCode}`

Returns a deposit reference and the deposits that have been matched to it.

**Requires** `COLLECTIONS_READ`, granted by `PAYMENTS_READ` or `COLLECTIONS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Fiat currency of the reference, e.g. `ZAR`. |
| referenceCode | path | string | Yes | The reference code returned when the reference was created. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| referenceCode | string | Yes | The reference your payer quotes when depositing. |
| currency | string | Yes | - |
| expectedAmount | string | No | - |
| createdAt | integer (int64) | Yes | When the reference was created, in Unix milliseconds. |
| name | string | No | - |
| email | string | No | - |
| matchedDeposits | UserMatchedDepositInfo\[] | Yes | Deposits matched to this reference. |
| matchedDepositCount | integer (int32) | Yes | - |

**`matchedDeposits` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| publicId | string (uuid) | Yes | - |
| amount | string | Yes | - |
| effectiveDate | string | Yes | - |
| creditedAt | integer (int64) | Yes | - |
| isOverride | boolean | Yes | `true` if this deposit is set as the reference's override deposit. |

**Example:**

```json
{
  "referenceCode": "VPAY-7K2Q9RT",
  "currency": "ZAR",
  "expectedAmount": "1500",
  "createdAt": 1792742400000,
  "name": "Thandi Nkosi",
  "email": "thandi@example.com",
  "matchedDeposits": [
    {
      "publicId": "3f1c2a9e-8b4d-4c1e-9f2a-6d7e8b9c0a1b",
      "amount": "1500",
      "effectiveDate": "2026-10-23",
      "creditedAt": 1792746000000,
      "isOverride": false
    }
  ],
  "matchedDepositCount": 1
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/wallet/fiat/{currency}/payment/references/{referenceCode}'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/wallet/fiat/{currency}/payment/references/{referenceCode}"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 404 | `-15114` | `UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND` | No reference with this code exists on your account. |
| 503 | `-15117` | `UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED` | Deposit references are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV2PaymentsBulkWithdrawalsBatchesById.md
description: 'GET /v2/payments/bulk-withdrawals/batches/{id}'
---

# Get a disbursement batch

`GET /v2/payments/bulk-withdrawals/batches/{id}`

Returns a disbursement batch with its status and totals. While withdrawals in the batch are still pending, `feeQuote` shows the fees they will incur.

**Requires** `DISBURSEMENTS_READ`, granted by `PAYMENTS_READ` or `DISBURSEMENTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | Yes | Batch ID. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | - |
| label | string | Yes | - |
| currency | string | Yes | - |
| totalAmount | string | Yes | Sum of the withdrawal amounts, as a decimal string. |
| withdrawalCount | integer (int32) | Yes | - |
| status | string | Yes | Batch status: `PENDING_APPROVAL`, `APPROVED`, `PROCESSING`, `COMPLETED`, `PARTIALLY_COMPLETED`, `FAILED` or `CANCELLED`. |
| uploadedBy | string | Yes | ID of the user or API key that created the batch. |
| uploadedByName | object | Yes | - |
| approvedBy | string | Yes | ID of the user or API key that approved the batch (for a batch created with an API key, that key); `null` until approved. |
| approvedByName | object | Yes | - |
| approvedAt | string (date-time) | Yes | - |
| createdAt | string (date-time) | Yes | - |
| updatedAt | string (date-time) | Yes | - |
| completedAt | string (date-time) | Yes | - |
| feeQuote | object | Yes | Fee for the batch's pending withdrawals, or the fee charged once none are pending. Only returned by `GET /v2/payments/bulk-withdrawals/batches/{id}`; `null` elsewhere, and when the fee can't be quoted. |

**`uploadedByName` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | - |
| surname | string | Yes | - |

**`approvedByName` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | - |
| surname | string | Yes | - |

**`feeQuote` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| fee | string | Yes | Fee as a decimal string. `null` means the fee is unknown, which isn't the same as no fee. |
| currency | string | Yes | - |
| withdrawalCount | integer (int32) | Yes | Number of withdrawals the fee covers. |
| grossTotal | string | Yes | Sum of those withdrawals' amounts. |
| requiredTotal | string | Yes | Gross total plus fee: the available balance your payout account needs. |
| feeGroups | DisbursementFeeGroupForDisplay\[] | Yes | Breakdown by fee type; `null` when the quote is the fee already charged. |

**`feeGroups` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| actionType | string | Yes | `FAST_WITHDRAWAL` for banks that take real-time payments, otherwise `REGULAR_WITHDRAWAL`. |
| withdrawalCount | integer (int32) | Yes | - |
| grossTotal | string | Yes | - |

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/payments/bulk-withdrawals/batches/{id}'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/payments/bulk-withdrawals/batches/{id}"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | The batch ID isn't a valid UUID. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No batch with this ID exists on your account. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1WalletFiatByCurrencyWithdrawalsById.md
description: 'GET /v1/wallet/fiat/{currency}/withdrawals/{id}'
---

# Get a fiat withdrawal

`GET /v1/wallet/fiat/{currency}/withdrawals/{id}`

Returns a fiat withdrawal with the bank account it was paid to, its fee and, if it was reversed, the amounts returned. It must belong to the account (the primary, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`), unless `includeAllSubAccounts` applies.

**Requires** `WITHDRAWALS_READ`, granted by `TREASURY_READ` or `TREASURY_WRITE` or `WITHDRAWALS_WRITE` or `BANK_ACCOUNTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Fiat currency of the withdrawal, e.g. `ZAR`. |
| id | path | string | Yes | Withdrawal ID: the `id` returned when the withdrawal was created. |
| includeAllSubAccounts | query | boolean | No | `true` to find the withdrawal on the primary or any sub-account apart from hidden ones. Only applies when you don't send `X-VALR-SUB-ACCOUNT-ID` and the key isn't restricted to sub-accounts; otherwise it's ignored. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | - |
| subAccountId | string | Yes | - |
| currency | string | Yes | - |
| amount | string | Yes | - |
| status | string (NEW, PENDING\_APPROVAL, PROCESSING, PAID, REVERSED, FAILED, DECLINED) | Yes | - |
| isFast | boolean | Yes | - |
| createdAt | string | Yes | - |
| updatedAt | string | Yes | - |
| linkedBankAccount | object | Yes | - |
| reference | string | No | - |
| feeAmount | string | No | - |
| reversal | object | No | - |
| failureReason | string | No | - |
| failureReasonDescription | string | No | - |
| failureReasonAction | string | No | - |
| failureRetryable | boolean | No | - |

**`linkedBankAccount` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | - |
| bankCode | string | Yes | - |
| bankName | string | Yes | - |
| accountHolder | string | Yes | - |
| accountNumber | string | Yes | - |
| branchCode | string | Yes | - |
| accountType | string | Yes | - |
| status | string (NEW, CONFIRMED, DELETED, VERIFIED, VERIFICATION\_FAILED) | Yes | - |
| insertedAt | string | Yes | - |
| updatedAt | string | Yes | - |
| country | string | Yes | - |
| currency | object | Yes | - |

**`currency` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| symbol | string | Yes | - |
| decimalPlaces | integer (int32) | Yes | - |
| isActive | boolean | Yes | - |
| shortName | string | Yes | - |
| longName | string | Yes | - |
| supportedWithdrawDecimalPlaces | integer (int32) | Yes | - |
| paymentReferenceFieldName | string | No | - |
| collateral | boolean | Yes | - |
| collateralWeight | string | Yes | - |
| supportedNetworks | SupportedNetworkForDisplay\[] | No | - |
| currencyTypeId | integer (int32) | No | - |

**`supportedNetworks` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| networkType | string | Yes | - |
| networkLongName | string | No | - |
| tokenContract | string | No | - |
| minimumWithdrawAmount | string | No | - |
| estimatedSendCost | string | No | - |
| deposit | boolean | Yes | - |
| withdraw | boolean | Yes | - |
| withdrawalDecimalPlaces | integer (int32) | No | - |

**`reversal` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| principalReturned | string | Yes | - |
| feeReturned | string | No | - |
| returnedAt | string | Yes | - |

**Example:**

```json
{
  "id": "d4a7c2e9-61f3-4b8d-9e05-7c1b3f6a2d84",
  "subAccountId": "0",
  "currency": "ZAR",
  "amount": "1500.00",
  "status": "PAID",
  "isFast": false,
  "createdAt": "2026-10-23T08:30:05.272523Z",
  "updatedAt": "2026-10-23T11:02:41.167902Z",
  "linkedBankAccount": {
    "id": "3c9e1f42-7d5b-4a8e-9f21-6b0d8c4e7a15",
    "bankCode": "FNB",
    "bankName": "FNB/RMB",
    "accountHolder": "Acme Trading (Pty) Ltd",
    "accountNumber": "62792461544",
    "branchCode": "250655",
    "accountType": "Current/Cheque",
    "status": "VERIFIED",
    "insertedAt": "2026-08-14T09:21:37.408215Z",
    "updatedAt": "2026-08-14T09:23:02.115480Z",
    "country": "ZA",
    "currency": {
      "symbol": "R",
      "decimalPlaces": 2,
      "isActive": true,
      "shortName": "ZAR",
      "longName": "Rand",
      "supportedWithdrawDecimalPlaces": 2,
      "collateral": true,
      "collateralWeight": "1"
    }
  },
  "reference": "INV 2026-0142",
  "feeAmount": "8.50"
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/wallet/fiat/{currency}/withdrawals/{id}'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/wallet/fiat/{currency}/withdrawals/{id}"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The withdrawal ID isn't a valid UUID, `includeAllSubAccounts` isn't `true` or `false`, or the currency isn't recognised. |
| 404 | `-15300` | `COULD_NOT_FIND_FIAT_WITHDRAWAL` | No withdrawal in this currency with this ID exists on the account, or on any of your business's visible accounts when `includeAllSubAccounts` applies. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1PublicByCurrencyPairMarketsummary.md
description: 'GET /v1/public/{currencyPair}/marketsummary'
---

# Get a pair's market summary

`GET /v1/public/{currencyPair}/marketsummary`

Returns one currency pair's market summary: best ask and bid, last traded price, and the high, low and volume over the last 24 hours, with the percentage change from the last price before then. Responses are cached for up to 5 seconds.

**Public**: no API key needed. Send the request as is, without signing it.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currencyPair | path | string | Yes | Currency pair symbol, e.g. `BTCZAR`. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| currencyPair | string | Yes | - |
| askPrice | string | Yes | - |
| bidPrice | string | Yes | - |
| lastTradedPrice | string | Yes | - |
| previousClosePrice | string | Yes | - |
| baseVolume | string | Yes | - |
| quoteVolume | string | Yes | - |
| highPrice | string | Yes | - |
| lowPrice | string | Yes | - |
| created | string | Yes | - |
| changeFromPrevious | string | Yes | - |
| markPrice | string | No | - |

**Example:**

```json
{
  "currencyPair": "BTCZAR",
  "askPrice": "1850012",
  "bidPrice": "1849800",
  "lastTradedPrice": "1849900",
  "previousClosePrice": "1832000",
  "baseVolume": "12.4518",
  "quoteVolume": "22958256.31",
  "highPrice": "1861000",
  "lowPrice": "1825500",
  "created": "2026-10-23T08:51:12.004Z",
  "changeFromPrevious": "0.98",
  "markPrice": "1849900"
}
```

## Example request

```bash
curl -X GET 'https://api.valr.com/v1/public/{currencyPair}/marketsummary'
```

```python
import requests

response = requests.request("GET", "https://api.valr.com/v1/public/{currencyPair}/marketsummary")
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-21` | `INVALID_CURRENCY_PAIR` | `currencyPair` isn't a currency pair VALR supports. |
| 404 | `-111` | `MARKET_SUMMARY_NOT_FOUND` | VALR has no market summary for the pair yet, which can happen for a pair that isn't trading. |

Public endpoints are not signed, so they never return authentication errors.

---

---
url: /api-docs/getV2PaymentsById.md
description: 'GET /v2/payments/{id}'
---

# Get a payment

`GET /v2/payments/{id}`

Returns a payment with its step-by-step timeline and the settled payouts that carried it. The payment can be on any account in your business.

**Requires** `COLLECTIONS_READ`, granted by `PAYMENTS_READ` or `COLLECTIONS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | Yes | Payment ID. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | Payment ID. |
| depositId | string | Yes | ID of the deposit that created the payment. |
| status | string | Yes | Overall status: `RECEIVED`, `CONVERTED`, `SWEPT`, `PENDING_SETTLEMENT`, `COMPLETED` or `FAILED`. |
| mode | string | Yes | How the payment is paid out: `INSTANT` or `SCHEDULED`. Null until a payout is set up. |
| type | string | Yes | `COLLECTION` for a payment from a payer, `DISBURSEMENT` for a deposit that funds disbursements. |
| inflowCurrency | string | Yes | - |
| inflowAmount | string | Yes | Amount deposited. |
| convertedCurrency | string | Yes | - |
| convertedAmount | string | Yes | Amount after conversion; null if the deposit hasn't been converted. |
| outflowCurrency | string | Yes | - |
| outflowAmount | string | Yes | Amount paid out; null until a payout is set up. |
| receivedAt | integer (int64) | Yes | When the deposit was received, in Unix milliseconds. |
| settlementAt | integer (int64) | Yes | Expected settlement time while a scheduled payout is pending, then the time the payment settled, in Unix milliseconds. |
| settlementStatus | string | Yes | `PENDING`, `SETTLED` or `FAILED`. |
| settlementRef | string | Yes | Payout reference, such as the blockchain transaction hash of a crypto payout. |
| settlementId | string | Yes | The settlement that paid this payment out; null until a payout has been requested. |
| linked | boolean | Yes | Whether the deposit carries a payer reference. |
| payerName | string | Yes | Payer's name. |
| reference | string | Yes | Payer reference quoted with the deposit. |
| timeline | FlowStepForDisplay\[] | Yes | Steps the payment has been through. Only returned when you get a single payment. |
| payouts | PaymentPayoutForUser\[] | Yes | Settled payouts that carried this payment; more than one if it was split. Only returned when you get a single payment. |

**`timeline` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| type | string | Yes | `FUNDING`, `CONVERSION`, `SWEEP`, `WITHDRAWAL` or `SETTLEMENT`. |
| label | string | Yes | - |
| status | string | Yes | `PENDING`, `COMPLETE` or `FAILED`. |
| data | object | Yes | Amounts and currencies for the step. |
| traceId | string | Yes | Reference you can quote to support, such as a conversion ID or blockchain transaction hash. |
| at | integer (int64) | Yes | When the step happened, in Unix milliseconds. For a pending settlement, the scheduled time. |

**`payouts` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| settlementId | string | Yes | - |
| amount | string | Yes | - |
| currency | string | Yes | - |
| status | string | Yes | Payout status. Only settled payouts are listed, so this is `SETTLED`. |
| settledAt | integer (int64) | Yes | When the payout settled, in Unix milliseconds. |

**Example:**

```json
{
  "id": "8d2f4b6a-1c3e-4f5a-9b7d-2e4c6a8b0d1f",
  "depositId": "3f1c2a9e-8b4d-4c1e-9f2a-6d7e8b9c0a1b",
  "status": "COMPLETED",
  "mode": "SCHEDULED",
  "type": "COLLECTION",
  "inflowCurrency": "ZAR",
  "inflowAmount": "1500.00",
  "convertedCurrency": "USDC",
  "convertedAmount": "82.45",
  "outflowCurrency": "USDC",
  "outflowAmount": "82.45",
  "receivedAt": 1792660500000,
  "settlementAt": 1792684950000,
  "settlementStatus": "SETTLED",
  "settlementRef": null,
  "settlementId": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f",
  "linked": true,
  "payerName": "Thandi Nkosi",
  "reference": "VLR4F7K2Q9",
  "timeline": [
    {
      "type": "FUNDING",
      "label": "1500.00 ZAR collected",
      "status": "COMPLETE",
      "data": {
        "currency": "ZAR",
        "amount": "1500.00"
      },
      "traceId": null,
      "at": 1792660500000
    },
    {
      "type": "CONVERSION",
      "label": "Converted to 82.45 USDC",
      "status": "COMPLETE",
      "data": {
        "fromCurrency": "ZAR",
        "fromAmount": "1500.00",
        "toCurrency": "USDC",
        "toAmount": "82.45",
        "rate": "18.1928",
        "conversionId": "b7d9f1a3-5c2e-4b8d-a6f0-3e5c7a9b1d4f"
      },
      "traceId": "b7d9f1a3-5c2e-4b8d-a6f0-3e5c7a9b1d4f",
      "at": 1792660565000
    },
    {
      "type": "SWEEP",
      "label": "Swept to payout account",
      "status": "COMPLETE",
      "data": {
        "currency": "USDC",
        "amount": "82.45"
      },
      "traceId": null,
      "at": 1792660600000
    },
    {
      "type": "SETTLEMENT",
      "label": "Settled",
      "status": "COMPLETE",
      "data": {
        "currency": "USDC",
        "amount": "82.45"
      },
      "traceId": null,
      "at": 1792684950000
    }
  ],
  "payouts": [
    {
      "settlementId": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f",
      "amount": "82.45",
      "currency": "USDC",
      "status": "SETTLED",
      "settledAt": 1792684950000
    }
  ]
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/payments/{id}'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/payments/{id}"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | The payment ID isn't a valid UUID. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No payment with this ID exists in your business. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV2PaymentsPayoutHistoryById.md
description: 'GET /v2/payments/payout/history/{id}'
---

# Get a payout account transaction

`GET /v2/payments/payout/history/{id}`

Returns one transaction on your payout account.

**Requires** `DISBURSEMENTS_READ`, granted by `PAYMENTS_READ` or `DISBURSEMENTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | Yes | Transaction ID. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | - |
| direction | string | Yes | `DEBIT` (money out) or `CREDIT` (money in). |
| kind | string | Yes | `WITHDRAWAL` (a payout), `FUNDING` (an automated funding transfer), `FUNDING_MANUAL` (any other top-up) or `REVERSAL` (a reversed payout returned to the account). |
| status | string | Yes | `COMPLETE`, `PROCESSING`, `REVERSED` or `FAILED`. |
| amount | string | Yes | Amount including any fee, as an unsigned decimal string; `direction` gives the sign. |
| currency | string | Yes | - |
| date | integer (int64) | Yes | When the transaction happened, in Unix milliseconds. |
| counterparty | string | Yes | The recipient's name for a debit; `Payout account` or `Reversal` for a credit. |
| reference | string | Yes | Payment reference, or `Funding` for a credit without one. |
| batchId | string | Yes | - |
| batchLabel | string | Yes | - |
| paymentId | string | Yes | For a funding credit, the ID of the payment that funded it; use it with `GET /v2/payments/{id}`. |

**Example:**

```json
{
  "id": "e3f5a7b9-1c2d-4e6f-8a0b-2c4d6e8f0a1b",
  "direction": "DEBIT",
  "kind": "WITHDRAWAL",
  "status": "COMPLETE",
  "amount": "12513.25",
  "currency": "ZAR",
  "date": 1792746164000,
  "counterparty": "Thandi Nkosi",
  "reference": "OCT SALARY",
  "batchId": "5b9a3c1e-2f4d-4a7b-9c8e-1d2f3a4b5c6d",
  "batchLabel": "October salaries",
  "paymentId": null
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/payments/payout/history/{id}'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/payments/payout/history/{id}"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | The transaction ID isn't a valid UUID. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No payout account transaction with this ID exists on your account. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV2PaymentsCollectRunsById.md
description: 'GET /v2/payments/collect/runs/{id}'
---

# Get a payout run

`GET /v2/payments/collect/runs/{id}`

Returns one scheduled payout run with its timing, status and total. The run must belong to one of your business's payout schedules.

**Requires** `COLLECTIONS_READ`, granted by `PAYMENTS_READ` or `COLLECTIONS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | Yes | Payout run ID. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | - |
| scheduledFor | integer (int64) | Yes | When the run pays out, in Unix milliseconds. |
| cutoffAt | integer (int64) | Yes | Payments received after this time wait for the next run, in Unix milliseconds. |
| status | string | Yes | `PENDING`, `PROCESSING`, `DONE`, `FAILED`, `CANCELLED` or `REVERSED`. |
| totalAmount | string | Yes | Total the run pays out; `0` until the run starts. |
| currency | string | Yes | - |
| createdAt | integer (int64) | Yes | - |

**Example:**

```json
{
  "id": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f",
  "scheduledFor": 1792684800000,
  "cutoffAt": 1792677600000,
  "status": "DONE",
  "totalAmount": "1240.75",
  "currency": "USDC",
  "createdAt": 1792598405000
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/payments/collect/runs/{id}'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/payments/collect/runs/{id}"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | The run ID isn't a valid UUID. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No payout run with this ID exists on your business's payout schedules. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV2PaymentsCollectEventsById.md
description: 'GET /v2/payments/collect/events/{id}'
---

# Get a scheduled payment

`GET /v2/payments/collect/events/{id}`

Returns one payment on a payout schedule, with the deposit it came from and its timeline. It must be on one of your business's payout schedules.

**Requires** `COLLECTIONS_READ`, granted by `PAYMENTS_READ` or `COLLECTIONS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | Yes | Scheduled payment ID, from List queued scheduled payments or List processed scheduled payments. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | - |
| withdrawalCurrency | string | Yes | - |
| withdrawalAmount | string | Yes | Amount the payment adds to the payout. |
| receivedAt | integer (int64) | Yes | When the payment joined the schedule, in Unix milliseconds. |
| status | string | Yes | `QUEUED`, `SCHEDULED`, `PROCESSING`, `COMPLETED`, `FAILED` or `REVERSED`. |
| depositCurrency | string | Yes | - |
| depositAmount | string | Yes | Amount of the deposit the payment came from. |
| payerName | string | Yes | - |
| reference | string | Yes | - |
| timeline | FlowStepForDisplay\[] | Yes | Steps the payment has been through. Only returned when you get a single scheduled payment. |

**`timeline` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| type | string | Yes | `FUNDING`, `CONVERSION`, `SWEEP`, `WITHDRAWAL` or `SETTLEMENT`. |
| label | string | Yes | - |
| status | string | Yes | `PENDING`, `COMPLETE` or `FAILED`. |
| data | object | Yes | Amounts and currencies for the step. |
| traceId | string | Yes | Reference you can quote to support, such as a conversion ID or blockchain transaction hash. |
| at | integer (int64) | Yes | When the step happened, in Unix milliseconds. For a pending settlement, the scheduled time. |

**Example:**

```json
{
  "id": "6b0d2f4a-8c1e-4a3b-9d5f-7e9a1b3c5d7e",
  "withdrawalCurrency": "USDC",
  "withdrawalAmount": "54.20",
  "receivedAt": 1792744300000,
  "status": "SCHEDULED",
  "depositCurrency": "ZAR",
  "depositAmount": "985.00",
  "payerName": "Sipho Dlamini",
  "reference": "VLR8M3N6P1",
  "timeline": [
    {
      "type": "CONVERSION",
      "label": "Converted to 54.20 USDC",
      "status": "COMPLETE",
      "data": {
        "fromCurrency": "ZAR",
        "fromAmount": "985.00",
        "toCurrency": "USDC",
        "toAmount": "54.20",
        "rate": "18.1734",
        "conversionId": "d1f3b5a7-9e2c-4d6f-8a0b-5c7e9f1a3b6d"
      },
      "traceId": "d1f3b5a7-9e2c-4d6f-8a0b-5c7e9f1a3b6d",
      "at": 1792744270000
    },
    {
      "type": "SETTLEMENT",
      "label": "Settlement pending",
      "status": "PENDING",
      "data": {
        "currency": "USDC",
        "amount": "54.20",
        "scheduledFor": "2026-10-23T16:00:00Z"
      },
      "traceId": null,
      "at": 1792771200000
    }
  ]
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/payments/collect/events/{id}'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/payments/collect/events/{id}"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | The scheduled payment ID isn't a valid UUID. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No scheduled payment with this ID exists on your business's payout schedules. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV2PaymentsCollectSettlementsById.md
description: 'GET /v2/payments/collect/settlements/{id}'
---

# Get a settlement

`GET /v2/payments/collect/settlements/{id}`

Returns one settlement with its totals and status. The settlement must belong to your business.

**Requires** `COLLECTIONS_READ`, granted by `PAYMENTS_READ` or `COLLECTIONS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | Yes | Settlement ID: a payout run ID for a scheduled payout, or a payout ID for an instant payout. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | Settlement ID: the payout run ID for a scheduled payout, or the payout ID for an instant payout. |
| currency | string | Yes | Payout currency. |
| totalAmount | string | Yes | Total the settlement pays out. |
| settledAmount | string | Yes | Amount paid out so far; equals `totalAmount` once fully settled. |
| paymentCount | integer (int32) | Yes | - |
| status | string | Yes | `PENDING`, `SETTLED`, `FAILED` or `PARTIALLY_SETTLED`. |
| settledAt | integer (int64) | Yes | Latest time a payment in the settlement settled, in Unix milliseconds; null if none has. |
| receivedAt | integer (int64) | Yes | When the most recent payment in the settlement was received, in Unix milliseconds. |

**Example:**

```json
{
  "id": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f",
  "currency": "USDC",
  "totalAmount": "1240.75",
  "settledAmount": "1240.75",
  "paymentCount": 23,
  "status": "SETTLED",
  "settledAt": 1792684950000,
  "receivedAt": 1792676400000
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/payments/collect/settlements/{id}'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/payments/collect/settlements/{id}"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | The settlement ID is longer than 64 characters, contains characters other than letters, digits, `.`, `_` and `-`, or is only dots. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No settlement with this ID exists in your business. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1AccountSubaccountByAccountPublicId.md
description: 'GET /v1/account/subaccount/{accountPublicId}'
---

# Get a sub-account

`GET /v1/account/subaccount/{accountPublicId}`

Returns a sub-account's ID and name. A sub-account registered with its account holder's KYC details also returns those details, such as `firstName`, `lastName`, `identityNumber` and `email`. Call it on your primary account (don't send `X-VALR-SUB-ACCOUNT-ID`); keys limited to some sub-accounts can't use it.

**Requires** `SUB_ACCOUNTS_READ`, granted by `TREASURY_READ` or `TREASURY_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| accountPublicId | path | string | Yes | Sub-account ID: the `id` returned by List sub-accounts. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | Sub-account ID. |
| label | string | Yes | Sub-account name. |
| firstName | string | No | - |
| lastName | string | No | - |
| dateOfBirth | string | No | - |
| residentialCountry | string | No | - |
| identityIssuingCountry | string | No | - |
| identityType | string | No | - |
| identityNumber | string | No | - |
| identityExpiryDate | string | No | - |
| cellNumber | string | No | - |
| email | string | No | - |
| gender | string | No | - |
| purpose | string | No | - |
| employmentStatus | string | No | - |
| sourceOfFunds | string | No | - |

**Example:**

```json
{
  "id": "7340032581337088",
  "label": "Treasury"
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/account/subaccount/{accountPublicId}'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/account/subaccount/{accountPublicId}"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The sub-account ID isn't a whole number. |
| 400 | `-11134` | `SUB_ACCOUNT_NOT_FOUND` | None of your business's sub-accounts has this ID. Your primary account (`0`) isn't a sub-account. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1WebhooksById.md
description: 'GET /v1/webhooks/{id}'
---

# Get a webhook

`GET /v1/webhooks/{id}`

Returns a webhook. The signing secret isn't included; to check which secret it uses, compare `signingSecretFingerprint` with the first 8 hex characters of the SHA-256 hash of the secret you stored. Keys restricted to sub-accounts can't use this endpoint.

**Requires** `WEBHOOKS_READ`, granted by `WEBHOOKS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | Yes | Webhook ID: the `identifier` returned when the webhook was created. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| identifier | string | Yes | Webhook ID. |
| scopeKind | string | Yes | What the webhook is attached to. Always `ENTITY` for webhooks managed with an institution key: the webhook receives events for every account in your business. |
| scopeLabel | string | Yes | Readable label for `scopeKind`. |
| url | string | Yes | URL events are delivered to. |
| eventTypes | string\[] | Yes | Event types delivered to this webhook. |
| active | boolean | Yes | Whether events are delivered. An inactive webhook receives nothing until it's reactivated. |
| description | string | No | Your label for the webhook. Absent if you didn't set one. |
| signingSecretFingerprint | string | Yes | First 8 hex characters of the SHA-256 hash of the signing secret, so you can check which secret the webhook uses. The secret itself is only returned when the webhook is created. |
| createdAt | string | Yes | When the webhook was created, as an ISO 8601 timestamp in UTC. |
| updatedAt | string | Yes | When the webhook was last changed, as an ISO 8601 timestamp in UTC. |

**Example:**

```json
{
  "identifier": "0b8f5d2e-7a41-4c3b-9e6d-2f1a8c7b5e90",
  "scopeKind": "ENTITY",
  "scopeLabel": "Entity",
  "url": "https://hooks.example.com/valr",
  "eventTypes": [
    "FIAT_DEPOSIT_CREDITED",
    "FIAT_WITHDRAWAL_STATUS_UPDATE"
  ],
  "active": true,
  "description": "Treasury reconciliation",
  "signingSecretFingerprint": "7477002c",
  "createdAt": "2026-10-23T08:00:00.214367Z",
  "updatedAt": "2026-10-23T08:00:00.214367Z"
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/webhooks/{id}'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/webhooks/{id}"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The webhook ID isn't a valid UUID. |
| 404 | `-18121` | `WEBHOOK_SUBSCRIPTION_NOT_FOUND` | No webhook with this ID exists for your business. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1WebhooksByIdEventsByEventId.md
description: 'GET /v1/webhooks/{id}/events/{eventId}'
---

# Get a webhook event

`GET /v1/webhooks/{id}/events/{eventId}`

Returns one event sent to a webhook: the exact JSON body that was delivered, as a string, and every attempt to deliver it, oldest first. Keys restricted to sub-accounts can't use this endpoint.

**Requires** `WEBHOOKS_READ`, granted by `WEBHOOKS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | Yes | Webhook ID: the `identifier` returned when the webhook was created. |
| eventId | path | string | Yes | Event ID: the `eventId` of a delivery attempt, or the `Valr-Webhook-Event-Id` header of a delivery. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| eventId | string | Yes | Event ID. |
| eventType | string | Yes | Event type. |
| payload | string | Yes | The exact JSON body that was delivered, as a string. Retries send the same body. |
| attempts | WebhookDeliveryAttemptForDisplay\[] | Yes | Every attempt to deliver this event, oldest first. |

**`attempts` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| eventId | string | Yes | Event ID. The same for every attempt to deliver an event, and sent in the `Valr-Webhook-Event-Id` header. |
| eventType | string | Yes | Event type, as sent in the `Valr-Webhook-Event-Type` header. |
| attemptNumber | integer (int32) | Yes | 1 for the first attempt, increasing by one with each retry. |
| responseStatus | integer (int32) | No | HTTP status your endpoint returned. Absent if no response was received. |
| errorCategory | string | No | Why the attempt failed: `TIMEOUT`, `CONNECTION_REFUSED`, `CONNECTION_RESET`, `DNS_FAILURE`, `TLS_FAILURE`, `NETWORK_UNREACHABLE`, `HTTP_STATUS`, `BLOCKED` or `UNKNOWN`. Absent if the attempt succeeded. |
| errorMessage | string | No | Readable explanation of `errorCategory`. |
| nextRetryAt | string | No | When the event will be retried, as an ISO 8601 timestamp in UTC. Absent if this attempt won't be retried. |
| terminalState | string | No | Set on the last attempt for an event: `SUCCESS`, `PERMANENT_FAILURE` (the failure isn't retried, for example a 4xx response) or `DEAD_LETTER` (every retry failed). Absent while delivery is still being retried. |
| createdAt | string | Yes | When the attempt was made, as an ISO 8601 timestamp in UTC. |

**Example:**

```json
{
  "eventId": "6c2e9b41-3d7f-4a8e-b5c1-9f0a2d4e6b8c",
  "eventType": "FIAT_DEPOSIT_CREDITED",
  "payload": "{\"id\":\"6c2e9b41-3d7f-4a8e-b5c1-9f0a2d4e6b8c\",\"type\":\"FIAT_DEPOSIT_CREDITED\",\"createdAt\":1792743330123,\"apiVersion\":\"2026-09-16\",\"subAccount\":null,\"data\":{\"depositId\":\"3f1c2a9e-8b4d-4c1e-9f2a-6d7e8b9c0a1b\",\"amount\":\"1500\",\"currencySymbol\":\"ZAR\",\"reference\":\"VLR4F7K2Q9\",\"effectiveDate\":1792713600000,\"creditedAt\":1792743330000}}",
  "attempts": [
    {
      "eventId": "6c2e9b41-3d7f-4a8e-b5c1-9f0a2d4e6b8c",
      "eventType": "FIAT_DEPOSIT_CREDITED",
      "attemptNumber": 1,
      "errorCategory": "TIMEOUT",
      "errorMessage": "Your endpoint did not respond within the delivery timeout.",
      "nextRetryAt": "2026-10-23T08:16:03.512874Z",
      "createdAt": "2026-10-23T08:15:33.512874Z"
    },
    {
      "eventId": "6c2e9b41-3d7f-4a8e-b5c1-9f0a2d4e6b8c",
      "eventType": "FIAT_DEPOSIT_CREDITED",
      "attemptNumber": 2,
      "responseStatus": 200,
      "terminalState": "SUCCESS",
      "createdAt": "2026-10-23T08:16:04.108392Z"
    }
  ]
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/webhooks/{id}/events/{eventId}'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/webhooks/{id}/events/{eventId}"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The webhook ID or event ID isn't a valid UUID. |
| 404 | `-18121` | `WEBHOOK_SUBSCRIPTION_NOT_FOUND` | No webhook with this ID exists for your business. |
| 404 | `-18123` | `WEBHOOK_EVENT_NOT_FOUND` | This webhook hasn't sent an event with this ID. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1WalletFiatByCurrencyDepositReferenceByBuyCurrencySymbol.md
description: 'GET /v1/wallet/fiat/{currency}/deposit/reference/{buyCurrencySymbol}'
---

# Get an auto-buy deposit reference

`GET /v1/wallet/fiat/{currency}/deposit/reference/{buyCurrencySymbol}`

Returns an auto-buy reference: a deposit in `currency` that quotes it is credited to the account (the primary, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`) and used to buy `buyCurrencySymbol`. List the currencies you can buy with List auto-buy currencies.

**Requires** `DEPOSITS_READ`, granted by `TREASURY_READ` or `TREASURY_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Fiat currency you'll deposit, e.g. `ZAR`. |
| buyCurrencySymbol | path | string | Yes | Currency to buy with the deposit, e.g. `BTC`. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| reference | string | Yes | - |

**Example:**

```json
{
  "reference": "BTC4NQ8ZKW"
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/wallet/fiat/{currency}/deposit/reference/{buyCurrencySymbol}'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/wallet/fiat/{currency}/deposit/reference/{buyCurrencySymbol}"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `currency` or `buyCurrencySymbol` isn't a recognised currency. |
| 400 | `-21` | `INVALID_CURRENCY_PAIR` | There's no market for buying `buyCurrencySymbol` with `currency`. |
| 400 | `-32` | `CURRENCY_PAIR_NOT_ACTIVE` | The market for buying `buyCurrencySymbol` with `currency` isn't active. |
| 400 | `-15132` | `CURRENCY_NOT_ENABLED_FOR_FIAT_DEPOSIT_AUTO_BUY` | `buyCurrencySymbol` can't be auto-bought with `currency`; list the currencies that can with List auto-buy currencies. |
| 451 | `-15134` | `CURRENCY_NOT_ALLOWED_FOR_FIAT_DEPOSIT_AUTO_BUY` | Auto-buy into `buyCurrencySymbol` with `currency` isn't available for your business. |
| 451 | `-15111` | `FIAT_DEPOSITS_NOT_ALLOWED_FOR_CURRENCY` | Your business's region doesn't allow deposits in `currency`. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1AccountBalances.md
description: GET /v1/account/balances
---

# Get balances

`GET /v1/account/balances`

Returns the balance of each currency in the account.

**Requires** `ACCOUNT_BALANCES_READ`, granted by `TRADING_READ` or `TRADING_WRITE` or `TREASURY_READ` or `TREASURY_WRITE` or `WITHDRAWALS_WRITE` or `VALR_PAY_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| excludeZeroBalances | query | boolean | No | Leave out currencies with a zero balance. |

## Responses

### 200

OK

Array of objects:

| Property | Type | Required | Description |
|---|---|---|---|
| currency | string | Yes | - |
| available | string | Yes | - |
| reserved | string | Yes | - |
| total | string | Yes | - |
| updatedAt | string | No | - |
| lendReserved | string | Yes | - |
| borrowReserved | string | Yes | - |
| borrowedAmount | string | Yes | - |
| totalInReference | string | Yes | - |
| totalInReferenceWeighted | string | Yes | - |
| referenceCurrency | string | Yes | - |

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/account/balances'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/account/balances"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

Only the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1AccountBalancesAll.md
description: GET /v1/account/balances/all
---

# Get balances for all accounts

`GET /v1/account/balances/all`

Returns the balances of your primary account and each of its sub-accounts in one call: every currency with a balance, reserved amount or debt, grouped by account. Accounts with nothing in them are listed with an empty `balances` array, and your primary account (`id` `0`) comes last. Balances in your payments payout, collections and funding accounts aren't included; use Get payments account balances for those. Call it on your primary account (don't send `X-VALR-SUB-ACCOUNT-ID`); keys limited to some sub-accounts can't use it.

**Requires** `ACCOUNT_BALANCES_READ`, granted by `TRADING_READ` or `TRADING_WRITE` or `TREASURY_READ` or `TREASURY_WRITE` or `WITHDRAWALS_WRITE` or `VALR_PAY_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Responses

### 200

OK

Array of objects:

| Property | Type | Required | Description |
|---|---|---|---|
| account | object | Yes | The account. `id` `0` is your primary account. |
| balances | V1CurrencyBalanceForApi\[] | Yes | Each currency in the account with a balance, reserved amount or debt. Empty if there are none. |

**`account` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| label | string | Yes | Account name. Your primary account's is `Primary`. |
| id | string | Yes | Account ID: `0` for your primary account. It's a string because sub-account IDs can be larger than some languages' numbers hold exactly. Send a sub-account's ID in `X-VALR-SUB-ACCOUNT-ID` to act on it. |
| accountTags | string\[] | No | Tags on the account, such as `CLIENT_FUNDS`. Only returned when you set `includeTags` to `true`. |
| autoPayoutLinkedBankAccountId | string | No | ID of the bank account this account pays out to automatically. Only returned when you set `includePayoutAccounts` to `true` and the account has one. |

**`balances` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| currency | string | Yes | Currency code, e.g. `ZAR`. |
| available | string | Yes | Amount available to trade, transfer or withdraw. |
| reserved | string | Yes | Amount reserved for open orders and pending withdrawals. |
| total | string | Yes | `available` plus `reserved`, `lendReserved` and `borrowReserved`, minus `borrowedAmount`. Negative if the account owes more of this currency than it holds. |
| updatedAt | string | No | When the balance last changed, as an ISO 8601 timestamp in UTC. |
| lendReserved | string | Yes | Amount committed to lending. |
| borrowReserved | string | Yes | Amount held as collateral for borrowing. |
| borrowedAmount | string | Yes | Amount borrowed and not yet repaid. |

**Example:**

```json
[
  {
    "account": {
      "label": "Treasury",
      "id": "7340032581337088"
    },
    "balances": [
      {
        "currency": "USDC",
        "available": "24850.12",
        "reserved": "0",
        "total": "24850.12",
        "updatedAt": "2026-10-22T09:30:12.884Z",
        "lendReserved": "0",
        "borrowReserved": "0",
        "borrowedAmount": "0"
      },
      {
        "currency": "USDT",
        "available": "998.5",
        "reserved": "0",
        "total": "998.5",
        "updatedAt": "2026-10-22T10:02:44.319Z",
        "lendReserved": "0",
        "borrowReserved": "0",
        "borrowedAmount": "0"
      }
    ]
  },
  {
    "account": {
      "label": "Client Funds",
      "id": "7339876125413376"
    },
    "balances": []
  },
  {
    "account": {
      "label": "Primary",
      "id": "0"
    },
    "balances": [
      {
        "currency": "ZAR",
        "available": "1265172.33",
        "reserved": "25000",
        "total": "1290172.33",
        "updatedAt": "2026-10-22T14:03:51.207Z",
        "lendReserved": "0",
        "borrowReserved": "0",
        "borrowedAmount": "0"
      },
      {
        "currency": "BTC",
        "available": "0.4175",
        "reserved": "0",
        "total": "0.4175",
        "updatedAt": "2026-10-22T14:03:51.207Z",
        "lendReserved": "0",
        "borrowReserved": "0",
        "borrowedAmount": "0"
      }
    ]
  }
]
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/account/balances/all'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/account/balances/all"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

Only the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1WalletCryptoByCurrencyWithdrawLimits.md
description: 'GET /v1/wallet/crypto/{currency}/withdraw/limits'
---

# Get crypto withdrawal limits

`GET /v1/wallet/crypto/{currency}/withdraw/limits`

Returns your business's withdrawal limit, valued in BTC, how much of it has been used, and the most you can still withdraw in this currency. Limits apply to your whole business, so the result is the same whichever account the request acts on.

**Requires** `WITHDRAWALS_READ`, granted by `TREASURY_READ` or `TREASURY_WRITE` or `WITHDRAWALS_WRITE` or `BANK_ACCOUNTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Currency to give the remaining limit in, e.g. `BTC`. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| limitType | string | Yes | `daily` for a limit over the last 24 hours, or `lifetime` for a limit over the life of the account. |
| totalWithdrawnAmountInReferenceCurrency | string | Yes | Amount withdrawn in the limit's period, valued in `referenceCurrency`. |
| withdrawLimitAmountInReferenceCurrency | string | Yes | The limit, in `referenceCurrency`. |
| referenceCurrency | string | Yes | - |
| maxWithdrawAmountInWithdrawCurrency | string | Yes | Most you can still withdraw in the period, in `withdrawCurrency`. |
| withdrawCurrency | string | Yes | - |

**Example:**

```json
{
  "limitType": "daily",
  "totalWithdrawnAmountInReferenceCurrency": "0.15000000",
  "withdrawLimitAmountInReferenceCurrency": "10.00000000",
  "referenceCurrency": "BTC",
  "maxWithdrawAmountInWithdrawCurrency": "9.85000000",
  "withdrawCurrency": "BTC"
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/wallet/crypto/{currency}/withdraw/limits'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/wallet/crypto/{currency}/withdraw/limits"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The currency isn't recognised. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1WalletCryptoByCurrencyWithdraw.md
description: 'GET /v1/wallet/crypto/{currency}/withdraw'
---

# Get crypto withdrawal settings

`GET /v1/wallet/crypto/{currency}/withdraw`

Returns the minimum amount, network fee and decimal places for withdrawing a currency on one network, and whether withdrawals on it are open. Amounts with more decimal places than `withdrawalDecimalPlaces` are rounded down when you withdraw.

**Requires** `WITHDRAWALS_READ`, granted by `TREASURY_READ` or `TREASURY_WRITE` or `WITHDRAWALS_WRITE` or `BANK_ACCOUNTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Crypto currency, e.g. `USDC`. |
| networkType | query | string | No | Network to get the settings for, e.g. `Ethereum`. Defaults to the currency's default network. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| currency | string | Yes | - |
| minimumWithdrawAmount | string | Yes | - |
| withdrawalDecimalPlaces | string | Yes | Most decimal places a withdrawal amount can have; extra places are rounded down. |
| isActive | boolean | Yes | Whether withdrawals of this currency on this network are open. |
| withdrawCost | string | Yes | Network fee charged on top of each withdrawal, in this currency. |
| networkType | string | Yes | - |
| supportsPaymentReference | boolean | Yes | Whether withdrawals on this network can carry a `paymentReference`. |
| paymentReferenceFieldName | string | No | What this network calls its payment reference, when it supports one. |

**Example:**

```json
{
  "currency": "USDC",
  "minimumWithdrawAmount": "10",
  "withdrawalDecimalPlaces": "6",
  "isActive": true,
  "withdrawCost": "1.5",
  "networkType": "Ethereum",
  "supportsPaymentReference": false
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/wallet/crypto/{currency}/withdraw'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/wallet/crypto/{currency}/withdraw"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The currency isn't recognised. |
| 400 | `-112` | `CURRENCY_NOT_SUPPORTED` | `networkType` wasn't sent and the currency can't be withdrawn on a blockchain, for example a fiat currency. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV2PaymentsAccountBalancesByType.md
description: 'GET /v2/payments/account/balances/{type}'
---

# Get payments account balances

`GET /v2/payments/account/balances/{type}`

Returns the balances of one of your business's payments accounts, chosen by account type and currency. The response lists every currency held in that account.

**Requires** `PAYMENTS_BALANCES_READ`, granted by `PAYMENTS_READ` or `COLLECTIONS_WRITE` or `DISBURSEMENTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| type | path | string | Yes | Which payments account to read: `PAYOUT` (pays your disbursements), `COLLECTIONS` (receives collections), `FUNDING` (receives the deposits that fund your payouts) or `HOLD` (holds collected funds until you convert or withdraw them). Case-insensitive. |
| currency | query | string | Yes | Currency of the account to read, e.g. `ZAR`. |

## Responses

### 200

OK

Array of objects:

| Property | Type | Required | Description |
|---|---|---|---|
| currency | object | Yes | - |
| available | string | Yes | Balance available to use, as a decimal string. |
| reserved | string | Yes | Balance that is reserved and not available, as a decimal string. |
| total | string | Yes | Available plus reserved, as a decimal string. |

**`currency` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| shortName | string | Yes | - |
| symbol | string | Yes | - |
| longName | string | Yes | - |

**Example:**

```json
[
  {
    "currency": {
      "shortName": "ZAR",
      "symbol": "R",
      "longName": "Rand"
    },
    "available": "125000.00",
    "reserved": "0",
    "total": "125000.00"
  }
]
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/payments/account/balances/{type}'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/payments/account/balances/{type}"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | `type` isn't one of `PAYOUT`, `COLLECTIONS`, `FUNDING` or `HOLD`. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | Your business has no account of this type set up for `currency`. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1WalletFiatByCurrencyDepositReference.md
description: 'GET /v1/wallet/fiat/{currency}/deposit/reference'
---

# Get the account deposit reference

`GET /v1/wallet/fiat/{currency}/deposit/reference`

Returns the reference to quote when you deposit this currency by bank transfer, so the deposit is credited to the account: the primary, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`. Each account has its own reference, created the first time you ask for it.

**Requires** `DEPOSITS_READ`, granted by `TREASURY_READ` or `TREASURY_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Fiat currency you'll deposit, e.g. `ZAR`. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| reference | string | Yes | - |

**Example:**

```json
{
  "reference": "VR4KQ7ZP2M"
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/wallet/fiat/{currency}/deposit/reference'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/wallet/fiat/{currency}/deposit/reference"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The currency isn't recognised. |
| 451 | `-15111` | `FIAT_DEPOSITS_NOT_ALLOWED_FOR_CURRENCY` | Your business's region doesn't allow deposits in this currency. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1PublicStatus.md
description: GET /v1/public/status
---

# Get the exchange status

`GET /v1/public/status`

Returns `online` when VALR accepts all requests, or `read-only` when it only accepts `GET` and `OPTIONS` requests and rejects the rest with `503`.

**Public**: no API key needed. Send the request as is, without signing it.

## Responses

### 200

OK

**Example:**

```json
{
  "status": "online"
}
```

## Example request

```bash
curl -X GET 'https://api.valr.com/v1/public/status'
```

```python
import requests

response = requests.request("GET", "https://api.valr.com/v1/public/status")
print(response.status_code, response.text)
```

## Errors

None specific to this endpoint.

---

---
url: /api-docs/getV1PublicTime.md
description: GET /v1/public/time
---

# Get the server time

`GET /v1/public/time`

Returns VALR's server time as Unix seconds (`epochTime`) and as an ISO 8601 timestamp (`time`). Signed requests are rejected when their timestamp is too far from the server's time, so use this to check your clock.

**Public**: no API key needed. Send the request as is, without signing it.

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| epochTime | integer (int64) | Yes | - |
| time | string | Yes | - |

**Example:**

```json
{
  "epochTime": 1793004161,
  "time": "2026-10-26T08:42:41.280178906Z"
}
```

## Example request

```bash
curl -X GET 'https://api.valr.com/v1/public/time'
```

```python
import requests

response = requests.request("GET", "https://api.valr.com/v1/public/time")
print(response.status_code, response.text)
```

## Errors

None specific to this endpoint.

---

---
url: /api-docs/getV2PaymentsCollectSettlementsWallet.md
description: GET /v2/payments/collect/settlements/wallet
---

# Get the settlement wallet

`GET /v2/payments/collect/settlements/wallet`

Returns the crypto wallet your business's collected funds settle to.

**Requires** `COLLECTIONS_READ`, granted by `PAYMENTS_READ` or `COLLECTIONS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | Wallet ID. |
| name | string | Yes | Label you gave the wallet. |
| address | string | Yes | - |
| network | string | Yes | Blockchain network of the wallet. |
| currency | string | Yes | - |
| beneficiaryName | string | Yes | Name of the wallet's owner. |
| serviceProviderName | string | Yes | Provider that hosts the wallet, if recorded. |

**Example:**

```json
{
  "id": "e2a4c6b8-0d1f-4e3a-b5c7-9d1e3f5a7b9c",
  "name": "Treasury USDC",
  "address": "0x7a2D4c9E1b3F5a8C0d6E2f4B9c1A3e5D7b9F0c2E",
  "network": "Ethereum",
  "currency": "USDC",
  "beneficiaryName": "Acme Trading (Pty) Ltd",
  "serviceProviderName": null
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/payments/collect/settlements/wallet'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/payments/collect/settlements/wallet"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No settlement wallet is set up for your business. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV2PaymentsCollectUpcoming.md
description: GET /v2/payments/collect/upcoming
---

# Get upcoming scheduled payouts

`GET /v2/payments/collect/upcoming`

Returns one entry per active payout schedule in your business, with the next run time, its cut-off and the total queued so far. A schedule with nothing queued shows a zero total and no run times.

**Requires** `COLLECTIONS_READ`, granted by `PAYMENTS_READ` or `COLLECTIONS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | No | Only include schedules that pay out in this currency. Use the upper-case code, e.g. `USDC`. |

## Responses

### 200

OK

Array of objects:

| Property | Type | Required | Description |
|---|---|---|---|
| scheduleId | string | Yes | - |
| currency | string | Yes | - |
| nextRunAt | integer (int64) | Yes | When the next run pays out, in Unix milliseconds; null if nothing is queued. |
| cutoffAt | integer (int64) | Yes | Cut-off for the next run, in Unix milliseconds; null if nothing is queued. |
| totalAmount | string | Yes | Total queued for the next run. |
| eventCount | integer (int32) | Yes | Number of payments queued for the next run. |

**Example:**

```json
[
  {
    "scheduleId": "1a7c3e5b-9d2f-4b6a-8e0c-2f4a6b8d0e1c",
    "currency": "USDC",
    "nextRunAt": 1792771200000,
    "cutoffAt": 1792764000000,
    "totalAmount": "54.20",
    "eventCount": 1
  }
]
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/payments/collect/upcoming'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/payments/collect/upcoming"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/postV1WalletFiatByCurrencyAccounts.md
description: 'POST /v1/wallet/fiat/{currency}/accounts'
---

# Link a bank account

`POST /v1/wallet/fiat/{currency}/accounts`

Links a bank account for fiat withdrawals to the account (the primary, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`). It's active straight away, with no email or two-factor confirmation; for currencies that only pay out to verified bank accounts, withdrawals to it are refused until it shows `VERIFIED`. Take `bank` from List banks for a currency; `accountType` is `CHEQUE`, `SAVINGS`, `BOND` or `TRANSMISSION` for South African accounts.

**Requires** `BANK_ACCOUNTS_MANAGE`, granted by `BANK_ACCOUNTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Fiat currency the bank account receives, e.g. `ZAR`. |

## Request Body

**Content-Type:** `application/json`

| Property | Type | Required | Description |
|---|---|---|---|
| bank | string | Yes | - |
| accountHolder | string | Yes | - |
| accountNumber | string | Yes | - |
| branchCode | string | Yes | - |
| suppliedBankCode | string | No | - |
| accountType | string | Yes | - |
| country | string | No | - |
| markForAutoPayout | boolean | No | - |
| tradingName | string | No | - |
| countryOfRegistration | string | No | - |

## Responses

### 202

Accepted

| Property | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | - |
| bankCode | string | Yes | - |
| bankName | string | Yes | - |
| accountHolder | string | Yes | - |
| accountNumber | string | Yes | - |
| branchCode | string | Yes | - |
| accountType | string | Yes | - |
| status | string (NEW, CONFIRMED, DELETED, VERIFIED, VERIFICATION\_FAILED) | Yes | - |
| insertedAt | string | Yes | - |
| updatedAt | string | Yes | - |
| country | string | Yes | - |
| currency | object | Yes | - |

**`currency` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| symbol | string | Yes | - |
| decimalPlaces | integer (int32) | Yes | - |
| isActive | boolean | Yes | - |
| shortName | string | Yes | - |
| longName | string | Yes | - |
| supportedWithdrawDecimalPlaces | integer (int32) | Yes | - |
| paymentReferenceFieldName | string | No | - |
| collateral | boolean | Yes | - |
| collateralWeight | string | Yes | - |
| supportedNetworks | SupportedNetworkForDisplay\[] | No | - |
| currencyTypeId | integer (int32) | No | - |

**`supportedNetworks` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| networkType | string | Yes | - |
| networkLongName | string | No | - |
| tokenContract | string | No | - |
| minimumWithdrawAmount | string | No | - |
| estimatedSendCost | string | No | - |
| deposit | boolean | Yes | - |
| withdraw | boolean | Yes | - |
| withdrawalDecimalPlaces | integer (int32) | No | - |

**Example:**

```json
{
  "id": "b71d4e93-2a6f-4c08-8e5b-d93f1a7c2e40",
  "bankCode": "FNB",
  "bankName": "FNB/RMB",
  "accountHolder": "Acme Trading (Pty) Ltd",
  "accountNumber": "62792461544",
  "branchCode": "250655",
  "accountType": "Current/Cheque",
  "status": "CONFIRMED",
  "insertedAt": "2026-10-23T08:14:02.518236Z",
  "updatedAt": "2026-10-23T08:14:02.611904Z",
  "country": "ZA",
  "currency": {
    "symbol": "R",
    "decimalPlaces": 2,
    "isActive": true,
    "shortName": "ZAR",
    "longName": "Rand",
    "supportedWithdrawDecimalPlaces": 2,
    "collateral": true,
    "collateralWeight": "1"
  }
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=POST
REQUEST_PATH='/v1/wallet/fiat/{currency}/accounts'
BODY='{"bank":"<bank>","accountHolder":"<accountHolder>","accountNumber":"<accountNumber>","branchCode":"<branchCode>","suppliedBankCode":"<suppliedBankCode>","accountType":"<accountType>","country":"<country>","markForAutoPayout":false,"tradingName":"<tradingName>","countryOfRegistration":"<countryOfRegistration>"}'
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}" -H "Content-Type: application/json" --data "$BODY"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "POST"
path = "/v1/wallet/fiat/{currency}/accounts"
body = "{\"bank\":\"<bank>\",\"accountHolder\":\"<accountHolder>\",\"accountNumber\":\"<accountNumber>\",\"branchCode\":\"<branchCode>\",\"suppliedBankCode\":\"<suppliedBankCode>\",\"accountType\":\"<accountType>\",\"country\":\"<country>\",\"markForAutoPayout\":false,\"tradingName\":\"<tradingName>\",\"countryOfRegistration\":\"<countryOfRegistration>\"}"  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID
headers["Content-Type"] = "application/json"

response = requests.request(method, "https://api.valr.com" + path, headers=headers, data=body.encode())
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation, including a `bank` that isn't in the country's bank list or a branch code, account number or account type that doesn't fit the country, or the currency isn't recognised; `validationErrors` lists each failing field. |
| 400 | `-15875` | `FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED` | Withdrawals to this branch code aren't supported. Use another branch or contact support. |
| 400 | `-13418` | `BANK_ACCOUNT_LINKING_TEMPORARILY_DISABLED` | Linking bank accounts is paused for a while after a security change on your account, such as a password reset or a new device; the message says when it's re-enabled. |
| 400 | `-115` | `INVALID_COUNTRY_ALPHA_2` | No banks are available for the bank account's country. |
| 451 | `-15320` | `FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY` | Your business's region doesn't allow withdrawals in this currency. |
| 500 | `-15317` | `BANK_REMOTE_FETCH_FAILURE` | The bank list for the bank account's country couldn't be loaded. Try again later. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/putV2WalletFiatByCurrencyPaymentDepositsByPublicIdReference.md
description: 'PUT /v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference'
---

# Link a deposit to a reference

`PUT /v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference`

Links a credited deposit to one of your deposit references, replacing any reference it was already matched to. Use it to correct which payer a deposit is attributed to; the funds stay where they are.

**Requires** `COLLECTIONS_UPDATE`, granted by `COLLECTIONS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Fiat currency of the deposits, e.g. `ZAR`. |
| publicId | path | string | Yes | The deposit's `publicId`. |

## Request Body

**Content-Type:** `application/json`

| Property | Type | Required | Description |
|---|---|---|---|
| referenceCode | string | Yes | The reference to link the deposit to. |

## Responses

### 204

No content

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=PUT
REQUEST_PATH='/v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference'
BODY='{"referenceCode":"<referenceCode>"}'
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}" -H "Content-Type: application/json" --data "$BODY"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "PUT"
path = "/v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference"
body = "{\"referenceCode\":\"<referenceCode>\"}"  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID
headers["Content-Type"] = "application/json"

response = requests.request(method, "https://api.valr.com" + path, headers=headers, data=body.encode())
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation; `validationErrors` lists each failing field. |
| 400 | `-15115` | `UNIQUE_DEPOSIT_REFERENCE_INVALID_OVERRIDE` | The deposit hasn't been fully credited yet. |
| 404 | `-15118` | `FIAT_DEPOSIT_NOT_FOUND` | No deposit with this ID exists on your collections account. |
| 404 | `-15114` | `UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND` | No reference with this code exists on your account. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV2PaymentsBulkWithdrawalsBatchesByIdWithdrawals.md
description: 'GET /v2/payments/bulk-withdrawals/batches/{id}/withdrawals'
---

# List a batch's withdrawals

`GET /v2/payments/bulk-withdrawals/batches/{id}/withdrawals`

Returns the withdrawals in a batch, newest first, a page at a time. Use `updatedSince` to fetch only the withdrawals that changed since you last checked.

**Requires** `DISBURSEMENTS_READ`, granted by `PAYMENTS_READ` or `DISBURSEMENTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | Yes | Batch ID. |
| status | query | string | No | Only withdrawals with this status. |
| failureCode | query | string | No | Only failed withdrawals with this failure category. |
| updatedSince | query | string | No | Only withdrawals whose status changed, or whose fee was refunded, at or after this time. ISO 8601 with a time zone. |
| limit | query | integer | No | Page size, from 1 to 200; values outside that range are clamped. |
| offset | query | integer | No | Number of items to skip. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| items | BulkWithdrawalForDisplay\[] | Yes | - |
| total | integer (int32) | Yes | - |
| limit | integer (int32) | Yes | - |
| offset | integer (int32) | Yes | - |
| truncated | boolean | Yes | - |

**`items` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | - |
| batchId | string (uuid) | Yes | - |
| uploadedBy | string | Yes | - |
| uploadedByName | object | Yes | - |
| approvedBy | string | Yes | - |
| approvedByName | object | Yes | - |
| amount | string | Yes | - |
| bank | string | Yes | - |
| bankDisplayName | string | Yes | - |
| accountType | string | Yes | - |
| accountHolder | string | Yes | - |
| accountNumberMasked | string | Yes | - |
| accountNumber | string | Yes | - |
| branchCode | string | Yes | - |
| reference | string | Yes | - |
| linkedBankAccountId | string (uuid) | Yes | - |
| withdrawalId | string | Yes | - |
| status | string | Yes | Withdrawal status: `PENDING`, `APPROVED`, `EXECUTING`, `SUBMITTED`, `PROCESSING`, `PAID`, `FAILED` or `SKIPPED`. |
| failureReason | string | Yes | Why the withdrawal failed; `null` unless it failed. |
| failureReasonCode | string | Yes | Failure category, e.g. `INSUFFICIENT_FUNDS` or `REVERSED`; `null` unless it failed. |
| reversed | boolean | Yes | - |
| feeReversed | boolean | Yes | Whether the withdrawal's fee has been refunded. |
| createdAt | string (date-time) | Yes | - |
| updatedAt | string (date-time) | Yes | - |
| lastChangedAt | string (date-time) | Yes | When the status last changed or the fee was refunded; this is what `updatedSince` filters on. |

**`uploadedByName` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | - |
| surname | string | Yes | - |

**`approvedByName` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | - |
| surname | string | Yes | - |

**Example:**

```json
{
  "items": [
    {
      "id": "c4e8a2b6-3d5f-4a1c-9e7b-2f4d6a8c0e1b",
      "batchId": "5b9a3c1e-2f4d-4a7b-9c8e-1d2f3a4b5c6d",
      "uploadedBy": "8d2f4e6a-1b3c-4d5e-8f9a-0b1c2d3e4f5a",
      "uploadedByName": null,
      "approvedBy": "8d2f4e6a-1b3c-4d5e-8f9a-0b1c2d3e4f5a",
      "approvedByName": null,
      "amount": "12500.75",
      "bank": "FNB",
      "bankDisplayName": "FNB/RMB",
      "accountType": "CHEQUE",
      "accountHolder": "Thandi Nkosi",
      "accountNumberMasked": "*******0327",
      "accountNumber": "62845190327",
      "branchCode": "250655",
      "reference": "OCT SALARY",
      "linkedBankAccountId": null,
      "withdrawalId": "0f3b5d7e-9a1c-4e2f-8b4d-6c8e0a2b4d6f",
      "status": "PAID",
      "failureReason": null,
      "failureReasonCode": null,
      "feeReversed": false,
      "createdAt": "2026-10-23T08:15:01.912Z",
      "updatedAt": "2026-10-23T09:02:44.118Z",
      "lastChangedAt": "2026-10-23T09:02:44.118Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0,
  "truncated": null
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/payments/bulk-withdrawals/batches/{id}/withdrawals'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/payments/bulk-withdrawals/batches/{id}/withdrawals"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | The batch ID isn't a valid UUID. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No batch with this ID exists on your account. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV2PaymentsCollectRunsByIdPayments.md
description: 'GET /v2/payments/collect/runs/{id}/payments'
---

# List a payout run's payments

`GET /v2/payments/collect/runs/{id}/payments`

Returns the payments a scheduled payout run includes. An ID that isn't one of your business's runs returns an empty page.

**Requires** `COLLECTIONS_READ`, granted by `PAYMENTS_READ` or `COLLECTIONS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | Yes | Payout run ID. |
| limit | query | integer | No | Maximum number of payments to return. |
| offset | query | integer | No | Number of payments to skip, for paging. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| items | PaymentForUser\[] | Yes | - |
| total | integer (int32) | Yes | - |
| limit | integer (int32) | Yes | - |
| offset | integer (int32) | Yes | - |

**`items` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | Payment ID. |
| depositId | string | Yes | ID of the deposit that created the payment. |
| status | string | Yes | Overall status: `RECEIVED`, `CONVERTED`, `SWEPT`, `PENDING_SETTLEMENT`, `COMPLETED` or `FAILED`. |
| mode | string | Yes | How the payment is paid out: `INSTANT` or `SCHEDULED`. Null until a payout is set up. |
| type | string | Yes | `COLLECTION` for a payment from a payer, `DISBURSEMENT` for a deposit that funds disbursements. |
| inflowCurrency | string | Yes | - |
| inflowAmount | string | Yes | Amount deposited. |
| convertedCurrency | string | Yes | - |
| convertedAmount | string | Yes | Amount after conversion; null if the deposit hasn't been converted. |
| outflowCurrency | string | Yes | - |
| outflowAmount | string | Yes | Amount paid out; null until a payout is set up. |
| receivedAt | integer (int64) | Yes | When the deposit was received, in Unix milliseconds. |
| settlementAt | integer (int64) | Yes | Expected settlement time while a scheduled payout is pending, then the time the payment settled, in Unix milliseconds. |
| settlementStatus | string | Yes | `PENDING`, `SETTLED` or `FAILED`. |
| settlementRef | string | Yes | Payout reference, such as the blockchain transaction hash of a crypto payout. |
| settlementId | string | Yes | The settlement that paid this payment out; null until a payout has been requested. |
| linked | boolean | Yes | Whether the deposit carries a payer reference. |
| payerName | string | Yes | Payer's name. |
| reference | string | Yes | Payer reference quoted with the deposit. |
| timeline | FlowStepForDisplay\[] | Yes | Steps the payment has been through. Only returned when you get a single payment. |
| payouts | PaymentPayoutForUser\[] | Yes | Settled payouts that carried this payment; more than one if it was split. Only returned when you get a single payment. |

**`timeline` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| type | string | Yes | `FUNDING`, `CONVERSION`, `SWEEP`, `WITHDRAWAL` or `SETTLEMENT`. |
| label | string | Yes | - |
| status | string | Yes | `PENDING`, `COMPLETE` or `FAILED`. |
| data | object | Yes | Amounts and currencies for the step. |
| traceId | string | Yes | Reference you can quote to support, such as a conversion ID or blockchain transaction hash. |
| at | integer (int64) | Yes | When the step happened, in Unix milliseconds. For a pending settlement, the scheduled time. |

**`payouts` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| settlementId | string | Yes | - |
| amount | string | Yes | - |
| currency | string | Yes | - |
| status | string | Yes | Payout status. Only settled payouts are listed, so this is `SETTLED`. |
| settledAt | integer (int64) | Yes | When the payout settled, in Unix milliseconds. |

**Example:**

```json
{
  "items": [
    {
      "id": "8d2f4b6a-1c3e-4f5a-9b7d-2e4c6a8b0d1f",
      "depositId": "3f1c2a9e-8b4d-4c1e-9f2a-6d7e8b9c0a1b",
      "status": "COMPLETED",
      "mode": "SCHEDULED",
      "type": "COLLECTION",
      "inflowCurrency": "ZAR",
      "inflowAmount": "1500.00",
      "convertedCurrency": "USDC",
      "convertedAmount": "82.45",
      "outflowCurrency": "USDC",
      "outflowAmount": "82.45",
      "receivedAt": 1792660500000,
      "settlementAt": 1792684950000,
      "settlementStatus": "SETTLED",
      "settlementRef": null,
      "settlementId": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f",
      "linked": true,
      "payerName": "Thandi Nkosi",
      "reference": "VLR4F7K2Q9",
      "timeline": null,
      "payouts": null
    }
  ],
  "total": 23,
  "limit": 1,
  "offset": 0
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/payments/collect/runs/{id}/payments'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/payments/collect/runs/{id}/payments"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | The run ID isn't a valid UUID. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV2PaymentsCollectSettlementsByIdPayments.md
description: 'GET /v2/payments/collect/settlements/{id}/payments'
---

# List a settlement's payments

`GET /v2/payments/collect/settlements/{id}/payments`

Returns the payments a settlement paid out, newest first. The settlement must belong to your business.

**Requires** `COLLECTIONS_READ`, granted by `PAYMENTS_READ` or `COLLECTIONS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | Yes | Settlement ID. |
| limit | query | integer | No | Maximum number of payments to return. |
| offset | query | integer | No | Number of payments to skip, for paging. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| items | PaymentForUser\[] | Yes | - |
| total | integer (int32) | Yes | - |
| limit | integer (int32) | Yes | - |
| offset | integer (int32) | Yes | - |

**`items` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | Payment ID. |
| depositId | string | Yes | ID of the deposit that created the payment. |
| status | string | Yes | Overall status: `RECEIVED`, `CONVERTED`, `SWEPT`, `PENDING_SETTLEMENT`, `COMPLETED` or `FAILED`. |
| mode | string | Yes | How the payment is paid out: `INSTANT` or `SCHEDULED`. Null until a payout is set up. |
| type | string | Yes | `COLLECTION` for a payment from a payer, `DISBURSEMENT` for a deposit that funds disbursements. |
| inflowCurrency | string | Yes | - |
| inflowAmount | string | Yes | Amount deposited. |
| convertedCurrency | string | Yes | - |
| convertedAmount | string | Yes | Amount after conversion; null if the deposit hasn't been converted. |
| outflowCurrency | string | Yes | - |
| outflowAmount | string | Yes | Amount paid out; null until a payout is set up. |
| receivedAt | integer (int64) | Yes | When the deposit was received, in Unix milliseconds. |
| settlementAt | integer (int64) | Yes | Expected settlement time while a scheduled payout is pending, then the time the payment settled, in Unix milliseconds. |
| settlementStatus | string | Yes | `PENDING`, `SETTLED` or `FAILED`. |
| settlementRef | string | Yes | Payout reference, such as the blockchain transaction hash of a crypto payout. |
| settlementId | string | Yes | The settlement that paid this payment out; null until a payout has been requested. |
| linked | boolean | Yes | Whether the deposit carries a payer reference. |
| payerName | string | Yes | Payer's name. |
| reference | string | Yes | Payer reference quoted with the deposit. |
| timeline | FlowStepForDisplay\[] | Yes | Steps the payment has been through. Only returned when you get a single payment. |
| payouts | PaymentPayoutForUser\[] | Yes | Settled payouts that carried this payment; more than one if it was split. Only returned when you get a single payment. |

**`timeline` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| type | string | Yes | `FUNDING`, `CONVERSION`, `SWEEP`, `WITHDRAWAL` or `SETTLEMENT`. |
| label | string | Yes | - |
| status | string | Yes | `PENDING`, `COMPLETE` or `FAILED`. |
| data | object | Yes | Amounts and currencies for the step. |
| traceId | string | Yes | Reference you can quote to support, such as a conversion ID or blockchain transaction hash. |
| at | integer (int64) | Yes | When the step happened, in Unix milliseconds. For a pending settlement, the scheduled time. |

**`payouts` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| settlementId | string | Yes | - |
| amount | string | Yes | - |
| currency | string | Yes | - |
| status | string | Yes | Payout status. Only settled payouts are listed, so this is `SETTLED`. |
| settledAt | integer (int64) | Yes | When the payout settled, in Unix milliseconds. |

**Example:**

```json
{
  "items": [
    {
      "id": "8d2f4b6a-1c3e-4f5a-9b7d-2e4c6a8b0d1f",
      "depositId": "3f1c2a9e-8b4d-4c1e-9f2a-6d7e8b9c0a1b",
      "status": "COMPLETED",
      "mode": "SCHEDULED",
      "type": "COLLECTION",
      "inflowCurrency": "ZAR",
      "inflowAmount": "1500.00",
      "convertedCurrency": "USDC",
      "convertedAmount": "82.45",
      "outflowCurrency": "USDC",
      "outflowAmount": "82.45",
      "receivedAt": 1792660500000,
      "settlementAt": 1792684950000,
      "settlementStatus": "SETTLED",
      "settlementRef": null,
      "settlementId": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f",
      "linked": true,
      "payerName": "Thandi Nkosi",
      "reference": "VLR4F7K2Q9",
      "timeline": null,
      "payouts": null
    }
  ],
  "total": 23,
  "limit": 1,
  "offset": 0
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/payments/collect/settlements/{id}/payments'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/payments/collect/settlements/{id}/payments"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 400 | `-11` | `INVALID_REQUEST` | The settlement ID is longer than 64 characters, contains characters other than letters, digits, `.`, `_` and `-`, or is only dots. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No settlement with this ID exists in your business. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1WalletCryptoAddressBook.md
description: GET /v1/wallet/crypto/address-book
---

# List address-book entries

`GET /v1/wallet/crypto/address-book`

Returns the saved withdrawal addresses in the address book of the account the request acts on (your primary account, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`), oldest first. Send an entry's `id` as `addressBookId` to withdraw to it.

**Requires** `WITHDRAWALS_READ`, granted by `TREASURY_READ` or `TREASURY_WRITE` or `WITHDRAWALS_WRITE` or `BANK_ACCOUNTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| skip | query | integer | No | Number of entries to skip, for paging. |
| limit | query | integer | No | Maximum number of entries to return, up to 100. |
| networkType | query | string | No | Only entries on this network, e.g. `Ethereum`. |

## Responses

### 200

OK

Array of objects:

| Property | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | Entry ID; send it as `addressBookId` to withdraw to this address. |
| label | string | Yes | - |
| currency | string | No | Currency of a `CURRENCY_SPECIFIC` entry; left out for `UNIVERSAL` entries. |
| address | string | Yes | - |
| networkType | string | Yes | - |
| paymentReference | string | No | - |
| createdAt | string | Yes | - |
| type | string (CURRENCY\_SPECIFIC, UNIVERSAL) | Yes | `CURRENCY_SPECIFIC`: one currency on one network. `UNIVERSAL`: any currency on the entry's network. |
| beneficiaryName | string | No | Recipient's name saved with the entry. When the entry holds the recipient's details, withdrawals to it don't need them in the request. |
| isCorporate | boolean | No | - |
| isSelfHosted | boolean | No | - |
| serviceProviderName | string | No | - |
| serviceProviderId | string | No | - |

**Example:**

```json
[
  {
    "id": "3b8e1f6a-2c4d-4e5f-8a9b-0c1d2e3f4a5b",
    "label": "Treasury cold wallet",
    "currency": "BTC",
    "address": "bc1q4u7h2kz9x8w3n5e6r0t2y7m8c9v3f5g6j8k2l0",
    "networkType": "Bitcoin",
    "createdAt": "2026-09-14T10:22:31.508Z",
    "type": "CURRENCY_SPECIFIC",
    "beneficiaryName": "Acme Treasury (Pty) Ltd",
    "isCorporate": true,
    "isSelfHosted": true
  },
  {
    "id": "9f2a7c3e-4b5d-4e6f-a7b8-c9d0e1f2a3b4",
    "label": "Exchange settlement (Ethereum)",
    "address": "0x8d3f2b6a91c04e7fa1b2c3d4e5f60718293a4b5c",
    "networkType": "Ethereum",
    "createdAt": "2026-10-02T13:05:47.219Z",
    "type": "UNIVERSAL",
    "beneficiaryName": "Acme Treasury (Pty) Ltd",
    "isCorporate": true,
    "isSelfHosted": false,
    "serviceProviderName": "Binance",
    "serviceProviderId": "676d1c189ef2fd542e5bbf33"
  },
  {
    "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
    "label": "Supplier USDC (Stellar)",
    "currency": "USDC",
    "address": "GBXK7Q2M4N6P8R0T2V4X6Z8B0D2F4H6J8L0N2P4R6T8V0X2Z4B6D8F",
    "networkType": "StellarLumens",
    "paymentReference": "INV-20431",
    "createdAt": "2026-10-12T07:41:09.880Z",
    "type": "CURRENCY_SPECIFIC",
    "beneficiaryName": "Northwind Supplies Ltd",
    "isCorporate": true,
    "isSelfHosted": false,
    "serviceProviderName": "Example Custody"
  }
]
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/wallet/crypto/address-book'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/wallet/crypto/address-book"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `skip` or `limit` isn't a whole number, `limit` is more than 100, or `networkType` is blank. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1WalletCryptoAddressBookByCurrency.md
description: 'GET /v1/wallet/crypto/address-book/{currency}'
---

# List address-book entries for a currency

`GET /v1/wallet/crypto/address-book/{currency}`

Returns the address-book entries of the account the request acts on (your primary account, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`) that you can withdraw this currency to: entries saved for the currency plus universal entries on its networks, oldest first.

**Requires** `WITHDRAWALS_READ`, granted by `TREASURY_READ` or `TREASURY_WRITE` or `WITHDRAWALS_WRITE` or `BANK_ACCOUNTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Currency to list entries for, e.g. `USDC`. |
| skip | query | integer | No | Number of entries to skip, for paging. |
| limit | query | integer | No | Maximum number of entries to return, up to 100. |
| networkType | query | string | No | Only entries on this network, e.g. `Ethereum`. |

## Responses

### 200

OK

Array of objects:

| Property | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | Entry ID; send it as `addressBookId` to withdraw to this address. |
| label | string | Yes | - |
| currency | string | No | Currency of a `CURRENCY_SPECIFIC` entry; left out for `UNIVERSAL` entries. |
| address | string | Yes | - |
| networkType | string | Yes | - |
| paymentReference | string | No | - |
| createdAt | string | Yes | - |
| type | string (CURRENCY\_SPECIFIC, UNIVERSAL) | Yes | `CURRENCY_SPECIFIC`: one currency on one network. `UNIVERSAL`: any currency on the entry's network. |
| beneficiaryName | string | No | Recipient's name saved with the entry. When the entry holds the recipient's details, withdrawals to it don't need them in the request. |
| isCorporate | boolean | No | - |
| isSelfHosted | boolean | No | - |
| serviceProviderName | string | No | - |
| serviceProviderId | string | No | - |

**Example:**

```json
[
  {
    "id": "9f2a7c3e-4b5d-4e6f-a7b8-c9d0e1f2a3b4",
    "label": "Exchange settlement (Ethereum)",
    "address": "0x8d3f2b6a91c04e7fa1b2c3d4e5f60718293a4b5c",
    "networkType": "Ethereum",
    "createdAt": "2026-10-02T13:05:47.219Z",
    "type": "UNIVERSAL",
    "beneficiaryName": "Acme Treasury (Pty) Ltd",
    "isCorporate": true,
    "isSelfHosted": false,
    "serviceProviderName": "Binance",
    "serviceProviderId": "676d1c189ef2fd542e5bbf33"
  },
  {
    "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
    "label": "Supplier USDC (Stellar)",
    "currency": "USDC",
    "address": "GBXK7Q2M4N6P8R0T2V4X6Z8B0D2F4H6J8L0N2P4R6T8V0X2Z4B6D8F",
    "networkType": "StellarLumens",
    "paymentReference": "INV-20431",
    "createdAt": "2026-10-12T07:41:09.880Z",
    "type": "CURRENCY_SPECIFIC",
    "beneficiaryName": "Northwind Supplies Ltd",
    "isCorporate": true,
    "isSelfHosted": false,
    "serviceProviderName": "Example Custody"
  }
]
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/wallet/crypto/address-book/{currency}'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/wallet/crypto/address-book/{currency}"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The currency isn't recognised, `skip` or `limit` isn't a whole number, `limit` is more than 100, or `networkType` is blank. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1WalletFiatByCurrencyAutoBuy.md
description: 'GET /v1/wallet/fiat/{currency}/auto-buy'
---

# List auto-buy currencies

`GET /v1/wallet/fiat/{currency}/auto-buy`

Lists the currencies that a deposit in this currency can buy automatically when it quotes an auto-buy reference. The list depends on your business's region, and is empty if auto-buy isn't available for the currency.

**Requires** `DEPOSITS_READ`, granted by `TREASURY_READ` or `TREASURY_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Fiat currency you'll deposit, e.g. `ZAR`. |

## Responses

### 200

OK

**Example:**

```json
[
  "BTC",
  "ETH",
  "SOL"
]
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/wallet/fiat/{currency}/auto-buy'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/wallet/fiat/{currency}/auto-buy"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The currency isn't recognised. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1WalletFiatByCurrencyAccounts.md
description: 'GET /v1/wallet/fiat/{currency}/accounts'
---

# List bank accounts

`GET /v1/wallet/fiat/{currency}/accounts`

Lists the bank accounts linked to the account for this currency, oldest first. Bank accounts belong to one account: the primary, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`.

**Requires** `WITHDRAWALS_READ`, granted by `TREASURY_READ` or `TREASURY_WRITE` or `WITHDRAWALS_WRITE` or `BANK_ACCOUNTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Fiat currency of the bank accounts, e.g. `ZAR`. |

## Responses

### 200

OK

Array of objects:

| Property | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | - |
| bank | string | Yes | - |
| accountHolder | string | Yes | - |
| accountNumber | string | Yes | - |
| branchCode | string | Yes | - |
| accountType | string | Yes | - |
| createdAt | string | Yes | - |
| country | string | Yes | - |

**Example:**

```json
[
  {
    "id": "3c9e1f42-7d5b-4a8e-9f21-6b0d8c4e7a15",
    "bank": "FNB/RMB",
    "accountHolder": "Acme Trading (Pty) Ltd",
    "accountNumber": "62792461544",
    "branchCode": "250655",
    "accountType": "Current/Cheque",
    "createdAt": "2026-08-14T09:21:37.408215Z",
    "country": "ZA"
  },
  {
    "id": "8f2a6d10-c3e4-4b7f-a915-2e7c0b9d4f68",
    "bank": "Standard Bank",
    "accountHolder": "Acme Trading (Pty) Ltd",
    "accountNumber": "10094857261",
    "branchCode": "051001",
    "accountType": "Current/Cheque",
    "createdAt": "2026-09-30T13:05:12.774031Z",
    "country": "ZA"
  }
]
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/wallet/fiat/{currency}/accounts'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/wallet/fiat/{currency}/accounts"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The currency isn't recognised. |
| 451 | `-15320` | `FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY` | Your business's region doesn't allow withdrawals in this currency. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1WalletFiatByCurrencyBanks.md
description: 'GET /v1/wallet/fiat/{currency}/banks'
---

# List banks for a currency

`GET /v1/wallet/fiat/{currency}/banks`

Lists the banks you can link a bank account at for this currency, with each bank's default branch code and whether it takes real-time (RTC) and RTGS payments. Use a bank's `code` as `bank` when you link a bank account.

**Requires** `WITHDRAWALS_READ`, granted by `TREASURY_READ` or `TREASURY_WRITE` or `WITHDRAWALS_WRITE` or `BANK_ACCOUNTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Fiat currency, e.g. `ZAR`. |

## Responses

### 200

OK

Array of objects:

| Property | Type | Required | Description |
|---|---|---|---|
| code | string | Yes | - |
| displayName | string | Yes | - |
| defaultBranchCode | string | Yes | - |
| rtcParticipant | boolean | Yes | - |
| rtgsParticipant | boolean | Yes | - |
| countryCode | string (UNDEFINED, AC, AD, AE, AF, AG, AI, AL, ...) | Yes | - |
| deprecated | string | No | - |

**Example:**

```json
[
  {
    "code": "ABSA",
    "displayName": "ABSA Bank",
    "defaultBranchCode": "632005",
    "rtcParticipant": true,
    "rtgsParticipant": true,
    "countryCode": "ZA"
  },
  {
    "code": "CAPITEC",
    "displayName": "Capitec Bank",
    "defaultBranchCode": "470010",
    "rtcParticipant": true,
    "rtgsParticipant": false,
    "countryCode": "ZA"
  },
  {
    "code": "FNB",
    "displayName": "FNB/RMB",
    "defaultBranchCode": "250655",
    "rtcParticipant": true,
    "rtgsParticipant": true,
    "countryCode": "ZA"
  }
]
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/wallet/fiat/{currency}/banks'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/wallet/fiat/{currency}/banks"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The currency isn't recognised. |
| 400 | `-112` | `CURRENCY_NOT_SUPPORTED` | Bank accounts can't be linked in this currency. |
| 451 | `-15320` | `FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY` | Your business's region doesn't allow withdrawals in this currency. |
| 500 | `-15317` | `BANK_REMOTE_FETCH_FAILURE` | The bank list couldn't be loaded. Try again later. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV2PaymentsBulkWithdrawalsBeneficiaries.md
description: GET /v2/payments/bulk-withdrawals/beneficiaries
---

# List beneficiaries

`GET /v2/payments/bulk-withdrawals/beneficiaries`

Returns your beneficiaries a page at a time, active ones by default. Use `query` to search by name, trading name, email address or account number.

**Requires** `DISBURSEMENTS_READ`, granted by `PAYMENTS_READ` or `DISBURSEMENTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| query | query | string | No | Text to search for in the name, trading name, email address and account number. Results are ranked by relevance and `sort` is ignored. |
| type | query | string | No | Only beneficiaries of this type. Beneficiaries saved from a batch without a type match neither value. Case-insensitive. |
| status | query | string | No | `ACTIVE`, `ARCHIVED` or `ALL`. Case-insensitive. |
| sort | query | string | No | `created` (newest first), `lastPaid` (most recently paid first, never paid last) or `archived` (most recently archived first). Defaults to `archived` when `status` is `ARCHIVED`, otherwise `created`; `archived` needs `status` `ARCHIVED` or `ALL`. |
| limit | query | integer | No | Page size, from 1 to 200; values outside that range are clamped. |
| offset | query | integer | No | Number of items to skip. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| items | BeneficiaryForDisplay\[] | Yes | - |
| total | integer (int32) | Yes | - |
| limit | integer (int32) | Yes | - |
| offset | integer (int32) | Yes | - |
| truncated | boolean | Yes | - |

**`items` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | - |
| bank | string | Yes | - |
| bankDisplayName | string | Yes | - |
| accountHolder | string | Yes | - |
| accountNumberMasked | string | Yes | Account number with all but the last four digits masked. |
| accountNumber | string | Yes | - |
| branchCode | string | Yes | - |
| accountType | string | Yes | - |
| email | string | Yes | - |
| type | string | Yes | `INDIVIDUAL`, `BUSINESS`, or `null` if never set, which is possible for beneficiaries saved from a batch. |
| tradingName | string | Yes | - |
| reference | string | Yes | Default payment reference for this beneficiary. It isn't applied to payouts automatically. |
| country | string | Yes | - |
| createdAt | string (date-time) | Yes | - |
| updatedAt | string (date-time) | Yes | - |
| lastPaidAt | string (date-time) | Yes | When a payout to this beneficiary was last attempted; `null` if never. |
| deletedAt | string (date-time) | Yes | When the beneficiary was archived; `null` if it's active. |
| deletedBy | string | Yes | ID of the user or API key that archived the beneficiary. |

**Example:**

```json
{
  "items": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "bank": "FNB",
      "bankDisplayName": "FNB/RMB",
      "accountHolder": "Thandi Nkosi",
      "accountNumberMasked": "*******0327",
      "accountNumber": "62845190327",
      "branchCode": "250655",
      "accountType": "CHEQUE",
      "email": "thandi@example.com",
      "type": "INDIVIDUAL",
      "tradingName": null,
      "reference": "SALARY",
      "country": "ZA",
      "createdAt": "2026-09-01T10:12:30.004Z",
      "updatedAt": "2026-10-23T08:15:02.010Z",
      "lastPaidAt": "2026-10-23T08:15:03.204Z",
      "deletedAt": null,
      "deletedBy": null
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0,
  "truncated": null
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/payments/bulk-withdrawals/beneficiaries'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/payments/bulk-withdrawals/beneficiaries"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV2WalletFiatByCurrencyPaymentBulkReferencesByJobIdItems.md
description: 'GET /v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}/items'
---

# List bulk reference job items

`GET /v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}/items`

Lists the payers in a bulk reference job in the order they were submitted, with the reference created for each or, if creation failed, an `errorCode`. Filter by `status` to fetch only the references that were created, that failed or that are still pending.

**Requires** `COLLECTIONS_READ`, granted by `PAYMENTS_READ` or `COLLECTIONS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Fiat currency of the references, e.g. `ZAR`. |
| jobId | path | integer | Yes | The `jobId` returned when the bulk job was created. |
| status | query | string | No | Only return items with this status. Case-insensitive. |
| skip | query | integer | No | Number of results to skip, for paging. |
| limit | query | integer | No | Maximum number of items to return, between 1 and 1000; values outside that range are clamped. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| items | BulkDepositItemForDisplay\[] | Yes | - |
| total | integer (int32) | Yes | - |
| limit | integer (int32) | Yes | - |
| offset | integer (int32) | Yes | - |

**`items` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| senderIndex | integer (int32) | Yes | Position of the payer in the submitted `senders` array, starting at 0. |
| currency | object | Yes | Currency code, e.g. `ZAR`. |
| expectedAmount | number | No | Amount you expect the payer to deposit, as a decimal string. Absent if you didn't give one. |
| name | string | Yes | - |
| email | string | Yes | - |
| status | string (PENDING, SUCCESS, FAILED) | Yes | `PENDING` until the payer has been processed, then `SUCCESS` or `FAILED`. |
| referenceCode | string | No | The reference created for this payer, once `status` is `SUCCESS`. |
| errorCode | integer (int32) | No | Why the reference couldn't be created, when `status` is `FAILED`: `-15116` daily limit reached, `-15119` maximum number of references reached, `-15113` any other failure. |
| processedAt | integer (int64) | No | When the payer was processed, in Unix milliseconds. |

**`currency` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| symbol | string | Yes | - |
| decimalPlaces | integer (int32) | Yes | - |
| isActive | boolean | Yes | - |
| shortName | string | Yes | - |
| longName | string | Yes | - |
| supportedWithdrawDecimalPlaces | integer (int32) | Yes | - |
| paymentReferenceFieldName | string | No | - |
| collateral | boolean | Yes | - |
| collateralWeight | string | Yes | - |
| supportedNetworks | SupportedNetworkForDisplay\[] | No | - |
| currencyTypeId | integer (int32) | No | - |

**`supportedNetworks` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| networkType | string | Yes | - |
| networkLongName | string | No | - |
| tokenContract | string | No | - |
| minimumWithdrawAmount | string | No | - |
| estimatedSendCost | string | No | - |
| deposit | boolean | Yes | - |
| withdraw | boolean | Yes | - |
| withdrawalDecimalPlaces | integer (int32) | No | - |

**Example:**

```json
{
  "items": [
    {
      "senderIndex": 0,
      "currency": "ZAR",
      "expectedAmount": "1500",
      "name": "Thandi Nkosi",
      "email": "thandi@example.com",
      "status": "SUCCESS",
      "referenceCode": "VPAY-7K2Q9RT",
      "processedAt": 1792749605000
    },
    {
      "senderIndex": 1,
      "currency": "ZAR",
      "name": "Pieter van der Merwe",
      "email": "pieter@example.com",
      "status": "FAILED",
      "errorCode": -15116,
      "processedAt": 1792749606000
    }
  ],
  "total": 2,
  "limit": 100,
  "offset": 0
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}/items'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}/items"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The job ID, `skip` or `limit` isn't a whole number, `status` isn't `PENDING`, `SUCCESS` or `FAILED`, or the currency isn't recognised. |
| 400 | `-15721` | `SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH` | Your collections account doesn't support this currency. |
| 404 | `-15122` | `BULK_DEPOSIT_REFERENCE_JOB_NOT_FOUND` | No bulk job with this ID exists on your account for this currency. |
| 503 | `-15120` | `BULK_DEPOSIT_REFERENCE_FEATURE_DISABLED` | Bulk deposit references are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV2PaymentsCollectionsHistory.md
description: GET /v2/payments/collections/history
---

# List collection activity

`GET /v2/payments/collections/history`

Returns one feed of payments received from payers and completed settlements of collected funds, newest first, across every account in your business. A `status` other than `SETTLED` leaves settlements out.

**Requires** `COLLECTIONS_READ`, granted by `PAYMENTS_READ` or `COLLECTIONS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| limit | query | integer | No | Maximum number of entries to return. |
| offset | query | integer | No | Number of entries to skip, for paging. |
| status | query | string | No | Settlement status of payments: `PENDING`, `SETTLED` or `FAILED`. |
| from | query | integer | No | Only include entries received at or after this time, in Unix milliseconds. |
| to | query | integer | No | Only include entries received before this time, in Unix milliseconds. |
| minAmount | query | string | No | Smallest payment amount to include, as a decimal string. |
| maxAmount | query | string | No | Largest payment amount to include, as a decimal string. |
| currency | query | string | No | Only include payments with this currency on any leg: deposit, conversion or payout. |
| reference | query | string | No | Payer reference, or part of one. Not case-sensitive. |
| query | query | string | No | Free-text search. A date (`YYYY-MM-DD`) matches that whole day, a number matches an exact amount, and anything else matches a currency or payer reference. Explicit filters take precedence. |
| tz | query | string | No | IANA time zone used to interpret a date in `query`, e.g. `Africa/Johannesburg`. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| items | CollectionActivityForUser\[] | Yes | - |
| total | integer (int32) | Yes | - |
| limit | integer (int32) | Yes | - |
| offset | integer (int32) | Yes | - |

**`items` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| kind | string | Yes | `PAYMENT` for a payment received from a payer, `SETTLEMENT` for collected funds paid out. |
| id | string | Yes | - |
| date | integer (int64) | Yes | When the payment was received or the settlement paid out, in Unix milliseconds. |
| status | string | Yes | For `PAYMENT` entries, the payment status (`RECEIVED`, `CONVERTED`, `SWEPT`, `PENDING_SETTLEMENT`, `COMPLETED` or `FAILED`). `SETTLEMENT` entries are always `SETTLED`. |
| amount | string | Yes | - |
| currency | string | Yes | - |
| convertedAmount | string | Yes | - |
| convertedCurrency | string | Yes | - |
| from | string | Yes | - |
| to | string | Yes | - |
| reference | string | Yes | - |
| paymentId | string | Yes | Payment ID for `PAYMENT` entries; use it with Get a payment. |
| settlementId | string | Yes | The settlement this entry belongs to; use it with Get a settlement. |

**Example:**

```json
{
  "items": [
    {
      "kind": "SETTLEMENT",
      "id": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f",
      "date": 1792684950000,
      "status": "SETTLED",
      "amount": "1240.75",
      "currency": "USDC",
      "convertedAmount": null,
      "convertedCurrency": null,
      "from": "Collections",
      "to": "USDC Wallet",
      "reference": "Settlement",
      "paymentId": null,
      "settlementId": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f"
    },
    {
      "kind": "PAYMENT",
      "id": "8d2f4b6a-1c3e-4f5a-9b7d-2e4c6a8b0d1f",
      "date": 1792660500000,
      "status": "COMPLETED",
      "amount": "1500.00",
      "currency": "ZAR",
      "convertedAmount": "82.45",
      "convertedCurrency": "USDC",
      "from": "Thandi Nkosi",
      "to": "Collections",
      "reference": "VLR4F7K2Q9",
      "paymentId": "8d2f4b6a-1c3e-4f5a-9b7d-2e4c6a8b0d1f",
      "settlementId": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f"
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/payments/collections/history'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/payments/collections/history"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV2WalletFiatByCurrencyPaymentDeposits.md
description: 'GET /v2/wallet/fiat/{currency}/payment/deposits'
---

# List credited deposits

`GET /v2/wallet/fiat/{currency}/payment/deposits`

Lists the deposits credited to your collections account in this currency, newest first, with the reference each one is linked to. Use it to find a deposit's `publicId` when you want to link it to a different reference.

**Requires** `COLLECTIONS_READ`, granted by `PAYMENTS_READ` or `COLLECTIONS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Fiat currency of the deposits, e.g. `ZAR`. |
| skip | query | integer | No | Number of results to skip, for paging. |
| limit | query | integer | No | Maximum number of deposits to return. Values above 1000 are treated as 1000. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| items | UserFiatDepositForDisplay\[] | Yes | - |
| total | integer (int32) | Yes | - |
| limit | integer (int32) | Yes | - |
| offset | integer (int32) | Yes | - |

**`items` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| publicId | string (uuid) | Yes | Deposit ID. Use it to link the deposit to a reference. |
| amount | string | Yes | - |
| effectiveDate | string | Yes | The deposit's effective date at the bank, as `YYYY-MM-DD`. |
| creditedAt | integer (int64) | Yes | When the deposit was recorded, in Unix milliseconds. |
| linkedReferenceCode | string | No | The reference this deposit is linked to, if any. |

**Example:**

```json
{
  "items": [
    {
      "publicId": "3f1c2a9e-8b4d-4c1e-9f2a-6d7e8b9c0a1b",
      "amount": "1500",
      "effectiveDate": "2026-10-23",
      "creditedAt": 1792746900000,
      "linkedReferenceCode": "VPAY-7K2Q9RT"
    },
    {
      "publicId": "9a7b6c5d-4e3f-4a2b-8c1d-0e9f8a7b6c5d",
      "amount": "820.5",
      "effectiveDate": "2026-10-22",
      "creditedAt": 1792675200000
    }
  ],
  "total": 2,
  "limit": 20,
  "offset": 0
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/wallet/fiat/{currency}/payment/deposits'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/wallet/fiat/{currency}/payment/deposits"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `skip` or `limit` isn't a whole number, or the currency isn't recognised. |
| 400 | `-15721` | `SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH` | Your collections account doesn't support this currency. |
| 503 | `-15117` | `UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED` | Deposit references are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1WalletCryptoDepositHistory.md
description: GET /v1/wallet/crypto/deposit/history
---

# List crypto deposits

`GET /v1/wallet/crypto/deposit/history`

Returns crypto deposits to the account the request acts on (your primary account, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`), newest first, including deposits still waiting for confirmations. Filter by currency with `currency`.

**Requires** `DEPOSITS_READ`, granted by `TREASURY_READ` or `TREASURY_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| skip | query | integer | No | Number of deposits to skip, for paging. |
| limit | query | integer | No | Maximum number of deposits to return, up to 100. |
| startTime | query | string | No | Only deposits detected at or after this time (ISO 8601, UTC). |
| endTime | query | string | No | Only deposits detected before this time (ISO 8601, UTC). |
| currency | query | string | No | Only deposits in this currency, e.g. `USDT`. Leave out for all currencies. |

## Responses

### 200

OK

Array of objects:

| Property | Type | Required | Description |
|---|---|---|---|
| currencyCode | string | Yes | - |
| networkType | string | No | Network the deposit arrived on. Left out for some older deposits. |
| receiveAddress | string | Yes | - |
| transactionHash | string | Yes | - |
| amount | string | Yes | - |
| createdAt | string | Yes | When the deposit was detected. `startTime` and `endTime` filter on this. |
| confirmations | integer (int32) | Yes | - |
| confirmed | boolean | Yes | - |
| confirmedAt | string | No | When the deposit was confirmed; left out until then. |

**Example:**

```json
[
  {
    "currencyCode": "USDT",
    "networkType": "Ethereum",
    "receiveAddress": "0x5b3f9a1c2e7d48a6b0c4e9f1a2d3b4c5e6f70812",
    "transactionHash": "0x5c5cd31c2f3ad5bf9ad71fa665e55033ae42f046d7c8124c25a234265190901e",
    "amount": "250",
    "createdAt": "2026-10-23T08:40:02Z",
    "confirmations": 3,
    "confirmed": false
  },
  {
    "currencyCode": "USDT",
    "networkType": "Ethereum",
    "receiveAddress": "0x5b3f9a1c2e7d48a6b0c4e9f1a2d3b4c5e6f70812",
    "transactionHash": "0x532c1d6c2d1aaae73bfbd818126c4853b0af2a081ad72ccbf716094a011e6bbc",
    "amount": "1500",
    "createdAt": "2026-10-22T14:03:19Z",
    "confirmations": 12,
    "confirmed": true,
    "confirmedAt": "2026-10-22T14:06:41.205Z"
  },
  {
    "currencyCode": "BTC",
    "networkType": "Bitcoin",
    "receiveAddress": "bc1q4u7h2kz9x8w3n5e6r0t2y7m8c9v3f5g6j8k2l0",
    "transactionHash": "c61bd9c633f3dc91eaf6bec6c3812b5542bf83a243076954f10a743a48d5f48e",
    "amount": "0.05",
    "createdAt": "2026-10-21T09:12:44Z",
    "confirmations": 6,
    "confirmed": true,
    "confirmedAt": "2026-10-21T10:08:13.917Z"
  }
]
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/wallet/crypto/deposit/history'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/wallet/crypto/deposit/history"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `skip` or `limit` isn't a whole number, `limit` is more than 100, `startTime` or `endTime` isn't an ISO 8601 timestamp, or the currency isn't recognised. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1WalletCryptoByCurrencyDepositHistory.md
description: 'GET /v1/wallet/crypto/{currency}/deposit/history'
---

# List crypto deposits for a currency

`GET /v1/wallet/crypto/{currency}/deposit/history`

Returns deposits of one currency to the account the request acts on (your primary account, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`), newest first, including deposits still waiting for confirmations.

**Requires** `DEPOSITS_READ`, granted by `TREASURY_READ` or `TREASURY_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Currency of the deposits, e.g. `USDT`. |
| skip | query | integer | No | Number of deposits to skip, for paging. |
| limit | query | integer | No | Maximum number of deposits to return, up to 100. |
| startTime | query | string | No | Only deposits detected at or after this time (ISO 8601, UTC). |
| endTime | query | string | No | Only deposits detected before this time (ISO 8601, UTC). |

## Responses

### 200

OK

Array of objects:

| Property | Type | Required | Description |
|---|---|---|---|
| currencyCode | string | Yes | - |
| networkType | string | No | Network the deposit arrived on. Left out for some older deposits. |
| receiveAddress | string | Yes | - |
| transactionHash | string | Yes | - |
| amount | string | Yes | - |
| createdAt | string | Yes | When the deposit was detected. `startTime` and `endTime` filter on this. |
| confirmations | integer (int32) | Yes | - |
| confirmed | boolean | Yes | - |
| confirmedAt | string | No | When the deposit was confirmed; left out until then. |

**Example:**

```json
[
  {
    "currencyCode": "USDT",
    "networkType": "Ethereum",
    "receiveAddress": "0x5b3f9a1c2e7d48a6b0c4e9f1a2d3b4c5e6f70812",
    "transactionHash": "0x5c5cd31c2f3ad5bf9ad71fa665e55033ae42f046d7c8124c25a234265190901e",
    "amount": "250",
    "createdAt": "2026-10-23T08:40:02Z",
    "confirmations": 3,
    "confirmed": false
  },
  {
    "currencyCode": "USDT",
    "networkType": "Ethereum",
    "receiveAddress": "0x5b3f9a1c2e7d48a6b0c4e9f1a2d3b4c5e6f70812",
    "transactionHash": "0x532c1d6c2d1aaae73bfbd818126c4853b0af2a081ad72ccbf716094a011e6bbc",
    "amount": "1500",
    "createdAt": "2026-10-22T14:03:19Z",
    "confirmations": 12,
    "confirmed": true,
    "confirmedAt": "2026-10-22T14:06:41.205Z"
  }
]
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/wallet/crypto/{currency}/deposit/history'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/wallet/crypto/{currency}/deposit/history"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `skip` or `limit` isn't a whole number, `limit` is more than 100, `startTime` or `endTime` isn't an ISO 8601 timestamp, or the currency isn't recognised. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1WalletCryptoWithdrawHistory.md
description: GET /v1/wallet/crypto/withdraw/history
---

# List crypto withdrawals

`GET /v1/wallet/crypto/withdraw/history`

Returns crypto withdrawals from the account the request acts on (your primary account, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`), newest first; filter by currency with `currency`. Cancelled withdrawals are left out, so a page can hold fewer than `limit` items.

**Requires** `WITHDRAWALS_READ`, granted by `TREASURY_READ` or `TREASURY_WRITE` or `WITHDRAWALS_WRITE` or `BANK_ACCOUNTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| skip | query | integer | No | Number of withdrawals to skip, for paging. |
| limit | query | integer | No | Maximum number of withdrawals to return, up to 100. |
| startTime | query | string | No | Only withdrawals created at or after this time (ISO 8601, UTC). |
| endTime | query | string | No | Only withdrawals created before this time (ISO 8601, UTC). |
| currency | query | string | No | Only withdrawals in this currency, e.g. `USDC`. Leave out for all currencies. |

## Responses

### 200

OK

Array of objects:

| Property | Type | Required | Description |
|---|---|---|---|
| currency | string | Yes | - |
| address | string | Yes | - |
| amount | string | Yes | - |
| feeAmount | string | Yes | Network fee, charged on top of `amount`. |
| transactionHash | string | No | Network transaction hash, once the withdrawal has been broadcast. |
| confirmations | integer (int32) | Yes | - |
| lastConfirmationAt | string | No | Time of the latest network confirmation, in UTC but without a time-zone designator. |
| uniqueId | string (uuid) | Yes | Withdrawal ID. |
| createdAt | string | Yes | When the withdrawal was created. `startTime` and `endTime` filter on this. |
| verified | boolean | Yes | - |
| status | string | Yes | `Pending`, `Awaiting approval`, `Processing`, `Complete`, `Failed` or `Cancelled`. Withdrawal lists leave out cancelled withdrawals. |
| networkType | string | No | - |
| paymentReference | string | No | - |
| paymentReferenceFieldName | string | No | - |

**Example:**

```json
[
  {
    "currency": "USDC",
    "address": "0x2a7c4e9b1d3f5a6c8e0b2d4f6a8c0e2b4d6f8a1c",
    "amount": "1200",
    "feeAmount": "1.5",
    "confirmations": 0,
    "uniqueId": "e4b2a1c9-8d7f-4e3a-b6c5-0f9e8d7c6b5a",
    "createdAt": "2026-10-23T09:02:37.106Z",
    "verified": true,
    "status": "Processing",
    "networkType": "Ethereum"
  },
  {
    "currency": "USDC",
    "address": "0x8d3f2b6a91c04e7fa1b2c3d4e5f60718293a4b5c",
    "amount": "250",
    "feeAmount": "1.5",
    "transactionHash": "0x5901a831de792a71a309438bd8ada659952c7662f1c130a74dd1852906971a84",
    "confirmations": 12,
    "lastConfirmationAt": "2026-10-23T08:21:47.318205",
    "uniqueId": "7c1d9e42-5a3b-4f6e-9d8c-2b1a0f3e4d5c",
    "createdAt": "2026-10-23T08:15:02.441Z",
    "verified": true,
    "status": "Complete",
    "networkType": "Ethereum"
  },
  {
    "currency": "BTC",
    "address": "bc1q7m3k9x2v5n8c4z6w1q0p3r5t7y9u2i4o6a8s0d",
    "amount": "0.25",
    "feeAmount": "0.0001",
    "transactionHash": "16297f4bc279b9085dff06661db1c251012bdb1f6044587d923d71958a13edb3",
    "confirmations": 6,
    "lastConfirmationAt": "2026-10-20T11:47:05.662190",
    "uniqueId": "3f8a6d2c-1b9e-4c7a-8e5d-2a4b6c8d0e1f",
    "createdAt": "2026-10-20T10:58:19.027Z",
    "verified": true,
    "status": "Complete",
    "networkType": "Bitcoin"
  }
]
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/wallet/crypto/withdraw/history'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/wallet/crypto/withdraw/history"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `skip` or `limit` isn't a whole number, `limit` is more than 100, `startTime` or `endTime` isn't an ISO 8601 timestamp, or the currency isn't recognised. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1WalletCryptoByCurrencyWithdrawHistory.md
description: 'GET /v1/wallet/crypto/{currency}/withdraw/history'
---

# List crypto withdrawals for a currency

`GET /v1/wallet/crypto/{currency}/withdraw/history`

Returns withdrawals of one currency from the account the request acts on (your primary account, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`), newest first. Cancelled withdrawals are left out, so a page can hold fewer than `limit` items.

**Requires** `WITHDRAWALS_READ`, granted by `TREASURY_READ` or `TREASURY_WRITE` or `WITHDRAWALS_WRITE` or `BANK_ACCOUNTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Currency of the withdrawals, e.g. `USDC`. |
| skip | query | integer | No | Number of withdrawals to skip, for paging. |
| limit | query | integer | No | Maximum number of withdrawals to return, up to 100. |
| startTime | query | string | No | Only withdrawals created at or after this time (ISO 8601, UTC). |
| endTime | query | string | No | Only withdrawals created before this time (ISO 8601, UTC). |

## Responses

### 200

OK

Array of objects:

| Property | Type | Required | Description |
|---|---|---|---|
| currency | string | Yes | - |
| address | string | Yes | - |
| amount | string | Yes | - |
| feeAmount | string | Yes | Network fee, charged on top of `amount`. |
| transactionHash | string | No | Network transaction hash, once the withdrawal has been broadcast. |
| confirmations | integer (int32) | Yes | - |
| lastConfirmationAt | string | No | Time of the latest network confirmation, in UTC but without a time-zone designator. |
| uniqueId | string (uuid) | Yes | Withdrawal ID. |
| createdAt | string | Yes | When the withdrawal was created. `startTime` and `endTime` filter on this. |
| verified | boolean | Yes | - |
| status | string | Yes | `Pending`, `Awaiting approval`, `Processing`, `Complete`, `Failed` or `Cancelled`. Withdrawal lists leave out cancelled withdrawals. |
| networkType | string | No | - |
| paymentReference | string | No | - |
| paymentReferenceFieldName | string | No | - |

**Example:**

```json
[
  {
    "currency": "USDC",
    "address": "0x2a7c4e9b1d3f5a6c8e0b2d4f6a8c0e2b4d6f8a1c",
    "amount": "1200",
    "feeAmount": "1.5",
    "confirmations": 0,
    "uniqueId": "e4b2a1c9-8d7f-4e3a-b6c5-0f9e8d7c6b5a",
    "createdAt": "2026-10-23T09:02:37.106Z",
    "verified": true,
    "status": "Processing",
    "networkType": "Ethereum"
  },
  {
    "currency": "USDC",
    "address": "0x8d3f2b6a91c04e7fa1b2c3d4e5f60718293a4b5c",
    "amount": "250",
    "feeAmount": "1.5",
    "transactionHash": "0x5901a831de792a71a309438bd8ada659952c7662f1c130a74dd1852906971a84",
    "confirmations": 12,
    "lastConfirmationAt": "2026-10-23T08:21:47.318205",
    "uniqueId": "7c1d9e42-5a3b-4f6e-9d8c-2b1a0f3e4d5c",
    "createdAt": "2026-10-23T08:15:02.441Z",
    "verified": true,
    "status": "Complete",
    "networkType": "Ethereum"
  }
]
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/wallet/crypto/{currency}/withdraw/history'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/wallet/crypto/{currency}/withdraw/history"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `skip` or `limit` isn't a whole number, `limit` is more than 100, `startTime` or `endTime` isn't an ISO 8601 timestamp, or the currency isn't recognised. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1PublicCurrencies.md
description: GET /v1/public/currencies
---

# List currencies

`GET /v1/public/currencies`

Returns every currency VALR lists, including inactive ones, with its decimal places, collateral weight and, for crypto, the networks it can be deposited and withdrawn on (`shortName` is the code used in currency pairs, e.g. ZAR, whose `symbol` is `R`). Responses are cached for up to a minute, so `estimatedSendCost` may be out of date.

**Public**: no API key needed. Send the request as is, without signing it.

## Responses

### 200

OK

Array of objects:

| Property | Type | Required | Description |
|---|---|---|---|
| symbol | string | Yes | - |
| isActive | boolean | Yes | - |
| shortName | string | Yes | - |
| longName | string | Yes | - |
| decimalPlaces | string | Yes | - |
| withdrawalDecimalPlaces | string | Yes | - |
| paymentReferenceFieldName | string | No | - |
| collateral | boolean | Yes | - |
| collateralWeight | string | Yes | - |
| defaultNetworkType | string | No | - |
| supportedNetworks | V1SupportedNetworkForApi\[] | No | - |

**`supportedNetworks` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| networkType | string | Yes | - |
| networkLongName | string | No | - |
| tokenContract | string | No | - |
| minimumWithdrawAmount | string | No | - |
| estimatedSendCost | string | No | - |
| deposit | boolean | Yes | - |
| withdraw | boolean | Yes | - |
| withdrawalDecimalPlaces | string | No | - |

**Example:**

```json
[
  {
    "symbol": "BTC",
    "isActive": true,
    "shortName": "BTC",
    "longName": "Bitcoin",
    "decimalPlaces": "8",
    "withdrawalDecimalPlaces": "8",
    "collateral": true,
    "collateralWeight": "0.95",
    "defaultNetworkType": "Bitcoin",
    "supportedNetworks": [
      {
        "networkType": "Bitcoin",
        "networkLongName": "Bitcoin",
        "minimumWithdrawAmount": "0.0002",
        "estimatedSendCost": "0.000012",
        "deposit": true,
        "withdraw": true,
        "withdrawalDecimalPlaces": "8"
      }
    ]
  },
  {
    "symbol": "USDC",
    "isActive": true,
    "shortName": "USDC",
    "longName": "USD Coin",
    "decimalPlaces": "2",
    "withdrawalDecimalPlaces": "6",
    "collateral": true,
    "collateralWeight": "1",
    "defaultNetworkType": "Ethereum",
    "supportedNetworks": [
      {
        "networkType": "Ethereum",
        "networkLongName": "Ethereum",
        "tokenContract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "minimumWithdrawAmount": "6.001789",
        "estimatedSendCost": "16",
        "deposit": true,
        "withdraw": true,
        "withdrawalDecimalPlaces": "6"
      },
      {
        "networkType": "Solana",
        "networkLongName": "Solana",
        "tokenContract": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        "minimumWithdrawAmount": "3.000594",
        "estimatedSendCost": "0.11",
        "deposit": true,
        "withdraw": true,
        "withdrawalDecimalPlaces": "6"
      }
    ]
  },
  {
    "symbol": "R",
    "isActive": true,
    "shortName": "ZAR",
    "longName": "Rand",
    "decimalPlaces": "2",
    "withdrawalDecimalPlaces": "2",
    "collateral": true,
    "collateralWeight": "1"
  }
]
```

## Example request

```bash
curl -X GET 'https://api.valr.com/v1/public/currencies'
```

```python
import requests

response = requests.request("GET", "https://api.valr.com/v1/public/currencies")
print(response.status_code, response.text)
```

## Errors

None specific to this endpoint.

---

---
url: /api-docs/getV1PublicPairs.md
description: GET /v1/public/pairs
---

# List currency pairs

`GET /v1/public/pairs`

Returns every currency pair VALR lists, including inactive ones, with its order size limits, tick size and type (`SPOT` or `FUTURE`); margin fractions are only included for margin and futures pairs. Responses are cached for up to a minute.

**Public**: no API key needed. Send the request as is, without signing it.

## Responses

### 200

OK

Array of objects:

| Property | Type | Required | Description |
|---|---|---|---|
| symbol | string | Yes | - |
| baseCurrency | string | Yes | - |
| quoteCurrency | string | Yes | - |
| shortName | string | Yes | - |
| active | boolean | Yes | - |
| minBaseAmount | string | Yes | - |
| maxBaseAmount | string | Yes | - |
| minQuoteAmount | string | Yes | - |
| maxQuoteAmount | string | Yes | - |
| tickSize | string | Yes | - |
| baseDecimalPlaces | string | Yes | - |
| marginTradingAllowed | boolean | Yes | - |
| currencyPairType | string | Yes | - |
| initialMarginFraction | string | No | - |
| maintenanceMarginFraction | string | No | - |
| autoCloseMarginFraction | string | No | - |

**Example:**

```json
[
  {
    "symbol": "ETHZAR",
    "baseCurrency": "ETH",
    "quoteCurrency": "ZAR",
    "shortName": "ETH/ZAR",
    "active": true,
    "minBaseAmount": "0.0002",
    "maxBaseAmount": "69.21",
    "minQuoteAmount": "10",
    "maxQuoteAmount": "5000000",
    "tickSize": "1",
    "baseDecimalPlaces": "8",
    "marginTradingAllowed": true,
    "currencyPairType": "SPOT",
    "initialMarginFraction": "0.2",
    "maintenanceMarginFraction": "0.1",
    "autoCloseMarginFraction": "0.033333333"
  },
  {
    "symbol": "BNBUSDC",
    "baseCurrency": "BNB",
    "quoteCurrency": "USDC",
    "shortName": "BNB/USDC",
    "active": true,
    "minBaseAmount": "0.0008",
    "maxBaseAmount": "80",
    "minQuoteAmount": "0.52",
    "maxQuoteAmount": "52000",
    "tickSize": "0.1",
    "baseDecimalPlaces": "4",
    "marginTradingAllowed": false,
    "currencyPairType": "SPOT"
  },
  {
    "symbol": "BTCUSDTPERP",
    "baseCurrency": "BTC",
    "quoteCurrency": "USDT",
    "shortName": "BTC/USDTPERP",
    "active": true,
    "minBaseAmount": "0.0001",
    "maxBaseAmount": "7",
    "minQuoteAmount": "1",
    "maxQuoteAmount": "250000",
    "tickSize": "1",
    "baseDecimalPlaces": "4",
    "marginTradingAllowed": false,
    "currencyPairType": "FUTURE",
    "initialMarginFraction": "0.025",
    "maintenanceMarginFraction": "0.0125",
    "autoCloseMarginFraction": "0.0125"
  }
]
```

## Example request

```bash
curl -X GET 'https://api.valr.com/v1/public/pairs'
```

```python
import requests

response = requests.request("GET", "https://api.valr.com/v1/public/pairs")
print(response.status_code, response.text)
```

## Errors

None specific to this endpoint.

---

---
url: /api-docs/getV1PublicPairsByType.md
description: 'GET /v1/public/pairs/{type}'
---

# List currency pairs by type

`GET /v1/public/pairs/{type}`

Returns the currency pairs of one type, spot or futures, including inactive ones, in the same form as List currency pairs. Responses are cached for up to a minute.

**Public**: no API key needed. Send the request as is, without signing it.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| type | path | string | Yes | `SPOT` or `FUTURE` (not case-sensitive). |

## Responses

### 200

OK

Array of objects:

| Property | Type | Required | Description |
|---|---|---|---|
| symbol | string | Yes | - |
| baseCurrency | string | Yes | - |
| quoteCurrency | string | Yes | - |
| shortName | string | Yes | - |
| active | boolean | Yes | - |
| minBaseAmount | string | Yes | - |
| maxBaseAmount | string | Yes | - |
| minQuoteAmount | string | Yes | - |
| maxQuoteAmount | string | Yes | - |
| tickSize | string | Yes | - |
| baseDecimalPlaces | string | Yes | - |
| marginTradingAllowed | boolean | Yes | - |
| currencyPairType | string | Yes | - |
| initialMarginFraction | string | No | - |
| maintenanceMarginFraction | string | No | - |
| autoCloseMarginFraction | string | No | - |

**Example:**

```json
[
  {
    "symbol": "BTCUSDTPERP",
    "baseCurrency": "BTC",
    "quoteCurrency": "USDT",
    "shortName": "BTC/USDTPERP",
    "active": true,
    "minBaseAmount": "0.0001",
    "maxBaseAmount": "7",
    "minQuoteAmount": "1",
    "maxQuoteAmount": "250000",
    "tickSize": "1",
    "baseDecimalPlaces": "4",
    "marginTradingAllowed": false,
    "currencyPairType": "FUTURE",
    "initialMarginFraction": "0.025",
    "maintenanceMarginFraction": "0.0125",
    "autoCloseMarginFraction": "0.0125"
  },
  {
    "symbol": "ETHUSDTPERP",
    "baseCurrency": "ETH",
    "quoteCurrency": "USDT",
    "shortName": "ETH/USDTPERP",
    "active": true,
    "minBaseAmount": "0.001",
    "maxBaseAmount": "32",
    "minQuoteAmount": "1",
    "maxQuoteAmount": "100000",
    "tickSize": "0.1",
    "baseDecimalPlaces": "3",
    "marginTradingAllowed": false,
    "currencyPairType": "FUTURE",
    "initialMarginFraction": "0.025",
    "maintenanceMarginFraction": "0.0125",
    "autoCloseMarginFraction": "0.0125"
  }
]
```

## Example request

```bash
curl -X GET 'https://api.valr.com/v1/public/pairs/{type}'
```

```python
import requests

response = requests.request("GET", "https://api.valr.com/v1/public/pairs/{type}")
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `type` isn't `SPOT` or `FUTURE`. |

Public endpoints are not signed, so they never return authentication errors.

---

---
url: /api-docs/getV2WalletFiatByCurrencyPaymentReferences.md
description: 'GET /v2/wallet/fiat/{currency}/payment/references'
---

# List deposit references

`GET /v2/wallet/fiat/{currency}/payment/references`

Lists your deposit references in this currency, newest first, with the number of deposits matched to each; get a single reference to see the deposits themselves. Pass `query` to search by reference code, payer name or payer email instead, with the best matches first.

**Requires** `COLLECTIONS_READ`, granted by `PAYMENTS_READ` or `COLLECTIONS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Fiat currency of the references, e.g. `ZAR`. |
| matched | query | boolean | No | `true` for references with at least one matched deposit, `false` for references with none. Leave it out to return both. |
| query | query | string | No | Search text: a full reference code for an exact match, or part of a payer's name or email for a fuzzy match. Shorter than two characters returns no results. |
| name | query | string | No | Same as `query`; used only when `query` isn't set. |
| email | query | string | No | Same as `query`; used only when neither `query` nor `name` is set. |
| skip | query | integer | No | Number of results to skip, for paging. |
| limit | query | integer | No | Maximum number of references to return. Values above 1000 are treated as 1000. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| items | UniqueDepositReferenceForDisplay\[] | Yes | - |
| total | integer (int32) | Yes | Total number of matching references across all pages. |
| limit | integer (int32) | Yes | - |
| offset | integer (int32) | Yes | - |
| truncated | boolean | Yes | `true` when a search had too many candidates to check them all. Narrow your search to be sure of finding the reference. |

**`items` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| referenceCode | string | Yes | The reference your payer quotes when depositing. |
| currency | string | Yes | - |
| expectedAmount | string | No | - |
| createdAt | integer (int64) | Yes | When the reference was created, in Unix milliseconds. |
| name | string | No | - |
| email | string | No | - |
| matchedDeposits | UserMatchedDepositInfo\[] | Yes | Deposits matched to this reference. |
| matchedDepositCount | integer (int32) | Yes | - |

**`matchedDeposits` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| publicId | string (uuid) | Yes | - |
| amount | string | Yes | - |
| effectiveDate | string | Yes | - |
| creditedAt | integer (int64) | Yes | - |
| isOverride | boolean | Yes | `true` if this deposit is set as the reference's override deposit. |

**Example:**

```json
{
  "items": [
    {
      "referenceCode": "VPAY-7K2Q9RT",
      "currency": "ZAR",
      "expectedAmount": "1500",
      "createdAt": 1792742400000,
      "name": "Thandi Nkosi",
      "email": "thandi@example.com",
      "matchedDeposits": [],
      "matchedDepositCount": 1
    },
    {
      "referenceCode": "VPAY-M4XH8WD",
      "currency": "ZAR",
      "createdAt": 1792571400000,
      "name": "Pieter van der Merwe",
      "email": "pieter@example.com",
      "matchedDeposits": [],
      "matchedDepositCount": 0
    }
  ],
  "total": 2,
  "limit": 100,
  "offset": 0,
  "truncated": false
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/wallet/fiat/{currency}/payment/references'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/wallet/fiat/{currency}/payment/references"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `matched` isn't `true` or `false`, `skip` or `limit` isn't a whole number, `query`, `name` or `email` is empty or too long, or the currency isn't recognised. |
| 400 | `-15721` | `SCOPED_DEPOSIT_ACCOUNT_CURRENCY_MISMATCH` | Your collections account doesn't support this currency. |
| 503 | `-15117` | `UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED` | Deposit references are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV2PaymentsBulkWithdrawalsBatches.md
description: GET /v2/payments/bulk-withdrawals/batches
---

# List disbursement batches

`GET /v2/payments/bulk-withdrawals/batches`

Returns your disbursement batches, newest first, a page at a time.

**Requires** `DISBURSEMENTS_READ`, granted by `PAYMENTS_READ` or `DISBURSEMENTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| status | query | string | No | Only batches with this status. |
| limit | query | integer | No | Page size, from 1 to 200; values outside that range are clamped. |
| offset | query | integer | No | Number of items to skip. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| items | BulkWithdrawalBatchForDisplay\[] | Yes | - |
| total | integer (int32) | Yes | - |
| limit | integer (int32) | Yes | - |
| offset | integer (int32) | Yes | - |
| truncated | boolean | Yes | - |

**`items` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | - |
| label | string | Yes | - |
| currency | string | Yes | - |
| totalAmount | string | Yes | Sum of the withdrawal amounts, as a decimal string. |
| withdrawalCount | integer (int32) | Yes | - |
| status | string | Yes | Batch status: `PENDING_APPROVAL`, `APPROVED`, `PROCESSING`, `COMPLETED`, `PARTIALLY_COMPLETED`, `FAILED` or `CANCELLED`. |
| uploadedBy | string | Yes | ID of the user or API key that created the batch. |
| uploadedByName | object | Yes | - |
| approvedBy | string | Yes | ID of the user or API key that approved the batch (for a batch created with an API key, that key); `null` until approved. |
| approvedByName | object | Yes | - |
| approvedAt | string (date-time) | Yes | - |
| createdAt | string (date-time) | Yes | - |
| updatedAt | string (date-time) | Yes | - |
| completedAt | string (date-time) | Yes | - |
| feeQuote | object | Yes | Fee for the batch's pending withdrawals, or the fee charged once none are pending. Only returned by `GET /v2/payments/bulk-withdrawals/batches/{id}`; `null` elsewhere, and when the fee can't be quoted. |

**`uploadedByName` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | - |
| surname | string | Yes | - |

**`approvedByName` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | - |
| surname | string | Yes | - |

**`feeQuote` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| fee | string | Yes | Fee as a decimal string. `null` means the fee is unknown, which isn't the same as no fee. |
| currency | string | Yes | - |
| withdrawalCount | integer (int32) | Yes | Number of withdrawals the fee covers. |
| grossTotal | string | Yes | Sum of those withdrawals' amounts. |
| requiredTotal | string | Yes | Gross total plus fee: the available balance your payout account needs. |
| feeGroups | DisbursementFeeGroupForDisplay\[] | Yes | Breakdown by fee type; `null` when the quote is the fee already charged. |

**`feeGroups` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| actionType | string | Yes | `FAST_WITHDRAWAL` for banks that take real-time payments, otherwise `REGULAR_WITHDRAWAL`. |
| withdrawalCount | integer (int32) | Yes | - |
| grossTotal | string | Yes | - |

**Example:**

```json
{
  "items": [
    {
      "id": "5b9a3c1e-2f4d-4a7b-9c8e-1d2f3a4b5c6d",
      "label": "October salaries",
      "currency": "ZAR",
      "totalAmount": "20501.00",
      "withdrawalCount": 2,
      "status": "COMPLETED",
      "uploadedBy": "8d2f4e6a-1b3c-4d5e-8f9a-0b1c2d3e4f5a",
      "uploadedByName": null,
      "approvedBy": "8d2f4e6a-1b3c-4d5e-8f9a-0b1c2d3e4f5a",
      "approvedByName": null,
      "approvedAt": "2026-10-23T08:15:02.481Z",
      "createdAt": "2026-10-23T08:15:01.912Z",
      "updatedAt": "2026-10-23T09:02:44.118Z",
      "completedAt": "2026-10-23T09:02:44.118Z",
      "feeQuote": null
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0,
  "truncated": null
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/payments/bulk-withdrawals/batches'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/payments/bulk-withdrawals/batches"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1WalletFiatByCurrencyWithdrawals.md
description: 'GET /v1/wallet/fiat/{currency}/withdrawals'
---

# List fiat withdrawals

`GET /v1/wallet/fiat/{currency}/withdrawals`

Lists fiat withdrawals in this currency, newest first, for the account (the primary, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`). `total` counts every match across pages; use it with `limit` and `offset` to page.

**Requires** `WITHDRAWALS_READ`, granted by `TREASURY_READ` or `TREASURY_WRITE` or `WITHDRAWALS_WRITE` or `BANK_ACCOUNTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Fiat currency of the withdrawals, e.g. `ZAR`. |
| status | query | string | No | Only return withdrawals with this status: `NEW` (created, nothing done yet), `PENDING_APPROVAL` (waiting for an approver), `PROCESSING` (debited and on its way to the bank), `PAID`, `REVERSED` (paid, then returned), `FAILED` (didn't complete and wasn't reversed) or `DECLINED` (declined in review or approval). A reversed withdrawal shows `FAILED` until the reversal completes. Leave it out for every status. |
| limit | query | integer | No | Maximum number of withdrawals to return, from 1 to 200; values outside that range are adjusted. |
| offset | query | integer | No | Number of withdrawals to skip, for paging. Negative values count as 0. |
| includeAllSubAccounts | query | boolean | No | `true` to include withdrawals from the primary and every sub-account apart from hidden ones. Only applies when you don't send `X-VALR-SUB-ACCOUNT-ID` and the key isn't restricted to sub-accounts; otherwise it's ignored. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| items | FiatWithdrawalForV1Display\[] | Yes | - |
| total | integer (int32) | Yes | - |
| limit | integer (int32) | Yes | - |
| offset | integer (int32) | Yes | - |

**`items` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | - |
| subAccountId | string | Yes | - |
| currency | string | Yes | - |
| amount | string | Yes | - |
| status | string (NEW, PENDING\_APPROVAL, PROCESSING, PAID, REVERSED, FAILED, DECLINED) | Yes | - |
| linkedBankAccountId | string (uuid) | Yes | - |
| isFast | boolean | Yes | - |
| createdAt | string | Yes | - |
| updatedAt | string | Yes | - |
| feeAmount | string | No | - |
| failureReason | string | No | - |
| failureReasonDescription | string | No | - |
| failureReasonAction | string | No | - |
| failureRetryable | boolean | No | - |

**Example:**

```json
{
  "items": [
    {
      "id": "d4a7c2e9-61f3-4b8d-9e05-7c1b3f6a2d84",
      "subAccountId": "0",
      "currency": "ZAR",
      "amount": "1500.00",
      "status": "PAID",
      "linkedBankAccountId": "3c9e1f42-7d5b-4a8e-9f21-6b0d8c4e7a15",
      "isFast": false,
      "createdAt": "2026-10-23T08:30:05.272523Z",
      "updatedAt": "2026-10-23T11:02:41.167902Z",
      "feeAmount": "8.50"
    },
    {
      "id": "5e9b3f17-a2c4-4d6e-8b91-0f4d7a2c6e33",
      "subAccountId": "0",
      "currency": "ZAR",
      "amount": "420.00",
      "status": "FAILED",
      "linkedBankAccountId": "8f2a6d10-c3e4-4b7f-a915-2e7c0b9d4f68",
      "isFast": true,
      "createdAt": "2026-10-20T14:12:44.091355Z",
      "updatedAt": "2026-10-20T14:40:18.630117Z",
      "feeAmount": "25.00",
      "failureReason": "INVALID_ACCOUNT_DETAILS",
      "failureReasonDescription": "The bank could not find an account with these details.",
      "failureReasonAction": "Check the account number, branch code and account type, update your bank account and try again.",
      "failureRetryable": false
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/wallet/fiat/{currency}/withdrawals'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/wallet/fiat/{currency}/withdrawals"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `status` is empty or isn't one of the listed values, `limit` or `offset` isn't a whole number, `includeAllSubAccounts` isn't `true` or `false`, or the currency isn't recognised. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1PublicMarketsummary.md
description: GET /v1/public/marketsummary
---

# List market summaries

`GET /v1/public/marketsummary`

Returns the market summary of every currency pair: best ask and bid, last traded price, and the high, low and volume over the last 24 hours. `changeFromPrevious` is the percentage change from `previousClosePrice`, the last traded price before those 24 hours; responses are cached for up to 5 seconds.

**Public**: no API key needed. Send the request as is, without signing it.

## Responses

### 200

OK

Array of objects:

| Property | Type | Required | Description |
|---|---|---|---|
| currencyPair | string | Yes | - |
| askPrice | string | Yes | - |
| bidPrice | string | Yes | - |
| lastTradedPrice | string | Yes | - |
| previousClosePrice | string | Yes | - |
| baseVolume | string | Yes | - |
| quoteVolume | string | Yes | - |
| highPrice | string | Yes | - |
| lowPrice | string | Yes | - |
| created | string | Yes | - |
| changeFromPrevious | string | Yes | - |
| markPrice | string | No | - |

**Example:**

```json
[
  {
    "currencyPair": "BTCZAR",
    "askPrice": "1850012",
    "bidPrice": "1849800",
    "lastTradedPrice": "1849900",
    "previousClosePrice": "1832000",
    "baseVolume": "12.4518",
    "quoteVolume": "22958256.31",
    "highPrice": "1861000",
    "lowPrice": "1825500",
    "created": "2026-10-23T08:51:12.004Z",
    "changeFromPrevious": "0.98",
    "markPrice": "1849900"
  },
  {
    "currencyPair": "BTCUSDTPERP",
    "askPrice": "105656",
    "bidPrice": "105594",
    "lastTradedPrice": "105611",
    "previousClosePrice": "106678",
    "baseVolume": "1.0638",
    "quoteVolume": "113947.8777",
    "highPrice": "108840",
    "lowPrice": "105600",
    "created": "2026-10-23T08:51:11.869Z",
    "changeFromPrevious": "-1",
    "markPrice": "105628"
  }
]
```

## Example request

```bash
curl -X GET 'https://api.valr.com/v1/public/marketsummary'
```

```python
import requests

response = requests.request("GET", "https://api.valr.com/v1/public/marketsummary")
print(response.status_code, response.text)
```

## Errors

None specific to this endpoint.

---

---
url: /api-docs/getV2Payments.md
description: GET /v2/payments
---

# List payments

`GET /v2/payments`

Returns payments received across every account in your business, newest first: each deposit, from a payer or to fund disbursements, with its conversion and settlement. Filter by type, settlement status, date, amount, currency or payer reference.

**Requires** `COLLECTIONS_READ`, granted by `PAYMENTS_READ` or `COLLECTIONS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| limit | query | integer | No | Maximum number of payments to return. |
| offset | query | integer | No | Number of payments to skip, for paging. |
| type | query | string | No | `COLLECTION` for payments from payers, `DISBURSEMENT` for deposits that fund disbursements. |
| status | query | string | No | Settlement status: `PENDING`, `SETTLED` or `FAILED`. |
| from | query | integer | No | Only include payments received at or after this time, in Unix milliseconds. |
| to | query | integer | No | Only include payments received before this time, in Unix milliseconds. |
| minAmount | query | string | No | Smallest deposit amount to include, as a decimal string. |
| maxAmount | query | string | No | Largest deposit amount to include, as a decimal string. |
| currency | query | string | No | Only include payments with this currency on any leg: deposit, conversion or payout. |
| reference | query | string | No | Payer reference, or part of one. Not case-sensitive. |
| referenceCodes | query | string | No | Comma-separated payer references. Only payments with one of these exact references are included. |
| payer | query | string | No | Same as `referenceCodes`; ignored when `referenceCodes` is sent. |
| query | query | string | No | Free-text search. A date (`YYYY-MM-DD`) matches that whole day, a number matches an exact amount on any leg, and anything else matches a currency or payer reference. Explicit filters take precedence. |
| tz | query | string | No | IANA time zone used to interpret a date in `query`, e.g. `Africa/Johannesburg`. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| items | PaymentForUser\[] | Yes | - |
| total | integer (int32) | Yes | - |
| limit | integer (int32) | Yes | - |
| offset | integer (int32) | Yes | - |

**`items` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | Payment ID. |
| depositId | string | Yes | ID of the deposit that created the payment. |
| status | string | Yes | Overall status: `RECEIVED`, `CONVERTED`, `SWEPT`, `PENDING_SETTLEMENT`, `COMPLETED` or `FAILED`. |
| mode | string | Yes | How the payment is paid out: `INSTANT` or `SCHEDULED`. Null until a payout is set up. |
| type | string | Yes | `COLLECTION` for a payment from a payer, `DISBURSEMENT` for a deposit that funds disbursements. |
| inflowCurrency | string | Yes | - |
| inflowAmount | string | Yes | Amount deposited. |
| convertedCurrency | string | Yes | - |
| convertedAmount | string | Yes | Amount after conversion; null if the deposit hasn't been converted. |
| outflowCurrency | string | Yes | - |
| outflowAmount | string | Yes | Amount paid out; null until a payout is set up. |
| receivedAt | integer (int64) | Yes | When the deposit was received, in Unix milliseconds. |
| settlementAt | integer (int64) | Yes | Expected settlement time while a scheduled payout is pending, then the time the payment settled, in Unix milliseconds. |
| settlementStatus | string | Yes | `PENDING`, `SETTLED` or `FAILED`. |
| settlementRef | string | Yes | Payout reference, such as the blockchain transaction hash of a crypto payout. |
| settlementId | string | Yes | The settlement that paid this payment out; null until a payout has been requested. |
| linked | boolean | Yes | Whether the deposit carries a payer reference. |
| payerName | string | Yes | Payer's name. |
| reference | string | Yes | Payer reference quoted with the deposit. |
| timeline | FlowStepForDisplay\[] | Yes | Steps the payment has been through. Only returned when you get a single payment. |
| payouts | PaymentPayoutForUser\[] | Yes | Settled payouts that carried this payment; more than one if it was split. Only returned when you get a single payment. |

**`timeline` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| type | string | Yes | `FUNDING`, `CONVERSION`, `SWEEP`, `WITHDRAWAL` or `SETTLEMENT`. |
| label | string | Yes | - |
| status | string | Yes | `PENDING`, `COMPLETE` or `FAILED`. |
| data | object | Yes | Amounts and currencies for the step. |
| traceId | string | Yes | Reference you can quote to support, such as a conversion ID or blockchain transaction hash. |
| at | integer (int64) | Yes | When the step happened, in Unix milliseconds. For a pending settlement, the scheduled time. |

**`payouts` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| settlementId | string | Yes | - |
| amount | string | Yes | - |
| currency | string | Yes | - |
| status | string | Yes | Payout status. Only settled payouts are listed, so this is `SETTLED`. |
| settledAt | integer (int64) | Yes | When the payout settled, in Unix milliseconds. |

**Example:**

```json
{
  "items": [
    {
      "id": "8d2f4b6a-1c3e-4f5a-9b7d-2e4c6a8b0d1f",
      "depositId": "3f1c2a9e-8b4d-4c1e-9f2a-6d7e8b9c0a1b",
      "status": "COMPLETED",
      "mode": "SCHEDULED",
      "type": "COLLECTION",
      "inflowCurrency": "ZAR",
      "inflowAmount": "1500.00",
      "convertedCurrency": "USDC",
      "convertedAmount": "82.45",
      "outflowCurrency": "USDC",
      "outflowAmount": "82.45",
      "receivedAt": 1792660500000,
      "settlementAt": 1792684950000,
      "settlementStatus": "SETTLED",
      "settlementRef": null,
      "settlementId": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f",
      "linked": true,
      "payerName": "Thandi Nkosi",
      "reference": "VLR4F7K2Q9",
      "timeline": null,
      "payouts": null
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/payments'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/payments"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV2PaymentsPayoutHistory.md
description: GET /v2/payments/payout/history
---

# List payout account transactions

`GET /v2/payments/payout/history`

Returns the transactions on your payout account, newest first: debits for payouts, and credits for funding and reversed payouts. A reversed payout keeps its original debit, marked `REVERSED`, alongside a credit for the amount returned.

**Requires** `DISBURSEMENTS_READ`, granted by `PAYMENTS_READ` or `DISBURSEMENTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| direction | query | string | No | `DEBIT` for money out (payouts) or `CREDIT` for money in (funding and reversals). Case-insensitive. |
| status | query | string | No | Only transactions with this status. Case-insensitive. |
| from | query | integer | No | Only transactions at or after this time, in Unix milliseconds. |
| to | query | integer | No | Only transactions before this time, in Unix milliseconds. |
| minAmount | query | number | No | Only transactions of at least this amount, before fees. |
| maxAmount | query | number | No | Only transactions of at most this amount, before fees. |
| exactAmount | query | number | No | Only transactions of exactly this amount, before fees. |
| query | query | string | No | Text to find in the payment reference or batch label. |
| beneficiaryId | query | string | No | Only payouts to this beneficiary. |
| limit | query | integer | No | Page size, from 1 to 200; values outside that range are clamped. |
| offset | query | integer | No | Number of items to skip. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| items | PayoutTransactionForDisplay\[] | Yes | - |
| total | integer (int32) | Yes | - |
| limit | integer (int32) | Yes | - |
| offset | integer (int32) | Yes | - |
| truncated | boolean | Yes | - |

**`items` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | - |
| direction | string | Yes | `DEBIT` (money out) or `CREDIT` (money in). |
| kind | string | Yes | `WITHDRAWAL` (a payout), `FUNDING` (an automated funding transfer), `FUNDING_MANUAL` (any other top-up) or `REVERSAL` (a reversed payout returned to the account). |
| status | string | Yes | `COMPLETE`, `PROCESSING`, `REVERSED` or `FAILED`. |
| amount | string | Yes | Amount including any fee, as an unsigned decimal string; `direction` gives the sign. |
| currency | string | Yes | - |
| date | integer (int64) | Yes | When the transaction happened, in Unix milliseconds. |
| counterparty | string | Yes | The recipient's name for a debit; `Payout account` or `Reversal` for a credit. |
| reference | string | Yes | Payment reference, or `Funding` for a credit without one. |
| batchId | string | Yes | - |
| batchLabel | string | Yes | - |
| paymentId | string | Yes | For a funding credit, the ID of the payment that funded it; use it with `GET /v2/payments/{id}`. |

**Example:**

```json
{
  "items": [
    {
      "id": "e3f5a7b9-1c2d-4e6f-8a0b-2c4d6e8f0a1b",
      "direction": "DEBIT",
      "kind": "WITHDRAWAL",
      "status": "COMPLETE",
      "amount": "12513.25",
      "currency": "ZAR",
      "date": 1792746164000,
      "counterparty": "Thandi Nkosi",
      "reference": "OCT SALARY",
      "batchId": "5b9a3c1e-2f4d-4a7b-9c8e-1d2f3a4b5c6d",
      "batchLabel": "October salaries",
      "paymentId": null
    },
    {
      "id": "4a6c8e0b-2d4f-4a1c-9e3b-5d7f9a1c3e5b",
      "direction": "CREDIT",
      "kind": "FUNDING",
      "status": "COMPLETE",
      "amount": "50000.00",
      "currency": "ZAR",
      "date": 1792654200000,
      "counterparty": "Payout account",
      "reference": "Funding",
      "batchId": null,
      "batchLabel": null,
      "paymentId": "f9a1c3e5-7b2d-4f6a-8c0e-1d3f5a7b9c2e"
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0,
  "truncated": null
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/payments/payout/history'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/payments/payout/history"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV2PaymentsCollectRunsHistory.md
description: GET /v2/payments/collect/runs/history
---

# List payout runs

`GET /v2/payments/collect/runs/history`

Returns scheduled payout runs, latest scheduled time first, across every payout schedule in your business.

**Requires** `COLLECTIONS_READ`, granted by `PAYMENTS_READ` or `COLLECTIONS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | No | Only include runs that pay out in this currency. Use the upper-case code, e.g. `USDC`. |
| limit | query | integer | No | Maximum number of runs to return. |
| offset | query | integer | No | Number of runs to skip, for paging. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| items | WithdrawalRunForDisplay\[] | Yes | - |
| total | integer (int32) | Yes | - |
| limit | integer (int32) | Yes | - |
| offset | integer (int32) | Yes | - |

**`items` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | - |
| scheduledFor | integer (int64) | Yes | When the run pays out, in Unix milliseconds. |
| cutoffAt | integer (int64) | Yes | Payments received after this time wait for the next run, in Unix milliseconds. |
| status | string | Yes | `PENDING`, `PROCESSING`, `DONE`, `FAILED`, `CANCELLED` or `REVERSED`. |
| totalAmount | string | Yes | Total the run pays out; `0` until the run starts. |
| currency | string | Yes | - |
| createdAt | integer (int64) | Yes | - |

**Example:**

```json
{
  "items": [
    {
      "id": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f",
      "scheduledFor": 1792684800000,
      "cutoffAt": 1792677600000,
      "status": "DONE",
      "totalAmount": "1240.75",
      "currency": "USDC",
      "createdAt": 1792598405000
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/payments/collect/runs/history'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/payments/collect/runs/history"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV2PaymentsCollectSchedules.md
description: GET /v2/payments/collect/schedules
---

# List payout schedules

`GET /v2/payments/collect/schedules`

Returns every payout schedule set up for your business, including inactive ones. Schedules are managed by VALR.

**Requires** `COLLECTIONS_READ`, granted by `PAYMENTS_READ` or `COLLECTIONS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Responses

### 200

OK

Array of objects:

| Property | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | - |
| currency | string | Yes | - |
| kind | string | Yes | `FIAT` to pay out to a bank account, `CRYPTO` to pay out to a wallet. |
| intervalType | string | Yes | `DAILY` or `WEEKLY`. |
| timeOfDay | string | Yes | Local time the run pays out, as `HH:mm` in `zoneId`. |
| zoneId | string | Yes | IANA time zone of `timeOfDay`. |
| dayOfWeek | integer (int32) | Yes | Day of a `WEEKLY` run, from 1 (Monday) to 7 (Sunday); null for `DAILY`. |
| cutoffMinutes | integer (int32) | Yes | Payments received less than this many minutes before a run wait for the next one. |
| paymentInstrumentId | string | Yes | The bank account or wallet the schedule pays out to. |
| isActive | boolean | Yes | Whether the schedule is running. |
| createdAt | integer (int64) | Yes | - |
| updatedAt | integer (int64) | Yes | - |

**Example:**

```json
[
  {
    "id": "1a7c3e5b-9d2f-4b6a-8e0c-2f4a6b8d0e1c",
    "currency": "USDC",
    "kind": "CRYPTO",
    "intervalType": "DAILY",
    "timeOfDay": "18:00",
    "zoneId": "Africa/Johannesburg",
    "dayOfWeek": null,
    "cutoffMinutes": 120,
    "paymentInstrumentId": "e2a4c6b8-0d1f-4e3a-b5c7-9d1e3f5a7b9c",
    "isActive": true,
    "createdAt": 1790848800000,
    "updatedAt": 1792067400000
  }
]
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/payments/collect/schedules'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/payments/collect/schedules"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1PublicByCurrencyPairBuckets.md
description: 'GET /v1/public/{currencyPair}/buckets'
---

# List price buckets

`GET /v1/public/{currencyPair}/buckets`

Returns the open, high, low and close prices and traded volume of a currency pair in buckets (candles) of `periodSeconds`, newest first. The current, unfinished bucket is included unless you skip results or `endTime` is in the past; responses are cached for up to 5 seconds.

**Public**: no API key needed. Send the request as is, without signing it.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currencyPair | path | string | Yes | Currency pair symbol, e.g. `BTCZAR`. |
| periodSeconds | query | integer | No | Length of each bucket in seconds: `60`, `300`, `900`, `1800`, `3600`, `21600` or `86400`. |
| startTime | query | string | No | Only buckets that start at or after this time, as an ISO 8601 timestamp or Unix seconds. A value in neither format is ignored. |
| endTime | query | string | No | Only buckets that start at or before this time, as an ISO 8601 timestamp or Unix seconds. A value in neither format is ignored. |
| skip | query | integer | No | Number of buckets to skip, for paging. |
| limit | query | integer | No | Maximum number of buckets to return, up to 400. |
| includeEmpty | query | boolean | No | `false` to leave out buckets with no trades. |

## Responses

### 200

OK

Array of objects:

| Property | Type | Required | Description |
|---|---|---|---|
| currencyPairSymbol | string | Yes | - |
| bucketPeriodInSeconds | integer (int32) | No | - |
| startTime | string | Yes | - |
| open | string | Yes | - |
| high | string | Yes | - |
| low | string | Yes | - |
| close | string | Yes | - |
| volume | string | Yes | - |
| quoteVolume | string | Yes | - |

**Example:**

```json
[
  {
    "currencyPairSymbol": "BTCZAR",
    "bucketPeriodInSeconds": 60,
    "startTime": "2026-10-23T08:51:00Z",
    "open": "1849800",
    "high": "1850012",
    "low": "1849800",
    "close": "1849900",
    "volume": "0.0517",
    "quoteVolume": "95638.42"
  },
  {
    "currencyPairSymbol": "BTCZAR",
    "bucketPeriodInSeconds": 60,
    "startTime": "2026-10-23T08:50:00Z",
    "open": "1849500",
    "high": "1849900",
    "low": "1849500",
    "close": "1849800",
    "volume": "0.2105",
    "quoteVolume": "389372.3"
  }
]
```

## Example request

```bash
curl -X GET 'https://api.valr.com/v1/public/{currencyPair}/buckets'
```

```python
import requests

response = requests.request("GET", "https://api.valr.com/v1/public/{currencyPair}/buckets")
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-21` | `INVALID_CURRENCY_PAIR` | `currencyPair` isn't a currency pair VALR supports. |
| 400 | `-11` | `INVALID_REQUEST` | `periodSeconds` isn't one of the supported periods, `skip` or `limit` isn't a whole number, `limit` is more than 400, or `includeEmpty` isn't `true` or `false`. |

Public endpoints are not signed, so they never return authentication errors.

---

---
url: /api-docs/getV2PaymentsCollectHistory.md
description: GET /v2/payments/collect/history
---

# List processed scheduled payments

`GET /v2/payments/collect/history`

Returns payments that scheduled payout runs have picked up (processing, completed or failed), newest first, across every payout schedule in your business.

**Requires** `COLLECTIONS_READ`, granted by `PAYMENTS_READ` or `COLLECTIONS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | No | Only include schedules that pay out in this currency. Use the upper-case code, e.g. `USDC`. |
| limit | query | integer | No | Maximum number of payments to return. |
| offset | query | integer | No | Number of payments to skip, for paging. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| items | ScheduledWithdrawalEventForUser\[] | Yes | - |
| total | integer (int32) | Yes | - |
| limit | integer (int32) | Yes | - |
| offset | integer (int32) | Yes | - |

**`items` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | - |
| withdrawalCurrency | string | Yes | - |
| withdrawalAmount | string | Yes | Amount the payment adds to the payout. |
| receivedAt | integer (int64) | Yes | When the payment joined the schedule, in Unix milliseconds. |
| status | string | Yes | `QUEUED`, `SCHEDULED`, `PROCESSING`, `COMPLETED`, `FAILED` or `REVERSED`. |
| depositCurrency | string | Yes | - |
| depositAmount | string | Yes | Amount of the deposit the payment came from. |
| payerName | string | Yes | - |
| reference | string | Yes | - |
| timeline | FlowStepForDisplay\[] | Yes | Steps the payment has been through. Only returned when you get a single scheduled payment. |

**`timeline` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| type | string | Yes | `FUNDING`, `CONVERSION`, `SWEEP`, `WITHDRAWAL` or `SETTLEMENT`. |
| label | string | Yes | - |
| status | string | Yes | `PENDING`, `COMPLETE` or `FAILED`. |
| data | object | Yes | Amounts and currencies for the step. |
| traceId | string | Yes | Reference you can quote to support, such as a conversion ID or blockchain transaction hash. |
| at | integer (int64) | Yes | When the step happened, in Unix milliseconds. For a pending settlement, the scheduled time. |

**Example:**

```json
{
  "items": [
    {
      "id": "2e4a6c8b-0d1f-4a3c-9e5b-7d9f1b3a5c7e",
      "withdrawalCurrency": "USDC",
      "withdrawalAmount": "82.45",
      "receivedAt": 1792660600000,
      "status": "COMPLETED",
      "depositCurrency": "ZAR",
      "depositAmount": "1500.00",
      "payerName": "Thandi Nkosi",
      "reference": "VLR4F7K2Q9",
      "timeline": null
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/payments/collect/history'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/payments/collect/history"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV2PaymentsCollectEvents.md
description: GET /v2/payments/collect/events
---

# List queued scheduled payments

`GET /v2/payments/collect/events`

Returns payments waiting for their next scheduled payout run, newest first, across every payout schedule in your business.

**Requires** `COLLECTIONS_READ`, granted by `PAYMENTS_READ` or `COLLECTIONS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | query | string | No | Only include schedules that pay out in this currency. Use the upper-case code, e.g. `USDC`. |
| limit | query | integer | No | Maximum number of payments to return. |
| offset | query | integer | No | Number of payments to skip, for paging. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| items | ScheduledWithdrawalEventForUser\[] | Yes | - |
| total | integer (int32) | Yes | - |
| limit | integer (int32) | Yes | - |
| offset | integer (int32) | Yes | - |

**`items` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | - |
| withdrawalCurrency | string | Yes | - |
| withdrawalAmount | string | Yes | Amount the payment adds to the payout. |
| receivedAt | integer (int64) | Yes | When the payment joined the schedule, in Unix milliseconds. |
| status | string | Yes | `QUEUED`, `SCHEDULED`, `PROCESSING`, `COMPLETED`, `FAILED` or `REVERSED`. |
| depositCurrency | string | Yes | - |
| depositAmount | string | Yes | Amount of the deposit the payment came from. |
| payerName | string | Yes | - |
| reference | string | Yes | - |
| timeline | FlowStepForDisplay\[] | Yes | Steps the payment has been through. Only returned when you get a single scheduled payment. |

**`timeline` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| type | string | Yes | `FUNDING`, `CONVERSION`, `SWEEP`, `WITHDRAWAL` or `SETTLEMENT`. |
| label | string | Yes | - |
| status | string | Yes | `PENDING`, `COMPLETE` or `FAILED`. |
| data | object | Yes | Amounts and currencies for the step. |
| traceId | string | Yes | Reference you can quote to support, such as a conversion ID or blockchain transaction hash. |
| at | integer (int64) | Yes | When the step happened, in Unix milliseconds. For a pending settlement, the scheduled time. |

**Example:**

```json
{
  "items": [
    {
      "id": "6b0d2f4a-8c1e-4a3b-9d5f-7e9a1b3c5d7e",
      "withdrawalCurrency": "USDC",
      "withdrawalAmount": "54.20",
      "receivedAt": 1792744300000,
      "status": "SCHEDULED",
      "depositCurrency": "ZAR",
      "depositAmount": "985.00",
      "payerName": "Sipho Dlamini",
      "reference": "VLR8M3N6P1",
      "timeline": null
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/payments/collect/events'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/payments/collect/events"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1WalletCryptoServiceProviders.md
description: GET /v1/wallet/crypto/service-providers
---

# List service providers

`GET /v1/wallet/crypto/service-providers`

Returns the exchanges and other crypto service providers you can name as a withdrawal recipient's provider, by sending an `id` as `serviceProviderId`. If the recipient's provider isn't listed, send its name in `serviceProviderName` instead.

**Requires** `WITHDRAWALS_READ`, granted by `TREASURY_READ` or `TREASURY_WRITE` or `WITHDRAWALS_WRITE` or `BANK_ACCOUNTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Responses

### 200

OK

Array of objects:

| Property | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | Provider ID; send it as `serviceProviderId` when withdrawing. |
| name | string | Yes | - |
| hidden | boolean | Yes | - |

**Example:**

```json
[
  {
    "id": "672b1ff8a1ff8a027906ff39",
    "name": "Bybit",
    "hidden": false
  },
  {
    "id": "676d1c189ef2fd542e5bbf33",
    "name": "Binance",
    "hidden": false
  }
]
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/wallet/crypto/service-providers'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/wallet/crypto/service-providers"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

Only the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV2PaymentsCollectSettlements.md
description: GET /v2/payments/collect/settlements
---

# List settlements

`GET /v2/payments/collect/settlements`

Returns settlements across every account in your business: each is a scheduled payout run or an instant payout of collected funds. Unsettled ones come first, then the most recently settled.

**Requires** `COLLECTIONS_READ`, granted by `PAYMENTS_READ` or `COLLECTIONS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| limit | query | integer | No | Maximum number of settlements to return. |
| offset | query | integer | No | Number of settlements to skip, for paging. |
| type | query | string | No | `COLLECTION` or `DISBURSEMENT`: only include settlements of that type of payment. |
| status | query | string | No | `PENDING`, `SETTLED`, `FAILED` or `PARTIALLY_SETTLED`. |
| from | query | integer | No | Only count payments received at or after this time, in Unix milliseconds. |
| to | query | integer | No | Only count payments received before this time, in Unix milliseconds. |
| minAmount | query | string | No | Smallest settlement total to include, as a decimal string. |
| maxAmount | query | string | No | Largest settlement total to include, as a decimal string. |
| currency | query | string | No | Payout currency. |
| query | query | string | No | Free-text search. A date (`YYYY-MM-DD`) matches that whole day, a number matches a settlement total exactly, and anything else matches the payout currency. Explicit filters take precedence. |
| tz | query | string | No | IANA time zone used to interpret a date in `query`, e.g. `Africa/Johannesburg`. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| items | SettlementForUser\[] | Yes | - |
| total | integer (int32) | Yes | - |
| limit | integer (int32) | Yes | - |
| offset | integer (int32) | Yes | - |

**`items` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | Settlement ID: the payout run ID for a scheduled payout, or the payout ID for an instant payout. |
| currency | string | Yes | Payout currency. |
| totalAmount | string | Yes | Total the settlement pays out. |
| settledAmount | string | Yes | Amount paid out so far; equals `totalAmount` once fully settled. |
| paymentCount | integer (int32) | Yes | - |
| status | string | Yes | `PENDING`, `SETTLED`, `FAILED` or `PARTIALLY_SETTLED`. |
| settledAt | integer (int64) | Yes | Latest time a payment in the settlement settled, in Unix milliseconds; null if none has. |
| receivedAt | integer (int64) | Yes | When the most recent payment in the settlement was received, in Unix milliseconds. |

**Example:**

```json
{
  "items": [
    {
      "id": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f",
      "currency": "USDC",
      "totalAmount": "1240.75",
      "settledAmount": "1240.75",
      "paymentCount": 23,
      "status": "SETTLED",
      "settledAt": 1792684950000,
      "receivedAt": 1792676400000
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/payments/collect/settlements'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/payments/collect/settlements"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1AccountSubaccounts.md
description: GET /v1/account/subaccounts
---

# List sub-accounts

`GET /v1/account/subaccounts`

Lists your primary account (`id` `0`, label `Primary`) followed by its sub-accounts, newest first. Deleted sub-accounts, and your payments payout, collections and funding accounts, aren't listed. Call it on your primary account (don't send `X-VALR-SUB-ACCOUNT-ID`); keys limited to some sub-accounts can't use it.

**Requires** `SUB_ACCOUNTS_READ`, granted by `TREASURY_READ` or `TREASURY_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| includeTags | query | boolean | No | `true` to include each account's `accountTags`. |
| includePayoutAccounts | query | boolean | No | `true` to include `autoPayoutLinkedBankAccountId` for accounts that pay out to a bank account automatically. |

## Responses

### 200

OK

Array of objects:

| Property | Type | Required | Description |
|---|---|---|---|
| label | string | Yes | Account name. Your primary account's is `Primary`. |
| id | string | Yes | Account ID: `0` for your primary account. It's a string because sub-account IDs can be larger than some languages' numbers hold exactly. Send a sub-account's ID in `X-VALR-SUB-ACCOUNT-ID` to act on it. |
| accountTags | string\[] | No | Tags on the account, such as `CLIENT_FUNDS`. Only returned when you set `includeTags` to `true`. |
| autoPayoutLinkedBankAccountId | string | No | ID of the bank account this account pays out to automatically. Only returned when you set `includePayoutAccounts` to `true` and the account has one. |

**Example:**

```json
[
  {
    "label": "Primary",
    "id": "0"
  },
  {
    "label": "Treasury",
    "id": "7340032581337088"
  },
  {
    "label": "Client Funds",
    "id": "7339876125413376"
  }
]
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/account/subaccounts'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/account/subaccounts"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `includeTags` or `includePayoutAccounts` isn't `true` or `false`. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV2PaymentsBulkWithdrawalsBanks.md
description: GET /v2/payments/bulk-withdrawals/banks
---

# List supported banks

`GET /v2/payments/bulk-withdrawals/banks`

Returns the banks you can pay out to, with each bank's default branch code. Send a bank's `code` as `bank` when you create withdrawals or beneficiaries.

**Requires** `DISBURSEMENTS_READ`, granted by `PAYMENTS_READ` or `DISBURSEMENTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Responses

### 200

OK

Array of objects:

| Property | Type | Required | Description |
|---|---|---|---|
| code | string | Yes | Bank code to send as `bank`. |
| displayName | string | Yes | - |
| defaultBranchCode | string | Yes | The bank's universal branch code; empty if it has none. |
| rtcParticipant | boolean | Yes | Whether the bank takes real-time payments. Payouts to these banks are sent, and charged, as fast withdrawals. |

**Example:**

```json
[
  {
    "code": "ABSA",
    "displayName": "ABSA Bank",
    "defaultBranchCode": "632005",
    "rtcParticipant": true
  },
  {
    "code": "CAPITEC",
    "displayName": "Capitec Bank",
    "defaultBranchCode": "470010",
    "rtcParticipant": false
  },
  {
    "code": "FNB",
    "displayName": "FNB/RMB",
    "defaultBranchCode": "250655",
    "rtcParticipant": true
  }
]
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/payments/bulk-withdrawals/banks'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/payments/bulk-withdrawals/banks"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1AccountTransactionhistory.md
description: GET /v1/account/transactionhistory
---

# List transactions

`GET /v1/account/transactionhistory`

Lists transactions on the account you call it on (your primary account, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`), newest first: trades, deposits, withdrawals, transfers between your accounts, fees and other balance changes. Filter by type, currency or time range, and page with `skip` and `limit`, or by passing the `id` of the oldest transaction you've received as `beforeId`.

**Requires** `TRANSACTION_HISTORY_READ`, granted by `TRADING_READ` or `TRADING_WRITE` or `TREASURY_READ` or `TREASURY_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| skip | query | integer | No | Number of transactions to skip, for paging. |
| limit | query | integer | No | Maximum number of transactions to return, up to 200. |
| startTime | query | string | No | Only include transactions at or after this time, as an ISO 8601 timestamp in UTC. |
| endTime | query | string | No | Only include transactions at or before this time, as an ISO 8601 timestamp in UTC. Mustn't be before `startTime`. |
| currency | query | string | No | Only include transactions that debit or credit this currency, e.g. `ZAR`. |
| transactionTypes | query | string | No | Comma-separated transaction types to include, in upper case, e.g. `LIMIT_BUY,MARKET_BUY`. The values are the `transactionType.type` values in responses. |
| beforeId | query | string | No | Only include transactions older than the transaction with this `id`. |

## Responses

### 200

OK

Array of objects:

| Property | Type | Required | Description |
|---|---|---|---|
| transactionType | object | Yes | What kind of transaction this is. |
| debitCurrency | string | No | Currency taken from the account. Absent if nothing was taken. |
| debitValue | string | No | Amount taken from the account. |
| creditCurrency | string | No | Currency added to the account. Absent if nothing was added. |
| creditValue | string | No | Amount added to the account. |
| feeCurrency | string | No | Currency of the fee. Absent if there was no fee. |
| feeValue | string | No | Fee charged. |
| eventAt | string | Yes | When the transaction happened, as an ISO 8601 timestamp in UTC. |
| id | string (uuid) | Yes | Transaction ID. In List transactions, pass it as `beforeId` to fetch older transactions. |
| additionalInfo | object | No | Details that depend on `transactionType`. For example, trades carry `currencyPairSymbol`, `orderId` and the price as `costPerCoin` in `costPerCoinSymbol`; transfers between your accounts carry `reason`, `reasonDescription`, `additional` (which accounts were involved) and `transferId`, the `id` returned by Transfer between accounts. Absent when there are no details. |

**`transactionType` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| type | string | Yes | Transaction type, e.g. `LIMIT_BUY`, `FIAT_DEPOSIT` or `INTERNAL_TRANSFER`. Use these values in `transactionTypes`. |
| description | string | Yes | Readable name of the type. |

**Example:**

```json
[
  {
    "transactionType": {
      "type": "LIMIT_SELL",
      "description": "Limit Sell"
    },
    "debitCurrency": "BTC",
    "debitValue": "0.0025",
    "creditCurrency": "ZAR",
    "creditValue": "2981.525",
    "feeCurrency": "ZAR",
    "feeValue": "5.975",
    "eventAt": "2026-10-22T14:03:51.207Z",
    "additionalInfo": {
      "costPerCoin": 1195000,
      "costPerCoinSymbol": "R",
      "currencyPairSymbol": "BTCZAR",
      "orderId": "019a0c4e-2e91-7f4a-b2c8-1d6e3f5a7b90"
    },
    "id": "019a0c4e-2f70-7a3b-8c4d-2e1f0a9b8c7d"
  },
  {
    "transactionType": {
      "type": "INTERNAL_TRANSFER",
      "description": "Transfer"
    },
    "debitCurrency": "USDC",
    "debitValue": "2500",
    "eventAt": "2026-10-22T09:30:12.884Z",
    "additionalInfo": {
      "reason": "SUB_ACCOUNT",
      "reasonDescription": "Transfer between subaccounts",
      "additional": "Transfer from Primary to Treasury",
      "transferId": "512874"
    },
    "id": "019a0b47-3d24-7c58-b1e9-6a7b8c9d0e1f"
  },
  {
    "transactionType": {
      "type": "FIAT_DEPOSIT",
      "description": "Deposit"
    },
    "creditCurrency": "ZAR",
    "creditValue": "150000",
    "eventAt": "2026-10-21T07:45:03.112Z",
    "id": "019a05a1-c2e8-7f30-8d4a-1b2c3d4e5f60"
  }
]
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/account/transactionhistory'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/account/transactionhistory"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `skip` or `limit` isn't a whole number, `limit` is more than 200, `startTime` or `endTime` isn't an ISO 8601 timestamp, `endTime` is before `startTime`, `currency` isn't a currency VALR supports, `transactionTypes` contains an unknown type, or `beforeId` isn't a valid UUID. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1AccountTransactionhistorySubaccounts.md
description: GET /v1/account/transactionhistory/subaccounts
---

# List transactions for all sub-accounts

`GET /v1/account/transactionhistory/subaccounts`

Lists transactions on all your sub-accounts in one call, grouped by sub-account and newest first within each. Only sub-accounts with matching transactions are included, and your primary account's own transactions aren't. Results cover at most 7 days; with no time range you get the last 24 hours. Sub-accounts are read in groups of 50, with `skip` and `limit` applied within each group, so with more than 50 sub-accounts you can get more than `limit` transactions. Call it on your primary account: on a sub-account it returns an empty list. Keys limited to some sub-accounts can't use it.

**Requires** `TRANSACTION_HISTORY_READ`, granted by `TRADING_READ` or `TRADING_WRITE` or `TREASURY_READ` or `TREASURY_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| skip | query | integer | No | Number of transactions to skip, for paging. |
| limit | query | integer | No | Maximum number of transactions to return, up to 200. |
| startTime | query | string | No | Only include transactions at or after this time, as an ISO 8601 timestamp in UTC. If you send only `startTime`, results run to 7 days after it or to now, whichever is earlier. |
| endTime | query | string | No | Only include transactions at or before this time, as an ISO 8601 timestamp in UTC; at most 7 days after `startTime`. If you send only `endTime`, results start 7 days before it. |
| currency | query | string | No | Only include transactions that debit or credit this currency, e.g. `USDC`. |
| transactionTypes | query | string | No | Comma-separated transaction types to include, in upper case, e.g. `LIMIT_BUY,MARKET_BUY`. The values are the `transactionType.type` values in responses. |

## Responses

### 200

OK

Array of objects:

| Property | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | Sub-account ID. |
| label | string | Yes | Sub-account name. |
| transactions | V1APIUserTransactionRecord\[] | Yes | The sub-account's matching transactions, newest first. |

**`transactions` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| transactionType | object | Yes | What kind of transaction this is. |
| debitCurrency | string | No | Currency taken from the account. Absent if nothing was taken. |
| debitValue | string | No | Amount taken from the account. |
| creditCurrency | string | No | Currency added to the account. Absent if nothing was added. |
| creditValue | string | No | Amount added to the account. |
| feeCurrency | string | No | Currency of the fee. Absent if there was no fee. |
| feeValue | string | No | Fee charged. |
| eventAt | string | Yes | When the transaction happened, as an ISO 8601 timestamp in UTC. |
| id | string (uuid) | Yes | Transaction ID. In List transactions, pass it as `beforeId` to fetch older transactions. |
| additionalInfo | object | No | Details that depend on `transactionType`. For example, trades carry `currencyPairSymbol`, `orderId` and the price as `costPerCoin` in `costPerCoinSymbol`; transfers between your accounts carry `reason`, `reasonDescription`, `additional` (which accounts were involved) and `transferId`, the `id` returned by Transfer between accounts. Absent when there are no details. |

**`transactionType` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| type | string | Yes | Transaction type, e.g. `LIMIT_BUY`, `FIAT_DEPOSIT` or `INTERNAL_TRANSFER`. Use these values in `transactionTypes`. |
| description | string | Yes | Readable name of the type. |

**Example:**

```json
[
  {
    "id": "7340032581337088",
    "label": "Treasury",
    "transactions": [
      {
        "transactionType": {
          "type": "MARKET_BUY",
          "description": "Market Buy"
        },
        "debitCurrency": "ZAR",
        "debitValue": "18420",
        "creditCurrency": "USDT",
        "creditValue": "998.5",
        "feeCurrency": "USDT",
        "feeValue": "1.5",
        "eventAt": "2026-10-22T10:02:44.319Z",
        "additionalInfo": {
          "costPerCoin": 18.42,
          "costPerCoinSymbol": "R",
          "currencyPairSymbol": "USDTZAR",
          "orderId": "019a0b64-9f13-7d2a-8e4b-5c6d7e8f9a0b"
        },
        "id": "019a0b64-a0c7-7b19-9f2e-3d4c5b6a7980"
      },
      {
        "transactionType": {
          "type": "INTERNAL_TRANSFER",
          "description": "Transfer"
        },
        "creditCurrency": "USDC",
        "creditValue": "2500",
        "eventAt": "2026-10-22T09:30:12.884Z",
        "additionalInfo": {
          "reason": "SUB_ACCOUNT",
          "reasonDescription": "Transfer between subaccounts",
          "additional": "Transfer from Primary to Treasury",
          "transferId": "512874"
        },
        "id": "019a0b47-3d25-7e61-a4c2-8b9c0d1e2f3a"
      }
    ]
  },
  {
    "id": "7339876125413376",
    "label": "Client Funds",
    "transactions": [
      {
        "transactionType": {
          "type": "FIAT_DEPOSIT",
          "description": "Deposit"
        },
        "creditCurrency": "ZAR",
        "creditValue": "42000",
        "eventAt": "2026-10-21T12:15:30.004Z",
        "id": "019a06c8-5b31-7a44-b6d1-2c3d4e5f6a7b"
      }
    ]
  }
]
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/account/transactionhistory/subaccounts'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/account/transactionhistory/subaccounts"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | `beforeId` was sent (it isn't supported here), `skip` or `limit` isn't a whole number, `limit` is more than 200, `startTime` or `endTime` isn't an ISO 8601 timestamp, `endTime` is before `startTime` or more than 7 days after it, `currency` isn't a currency VALR supports, or `transactionTypes` contains an unknown type. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1WebhooksByIdDeliveries.md
description: 'GET /v1/webhooks/{id}/deliveries'
---

# List webhook delivery attempts

`GET /v1/webhooks/{id}/deliveries`

Returns the attempts to deliver events to a webhook, newest first, with the total across all pages. A failed attempt explains why in `errorCategory` and `errorMessage`, and shows when it will be retried in `nextRetryAt`. Keys restricted to sub-accounts can't use this endpoint.

**Requires** `WEBHOOKS_READ`, granted by `WEBHOOKS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | Yes | Webhook ID: the `identifier` returned when the webhook was created. |
| skip | query | integer | No | Number of attempts to skip, for paging. |
| limit | query | integer | No | Maximum number of attempts to return, up to 100. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| items | WebhookDeliveryAttemptForDisplay\[] | Yes | Delivery attempts on this page, newest first. |
| total | integer (int32) | Yes | Number of attempts across all pages. |
| limit | integer (int32) | Yes | The `limit` used for this page. |
| offset | integer (int32) | Yes | The `skip` used for this page. |

**`items` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| eventId | string | Yes | Event ID. The same for every attempt to deliver an event, and sent in the `Valr-Webhook-Event-Id` header. |
| eventType | string | Yes | Event type, as sent in the `Valr-Webhook-Event-Type` header. |
| attemptNumber | integer (int32) | Yes | 1 for the first attempt, increasing by one with each retry. |
| responseStatus | integer (int32) | No | HTTP status your endpoint returned. Absent if no response was received. |
| errorCategory | string | No | Why the attempt failed: `TIMEOUT`, `CONNECTION_REFUSED`, `CONNECTION_RESET`, `DNS_FAILURE`, `TLS_FAILURE`, `NETWORK_UNREACHABLE`, `HTTP_STATUS`, `BLOCKED` or `UNKNOWN`. Absent if the attempt succeeded. |
| errorMessage | string | No | Readable explanation of `errorCategory`. |
| nextRetryAt | string | No | When the event will be retried, as an ISO 8601 timestamp in UTC. Absent if this attempt won't be retried. |
| terminalState | string | No | Set on the last attempt for an event: `SUCCESS`, `PERMANENT_FAILURE` (the failure isn't retried, for example a 4xx response) or `DEAD_LETTER` (every retry failed). Absent while delivery is still being retried. |
| createdAt | string | Yes | When the attempt was made, as an ISO 8601 timestamp in UTC. |

**Example:**

```json
{
  "items": [
    {
      "eventId": "6c2e9b41-3d7f-4a8e-b5c1-9f0a2d4e6b8c",
      "eventType": "FIAT_DEPOSIT_CREDITED",
      "attemptNumber": 2,
      "responseStatus": 200,
      "terminalState": "SUCCESS",
      "createdAt": "2026-10-23T08:16:04.108392Z"
    },
    {
      "eventId": "6c2e9b41-3d7f-4a8e-b5c1-9f0a2d4e6b8c",
      "eventType": "FIAT_DEPOSIT_CREDITED",
      "attemptNumber": 1,
      "errorCategory": "TIMEOUT",
      "errorMessage": "Your endpoint did not respond within the delivery timeout.",
      "nextRetryAt": "2026-10-23T08:16:03.512874Z",
      "createdAt": "2026-10-23T08:15:33.512874Z"
    }
  ],
  "total": 2,
  "limit": 100,
  "offset": 0
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/webhooks/{id}/deliveries'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/webhooks/{id}/deliveries"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The webhook ID isn't a valid UUID, `skip` or `limit` isn't an integer, or `limit` is more than 100. |
| 404 | `-18121` | `WEBHOOK_SUBSCRIPTION_NOT_FOUND` | No webhook with this ID exists for your business. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1WebhooksEventTypes.md
description: GET /v1/webhooks/event-types
---

# List webhook event types

`GET /v1/webhooks/event-types`

Lists the event types a webhook can subscribe to. Use the `name` values in `eventTypes` when you create or update a webhook.

**Requires** `WEBHOOKS_READ`, granted by `WEBHOOKS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Responses

### 200

OK

Array of objects:

| Property | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Value to use in a webhook's `eventTypes`. |
| displayName | string | Yes | Short readable label. |
| description | string | No | What triggers the event. Absent for some event types. |

**Example:**

```json
[
  {
    "name": "NEW_PENDING_RECEIVE",
    "displayName": "Crypto deposit received",
    "description": "A crypto deposit was seen on-chain and is pending confirmation."
  },
  {
    "name": "CRYPTO_DEPOSIT_CREDITED",
    "displayName": "Crypto deposit credited",
    "description": "A crypto deposit has been fully confirmed and credited to your balance."
  },
  {
    "name": "FIAT_WITHDRAWAL_STATUS_UPDATE",
    "displayName": "Fiat withdrawal status",
    "description": "A fiat withdrawal changed status."
  },
  {
    "name": "FIAT_DEPOSIT_CREDITED",
    "displayName": "Fiat deposit credited",
    "description": "A fiat bank deposit was credited to your account."
  }
]
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/webhooks/event-types'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/webhooks/event-types"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

Only the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV1Webhooks.md
description: GET /v1/webhooks
---

# List webhooks

`GET /v1/webhooks`

Returns your business's webhooks, newest first. Keys restricted to sub-accounts can't use this endpoint.

**Requires** `WEBHOOKS_READ`, granted by `WEBHOOKS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Responses

### 200

OK

Array of objects:

| Property | Type | Required | Description |
|---|---|---|---|
| identifier | string | Yes | Webhook ID. |
| scopeKind | string | Yes | What the webhook is attached to. Always `ENTITY` for webhooks managed with an institution key: the webhook receives events for every account in your business. |
| scopeLabel | string | Yes | Readable label for `scopeKind`. |
| url | string | Yes | URL events are delivered to. |
| eventTypes | string\[] | Yes | Event types delivered to this webhook. |
| active | boolean | Yes | Whether events are delivered. An inactive webhook receives nothing until it's reactivated. |
| description | string | No | Your label for the webhook. Absent if you didn't set one. |
| signingSecretFingerprint | string | Yes | First 8 hex characters of the SHA-256 hash of the signing secret, so you can check which secret the webhook uses. The secret itself is only returned when the webhook is created. |
| createdAt | string | Yes | When the webhook was created, as an ISO 8601 timestamp in UTC. |
| updatedAt | string | Yes | When the webhook was last changed, as an ISO 8601 timestamp in UTC. |

**Example:**

```json
[
  {
    "identifier": "0b8f5d2e-7a41-4c3b-9e6d-2f1a8c7b5e90",
    "scopeKind": "ENTITY",
    "scopeLabel": "Entity",
    "url": "https://hooks.example.com/valr",
    "eventTypes": [
      "FIAT_DEPOSIT_CREDITED",
      "FIAT_WITHDRAWAL_STATUS_UPDATE"
    ],
    "active": true,
    "description": "Treasury reconciliation",
    "signingSecretFingerprint": "7477002c",
    "createdAt": "2026-10-23T08:00:00.214367Z",
    "updatedAt": "2026-10-23T08:00:00.214367Z"
  },
  {
    "identifier": "9a4c7e1f-2b6d-4f8a-8c3e-5d7b9f1a3c6e",
    "scopeKind": "ENTITY",
    "scopeLabel": "Entity",
    "url": "https://ops.example.com/hooks/crypto",
    "eventTypes": [
      "CRYPTO_DEPOSIT_CREDITED",
      "SEND_STATUS_UPDATE"
    ],
    "active": false,
    "signingSecretFingerprint": "c19e04ab",
    "createdAt": "2026-10-01T13:42:07.581902Z",
    "updatedAt": "2026-10-20T09:05:44.017356Z"
  }
]
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v1/webhooks'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v1/webhooks"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

Only the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/getV2PaymentsBulkWithdrawalsWithdrawals.md
description: GET /v2/payments/bulk-withdrawals/withdrawals
---

# List withdrawals

`GET /v2/payments/bulk-withdrawals/withdrawals`

Returns withdrawals across all your batches, newest first, each with a summary of its batch.

**Requires** `DISBURSEMENTS_READ`, granted by `PAYMENTS_READ` or `DISBURSEMENTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| status | query | string | No | Only withdrawals with this status. |
| failureCode | query | string | No | Only failed withdrawals with this failure category. |
| beneficiaryId | query | string | No | Only withdrawals to this beneficiary. |
| limit | query | integer | No | Page size, from 1 to 200; values outside that range are clamped. |
| offset | query | integer | No | Number of items to skip. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| items | WithdrawalWithBatchForDisplay\[] | Yes | - |
| total | integer (int32) | Yes | - |
| limit | integer (int32) | Yes | - |
| offset | integer (int32) | Yes | - |
| truncated | boolean | Yes | - |

**`items` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | - |
| amount | string | Yes | - |
| bank | string | Yes | - |
| bankDisplayName | string | Yes | - |
| accountType | string | Yes | - |
| accountHolder | string | Yes | - |
| accountNumberMasked | string | Yes | - |
| accountNumber | string | Yes | - |
| branchCode | string | Yes | - |
| reference | string | Yes | - |
| linkedBankAccountId | string (uuid) | Yes | - |
| withdrawalId | string | Yes | - |
| status | string | Yes | Withdrawal status: `PENDING`, `APPROVED`, `EXECUTING`, `SUBMITTED`, `PROCESSING`, `PAID`, `FAILED` or `SKIPPED`. |
| failureReason | string | Yes | Why the withdrawal failed; `null` unless it failed. |
| failureReasonCode | string | Yes | Failure category, e.g. `INSUFFICIENT_FUNDS` or `REVERSED`; `null` unless it failed. |
| reversed | boolean | Yes | - |
| createdAt | string (date-time) | Yes | - |
| updatedAt | string (date-time) | Yes | - |
| batch | object | Yes | The batch the withdrawal belongs to. |

**`batch` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | - |
| label | string | Yes | - |
| status | string | Yes | - |
| uploadedBy | string | Yes | - |
| uploadedByName | object | Yes | - |
| approvedBy | string | Yes | - |
| approvedByName | object | Yes | - |

**`uploadedByName` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | - |
| surname | string | Yes | - |

**`approvedByName` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | - |
| surname | string | Yes | - |

**Example:**

```json
{
  "items": [
    {
      "id": "c4e8a2b6-3d5f-4a1c-9e7b-2f4d6a8c0e1b",
      "amount": "12500.75",
      "bank": "FNB",
      "bankDisplayName": "FNB/RMB",
      "accountType": "CHEQUE",
      "accountHolder": "Thandi Nkosi",
      "accountNumberMasked": "*******0327",
      "accountNumber": "62845190327",
      "branchCode": "250655",
      "reference": "OCT SALARY",
      "linkedBankAccountId": null,
      "withdrawalId": "0f3b5d7e-9a1c-4e2f-8b4d-6c8e0a2b4d6f",
      "status": "PAID",
      "failureReason": null,
      "failureReasonCode": null,
      "createdAt": "2026-10-23T08:15:01.912Z",
      "updatedAt": "2026-10-23T09:02:44.118Z",
      "batch": {
        "id": "5b9a3c1e-2f4d-4a7b-9c8e-1d2f3a4b5c6d",
        "label": "October salaries",
        "status": "COMPLETED",
        "uploadedBy": "8d2f4e6a-1b3c-4d5e-8f9a-0b1c2d3e4f5a",
        "uploadedByName": null,
        "approvedBy": "8d2f4e6a-1b3c-4d5e-8f9a-0b1c2d3e4f5a",
        "approvedByName": null
      }
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0,
  "truncated": null
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=GET
REQUEST_PATH='/v2/payments/bulk-withdrawals/withdrawals'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "GET"
path = "/v2/payments/bulk-withdrawals/withdrawals"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/postV2FiatPayments.md
description: POST /v2/fiat/payments
---

# Pay a bank beneficiary

`POST /v2/fiat/payments`

Pays a bank beneficiary from the account (the primary, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`) straight away, with no approval step: the one-call alternative to linking a bank account and then using Withdraw fiat to a bank account. Send `beneficiaryId` to pay a bank account already linked to that account, or `newBeneficiary` (the fields of Link a bank account) to link one and pay it in the same call; `currency` defaults to `ZAR`, the fee is charged on top of `amount`, and borrowing isn't available. The response holds the withdrawal's `id`; track it with Get a fiat withdrawal.

**Requires** `WITHDRAWALS_CREATE`, granted by `WITHDRAWALS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Request Body

**Content-Type:** `application/json`

| Property | Type | Required | Description |
|---|---|---|---|
| amount | string | Yes | - |
| currency | string | No | - |
| beneficiaryId | string | No | - |
| newBeneficiary | object | No | - |
| fast | boolean | No | - |
| reference | string | No | - |

**`newBeneficiary` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| bank | string | Yes | - |
| accountHolder | string | Yes | - |
| accountNumber | string | Yes | - |
| branchCode | string | Yes | - |
| suppliedBankCode | string | No | - |
| accountType | string | Yes | - |
| country | string | No | - |
| markForAutoPayout | boolean | No | - |
| tradingName | string | No | - |
| countryOfRegistration | string | No | - |

## Responses

### 202

Accepted

**Example:**

```json
{
  "id": "1f6c8a3e-5b2d-4e97-a0c4-8d3e6f1b9a57"
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=POST
REQUEST_PATH='/v2/fiat/payments'
BODY='{"amount":"<amount>","currency":"<currency>","beneficiaryId":"<beneficiaryId>","newBeneficiary":"<newBeneficiary>","fast":false,"reference":"<reference>"}'
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}" -H "Content-Type: application/json" --data "$BODY"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "POST"
path = "/v2/fiat/payments"
body = "{\"amount\":\"<amount>\",\"currency\":\"<currency>\",\"beneficiaryId\":\"<beneficiaryId>\",\"newBeneficiary\":\"<newBeneficiary>\",\"fast\":false,\"reference\":\"<reference>\"}"  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID
headers["Content-Type"] = "application/json"

response = requests.request(method, "https://api.valr.com" + path, headers=headers, data=body.encode())
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation, including a `newBeneficiary` field or a `newBeneficiary.bank` that isn't in the country's bank list, or `reference` was rejected; `validationErrors` lists each failing field. |
| 400 | `-109` | `INVALID_CURRENCY_SYMBOL` | `currency` isn't a recognised currency. |
| 400 | `-18104` | `PAYMENT_BENEFICIARY_DETAILS_REQUIRED` | Neither `beneficiaryId` nor `newBeneficiary` was sent. |
| 400 | `-115` | `INVALID_COUNTRY_ALPHA_2` | No banks are available for `newBeneficiary`'s country. |
| 400 | `-13418` | `BANK_ACCOUNT_LINKING_TEMPORARILY_DISABLED` | Adding a beneficiary is paused for a while after a security change on your account; the message says when it's re-enabled. You can still pay an existing beneficiary. |
| 400 | `-15875` | `FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED` | Payments to the beneficiary's branch code aren't supported. Use another bank account or contact support. |
| 400 | `-13415` | `WITHDRAWALS_TEMPORARILY_SUSPENDED` | Withdrawals are paused for a while after a security change on your account, such as a password reset or a new device; the message says when they're re-enabled. |
| 400 | `-32765` | `WITHDRAWAL_RESTRICTION_APPLIED` | The payment would take your portfolio below the minimum value it must keep. |
| 400 | `-15307` | `FIAT_WITHDRAWAL_AMOUNT_BELOW_MINIMUM` | `amount` is below the minimum withdrawal for this currency. |
| 400 | `-15318` | `FIAT_WITHDRAWAL_CURRENCY_MISMATCH` | The beneficiary's bank account was linked for a different currency from `currency`. |
| 400 | `-6` | `INSUFFICIENT_BALANCE` | The account's available balance doesn't cover `amount` plus the fee. |
| 400 | `-15309` | `CAN_NOT_WITHDRAW_TO_AN_UNVERIFIED_BANK_ACCOUNT` | This currency only pays out to verified bank accounts, and the beneficiary hasn't been verified yet or failed verification. |
| 404 | `-18106` | `PAYMENTS_API_DISABLED` | This endpoint isn't available yet. |
| 404 | `-14203` | `COULD_NOT_GET_LINKED_ACCOUNT` | No bank account with `beneficiaryId` exists. |
| 409 | `-18103` | `PAYMENT_BENEFICIARY_NOT_ACTIVE` | The beneficiary with `beneficiaryId` was never confirmed or has been deleted. |
| 451 | `-15320` | `FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY` | Your business's region doesn't allow withdrawals in this currency. |
| 500 | `-15317` | `BANK_REMOTE_FETCH_FAILURE` | The bank list for `newBeneficiary`'s country couldn't be loaded. Try again later. |
| 503 | `-12015` | `WITHDRAWALS_NOT_AVAILABLE` | Withdrawals are unavailable at the moment. Try again later. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/postV2CryptoPayments.md
description: POST /v2/crypto/payments
---

# Pay a crypto beneficiary

`POST /v2/crypto/payments`

Sends crypto from the account (the primary, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`) to an address-book beneficiary straight away, with no approval step. Send `beneficiaryId` for an active address-book entry on that account, or `newBeneficiary` to add one and pay it in the same call; the address, network and payment reference always come from the beneficiary, `currency` defaults to `BTC`, and the network's normal fee for `feePriority` is charged on top of `amount` (a `fee` in the body is ignored). The response holds the withdrawal's `id`; track it with `GET /v1/wallet/crypto/{currency}/withdraw/{id}`.

**Requires** `WITHDRAWALS_CREATE`, granted by `WITHDRAWALS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Request Body

**Content-Type:** `application/json`

| Property | Type | Required | Description |
|---|---|---|---|
| amount | string | Yes | - |
| currency | string | No | - |
| beneficiaryId | string | No | - |
| newBeneficiary | object | No | - |
| fee | string | No | - |
| feePriority | string | No | - |
| allowBorrow | boolean | No | - |

**`newBeneficiary` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| label | string | Yes | - |
| currency | string | No | - |
| address | string | Yes | - |
| paymentReference | string | Yes | - |
| networkType | string | Yes | - |
| beneficiaryName | string | No | - |
| isCorporate | boolean | No | - |
| isSelfHosted | boolean | No | - |
| serviceProviderName | string | No | - |
| serviceProviderId | string | No | - |

## Responses

### 202

Accepted

**Example:**

```json
{
  "id": "e8c41a7d-3f5b-4a92-8d6e-2b7f0c9a4e51"
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=POST
REQUEST_PATH='/v2/crypto/payments'
BODY='{"amount":"<amount>","currency":"<currency>","beneficiaryId":"<beneficiaryId>","newBeneficiary":"<newBeneficiary>","fee":"<fee>","feePriority":"<feePriority>","allowBorrow":false}'
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}" -H "Content-Type: application/json" --data "$BODY"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "POST"
path = "/v2/crypto/payments"
body = "{\"amount\":\"<amount>\",\"currency\":\"<currency>\",\"beneficiaryId\":\"<beneficiaryId>\",\"newBeneficiary\":\"<newBeneficiary>\",\"fee\":\"<fee>\",\"feePriority\":\"<feePriority>\",\"allowBorrow\":false}"  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID
headers["Content-Type"] = "application/json"

response = requests.request(method, "https://api.valr.com" + path, headers=headers, data=body.encode())
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation, including a `newBeneficiary` field or missing travel-rule details (`beneficiaryName`, `isCorporate`, `isSelfHosted`, and a service provider for a hosted wallet) for an address outside VALR; `validationErrors` lists each failing field. |
| 400 | `-109` | `INVALID_CURRENCY_SYMBOL` | `currency` isn't a recognised currency. |
| 400 | `-18104` | `PAYMENT_BENEFICIARY_DETAILS_REQUIRED` | Neither `beneficiaryId` nor `newBeneficiary` was sent. |
| 400 | `-13426` | `ADDRESS_BOOK_ENTRY_LABEL_IN_USE` | Another address-book entry on the account already uses `newBeneficiary.label`. |
| 400 | `-50` | `INVALID_WITHDRAW_ADDRESS` | The beneficiary's address isn't valid for this currency and network. |
| 400 | `-13410` | `PAYMENT_REFERENCE_MISSING` | The beneficiary's address needs a payment reference, such as a memo or tag. |
| 400 | `-13405` | `INVALID_WITHDRAW_TRANSACTION_REFERENCE` | The beneficiary's payment reference isn't valid for this address. |
| 400 | `-13402` | `CURRENCY_DOES_NOT_SUPPORT_PAYMENT_REFERENCE` | The beneficiary has a payment reference, but this currency and network don't use one. |
| 400 | `-13415` | `WITHDRAWALS_TEMPORARILY_SUSPENDED` | Withdrawals are paused for a while after a security change on your account, such as a password reset or a new device; the message says when they're re-enabled. |
| 400 | `-13411` | `WITHDRAW_AMOUNT_BELOW_MINIMUM` | `amount` is below the minimum withdrawal for this currency and network. |
| 400 | `-13404` | `INVALID_WITHDRAW_AMOUNT` | `amount` isn't valid for this currency and network, for example it has too many decimal places. |
| 400 | `-13419` | `NETWORK_FEE_FOR_TRANSACTION_EXCEEDED` | Withdrawals to the beneficiary's address aren't allowed because sending to it would cost too much in network fees. |
| 400 | `-6` | `INSUFFICIENT_BALANCE` | The account's available balance doesn't cover `amount` plus the network fee. |
| 400 | `-108` | `WITHDRAW_LIMIT_REACHED` | The payment would exceed your daily withdrawal limit. |
| 400 | `-32765` | `WITHDRAWAL_RESTRICTION_APPLIED` | The payment would take your portfolio below the minimum value it must keep. |
| 400 | `-19243` | `BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE` | `allowBorrow` was set, but borrowing for withdrawals is unavailable at the moment. |
| 400 | `-19244` | `BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY` | `allowBorrow` was set, but this currency can't be borrowed for a withdrawal. |
| 400 | `-19213` | `MARGIN_NOT_ENABLED_FOR_ACCOUNT` | `allowBorrow` was set, but margin isn't enabled on the account. |
| 400 | `-11533` | `CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING` | Borrowing the shortfall would exceed the account's borrow limit for this currency. |
| 400 | `-11534` | `ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING` | Borrowing the shortfall would exceed the account's total borrow limit. |
| 404 | `-18106` | `PAYMENTS_API_DISABLED` | This endpoint isn't available yet. |
| 404 | `-18101` | `PAYMENT_BENEFICIARY_NOT_FOUND` | No address-book entry with `beneficiaryId` exists on the account. |
| 409 | `-18103` | `PAYMENT_BENEFICIARY_NOT_ACTIVE` | The address-book entry with `beneficiaryId` hasn't been activated. |
| 500 | `-19502` | `CURRENCY_UNDER_MAINTENANCE` | Withdrawals of this currency are paused for maintenance. Try again in a few minutes. |
| 500 | `-46` | `WITHDRAW_UNAVAILABLE` | Withdrawals of this currency on this network are unavailable at the moment. Try again later. |
| 500 | `-19202` | `INSUFFICIENT_LIQUIDITY_FOR_BORROW` | `allowBorrow` was set, but the amount to borrow isn't available right now. Try again later. |
| 503 | `-12015` | `WITHDRAWALS_NOT_AVAILABLE` | Withdrawals are unavailable at the moment. Try again later. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api/payouts.md
description: >-
  Pay many bank beneficiaries in one batch from your payout account, and track
  every payout to completion.
---

# Payouts

Payouts (disbursements) pay many recipients by bank transfer in one request. You send a batch of ZAR payouts, each
with the recipient's bank details, amount and reference; VALR charges the batch fee and pays each recipient from your
business's payout account. Recipients are saved as beneficiaries, so you can manage and reuse their details.

## How a payout batch works

1. **Look up banks.** [List supported banks](/operations/getV2PaymentsBulkWithdrawalsBanks) gives the code to send for
   each recipient's bank.
2. **Check the cost.** [Quote fees for withdrawals](/operations/postV2PaymentsBulkWithdrawalsFeeQuote) returns the fee
   and `requiredTotal`, the available balance your payout account needs for the payouts plus the fee. Compare it with
   the `PAYOUT` balance from [Get payments account balances](/operations/getV2PaymentsAccountBalancesByType).
3. **Create the batch** with [Create a disbursement batch](/operations/postV2PaymentsBulkWithdrawalsBatches). A batch
   created with an API key is executed straight away: there's no separate approval step, the fee is charged and the
   payouts are submitted.
4. **Track it.** Get the batch for its status and totals, and list its withdrawals for each payout's status. Pass
   `updatedSince` to fetch only the payouts that changed since you last checked.
5. **Reconcile.** [List payout account transactions](/operations/getV2PaymentsPayoutHistory) shows each payout debit,
   each funding credit, and a credit for any payout the bank returned.

Talk to your VALR account manager about how your payout account is funded.

## Safe retries

The `X-VALR-Idempotency-Key` header is optional, but without it every request creates a new batch. Send a new key with
each batch. If a request times out or you aren't sure it arrived, send it again with the same key: you get the original
batch's ID back with status `200` instead of a second batch.

## Beneficiaries

Beneficiaries are the recipients you pay. Every recipient in a batch is saved as one automatically, and you can also
create, update and archive them yourself, one at a time or in bulk. Each bank and account number belongs to one
beneficiary: saving an archived recipient again restores it with its original ID.

## Before you start

* **API key:** the `DISBURSEMENTS_WRITE` bundle manages beneficiaries and creates batches. Because API-key batches
  execute immediately, it includes the `DISBURSEMENTS_APPROVE` permission. `PAYMENTS_READ` reads batches,
  beneficiaries and balances without changing anything.
* **Account:** payouts work on your business as a whole. Call these endpoints without `X-VALR-SUB-ACCOUNT-ID`, with a
  key that isn't limited to specific sub-accounts; otherwise they return `401` with code `-93`.
* **Formats:** amounts in responses are decimal strings, and batch and payout times are ISO 8601 date-times. Paged
  lists return `items`, `total`, `limit` and `offset`; page through them with `limit` and `offset`.

## Endpoints

### Disbursements

Batches of payouts to beneficiaries.

| Endpoint | Request | Needs |
|---|---|---|
| [Get a disbursement batch](/operations/getV2PaymentsBulkWithdrawalsBatchesById) | `GET /v2/payments/bulk-withdrawals/batches/{id}` | `DISBURSEMENTS_READ` |
| [List supported banks](/operations/getV2PaymentsBulkWithdrawalsBanks) | `GET /v2/payments/bulk-withdrawals/banks` | `DISBURSEMENTS_READ` |
| [List disbursement batches](/operations/getV2PaymentsBulkWithdrawalsBatches) | `GET /v2/payments/bulk-withdrawals/batches` | `DISBURSEMENTS_READ` |
| [Create a disbursement batch](/operations/postV2PaymentsBulkWithdrawalsBatches) | `POST /v2/payments/bulk-withdrawals/batches` | `DISBURSEMENTS_CREATE` and `DISBURSEMENTS_APPROVE` |
| [Cancel a disbursement batch](/operations/postV2PaymentsBulkWithdrawalsBatchesByIdCancel) | `POST /v2/payments/bulk-withdrawals/batches/{id}/cancel` | `DISBURSEMENTS_UPDATE` |
| [Get a batch's fee quote](/operations/getV2PaymentsBulkWithdrawalsBatchesByIdFeeQuote) | `GET /v2/payments/bulk-withdrawals/batches/{id}/fee-quote` | `DISBURSEMENTS_READ` |
| [Rename a disbursement batch](/operations/putV2PaymentsBulkWithdrawalsBatchesByIdLabel) | `PUT /v2/payments/bulk-withdrawals/batches/{id}/label` | `DISBURSEMENTS_UPDATE` |
| [List a batch's withdrawals](/operations/getV2PaymentsBulkWithdrawalsBatchesByIdWithdrawals) | `GET /v2/payments/bulk-withdrawals/batches/{id}/withdrawals` | `DISBURSEMENTS_READ` |
| [Quote fees for withdrawals](/operations/postV2PaymentsBulkWithdrawalsFeeQuote) | `POST /v2/payments/bulk-withdrawals/fee-quote` | `DISBURSEMENTS_READ` |
| [List withdrawals](/operations/getV2PaymentsBulkWithdrawalsWithdrawals) | `GET /v2/payments/bulk-withdrawals/withdrawals` | `DISBURSEMENTS_READ` |
| [List payout account transactions](/operations/getV2PaymentsPayoutHistory) | `GET /v2/payments/payout/history` | `DISBURSEMENTS_READ` |
| [Get a payout account transaction](/operations/getV2PaymentsPayoutHistoryById) | `GET /v2/payments/payout/history/{id}` | `DISBURSEMENTS_READ` |

### Beneficiaries

Recipients you pay out to. Recipients in each disbursement batch are also saved as beneficiaries automatically.

| Endpoint | Request | Needs |
|---|---|---|
| [List beneficiaries](/operations/getV2PaymentsBulkWithdrawalsBeneficiaries) | `GET /v2/payments/bulk-withdrawals/beneficiaries` | `DISBURSEMENTS_READ` |
| [Create a beneficiary](/operations/postV2PaymentsBulkWithdrawalsBeneficiaries) | `POST /v2/payments/bulk-withdrawals/beneficiaries` | `DISBURSEMENTS_CREATE` |
| [Archive a beneficiary](/operations/deleteV2PaymentsBulkWithdrawalsBeneficiariesById) | `DELETE /v2/payments/bulk-withdrawals/beneficiaries/{id}` | `DISBURSEMENTS_DELETE` |
| [Get a beneficiary](/operations/getV2PaymentsBulkWithdrawalsBeneficiariesById) | `GET /v2/payments/bulk-withdrawals/beneficiaries/{id}` | `DISBURSEMENTS_READ` |
| [Update a beneficiary](/operations/putV2PaymentsBulkWithdrawalsBeneficiariesById) | `PUT /v2/payments/bulk-withdrawals/beneficiaries/{id}` | `DISBURSEMENTS_UPDATE` |
| [Create beneficiaries in bulk](/operations/postV2PaymentsBulkWithdrawalsBeneficiariesBulk) | `POST /v2/payments/bulk-withdrawals/beneficiaries/bulk` | `DISBURSEMENTS_CREATE` |

### Payments balances

Balances of your business's payments accounts: payouts, collections, funding and amounts on hold.

| Endpoint | Request | Needs |
|---|---|---|
| [Get payments account balances](/operations/getV2PaymentsAccountBalancesByType) | `GET /v2/payments/account/balances/{type}` | `PAYMENTS_BALANCES_READ` |

---

---
url: /guides/performance.md
description: >-
  Avoiding polling, caching, and keeping your clock and connections in good
  shape
---

# Performance

## Use webhooks instead of polling

[Webhooks](/api/webhooks) notify your server when something happens on your accounts, such as a deposit being
credited or a withdrawal changing status. Polling for the same information uses up your
[rate limits](/guides/rate-limiting) and finds changes later. Deliveries can arrive more than once and out of order,
so treat a webhook as a signal and read the current state from the API before acting on anything important.

## Caching

Some `GET` responses are cached, and say for how long in a `Cache-Control` header, for example
`Cache-Control: max-age=30,public`. Requesting them more often returns the same data.

| Responses | Cached for up to |
|---|---|
| Public market summaries and price buckets | 5 seconds |
| Public currencies and currency pairs | 60 seconds |
| Banks you can link for a currency | 10 minutes |

## Keep your clock and connections in good shape

* Signed requests are rejected if their timestamp is too old. Keep your server's clock synchronised, and compare it
  with `GET /v1/public/time` if requests fail with a timestamp error.
* Reuse HTTPS connections rather than opening a new one for each request.

---

---
url: /guides/permissions.md
description: >-
  The permission bundles an institution API key can hold, and the endpoints each
  permission opens
---

# Permissions & bundles

An institution API key holds one or more **bundles**, chosen when the key is created. Each bundle grants a set of **permissions**, and each endpoint needs one permission. A key can call an endpoint if any of its bundles grants that permission. A key with no matching bundle gets `401` with code `-93`.

## Bundles

| Bundle | What it allows | Permissions |
|---|---|---|
| `PAYMENTS_READ` | Payments — read collections, disbursements and payments balances, including reads added later | `COLLECTIONS_READ`, `DISBURSEMENTS_READ`, `PAYMENTS_BALANCES_READ` |
| `COLLECTIONS_WRITE` | Collections — create, update and delete deposit references, and read collections | `COLLECTIONS_CREATE`, `COLLECTIONS_READ`, `COLLECTIONS_UPDATE`, `COLLECTIONS_DELETE`, `PAYMENTS_BALANCES_READ` |
| `DISBURSEMENTS_WRITE` | Disbursements — manage beneficiaries and batches, and create batches, which execute immediately | `DISBURSEMENTS_CREATE`, `DISBURSEMENTS_READ`, `DISBURSEMENTS_UPDATE`, `DISBURSEMENTS_DELETE`, `DISBURSEMENTS_APPROVE`, `PAYMENTS_BALANCES_READ` |
| `TRADING_READ` | Trading — read orders, balances and history | `TRADING_READ`, `ACCOUNT_BALANCES_READ`, `TRANSACTION_HISTORY_READ` |
| `TRADING_WRITE` | Trading — place, modify and cancel orders, convert, and read orders, balances and history | `TRADING_READ`, `TRADING_CREATE`, `CONVERT_CREATE`, `ACCOUNT_BALANCES_READ`, `TRANSACTION_HISTORY_READ` |
| `TREASURY_READ` | Treasury — read balances, history, deposit details, sub-accounts, withdrawals and VALR Pay payments | `ACCOUNT_BALANCES_READ`, `TRANSACTION_HISTORY_READ`, `DEPOSITS_READ`, `SUB_ACCOUNTS_READ`, `WITHDRAWALS_READ`, `PAY_READ` |
| `TREASURY_WRITE` | Treasury — everything in treasury read, plus manage sub-accounts and move funds between them | `ACCOUNT_BALANCES_READ`, `TRANSACTION_HISTORY_READ`, `DEPOSITS_READ`, `SUB_ACCOUNTS_READ`, `WITHDRAWALS_READ`, `PAY_READ`, `SUB_ACCOUNTS_MANAGE`, `TRANSFERS_CREATE` |
| `WITHDRAWALS_WRITE` | Withdrawals — send crypto and fiat, and read withdrawals and balances | `WITHDRAWALS_READ`, `WITHDRAWALS_CREATE`, `ACCOUNT_BALANCES_READ` |
| `BANK_ACCOUNTS_WRITE` | Bank accounts — link and remove bank accounts, and onboard and read virtual accounts | `BANK_ACCOUNTS_MANAGE`, `WITHDRAWALS_READ` |
| `WEBHOOKS_WRITE` | Webhooks — manage webhook subscriptions | `WEBHOOKS_READ`, `WEBHOOKS_MANAGE` |
| `VALR_PAY_WRITE` | VALR Pay — send and reverse payments, and read payment history and balances | `PAY_READ`, `PAY_SEND`, `ACCOUNT_BALANCES_READ` |

## Endpoints by permission

| Permission | Granted by | Endpoints |
|---|---|---|
| `ACCOUNT_BALANCES_READ` | `TRADING_READ`, `TRADING_WRITE`, `TREASURY_READ`, `TREASURY_WRITE`, `WITHDRAWALS_WRITE`, `VALR_PAY_WRITE` | [`GET /v1/account/balances`](/operations/getV1AccountBalances)[`GET /v1/account/balances/all`](/operations/getV1AccountBalancesAll) |
| `BANK_ACCOUNTS_MANAGE` | `BANK_ACCOUNTS_WRITE` | [`POST /v1/wallet/fiat/{currency}/accounts`](/operations/postV1WalletFiatByCurrencyAccounts)[`DELETE /v1/wallet/fiat/{currency}/accounts/{id}`](/operations/deleteV1WalletFiatByCurrencyAccountsById) |
| `COLLECTIONS_CREATE` | `COLLECTIONS_WRITE` | [`POST /v2/wallet/fiat/{currency}/payment/references`](/operations/postV2WalletFiatByCurrencyPaymentReferences)[`POST /v2/wallet/fiat/{currency}/payment/bulk-references`](/operations/postV2WalletFiatByCurrencyPaymentBulkReferences) |
| `COLLECTIONS_DELETE` | `COLLECTIONS_WRITE` | [`DELETE /v2/wallet/fiat/{currency}/payment/references/{referenceCode}`](/operations/deleteV2WalletFiatByCurrencyPaymentReferencesByReferenceCode)[`DELETE /v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference`](/operations/deleteV2WalletFiatByCurrencyPaymentDepositsByPublicIdReference) |
| `COLLECTIONS_READ` | `PAYMENTS_READ`, `COLLECTIONS_WRITE` | [`GET /v2/wallet/fiat/{currency}/payment/references/{referenceCode}`](/operations/getV2WalletFiatByCurrencyPaymentReferencesByReferenceCode)[`GET /v2/wallet/fiat/{currency}/payment/references`](/operations/getV2WalletFiatByCurrencyPaymentReferences)[`GET /v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}`](/operations/getV2WalletFiatByCurrencyPaymentBulkReferencesByJobId)[`GET /v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}/items`](/operations/getV2WalletFiatByCurrencyPaymentBulkReferencesByJobIdItems)[`GET /v2/wallet/fiat/{currency}/payment/deposits`](/operations/getV2WalletFiatByCurrencyPaymentDeposits)[`GET /v2/payments`](/operations/getV2Payments)[`GET /v2/payments/{id}`](/operations/getV2PaymentsById)[`GET /v2/payments/collect/events`](/operations/getV2PaymentsCollectEvents)[`GET /v2/payments/collect/events/{id}`](/operations/getV2PaymentsCollectEventsById)[`GET /v2/payments/collect/history`](/operations/getV2PaymentsCollectHistory)[`GET /v2/payments/collect/runs/{id}`](/operations/getV2PaymentsCollectRunsById)[`GET /v2/payments/collect/runs/{id}/payments`](/operations/getV2PaymentsCollectRunsByIdPayments)[`GET /v2/payments/collect/runs/history`](/operations/getV2PaymentsCollectRunsHistory)[`GET /v2/payments/collect/schedules`](/operations/getV2PaymentsCollectSchedules)[`GET /v2/payments/collect/settlements`](/operations/getV2PaymentsCollectSettlements)[`GET /v2/payments/collect/settlements/{id}`](/operations/getV2PaymentsCollectSettlementsById)[`GET /v2/payments/collect/settlements/{id}/payments`](/operations/getV2PaymentsCollectSettlementsByIdPayments)[`GET /v2/payments/collect/settlements/wallet`](/operations/getV2PaymentsCollectSettlementsWallet)[`GET /v2/payments/collect/upcoming`](/operations/getV2PaymentsCollectUpcoming)[`GET /v2/payments/collections/history`](/operations/getV2PaymentsCollectionsHistory) |
| `COLLECTIONS_UPDATE` | `COLLECTIONS_WRITE` | [`PUT /v2/wallet/fiat/{currency}/payment/references/{referenceCode}`](/operations/putV2WalletFiatByCurrencyPaymentReferencesByReferenceCode)[`PUT /v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference`](/operations/putV2WalletFiatByCurrencyPaymentDepositsByPublicIdReference) |
| `DEPOSITS_READ` | `TREASURY_READ`, `TREASURY_WRITE` | [`GET /v1/wallet/crypto/{currency}/deposit/address`](/operations/getV1WalletCryptoByCurrencyDepositAddress)[`GET /v1/wallet/crypto/{currency}/deposit/history`](/operations/getV1WalletCryptoByCurrencyDepositHistory)[`GET /v1/wallet/crypto/deposit/history`](/operations/getV1WalletCryptoDepositHistory)[`GET /v1/wallet/fiat/{currency}/deposit/reference`](/operations/getV1WalletFiatByCurrencyDepositReference)[`GET /v1/wallet/fiat/{currency}/deposit/reference/{buyCurrencySymbol}`](/operations/getV1WalletFiatByCurrencyDepositReferenceByBuyCurrencySymbol)[`GET /v1/wallet/fiat/{currency}/auto-buy`](/operations/getV1WalletFiatByCurrencyAutoBuy) |
| `DISBURSEMENTS_APPROVE` | `DISBURSEMENTS_WRITE` | [`POST /v2/payments/bulk-withdrawals/batches`](/operations/postV2PaymentsBulkWithdrawalsBatches) (also) |
| `DISBURSEMENTS_CREATE` | `DISBURSEMENTS_WRITE` | [`POST /v2/payments/bulk-withdrawals/batches`](/operations/postV2PaymentsBulkWithdrawalsBatches)[`POST /v2/payments/bulk-withdrawals/beneficiaries`](/operations/postV2PaymentsBulkWithdrawalsBeneficiaries)[`POST /v2/payments/bulk-withdrawals/beneficiaries/bulk`](/operations/postV2PaymentsBulkWithdrawalsBeneficiariesBulk) |
| `DISBURSEMENTS_DELETE` | `DISBURSEMENTS_WRITE` | [`DELETE /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/deleteV2PaymentsBulkWithdrawalsBeneficiariesById) |
| `DISBURSEMENTS_READ` | `PAYMENTS_READ`, `DISBURSEMENTS_WRITE` | [`GET /v2/payments/bulk-withdrawals/batches/{id}`](/operations/getV2PaymentsBulkWithdrawalsBatchesById)[`GET /v2/payments/bulk-withdrawals/banks`](/operations/getV2PaymentsBulkWithdrawalsBanks)[`GET /v2/payments/bulk-withdrawals/batches`](/operations/getV2PaymentsBulkWithdrawalsBatches)[`GET /v2/payments/bulk-withdrawals/batches/{id}/fee-quote`](/operations/getV2PaymentsBulkWithdrawalsBatchesByIdFeeQuote)[`GET /v2/payments/bulk-withdrawals/batches/{id}/withdrawals`](/operations/getV2PaymentsBulkWithdrawalsBatchesByIdWithdrawals)[`GET /v2/payments/bulk-withdrawals/beneficiaries`](/operations/getV2PaymentsBulkWithdrawalsBeneficiaries)[`GET /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/getV2PaymentsBulkWithdrawalsBeneficiariesById)[`POST /v2/payments/bulk-withdrawals/fee-quote`](/operations/postV2PaymentsBulkWithdrawalsFeeQuote)[`GET /v2/payments/bulk-withdrawals/withdrawals`](/operations/getV2PaymentsBulkWithdrawalsWithdrawals)[`GET /v2/payments/payout/history`](/operations/getV2PaymentsPayoutHistory)[`GET /v2/payments/payout/history/{id}`](/operations/getV2PaymentsPayoutHistoryById) |
| `DISBURSEMENTS_UPDATE` | `DISBURSEMENTS_WRITE` | [`POST /v2/payments/bulk-withdrawals/batches/{id}/cancel`](/operations/postV2PaymentsBulkWithdrawalsBatchesByIdCancel)[`PUT /v2/payments/bulk-withdrawals/batches/{id}/label`](/operations/putV2PaymentsBulkWithdrawalsBatchesByIdLabel)[`PUT /v2/payments/bulk-withdrawals/beneficiaries/{id}`](/operations/putV2PaymentsBulkWithdrawalsBeneficiariesById) |
| `PAYMENTS_BALANCES_READ` | `PAYMENTS_READ`, `COLLECTIONS_WRITE`, `DISBURSEMENTS_WRITE` | [`GET /v2/payments/account/balances/{type}`](/operations/getV2PaymentsAccountBalancesByType) |
| `SUB_ACCOUNTS_MANAGE` | `TREASURY_WRITE` | [`POST /v1/account/subaccount`](/operations/postV1AccountSubaccount)[`PUT /v1/account/subaccount`](/operations/putV1AccountSubaccount)[`DELETE /v1/account/subaccount`](/operations/deleteV1AccountSubaccount) |
| `SUB_ACCOUNTS_READ` | `TREASURY_READ`, `TREASURY_WRITE` | [`GET /v1/account/subaccounts`](/operations/getV1AccountSubaccounts)[`GET /v1/account/subaccount/{accountPublicId}`](/operations/getV1AccountSubaccountByAccountPublicId) |
| `TRANSACTION_HISTORY_READ` | `TRADING_READ`, `TRADING_WRITE`, `TREASURY_READ`, `TREASURY_WRITE` | [`GET /v1/account/transactionhistory`](/operations/getV1AccountTransactionhistory)[`GET /v1/account/transactionhistory/subaccounts`](/operations/getV1AccountTransactionhistorySubaccounts) |
| `TRANSFERS_CREATE` | `TREASURY_WRITE` | [`POST /v1/account/subaccounts/transfer`](/operations/postV1AccountSubaccountsTransfer) |
| `WEBHOOKS_MANAGE` | `WEBHOOKS_WRITE` | [`POST /v1/webhooks`](/operations/postV1Webhooks)[`DELETE /v1/webhooks/{id}`](/operations/deleteV1WebhooksById)[`PUT /v1/webhooks/{id}`](/operations/putV1WebhooksById) |
| `WEBHOOKS_READ` | `WEBHOOKS_WRITE` | [`GET /v1/webhooks`](/operations/getV1Webhooks)[`GET /v1/webhooks/{id}`](/operations/getV1WebhooksById)[`GET /v1/webhooks/{id}/deliveries`](/operations/getV1WebhooksByIdDeliveries)[`GET /v1/webhooks/{id}/events/{eventId}`](/operations/getV1WebhooksByIdEventsByEventId)[`GET /v1/webhooks/event-types`](/operations/getV1WebhooksEventTypes) |
| `WITHDRAWALS_CREATE` | `WITHDRAWALS_WRITE` | [`POST /v1/wallet/crypto/{currency}/withdraw`](/operations/postV1WalletCryptoByCurrencyWithdraw)[`POST /v1/wallet/fiat/{currency}/withdraw`](/operations/postV1WalletFiatByCurrencyWithdraw)[`POST /v2/fiat/payments`](/operations/postV2FiatPayments)[`POST /v2/crypto/payments`](/operations/postV2CryptoPayments) |
| `WITHDRAWALS_READ` | `TREASURY_READ`, `TREASURY_WRITE`, `WITHDRAWALS_WRITE`, `BANK_ACCOUNTS_WRITE` | [`GET /v1/wallet/crypto/{currency}/withdraw`](/operations/getV1WalletCryptoByCurrencyWithdraw)[`GET /v1/wallet/crypto/{currency}/withdraw/{id}`](/operations/getV1WalletCryptoByCurrencyWithdrawById)[`GET /v1/wallet/crypto/{currency}/withdraw/history`](/operations/getV1WalletCryptoByCurrencyWithdrawHistory)[`GET /v1/wallet/crypto/{currency}/withdraw/limits`](/operations/getV1WalletCryptoByCurrencyWithdrawLimits)[`GET /v1/wallet/crypto/address-book`](/operations/getV1WalletCryptoAddressBook)[`GET /v1/wallet/crypto/address-book/{currency}`](/operations/getV1WalletCryptoAddressBookByCurrency)[`GET /v1/wallet/crypto/service-providers`](/operations/getV1WalletCryptoServiceProviders)[`GET /v1/wallet/crypto/withdraw/history`](/operations/getV1WalletCryptoWithdrawHistory)[`GET /v1/wallet/fiat/{currency}/accounts`](/operations/getV1WalletFiatByCurrencyAccounts)[`GET /v1/wallet/fiat/{currency}/accounts/{id}`](/operations/getV1WalletFiatByCurrencyAccountsById)[`GET /v1/wallet/fiat/{currency}/banks`](/operations/getV1WalletFiatByCurrencyBanks)[`GET /v1/wallet/fiat/{currency}/withdraw/estimate-fee`](/operations/getV1WalletFiatByCurrencyWithdrawEstimateFee)[`GET /v1/wallet/fiat/{currency}/withdrawals`](/operations/getV1WalletFiatByCurrencyWithdrawals)[`GET /v1/wallet/fiat/{currency}/withdrawals/{id}`](/operations/getV1WalletFiatByCurrencyWithdrawalsById) |

---

---
url: /api/public-data.md
description: >-
  Exchange status, server time, currencies and pairs, and market prices, with no
  API key needed.
---

# Public data

Public endpoints return reference and market data that isn't tied to your business: whether the exchange is online,
its clock, the currencies and pairs it lists, and market summaries and price history. They take no API key, so send
them unsigned from anywhere.

## When to use them

* **Checking your clock:** signed requests are rejected if their timestamp is too old, so compare your server's clock
  with the server time if they start failing.
* **Monitoring:** the exchange status says whether VALR is accepting all requests or only reads.
* **Prices and charts:** market summaries for every pair and price buckets (candles).

## Limits and freshness

Public endpoints are [limited](/guides/rate-limiting) per IP address rather than per key, and their responses are
cached: up to 5 seconds for market summaries and price buckets, and up to a minute for currencies and pairs. Each
response's `Cache-Control` header says for how long.

## Endpoints

### Status and time

Whether VALR is accepting all requests, and the server's clock for checking your request timestamps. These endpoints are public, so no API key is needed.

| Endpoint | Request | Needs |
|---|---|---|
| [Get the server time](/operations/getV1PublicTime) | `GET /v1/public/time` | No API key |
| [Get the exchange status](/operations/getV1PublicStatus) | `GET /v1/public/status` | No API key |

### Currencies and pairs

The currencies and currency pairs VALR lists, with each pair's trading limits, the order types it accepts and its slippage limits. These endpoints are public, so no API key is needed.

| Endpoint | Request | Needs |
|---|---|---|
| [List currencies](/operations/getV1PublicCurrencies) | `GET /v1/public/currencies` | No API key |
| [List currency pairs](/operations/getV1PublicPairs) | `GET /v1/public/pairs` | No API key |
| [List currency pairs by type](/operations/getV1PublicPairsByType) | `GET /v1/public/pairs/{type}` | No API key |

### Market prices

Market summaries and price buckets for every currency pair, with no API key needed. Responses can be up to 5 seconds old.

| Endpoint | Request | Needs |
|---|---|---|
| [List market summaries](/operations/getV1PublicMarketsummary) | `GET /v1/public/marketsummary` | No API key |
| [Get a pair's market summary](/operations/getV1PublicByCurrencyPairMarketsummary) | `GET /v1/public/{currencyPair}/marketsummary` | No API key |
| [List price buckets](/operations/getV1PublicByCurrencyPairBuckets) | `GET /v1/public/{currencyPair}/buckets` | No API key |

---

---
url: /api-docs/postV2PaymentsBulkWithdrawalsFeeQuote.md
description: POST /v2/payments/bulk-withdrawals/fee-quote
---

# Quote fees for withdrawals

`POST /v2/payments/bulk-withdrawals/fee-quote`

Estimates the fee for a set of withdrawals before you create a batch, without saving anything. `requiredTotal` is the available balance your payout account needs for the payouts plus the fee.

**Requires** `DISBURSEMENTS_READ`, granted by `PAYMENTS_READ` or `DISBURSEMENTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Request Body

**Content-Type:** `application/json`

| Property | Type | Required | Description |
|---|---|---|---|
| withdrawals | FeeQuoteItemRequest\[] | Yes | - |

**`withdrawals` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| bank | string | Yes | Bank code, e.g. `FNB`. Decides whether the withdrawal is quoted as fast or regular. |
| amount | number | No | Amount in ZAR, greater than zero with at most two decimal places. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| fee | string | Yes | Fee as a decimal string. `null` means the fee is unknown, which isn't the same as no fee. |
| currency | string | Yes | - |
| withdrawalCount | integer (int32) | Yes | Number of withdrawals the fee covers. |
| grossTotal | string | Yes | Sum of those withdrawals' amounts. |
| requiredTotal | string | Yes | Gross total plus fee: the available balance your payout account needs. |
| feeGroups | DisbursementFeeGroupForDisplay\[] | Yes | Breakdown by fee type; `null` when the quote is the fee already charged. |

**`feeGroups` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| actionType | string | Yes | `FAST_WITHDRAWAL` for banks that take real-time payments, otherwise `REGULAR_WITHDRAWAL`. |
| withdrawalCount | integer (int32) | Yes | - |
| grossTotal | string | Yes | - |

**Example:**

```json
{
  "fee": "25.00",
  "currency": "ZAR",
  "withdrawalCount": 2,
  "grossTotal": "20501.00",
  "requiredTotal": "20526.00",
  "feeGroups": [
    {
      "actionType": "FAST_WITHDRAWAL",
      "withdrawalCount": 1,
      "grossTotal": "12500.75"
    },
    {
      "actionType": "REGULAR_WITHDRAWAL",
      "withdrawalCount": 1,
      "grossTotal": "8000.25"
    }
  ]
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=POST
REQUEST_PATH='/v2/payments/bulk-withdrawals/fee-quote'
BODY='{"withdrawals":"<withdrawals>"}'
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}" -H "Content-Type: application/json" --data "$BODY"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "POST"
path = "/v2/payments/bulk-withdrawals/fee-quote"
body = "{\"withdrawals\":\"<withdrawals>\"}"  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID
headers["Content-Type"] = "application/json"

response = requests.request(method, "https://api.valr.com" + path, headers=headers, data=body.encode())
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation; `validationErrors` lists each failing field. |
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /guides/rate-limiting.md
description: >-
  Request limits per API key and per IP address, and the routes with their own
  per-second limits
---

# Rate limits

## General limits

Two limits apply to every request at the same time:

| Limit | Requests |
|---|---|
| Per API key | 2,000 per minute |
| Per IP address | 1,200 per minute |

A request over either limit is rejected with `429 Too Many Requests`. Wait for the counter to reset before you send
more, and spread requests out rather than retrying straight away.

## When counters reset

Counters reset at the start of each minute, not a minute after your first request.

* If one IP address sends 1,200 requests between 12:00:00 and 12:00:30, further requests from it are rejected until
  12:01:00.
* If it sends 1,000 requests between 12:00:00 and 12:00:59, it can send another 1,200 from 12:01:00.

Spreading requests across several IP addresses doesn't raise a key's limit: a key can make 2,000 requests a minute in
total, whichever addresses they come from.

## Routes with their own limits

These routes have their own limit per IP address instead of the general limits above. Per-second limits reset at the
start of each second.

| Route | Method | Limit per IP address |
|---|---|---|
| `/v1/account/subaccount` | `POST` | 1 per second |
| `/v1/account/subaccounts/transfer` | `POST` | 20 per second |
| `/v1/public/time`, `/v1/public/status`, `/v1/public/{currencyPair}/buckets` | `GET` | 20 per second |
| Other `/v1/public` routes | `GET` | 30 per minute |

Public routes take no API key, so only the limit per IP address applies to them.

::: warning
We may lower limits temporarily when the platform is under severe load.
:::

## Staying within the limits

* Use [webhooks](/api/webhooks) to find out when something happens on your accounts, such as a deposit or a
  withdrawal, instead of polling.
* Fetch lists a page at a time with the largest page size an endpoint allows, and filter by time where you can.
* Cache responses for as long as their `Cache-Control` header allows. See [Performance](/guides/performance).

---

---
url: /api-docs/putV2PaymentsBulkWithdrawalsBatchesByIdLabel.md
description: 'PUT /v2/payments/bulk-withdrawals/batches/{id}/label'
---

# Rename a disbursement batch

`PUT /v2/payments/bulk-withdrawals/batches/{id}/label`

Changes a batch's label.

**Requires** `DISBURSEMENTS_UPDATE`, granted by `DISBURSEMENTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | Yes | Batch ID. |

## Request Body

**Content-Type:** `application/json`

| Property | Type | Required | Description |
|---|---|---|---|
| label | string | Yes | New label, up to 64 characters. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | - |
| label | string | Yes | - |
| currency | string | Yes | - |
| totalAmount | string | Yes | Sum of the withdrawal amounts, as a decimal string. |
| withdrawalCount | integer (int32) | Yes | - |
| status | string | Yes | Batch status: `PENDING_APPROVAL`, `APPROVED`, `PROCESSING`, `COMPLETED`, `PARTIALLY_COMPLETED`, `FAILED` or `CANCELLED`. |
| uploadedBy | string | Yes | ID of the user or API key that created the batch. |
| uploadedByName | object | Yes | - |
| approvedBy | string | Yes | ID of the user or API key that approved the batch (for a batch created with an API key, that key); `null` until approved. |
| approvedByName | object | Yes | - |
| approvedAt | string (date-time) | Yes | - |
| createdAt | string (date-time) | Yes | - |
| updatedAt | string (date-time) | Yes | - |
| completedAt | string (date-time) | Yes | - |
| feeQuote | object | Yes | Fee for the batch's pending withdrawals, or the fee charged once none are pending. Only returned by `GET /v2/payments/bulk-withdrawals/batches/{id}`; `null` elsewhere, and when the fee can't be quoted. |

**`uploadedByName` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | - |
| surname | string | Yes | - |

**`approvedByName` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | - |
| surname | string | Yes | - |

**`feeQuote` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| fee | string | Yes | Fee as a decimal string. `null` means the fee is unknown, which isn't the same as no fee. |
| currency | string | Yes | - |
| withdrawalCount | integer (int32) | Yes | Number of withdrawals the fee covers. |
| grossTotal | string | Yes | Sum of those withdrawals' amounts. |
| requiredTotal | string | Yes | Gross total plus fee: the available balance your payout account needs. |
| feeGroups | DisbursementFeeGroupForDisplay\[] | Yes | Breakdown by fee type; `null` when the quote is the fee already charged. |

**`feeGroups` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| actionType | string | Yes | `FAST_WITHDRAWAL` for banks that take real-time payments, otherwise `REGULAR_WITHDRAWAL`. |
| withdrawalCount | integer (int32) | Yes | - |
| grossTotal | string | Yes | - |

**Example:**

```json
{
  "id": "7c1e9a3b-5d2f-4b6a-8e0c-2a4b6c8d0e1f",
  "label": "November rent (final)",
  "currency": "ZAR",
  "totalAmount": "45000.00",
  "withdrawalCount": 3,
  "status": "PENDING_APPROVAL",
  "uploadedBy": "2e4a6c8e-0b1d-4f3a-9c5e-7a9b1d3f5a7c",
  "uploadedByName": {
    "name": "Lerato",
    "surname": "Mokoena"
  },
  "approvedBy": null,
  "approvedByName": null,
  "approvedAt": null,
  "createdAt": "2026-10-22T14:03:11.250Z",
  "updatedAt": "2026-10-23T08:32:05.118Z",
  "completedAt": null,
  "feeQuote": null
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=PUT
REQUEST_PATH='/v2/payments/bulk-withdrawals/batches/{id}/label'
BODY='{"label":"<label>"}'
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}" -H "Content-Type: application/json" --data "$BODY"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "PUT"
path = "/v2/payments/bulk-withdrawals/batches/{id}/label"
body = "{\"label\":\"<label>\"}"  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID
headers["Content-Type"] = "application/json"

response = requests.request(method, "https://api.valr.com" + path, headers=headers, data=body.encode())
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation; `validationErrors` lists each failing field. |
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No batch with this ID exists on your account. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/putV1AccountSubaccount.md
description: PUT /v1/account/subaccount
---

# Rename a sub-account

`PUT /v1/account/subaccount`

Changes a sub-account's name and responds with 202 and no body. Call it on your primary account (don't send `X-VALR-SUB-ACCOUNT-ID`); keys limited to some sub-accounts can't use it.

**Requires** `SUB_ACCOUNTS_MANAGE`, granted by `TREASURY_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| isProprietarySubAccount | query | boolean | No | Only matters if VALR has made KYC details mandatory for your sub-accounts: then `true` changes just the name, and with `false` the body must also include the account holder's KYC details. |

## Request Body

**Content-Type:** `application/json`

| Property | Type | Required | Description |
|---|---|---|---|
| id | integer (int64) | Yes | ID of the sub-account to rename. You can also send it as a string, which avoids losing precision in languages whose numbers are 64-bit floats. |
| label | string | Yes | New name, under the same rules as when creating a sub-account. Sending the current name changes nothing. |

## Responses

### 202

Accepted

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=PUT
REQUEST_PATH='/v1/account/subaccount'
BODY='{"id":0,"label":"<label>"}'
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}" -H "Content-Type: application/json" --data "$BODY"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "PUT"
path = "/v1/account/subaccount"
body = "{\"id\":0,\"label\":\"<label>\"}"  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID
headers["Content-Type"] = "application/json"

response = requests.request(method, "https://api.valr.com" + path, headers=headers, data=body.encode())
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation (`validationErrors` lists each failing field), or `isProprietarySubAccount` isn't `true` or `false`. |
| 400 | `-11134` | `SUB_ACCOUNT_NOT_FOUND` | None of your business's sub-accounts has this `id`. |
| 403 | `-11132` | `SUB_ACCOUNT_ALREADY_EXISTS` | Another of your sub-accounts already has this name (ignoring case), or the name is `Primary` or `Main`. |
| 409 | `-11423` | `SUB_ACCOUNT_PROFILE_INFO_ALREADY_EXISTS` | Only when KYC details are mandatory for your sub-accounts: another of your sub-accounts already has this email address, ID number or cell number. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/postV1AccountSubaccountsTransfer.md
description: POST /v1/account/subaccounts/transfer
---

# Transfer between accounts

`POST /v1/account/subaccounts/transfer`

Moves funds between two of your accounts: your primary account (`0`) and its sub-accounts. Called on your primary account it can move funds between any of them; called on a sub-account (with `X-VALR-SUB-ACCOUNT-ID`) it can only move funds out of that sub-account. A key limited to some sub-accounts can only move funds between those sub-accounts. The transfer is processed asynchronously: the 202 response means it was accepted, so check balances or transaction history to confirm it completed. The returned `id` appears as `additionalInfo.transferId` on the resulting `INTERNAL_TRANSFER` transactions.

**Requires** `TRANSFERS_CREATE`, granted by `TREASURY_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Request Body

**Content-Type:** `application/json`

| Property | Type | Required | Description |
|---|---|---|---|
| fromId | integer (int64) | Yes | ID of the account to transfer from: `0` for your primary account, or a sub-account's `id`. You can also send it as a string. |
| toId | integer (int64) | Yes | ID of the account to transfer to, in the same form as `fromId`. |
| currencyCode | string | Yes | Currency to transfer, in upper case, e.g. `USDC`. |
| amount | string | Yes | Amount to transfer, as a decimal string greater than zero of up to 32 characters. |
| allowBorrow | boolean | Yes | `true` to borrow any shortfall against the source account's collateral, if that account is enabled for margin. Defaults to `false` if left out. |

## Responses

### 202

Accepted. The body holds the transfer's ID as a string in `id`.

**Example:**

```json
{
  "id": "512874"
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=POST
REQUEST_PATH='/v1/account/subaccounts/transfer'
BODY='{"fromId":0,"toId":0,"currencyCode":"<currencyCode>","amount":"<amount>","allowBorrow":false}'
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}" -H "Content-Type: application/json" --data "$BODY"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "POST"
path = "/v1/account/subaccounts/transfer"
body = "{\"fromId\":0,\"toId\":0,\"currencyCode\":\"<currencyCode>\",\"amount\":\"<amount>\",\"allowBorrow\":false}"  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID
headers["Content-Type"] = "application/json"

response = requests.request(method, "https://api.valr.com" + path, headers=headers, data=body.encode())
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation; `validationErrors` lists each failing field. |
| 400 | `-109` | `INVALID_CURRENCY_SYMBOL` | `currencyCode` isn't a currency VALR supports. |
| 400 | `-19213` | `MARGIN_NOT_ENABLED_FOR_ACCOUNT` | `allowBorrow` is `true`, but the source account isn't enabled for margin. |
| 400 | `-6` | `INSUFFICIENT_BALANCE` | `allowBorrow` is `true`, but the source account doesn't have enough collateral to borrow the shortfall. |
| 400 | `-19243` | `BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE` | Borrowing for transfers is temporarily unavailable. Transfer no more than the available balance, or try again later. |
| 400 | `-19244` | `BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY` | This currency can't be borrowed for a transfer. |
| 400 | `-11533` | `CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING` | Borrowing the shortfall would take the source account past its borrow limit for this currency. |
| 400 | `-11534` | `ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING` | Borrowing the shortfall would take the source account past its total borrow limit. |
| 403 | `-11133` | `SUB_ACCOUNT_INTERNAL_TRANSFER_NOT_ALLOWED` | The transfer was refused, and the message says why: `fromId` and `toId` are the same, one of them isn't an account in your business, the source account doesn't have enough available balance and `allowBorrow` is `false`, you called it on a sub-account and `fromId` isn't that sub-account, or your key is limited to sub-accounts and one of the accounts isn't among them. |
| 500 | `-19202` | `INSUFFICIENT_LIQUIDITY_FOR_BORROW` | Not enough of this currency is available to borrow right now. Try again later. |
| 500 | `-19502` | `CURRENCY_UNDER_MAINTENANCE` | The currency is under maintenance. Try again in a few minutes. |
| 503 | `-11652` | `INTERNAL_TRANSFERS_NOT_AVAILABLE` | Transfers between accounts are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/deleteV2WalletFiatByCurrencyPaymentDepositsByPublicIdReference.md
description: 'DELETE /v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference'
---

# Unlink a deposit from its reference

`DELETE /v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference`

Removes the link between a deposit and its reference. The deposit stays credited, but no longer counts as a matched deposit for any reference.

**Requires** `COLLECTIONS_DELETE`, granted by `COLLECTIONS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Fiat currency of the deposits, e.g. `ZAR`. |
| publicId | path | string | Yes | The deposit's `publicId`. |

## Responses

### 204

No content

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=DELETE
REQUEST_PATH='/v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference'
BODY=''
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "DELETE"
path = "/v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference"
body = ""  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID

response = requests.request(method, "https://api.valr.com" + path, headers=headers)
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-11` | `INVALID_REQUEST` | The deposit ID isn't a valid UUID. |
| 404 | `-15118` | `FIAT_DEPOSIT_NOT_FOUND` | No deposit with this ID exists on your collections account. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/putV2PaymentsBulkWithdrawalsBeneficiariesById.md
description: 'PUT /v2/payments/bulk-withdrawals/beneficiaries/{id}'
---

# Update a beneficiary

`PUT /v2/payments/bulk-withdrawals/beneficiaries/{id}`

Replaces every field of an active beneficiary; optional fields you leave out are cleared. Changing the bank or account number fails if another beneficiary, including an archived one, already has them.

**Requires** `DISBURSEMENTS_UPDATE`, granted by `DISBURSEMENTS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | Yes | Beneficiary ID. |

## Request Body

**Content-Type:** `application/json`

| Property | Type | Required | Description |
|---|---|---|---|
| bank | string | Yes | Bank code from `GET /v2/payments/bulk-withdrawals/banks`, e.g. `FNB`. Case-insensitive. |
| accountHolder | string | No | - |
| accountNumber | string | No | - |
| branchCode | string | No | - |
| accountType | string | No | Account type: `CHEQUE`, `SAVINGS`, `BOND` or `TRANSMISSION`. Case-insensitive. |
| type | string | No | `INDIVIDUAL` or `BUSINESS`. Case-insensitive. |
| email | string | No | - |
| tradingName | string | No | - |
| reference | string | No | Default payment reference for this beneficiary. It isn't applied to payouts automatically: send it as the withdrawal's `reference`. |
| country | string | No | Country of registration as an ISO 3166 alpha-2 code, e.g. `ZA`. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | - |
| bank | string | Yes | - |
| bankDisplayName | string | Yes | - |
| accountHolder | string | Yes | - |
| accountNumberMasked | string | Yes | Account number with all but the last four digits masked. |
| accountNumber | string | Yes | - |
| branchCode | string | Yes | - |
| accountType | string | Yes | - |
| email | string | Yes | - |
| type | string | Yes | `INDIVIDUAL`, `BUSINESS`, or `null` if never set, which is possible for beneficiaries saved from a batch. |
| tradingName | string | Yes | - |
| reference | string | Yes | Default payment reference for this beneficiary. It isn't applied to payouts automatically. |
| country | string | Yes | - |
| createdAt | string (date-time) | Yes | - |
| updatedAt | string (date-time) | Yes | - |
| lastPaidAt | string (date-time) | Yes | When a payout to this beneficiary was last attempted; `null` if never. |
| deletedAt | string (date-time) | Yes | When the beneficiary was archived; `null` if it's active. |
| deletedBy | string | Yes | ID of the user or API key that archived the beneficiary. |

**Example:**

```json
{
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "bank": "FNB",
  "bankDisplayName": "FNB/RMB",
  "accountHolder": "Thandi Nkosi",
  "accountNumberMasked": "*******0327",
  "accountNumber": "62845190327",
  "branchCode": "250655",
  "accountType": "SAVINGS",
  "email": "thandi.nkosi@example.com",
  "type": "INDIVIDUAL",
  "tradingName": null,
  "reference": "SALARY",
  "country": "ZA",
  "createdAt": "2026-09-01T10:12:30.004Z",
  "updatedAt": "2026-10-23T11:05:48.902Z",
  "lastPaidAt": null,
  "deletedAt": null,
  "deletedBy": null
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=PUT
REQUEST_PATH='/v2/payments/bulk-withdrawals/beneficiaries/{id}'
BODY='{"bank":"<bank>","accountHolder":"<accountHolder>","accountNumber":"<accountNumber>","branchCode":"<branchCode>","accountType":"<accountType>","type":"<type>","email":"<email>","tradingName":"<tradingName>","reference":"<reference>","country":"<country>"}'
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}" -H "Content-Type: application/json" --data "$BODY"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "PUT"
path = "/v2/payments/bulk-withdrawals/beneficiaries/{id}"
body = "{\"bank\":\"<bank>\",\"accountHolder\":\"<accountHolder>\",\"accountNumber\":\"<accountNumber>\",\"branchCode\":\"<branchCode>\",\"accountType\":\"<accountType>\",\"type\":\"<type>\",\"email\":\"<email>\",\"tradingName\":\"<tradingName>\",\"reference\":\"<reference>\",\"country\":\"<country>\"}"  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID
headers["Content-Type"] = "application/json"

response = requests.request(method, "https://api.valr.com" + path, headers=headers, data=body.encode())
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation; `validationErrors` lists each failing field. |
| 400 | `BAD_REQUEST` | `BAD_REQUEST` | A query parameter or field is invalid. |
| 403 | `-16098` | `PAYMENTS_USER_ACCESS_NOT_CONFIGURED` | Payments haven't been set up for your business yet. |
| 404 | `NOT_FOUND` | `NOT_FOUND` | No active beneficiary with this ID exists on your account; archived beneficiaries can't be updated. |
| 409 | `CONFLICT` | `CONFLICT` | Another beneficiary, active or archived, already has this bank and account number. |
| 500 | `INTERNAL_ERROR` | `INTERNAL_ERROR` | Unexpected error in the payments service. |
| 502 | `-16097` | `EXCHANGE_API_ERROR` | The payments service failed to process the request. |
| 502 | `EXCHANGE_API_ERROR` | `EXCHANGE_API_ERROR` | The payments service couldn't complete the request. Try again later. |
| 503 | `-16099` | `PAYMENTS_BACKEND_PROXY_DISABLED` | Payments endpoints are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/putV2WalletFiatByCurrencyPaymentReferencesByReferenceCode.md
description: 'PUT /v2/wallet/fiat/{currency}/payment/references/{referenceCode}'
---

# Update a deposit reference

`PUT /v2/wallet/fiat/{currency}/payment/references/{referenceCode}`

Updates the expected amount, payer name or payer email of a deposit reference; fields you leave out keep their current values. The response includes `matchedDepositCount` but not the matched deposits themselves.

**Requires** `COLLECTIONS_UPDATE`, granted by `COLLECTIONS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Fiat currency of the reference, e.g. `ZAR`. |
| referenceCode | path | string | Yes | The reference code returned when the reference was created. |

## Request Body

**Content-Type:** `application/json`

| Property | Type | Required | Description |
|---|---|---|---|
| expectedAmount | string | No | Amount you expect the payer to deposit, as a decimal string greater than zero. |
| name | string | No | Payer's name. |
| email | string | No | Payer's email address. |

## Responses

### 200

OK

| Property | Type | Required | Description |
|---|---|---|---|
| referenceCode | string | Yes | The reference your payer quotes when depositing. |
| currency | string | Yes | - |
| expectedAmount | string | No | - |
| createdAt | integer (int64) | Yes | When the reference was created, in Unix milliseconds. |
| name | string | No | - |
| email | string | No | - |
| matchedDeposits | UserMatchedDepositInfo\[] | Yes | Deposits matched to this reference. |
| matchedDepositCount | integer (int32) | Yes | - |

**`matchedDeposits` properties:**

| Property | Type | Required | Description |
|---|---|---|---|
| publicId | string (uuid) | Yes | - |
| amount | string | Yes | - |
| effectiveDate | string | Yes | - |
| creditedAt | integer (int64) | Yes | - |
| isOverride | boolean | Yes | `true` if this deposit is set as the reference's override deposit. |

**Example:**

```json
{
  "referenceCode": "VPAY-7K2Q9RT",
  "currency": "ZAR",
  "expectedAmount": "2000",
  "createdAt": 1792742400000,
  "name": "Thandi Nkosi",
  "email": "thandi.nkosi@example.com",
  "matchedDeposits": [],
  "matchedDepositCount": 1
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=PUT
REQUEST_PATH='/v2/wallet/fiat/{currency}/payment/references/{referenceCode}'
BODY='{"expectedAmount":"<expectedAmount>","name":"<name>","email":"<email>"}'
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}" -H "Content-Type: application/json" --data "$BODY"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "PUT"
path = "/v2/wallet/fiat/{currency}/payment/references/{referenceCode}"
body = "{\"expectedAmount\":\"<expectedAmount>\",\"name\":\"<name>\",\"email\":\"<email>\"}"  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID
headers["Content-Type"] = "application/json"

response = requests.request(method, "https://api.valr.com" + path, headers=headers, data=body.encode())
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation; `validationErrors` lists each failing field. |
| 404 | `-15114` | `UNIQUE_DEPOSIT_REFERENCE_NOT_FOUND` | No reference with this code exists on your account. |
| 503 | `-15117` | `UNIQUE_DEPOSIT_REFERENCES_FEATURE_DISABLED` | Deposit references are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/putV1WebhooksById.md
description: 'PUT /v1/webhooks/{id}'
---

# Update a webhook

`PUT /v1/webhooks/{id}`

Changes a webhook's URL, event types, description or active state; fields you leave out keep their current values, and the signing secret doesn't change. Set `active` to `false` to pause deliveries without deleting the webhook. A key restricted to sub-accounts can't manage webhooks.

**Requires** `WEBHOOKS_MANAGE`, granted by `WEBHOOKS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | Yes | Webhook ID: the `identifier` returned when the webhook was created. |

## Request Body

**Content-Type:** `application/json`

| Property | Type | Required | Description |
|---|---|---|---|
| url | string | No | New HTTPS URL, under the same rules as when creating a webhook. Leave out to keep the current URL. |
| eventTypes | string\[] | No | Replaces the webhook's event types, from 1 to 20 `name` values. Leave out to keep the current ones. |
| active | boolean | No | `false` pauses deliveries and `true` resumes them. Leave out to keep the current state. |
| description | string | No | New label for the webhook, up to 256 characters of letters, digits, spaces and punctuation. Leave out to keep the current one. |

## Responses

### 200

OK

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=PUT
REQUEST_PATH='/v1/webhooks/{id}'
BODY='{"url":"<url>","eventTypes":"<eventTypes>","active":false,"description":"<description>"}'
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}" -H "Content-Type: application/json" --data "$BODY"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "PUT"
path = "/v1/webhooks/{id}"
body = "{\"url\":\"<url>\",\"eventTypes\":\"<eventTypes>\",\"active\":false,\"description\":\"<description>\"}"  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID
headers["Content-Type"] = "application/json"

response = requests.request(method, "https://api.valr.com" + path, headers=headers, data=body.encode())
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation; `validationErrors` lists each failing field. |
| 404 | `-18121` | `WEBHOOK_SUBSCRIPTION_NOT_FOUND` | No webhook with this ID exists for your business. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api/wallets.md
description: >-
  Receive and send crypto and fiat, manage saved crypto addresses and linked
  bank accounts, and track every deposit and withdrawal.
---

# Wallets

Wallets cover money coming into and going out of your accounts: crypto deposit addresses and withdrawals, bank
deposits and withdrawals, and the saved addresses and bank accounts you send to. Each account, primary or
sub-account, has its own deposit addresses, deposit reference, address book and linked bank accounts, so select the
account with `X-VALR-SUB-ACCOUNT-ID` as described in [Account](/api/account).

## Receiving funds

* **Crypto:** [Get a crypto deposit address](/operations/getV1WalletCryptoByCurrencyDepositAddress) returns the
  account's address for a currency on one network, creating it the first time.
* **Fiat:** [Get the account deposit reference](/operations/getV1WalletFiatByCurrencyDepositReference) returns the
  reference to quote on a bank transfer so it's credited to that account. An auto-buy reference also uses the deposit
  to buy another currency.

## Sending funds

Withdrawals are sent straight away, with no further confirmation, and any fee is charged on top of the amount. Each
has an ID to follow it by.

* **Crypto** to an address, or to an entry in the account's address book. If your business only allows withdrawals to
  address-book entries, the address must already be saved there and past its waiting period.
* **Fiat** to a bank account linked to the same account. To link a new bank account and pay it in one call, use
  [Pay a bank beneficiary](/operations/postV2FiatPayments); [Pay a crypto beneficiary](/operations/postV2CryptoPayments)
  does the same for an address-book entry.

Check a currency's withdrawal settings and your limits before you send, and estimate fiat withdrawal fees with the
fee estimate.

## Following deposits and withdrawals

Subscribe a [webhook](/api/webhooks) to `CRYPTO_DEPOSIT_CREDITED`, `FIAT_DEPOSIT_CREDITED`, `SEND_STATUS_UPDATE` and
`FIAT_WITHDRAWAL_STATUS_UPDATE` to hear about changes as they happen, or read the deposit and withdrawal history.

## Before you start

| Bundle | Allows |
|---|---|
| `TREASURY_READ` | Read deposit details, withdrawals and balances |
| `WITHDRAWALS_WRITE` | Send crypto and fiat, and read withdrawals and balances |
| `BANK_ACCOUNTS_WRITE` | Link and remove bank accounts |

## Endpoints

### Crypto deposits

Deposit addresses for receiving crypto, and the history of crypto deposits to your accounts.

| Endpoint | Request | Needs |
|---|---|---|
| [Get a crypto deposit address](/operations/getV1WalletCryptoByCurrencyDepositAddress) | `GET /v1/wallet/crypto/{currency}/deposit/address` | `DEPOSITS_READ` |
| [List crypto deposits for a currency](/operations/getV1WalletCryptoByCurrencyDepositHistory) | `GET /v1/wallet/crypto/{currency}/deposit/history` | `DEPOSITS_READ` |
| [List crypto deposits](/operations/getV1WalletCryptoDepositHistory) | `GET /v1/wallet/crypto/deposit/history` | `DEPOSITS_READ` |

### Crypto withdrawals

Send crypto to an address or a saved address-book entry, check a currency's withdrawal settings and your limits, and follow each withdrawal's progress. Withdrawals to an address hosted by another provider need the recipient's details.

| Endpoint | Request | Needs |
|---|---|---|
| [Get crypto withdrawal settings](/operations/getV1WalletCryptoByCurrencyWithdraw) | `GET /v1/wallet/crypto/{currency}/withdraw` | `WITHDRAWALS_READ` |
| [Withdraw crypto](/operations/postV1WalletCryptoByCurrencyWithdraw) | `POST /v1/wallet/crypto/{currency}/withdraw` | `WITHDRAWALS_CREATE` |
| [Get a crypto withdrawal](/operations/getV1WalletCryptoByCurrencyWithdrawById) | `GET /v1/wallet/crypto/{currency}/withdraw/{id}` | `WITHDRAWALS_READ` |
| [List crypto withdrawals for a currency](/operations/getV1WalletCryptoByCurrencyWithdrawHistory) | `GET /v1/wallet/crypto/{currency}/withdraw/history` | `WITHDRAWALS_READ` |
| [Get crypto withdrawal limits](/operations/getV1WalletCryptoByCurrencyWithdrawLimits) | `GET /v1/wallet/crypto/{currency}/withdraw/limits` | `WITHDRAWALS_READ` |
| [List service providers](/operations/getV1WalletCryptoServiceProviders) | `GET /v1/wallet/crypto/service-providers` | `WITHDRAWALS_READ` |
| [List crypto withdrawals](/operations/getV1WalletCryptoWithdrawHistory) | `GET /v1/wallet/crypto/withdraw/history` | `WITHDRAWALS_READ` |
| [Pay a crypto beneficiary](/operations/postV2CryptoPayments) | `POST /v2/crypto/payments` | `WITHDRAWALS_CREATE` |

### Address book

Saved withdrawal addresses, with the recipient's details where they've been added. Your business can require crypto withdrawals to go only to these addresses.

| Endpoint | Request | Needs |
|---|---|---|
| [List address-book entries](/operations/getV1WalletCryptoAddressBook) | `GET /v1/wallet/crypto/address-book` | `WITHDRAWALS_READ` |
| [List address-book entries for a currency](/operations/getV1WalletCryptoAddressBookByCurrency) | `GET /v1/wallet/crypto/address-book/{currency}` | `WITHDRAWALS_READ` |

### Bank accounts

Bank accounts you withdraw fiat to, and the banks you can link. Each bank account belongs to one account, the primary or a sub-account, and only that account can withdraw to it.

| Endpoint | Request | Needs |
|---|---|---|
| [List bank accounts](/operations/getV1WalletFiatByCurrencyAccounts) | `GET /v1/wallet/fiat/{currency}/accounts` | `WITHDRAWALS_READ` |
| [Link a bank account](/operations/postV1WalletFiatByCurrencyAccounts) | `POST /v1/wallet/fiat/{currency}/accounts` | `BANK_ACCOUNTS_MANAGE` |
| [Delete a bank account](/operations/deleteV1WalletFiatByCurrencyAccountsById) | `DELETE /v1/wallet/fiat/{currency}/accounts/{id}` | `BANK_ACCOUNTS_MANAGE` |
| [Get a bank account](/operations/getV1WalletFiatByCurrencyAccountsById) | `GET /v1/wallet/fiat/{currency}/accounts/{id}` | `WITHDRAWALS_READ` |
| [List banks for a currency](/operations/getV1WalletFiatByCurrencyBanks) | `GET /v1/wallet/fiat/{currency}/banks` | `WITHDRAWALS_READ` |

### Fiat deposits

References to quote when you deposit fiat by bank transfer, including auto-buy references that use the deposit to buy another currency.

| Endpoint | Request | Needs |
|---|---|---|
| [Get the account deposit reference](/operations/getV1WalletFiatByCurrencyDepositReference) | `GET /v1/wallet/fiat/{currency}/deposit/reference` | `DEPOSITS_READ` |
| [Get an auto-buy deposit reference](/operations/getV1WalletFiatByCurrencyDepositReferenceByBuyCurrencySymbol) | `GET /v1/wallet/fiat/{currency}/deposit/reference/{buyCurrencySymbol}` | `DEPOSITS_READ` |
| [List auto-buy currencies](/operations/getV1WalletFiatByCurrencyAutoBuy) | `GET /v1/wallet/fiat/{currency}/auto-buy` | `DEPOSITS_READ` |

### Fiat withdrawals

Withdraw fiat to a linked bank account or pay a bank beneficiary in one call, estimate fees, and track withdrawals.

| Endpoint | Request | Needs |
|---|---|---|
| [Estimate a fiat withdrawal fee](/operations/getV1WalletFiatByCurrencyWithdrawEstimateFee) | `GET /v1/wallet/fiat/{currency}/withdraw/estimate-fee` | `WITHDRAWALS_READ` |
| [Withdraw fiat to a bank account](/operations/postV1WalletFiatByCurrencyWithdraw) | `POST /v1/wallet/fiat/{currency}/withdraw` | `WITHDRAWALS_CREATE` |
| [List fiat withdrawals](/operations/getV1WalletFiatByCurrencyWithdrawals) | `GET /v1/wallet/fiat/{currency}/withdrawals` | `WITHDRAWALS_READ` |
| [Get a fiat withdrawal](/operations/getV1WalletFiatByCurrencyWithdrawalsById) | `GET /v1/wallet/fiat/{currency}/withdrawals/{id}` | `WITHDRAWALS_READ` |
| [Pay a bank beneficiary](/operations/postV2FiatPayments) | `POST /v2/fiat/payments` | `WITHDRAWALS_CREATE` |

---

---
url: /api/webhooks.md
description: >-
  Get an HTTPS notification when something happens on your business's accounts,
  instead of polling the API.
---

# Webhooks

Webhooks let VALR tell your server when something happens on your business's accounts, such as a deposit being
credited or a withdrawal changing status. You give us an HTTPS URL and the event types you want, and we send an HTTP
`POST` to that URL for each event. Every delivery is signed, so you can check it came from VALR, and
failed deliveries are retried for about two days.

::: info Beta
Webhooks are in beta. Event payloads may gain fields before general availability, so ignore fields you don't
recognise rather than failing on them.
:::

## Getting started

1. **Build an endpoint** that accepts `POST` requests over HTTPS and returns a `2xx` status within 3 seconds. See
   [Receiving deliveries](#receiving-deliveries).
2. **Create a webhook** with [Create a webhook](/operations/postV1Webhooks), giving your URL and the event types you
   want. [List webhook event types](/operations/getV1WebhooksEventTypes) shows what's available.
3. **Store the signing secret** from the response. It's shown only once.
4. **Verify the signature** on every delivery before you trust it. See [Verifying signatures](#verifying-signatures).
5. **Check delivery history** with [List webhook delivery attempts](/operations/getV1WebhooksByIdDeliveries) and
   [Get a webhook event](/operations/getV1WebhooksByIdEventsByEventId) while you build, and whenever you need to
   troubleshoot.

## API keys and scope

Managing webhooks needs an API key with the `WEBHOOKS_WRITE` bundle that isn't limited to specific sub-accounts. A key
limited to sub-accounts gets `401` with code `-93` from every webhook endpoint except listing event types.

A webhook covers your whole business: it receives events from your primary account and every sub-account. The
envelope's `subAccount` field says which sub-account an event happened on, and is `null` for your primary account.
Sending `X-VALR-SUB-ACCOUNT-ID` doesn't narrow a webhook to one sub-account.

## Limits

| Limit | Value |
|---|---|
| Webhooks per business | 20, counting paused webhooks and those created by your team in VALR Business |
| Event types per webhook | 1 to 20 |
| URL length | 2,048 characters |
| Description | Up to 256 characters of plain text |
| Delivery timeout | 3 seconds |
| Delivery attempts | Up to 10, over about 46 hours. See [Retries](#retries). |
| Delivery history page size | Up to 100 attempts |

## Endpoint requirements

When you create or update a webhook, we check its URL:

* It must use `https`.
* Its host must resolve, and only to public addresses. Private, loopback, link-local and other reserved ranges are
  rejected.
* It can't contain a username or password, such as `https://user:pass@example.com`.

We can't add your own headers or credentials to deliveries, so secure your endpoint by verifying the signature.

Deliveries come from the IP address `34.39.42.17`. If your endpoint is behind a firewall or an IP allowlist, allow
this address. Do this as well as verifying the signature, not instead of it.

## The delivery

Each delivery is an HTTP `POST` with a JSON body.

### Headers

| Header | Value |
|---|---|
| `Content-Type` | `application/json` |
| `User-Agent` | `VALR-Webhooks/1.0` |
| `Valr-Webhook-Event-Id` | The event's ID. The same on every retry, and on every webhook that receives the event. |
| `Valr-Webhook-Event-Type` | The event type, for example `FIAT_DEPOSIT_CREDITED` |
| `Valr-Webhook-Delivery-Attempt` | `1` for the first attempt, then `2`, `3` and so on |
| `Valr-Webhook-Timestamp` | When this attempt was signed, in Unix milliseconds |
| `Valr-Webhook-Signature` | `v1=` followed by the signature. See [Verifying signatures](#verifying-signatures). |

### Body

Every event has the same envelope:

```json
{
  "id": "11111111-1111-1111-1111-111111111111",
  "type": "FIAT_DEPOSIT_CREDITED",
  "createdAt": 1700000000000,
  "apiVersion": "2026-09-16",
  "subAccount": { "subAccountId": "12345", "label": "Collections" },
  "data": { }
}
```

| Field | Description |
|---|---|
| `id` | The event's ID, as in `Valr-Webhook-Event-Id` |
| `type` | The event type, as in `Valr-Webhook-Event-Type` |
| `createdAt` | When the event was created, in Unix milliseconds |
| `apiVersion` | The payload version, currently `2026-09-16` |
| `subAccount` | The sub-account the event happened on, with its `subAccountId` (a string) and `label`; `null` for your primary account |
| `data` | The event's details. Its shape depends on `type`; see [Event types](#event-types). |

Across all payloads:

* Amounts are strings, such as `"1500.00"`, so no precision is lost. Don't convert them to floating-point numbers.
* Times are Unix milliseconds.
* Fields with no value are sent as `null` rather than left out.

## Verifying signatures

Check the signature on every delivery before you act on it. Anyone who learns your URL can send it requests; only
VALR knows your signing secret.

The signature is an HMAC-SHA256 of the timestamp header, a full stop and the raw request body, keyed with your signing
secret:

```
signature = hex( HMAC_SHA256( key = signingSecret, message = timestamp + "." + rawBody ) )
```

To verify a delivery:

1. Read the `Valr-Webhook-Timestamp` and `Valr-Webhook-Signature` headers.
2. Build the string `{timestamp}.{rawBody}` from the body **exactly as received**. Don't parse and re-serialise the
   JSON first: any change in spacing or key order changes the signature.
3. Compute the HMAC-SHA256 of that string, keyed with the UTF-8 bytes of your signing secret, and encode it as
   lower-case hex. Use the secret exactly as you were given it; don't base64-decode it.
4. Compare your result with the value after `v1=` in `Valr-Webhook-Signature`, using a constant-time comparison.
   Ignore any other versions in the header.
5. Reject the delivery if its timestamp is more than a few minutes from your server's clock (we suggest 5 minutes),
   so a captured delivery can't be replayed later.

Each retry is signed again with a new timestamp, so its signature differs from the previous attempt's even though the
body is the same.

Check your implementation with this example: the secret `known-fixed-secret`, the timestamp `1700000000000` and the
body `{"hello":"world"}` give the signature
`v1=715658e15fcd41e22e2fde274c0b14a3c228a5ae7f00cbf91a2a56c2668ca7d7`.

::: code-group

```javascript [Node.js]
const crypto = require('crypto')
const express = require('express')

const app = express()
const SIGNING_SECRET = process.env.VALR_WEBHOOK_SECRET
const TOLERANCE_MS = 5 * 60 * 1000

// Keep the raw body: the signature is over the exact bytes we sent.
app.post('/valr/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.get('Valr-Webhook-Timestamp') || ''
  const signature = (req.get('Valr-Webhook-Signature') || '').replace(/^v1=/, '')
  const rawBody = req.body.toString('utf8')

  const sentAt = Number(timestamp)
  if (!Number.isFinite(sentAt) || Math.abs(Date.now() - sentAt) > TOLERANCE_MS) {
    return res.status(400).send('stale or missing timestamp')
  }
  const expected = crypto.createHmac('sha256', SIGNING_SECRET).update(`${timestamp}.${rawBody}`).digest('hex')
  // Compare the hex strings' bytes: a forged header can't make timingSafeEqual throw on mismatched lengths
  const signatureBytes = Buffer.from(signature, 'utf8')
  const expectedBytes = Buffer.from(expected, 'utf8')
  const valid = signatureBytes.length === expectedBytes.length && crypto.timingSafeEqual(signatureBytes, expectedBytes)
  if (!valid) return res.status(400).send('invalid signature')

  // Acknowledge first, then process the event asynchronously (for example from a queue).
  res.sendStatus(200)
  handleEvent(JSON.parse(rawBody))
})
```

```python [Python]
import hashlib
import hmac
import os
import time

SIGNING_SECRET = os.environ["VALR_WEBHOOK_SECRET"]
TOLERANCE_MS = 5 * 60 * 1000


def is_valid_delivery(headers: dict, raw_body: bytes) -> bool:
    timestamp = headers.get("Valr-Webhook-Timestamp", "")
    signature = headers.get("Valr-Webhook-Signature", "").removeprefix("v1=")
    try:
        sent_at = int(timestamp)
    except ValueError:
        return False
    if abs(time.time() * 1000 - sent_at) > TOLERANCE_MS:
        return False
    message = timestamp.encode("utf-8") + b"." + raw_body
    expected = hmac.new(SIGNING_SECRET.encode("utf-8"), message, hashlib.sha256).hexdigest()
    # Compare bytes: compare_digest raises on a str with non-ASCII characters, which a forged header can contain
    return hmac.compare_digest(signature.encode("utf-8"), expected.encode("utf-8"))
```

:::

## Receiving deliveries

* **Respond within 3 seconds** with any `2xx` status. Without a response by then, the attempt counts as a timeout and
  is retried.
* **Acknowledge first, process later.** Verify the signature, store or queue the event and return `200`. Do slow work,
  such as database writes or calls to other services, after responding.
* **Don't redirect.** We don't follow redirects, and a `3xx` response is a permanent failure.
* **Expect duplicates.** Delivery is at least once: a retry can arrive after you've already handled the first attempt,
  for example if your response was lost. Record the event IDs you've processed and skip repeats.
* **Don't rely on order.** Events usually arrive in the order they happened, but that isn't guaranteed, particularly
  with retries. Use the times in `data` and, where it matters, read the current state from the API.
* **Ignore unknown event types and fields**, so additions don't break your integration.

## Retries

| Your response | What happens |
|---|---|
| `2xx` | Delivered. Nothing more is sent for this event. |
| `408`, `429` or any `5xx` | Retried |
| No response within 3 seconds, connection refused or reset, DNS or TLS failure | Retried |
| Any other `4xx`, or any `3xx` | Permanent failure, not retried |

Each retry waits longer after the previous attempt:

| Attempt | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
|---|---|---|---|---|---|---|---|---|---|
| Delay | 30 s | 1 min | 5 min | 15 min | 1 h | 3 h | 6 h | 12 h | 24 h |

If the 10th attempt fails, about 46 hours after the first, we stop and mark the event `DEAD_LETTER`. Use
[Get a webhook event](/operations/getV1WebhooksByIdEventsByEventId) to fetch its payload if you need to process it
yourself.

A webhook is never paused or disabled automatically, however many deliveries fail. If you pause a webhook (set
`active` to `false`) or delete it, its pending retries stop and aren't resumed when you reactivate it, and events that
happen while it's paused aren't delivered.

## Delivery history

[List webhook delivery attempts](/operations/getV1WebhooksByIdDeliveries) lists every attempt for a webhook, newest
first. [Get a webhook event](/operations/getV1WebhooksByIdEventsByEventId) returns one event's payload with all its
attempts. Each attempt's `terminalState` is `SUCCESS`, `PERMANENT_FAILURE` or `DEAD_LETTER` once the event is
finished, and `null` while it's still being retried.

When an attempt fails, `errorCategory` says why:

| Category | Meaning |
|---|---|
| `HTTP_STATUS` | Your endpoint returned a status other than `2xx`; see `responseStatus` |
| `TIMEOUT` | Your endpoint didn't respond within 3 seconds |
| `CONNECTION_REFUSED` | Your endpoint refused the connection |
| `CONNECTION_RESET` | Your endpoint closed the connection unexpectedly |
| `DNS_FAILURE` | The host name couldn't be resolved |
| `TLS_FAILURE` | The TLS handshake failed. Check that your certificate is valid and hasn't expired. |
| `NETWORK_UNREACHABLE` | Your endpoint's host couldn't be reached |
| `BLOCKED` | The URL failed our safety checks when sending, for example because its host now resolves to a private address |
| `UNKNOWN` | Something else went wrong. Contact support if it keeps happening. |

## Event types

[List webhook event types](/operations/getV1WebhooksEventTypes) returns the current list.

| Event type | Sent when |
|---|---|
| `FIAT_DEPOSIT_CREDITED` | A bank deposit is credited. `reference` is the deposit reference it matched, or `null`. |
| `FIAT_WITHDRAWAL_STATUS_UPDATE` | A fiat withdrawal changes status |
| `NEW_PENDING_RECEIVE` | A crypto deposit is detected on one of your deposit addresses |
| `CRYPTO_DEPOSIT_CREDITED` | A crypto deposit is confirmed and credited |
| `SEND_STATUS_UPDATE` | A crypto withdrawal completes or fails |
| `TRANSFER` | Funds move between your primary account and a sub-account, or between sub-accounts. Sent for the account the funds left. |
| `NEW_ACCOUNT_HISTORY_RECORD` | Any new entry in an account's transaction history. This can be high volume; subscribe to the specific events above if you only need some of it. |

Typical payloads:

::: details FIAT\_DEPOSIT\_CREDITED

```json
{
  "id": "11111111-1111-1111-1111-111111111111",
  "type": "FIAT_DEPOSIT_CREDITED",
  "createdAt": 1700000000000,
  "apiVersion": "2026-09-16",
  "subAccount": null,
  "data": {
    "depositId": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
    "amount": "1000.00",
    "currencySymbol": "ZAR",
    "reference": "VALRABCDEF",
    "effectiveDate": 1699920000000,
    "creditedAt": 1700000000000
  }
}
```

:::

::: details FIAT\_WITHDRAWAL\_STATUS\_UPDATE

Use `withdrawalId` with the fiat withdrawal endpoints for the full details; `status` takes the same values. When the
bank rejects a withdrawal you receive `FAILED` straight away, then `REVERSED` once the funds are back in your account.
Both include `failureReason`, `failureReasonDescription`, `failureReasonAction` and `failureRetryable` when a reason is
known. `REVERSED` also has `principalReturned`, `feeReturned` (`null` if the fee wasn't returned) and `returnedAt`.
These fields are `null` on other updates. Rarely, a `FAILED` withdrawal returns to `PROCESSING`.

```json
{
  "id": "11111111-1111-1111-1111-111111111111",
  "type": "FIAT_WITHDRAWAL_STATUS_UPDATE",
  "createdAt": 1700000000000,
  "apiVersion": "2026-09-16",
  "subAccount": null,
  "data": {
    "withdrawalId": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
    "status": "REVERSED",
    "currencySymbol": "ZAR",
    "amount": "1500.00",
    "failureReason": "ACCOUNT_CLOSED",
    "failureReasonDescription": "The bank account is closed.",
    "failureReasonAction": "Withdraw to a different bank account.",
    "failureRetryable": false,
    "principalReturned": "1500.00",
    "feeReturned": "8.00",
    "returnedAt": 1700000000000
  }
}
```

:::

::: details NEW\_PENDING\_RECEIVE and CRYPTO\_DEPOSIT\_CREDITED

Both have the same `data`; `confirmed` is `true` once the deposit is credited.

```json
{
  "id": "11111111-1111-1111-1111-111111111111",
  "type": "CRYPTO_DEPOSIT_CREDITED",
  "createdAt": 1700000000000,
  "apiVersion": "2026-09-16",
  "subAccount": { "subAccountId": "12345", "label": "Treasury" },
  "data": {
    "currencySymbol": "BTC",
    "receiveAddress": "bc1qtestaddressexample",
    "transactionHash": "0xabcdef",
    "networkType": "bitcoin",
    "amount": "0.05",
    "sourceCreatedAt": 1700000000000,
    "confirmations": 3,
    "confirmed": true,
    "indexInTx": 0,
    "paymentReference": "invoice-42"
  }
}
```

:::

::: details SEND\_STATUS\_UPDATE

```json
{
  "id": "11111111-1111-1111-1111-111111111111",
  "type": "SEND_STATUS_UPDATE",
  "createdAt": 1700000000000,
  "apiVersion": "2026-09-16",
  "subAccount": null,
  "data": {
    "uniqueId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "status": "COMPLETE",
    "transactionHash": "0xdeadbeef",
    "confirmations": 6,
    "failureReason": null
  }
}
```

:::

::: details TRANSFER

`fromSubAccountId` and `toSubAccountId` are strings, and `null` on the primary account's side.

```json
{
  "id": "11111111-1111-1111-1111-111111111111",
  "type": "TRANSFER",
  "createdAt": 1700000000000,
  "apiVersion": "2026-09-16",
  "subAccount": null,
  "data": {
    "id": 42,
    "success": true,
    "failureReason": null,
    "fromIsPrimary": true,
    "fromSubAccountId": null,
    "fromSubAccountLabel": null,
    "toIsPrimary": false,
    "toSubAccountId": "999",
    "toSubAccountLabel": "Treasury",
    "currencySymbol": "USDC",
    "amount": "100.00",
    "description": "Monthly treasury sweep",
    "completedAt": 1700000000000
  }
}
```

:::

::: details NEW\_ACCOUNT\_HISTORY\_RECORD

```json
{
  "id": "11111111-1111-1111-1111-111111111111",
  "type": "NEW_ACCOUNT_HISTORY_RECORD",
  "createdAt": 1700000000000,
  "apiVersion": "2026-09-16",
  "subAccount": null,
  "data": {
    "transactionType": "PAYMENT_RECEIVED",
    "debitCurrencySymbol": null,
    "debitValue": null,
    "creditCurrencySymbol": "ZAR",
    "creditValue": "250.00",
    "feeCurrencySymbol": null,
    "feeValue": null,
    "eventAt": 1700000000000,
    "additionalInfo": null,
    "id": "dddddddd-dddd-dddd-dddd-dddddddddddd"
  }
}
```

:::

## Security checklist

* Verify the signature on every delivery, over the raw body, with a constant-time comparison.
* Reject deliveries whose timestamp is more than about 5 minutes old.
* If you restrict inbound traffic, allow `34.39.42.17`, and keep verifying signatures.
* Keep the signing secret out of source control and logs, as you would an API secret.
* To rotate a secret, create a new webhook with the same URL and event types, update your endpoint to accept the new
  secret, then delete the old webhook. While both exist, each event arrives twice with the same event ID, each copy
  signed with its own webhook's secret; skip the repeat by event ID.
* Treat a webhook as a signal that something changed. Before a high-value action, confirm the details with the API.

## Testing your integration

* Your endpoint must be reachable from the internet over HTTPS. While developing, a tunnelling tool can give a local
  server a public HTTPS URL.
* Trigger a real event, for example a small transfer between two of your sub-accounts for `TRANSFER`, and check it
  with the delivery history.
* To test your retry handling, have your endpoint return `503` and watch the next attempts arrive with the same event
  ID.
* Check your signature code against the example in [Verifying signatures](#verifying-signatures) before going live.

## Endpoints

| Endpoint | Request | Needs |
|---|---|---|
| [List webhooks](/operations/getV1Webhooks) | `GET /v1/webhooks` | `WEBHOOKS_READ` |
| [Create a webhook](/operations/postV1Webhooks) | `POST /v1/webhooks` | `WEBHOOKS_MANAGE` |
| [Delete a webhook](/operations/deleteV1WebhooksById) | `DELETE /v1/webhooks/{id}` | `WEBHOOKS_MANAGE` |
| [Get a webhook](/operations/getV1WebhooksById) | `GET /v1/webhooks/{id}` | `WEBHOOKS_READ` |
| [Update a webhook](/operations/putV1WebhooksById) | `PUT /v1/webhooks/{id}` | `WEBHOOKS_MANAGE` |
| [List webhook delivery attempts](/operations/getV1WebhooksByIdDeliveries) | `GET /v1/webhooks/{id}/deliveries` | `WEBHOOKS_READ` |
| [Get a webhook event](/operations/getV1WebhooksByIdEventsByEventId) | `GET /v1/webhooks/{id}/events/{eventId}` | `WEBHOOKS_READ` |
| [List webhook event types](/operations/getV1WebhooksEventTypes) | `GET /v1/webhooks/event-types` | `WEBHOOKS_READ` |

---

---
url: /api-docs/postV1WalletCryptoByCurrencyWithdraw.md
description: 'POST /v1/wallet/crypto/{currency}/withdraw'
---

# Withdraw crypto

`POST /v1/wallet/crypto/{currency}/withdraw`

Sends crypto from the account the request acts on (your primary account, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`) to `address`, or to the entry in that account's address book given by `addressBookId`. The network fee from `GET /v1/wallet/crypto/{currency}/withdraw` is charged on top of `amount` (sends to another VALR account are free), and if your business only allows withdrawals to address-book entries, the address must already be saved there and past its waiting period.

**Requires** `WITHDRAWALS_CREATE`, granted by `WITHDRAWALS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Currency to withdraw, e.g. `USDC`. |

## Request Body

**Content-Type:** `application/json`

| Property | Type | Required | Description |
|---|---|---|---|
| amount | string | Yes | Amount to send, in the currency in the path, as a decimal string greater than zero. Decimal places beyond the network's `withdrawalDecimalPlaces` are rounded down. |
| addressBookId | string | No | ID of an entry in the account's address book, from `GET /v1/wallet/crypto/address-book`. Send either this or `address`, not both; the entry's network and payment reference are used. |
| address | string | No | Destination address. Send either this or `addressBookId`, not both. |
| networkType | string | No | Network to send on, e.g. `Ethereum`; defaults to the currency's default network. Make sure it matches the address: sending on the wrong network can lose the funds. Ignored with `addressBookId`. |
| paymentReference | string | No | Memo, tag or payment reference, for networks that use one; up to 256 characters. Ignored with `addressBookId`. |
| allowBorrow | boolean | No | Borrow against the account's other assets to cover a shortfall. Only for margin-enabled accounts; defaults to `false`. |
| beneficiaryName | string | No | Recipient's full name. Required, with `isCorporate` and `isSelfHosted`, unless the address belongs to a VALR account or the address-book entry already holds the recipient's details. |
| isCorporate | boolean | No | `true` if the recipient is a business, `false` if a person. |
| isSelfHosted | boolean | No | `true` if the recipient holds their own keys, `false` if an exchange or other provider hosts the address. When `false`, also send `serviceProviderId` or `serviceProviderName`. |
| serviceProviderName | string | No | Name of the recipient's provider, if it isn't in the service-providers list. Send this or `serviceProviderId`, not both. |
| serviceProviderId | string | No | ID of the recipient's provider, from `GET /v1/wallet/crypto/service-providers`. Send this or `serviceProviderName`, not both. |

## Responses

### 202

Withdrawal accepted for processing. The body is `{"id": "<withdrawal ID>"}`, for example `{"id": "7c1d9e42-5a3b-4f6e-9d8c-2b1a0f3e4d5c"}`. The withdrawal can still fail later, so follow it with `GET /v1/wallet/crypto/{currency}/withdraw/{id}`.

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=POST
REQUEST_PATH='/v1/wallet/crypto/{currency}/withdraw'
BODY='{"amount":"<amount>","addressBookId":"<addressBookId>","address":"<address>","networkType":"<networkType>","paymentReference":"<paymentReference>","allowBorrow":false,"beneficiaryName":"<beneficiaryName>","isCorporate":false,"isSelfHosted":false,"serviceProviderName":"<serviceProviderName>","serviceProviderId":"<serviceProviderId>"}'
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}" -H "Content-Type: application/json" --data "$BODY"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "POST"
path = "/v1/wallet/crypto/{currency}/withdraw"
body = "{\"amount\":\"<amount>\",\"addressBookId\":\"<addressBookId>\",\"address\":\"<address>\",\"networkType\":\"<networkType>\",\"paymentReference\":\"<paymentReference>\",\"allowBorrow\":false,\"beneficiaryName\":\"<beneficiaryName>\",\"isCorporate\":false,\"isSelfHosted\":false,\"serviceProviderName\":\"<serviceProviderName>\",\"serviceProviderId\":\"<serviceProviderId>\"}"  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID
headers["Content-Type"] = "application/json"

response = requests.request(method, "https://api.valr.com" + path, headers=headers, data=body.encode())
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The currency isn't recognised, or the body fails validation, for example `amount` isn't a positive decimal, both or neither of `address` and `addressBookId` are sent, or the recipient's details are missing; `validationErrors` lists each failing field. |
| 400 | `-13427` | `NON_ADDRESS_BOOK_WITHDRAWALS_DISABLED` | Withdrawals are restricted to address-book entries, and the address isn't saved in the account's address book. |
| 400 | `-13428` | `ADDRESS_BOOK_ENTRY_STILL_WARMING_UP` | Withdrawals are restricted to address-book entries, and this entry was added or changed too recently. Try again once its waiting period has passed. |
| 400 | `-13415` | `WITHDRAWALS_TEMPORARILY_SUSPENDED` | Withdrawals are paused after a recent security change on your account; the message says when they resume. Withdrawals to address-book entries may still be allowed. |
| 400 | `-112` | `CURRENCY_NOT_SUPPORTED` | The currency can't be withdrawn on a blockchain, for example a fiat currency. |
| 400 | `-13018` | `BLOCKCHAIN_INVALID_NETWORK_FOR_CURRENCY` | The network isn't available for this currency. |
| 400 | `-13402` | `CURRENCY_DOES_NOT_SUPPORT_PAYMENT_REFERENCE` | A `paymentReference` was sent, but this currency and network don't use one. |
| 400 | `-13410` | `PAYMENT_REFERENCE_MISSING` | The address needs a payment reference, such as a memo or tag; send it in `paymentReference`. |
| 400 | `-13405` | `INVALID_WITHDRAW_TRANSACTION_REFERENCE` | The `paymentReference` isn't valid for this network. |
| 400 | `-50` | `INVALID_WITHDRAW_ADDRESS` | The address isn't valid for this currency and network. |
| 400 | `-13411` | `WITHDRAW_AMOUNT_BELOW_MINIMUM` | The amount is below the network's minimum, which the message gives. |
| 400 | `-13404` | `INVALID_WITHDRAW_AMOUNT` | The network rejected the amount, for example because it has too many decimal places. |
| 400 | `-13419` | `NETWORK_FEE_FOR_TRANSACTION_EXCEEDED` | Sending to this address would need more network fee than is allowed, so it can't receive withdrawals. |
| 400 | `-13017` | `BLOCKCHAIN_SEND_TRUSTLINE_NOT_VALID` | The destination address has no active trustline for this asset. |
| 400 | `-13019` | `BLOCKCHAIN_SEND_MISSING_KYC_PERMIT` | The token issuer hasn't whitelisted the destination address. |
| 400 | `-30071` | `SERVICE_PROVIDER_NOT_FOUND` | `serviceProviderId` isn't in the list from `GET /v1/wallet/crypto/service-providers`. |
| 400 | `-6` | `INSUFFICIENT_BALANCE` | The account's available balance doesn't cover the amount plus the network fee. |
| 400 | `-108` | `WITHDRAW_LIMIT_REACHED` | The withdrawal would exceed your business's withdrawal limit; see `GET /v1/wallet/crypto/{currency}/withdraw/limits`. |
| 400 | `-32765` | `WITHDRAWAL_RESTRICTION_APPLIED` | Your business must keep a minimum portfolio value, and this withdrawal would take it below that. |
| 400 | `-19213` | `MARGIN_NOT_ENABLED_FOR_ACCOUNT` | `allowBorrow` is `true`, but margin isn't enabled on the account. |
| 400 | `-19243` | `BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE` | `allowBorrow` is `true`, but borrowing for withdrawals is currently unavailable. |
| 400 | `-19244` | `BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY` | `allowBorrow` is `true`, but this currency can't be borrowed for withdrawals. |
| 404 | `-13422` | `ADDRESS_BOOK_ENTRY_NOT_FOUND` | No entry with this `addressBookId` exists in the account's address book. |
| 500 | `-13423` | `ADDRESS_BOOK_ENTRY_CURRENCY_WRONG` | The address-book entry is saved for a different currency. |
| 500 | `-19502` | `CURRENCY_UNDER_MAINTENANCE` | The currency is under maintenance. Try again in a few minutes. |
| 500 | `-46` | `WITHDRAW_UNAVAILABLE` | Withdrawals of this currency on this network are currently disabled, or the withdrawal couldn't be recorded. Try again later. |
| 500 | `-29` | `BLOCKCHAIN_SEND_FAILURE` | The withdrawal couldn't be checked with the network. Try again later. |
| 500 | `-19202` | `INSUFFICIENT_LIQUIDITY_FOR_BORROW` | `allowBorrow` is `true`, but the amount can't be borrowed right now. Try again later. |
| 503 | `-12015` | `WITHDRAWALS_NOT_AVAILABLE` | Withdrawals are temporarily unavailable. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).

---

---
url: /api-docs/postV1WalletFiatByCurrencyWithdraw.md
description: 'POST /v1/wallet/fiat/{currency}/withdraw'
---

# Withdraw fiat to a bank account

`POST /v1/wallet/fiat/{currency}/withdraw`

Withdraws fiat from the account (the primary, or the sub-account selected with `X-VALR-SUB-ACCOUNT-ID`) to a bank account linked to that same account, with no email or two-factor confirmation; the fee is charged on top of `amount`. Set `fast` for a real-time (RTC) or RTGS payment at participating banks, and `allowBorrow` to borrow any shortfall against your other assets on a margin-enabled account. The response holds the withdrawal's `id`; track it with Get a fiat withdrawal.

**Requires** `WITHDRAWALS_CREATE`, granted by `WITHDRAWALS_WRITE` ([bundles](/guides/permissions))

Sign the request as described in [Authentication](/guides/authentication).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| currency | path | string | Yes | Fiat currency to withdraw, e.g. `ZAR`. |

## Request Body

**Content-Type:** `application/json`

| Property | Type | Required | Description |
|---|---|---|---|
| linkedBankAccountId | string | Yes | - |
| amount | string | Yes | - |
| fast | boolean | No | - |
| instant | boolean | No | - |
| allowBorrow | boolean | No | - |
| reference | string | No | - |

## Responses

### 202

Accepted

**Example:**

```json
{
  "id": "d4a7c2e9-61f3-4b8d-9e05-7c1b3f6a2d84"
}
```

## Example request

Signs the request when it runs. Set `VALR_API_KEY` and `VALR_API_SECRET` first.

```bash
#!/usr/bin/env bash
# Needs VALR_API_KEY and VALR_API_SECRET. Set VALR_SUBACCOUNT_ID to act on a sub-account.

METHOD=POST
REQUEST_PATH='/v1/wallet/fiat/{currency}/withdraw'
BODY='{"linkedBankAccountId":"<linkedBankAccountId>","amount":"<amount>","fast":false,"instant":false,"allowBorrow":false,"reference":"<reference>"}'
TIMESTAMP=$(($(date +%s) * 1000))

SIGNATURE=$(printf '%s' "${TIMESTAMP}${METHOD}${REQUEST_PATH}${BODY}${VALR_SUBACCOUNT_ID:-}" \
  | openssl dgst -sha512 -hmac "$VALR_API_SECRET" | awk '{print $NF}')

HEADERS=(-H "X-VALR-API-KEY: $VALR_API_KEY" -H "X-VALR-SIGNATURE: $SIGNATURE" -H "X-VALR-TIMESTAMP: $TIMESTAMP")
[ -n "$VALR_SUBACCOUNT_ID" ] && HEADERS+=(-H "X-VALR-SUB-ACCOUNT-ID: $VALR_SUBACCOUNT_ID")
curl -X "$METHOD" "https://api.valr.com$REQUEST_PATH" "${HEADERS[@]}" -H "Content-Type: application/json" --data "$BODY"
```

```python
import hashlib
import hmac
import os
import time

import requests

API_KEY = os.environ["VALR_API_KEY"]
API_SECRET = os.environ["VALR_API_SECRET"]
SUBACCOUNT_ID = os.environ.get("VALR_SUBACCOUNT_ID", "")

method = "POST"
path = "/v1/wallet/fiat/{currency}/withdraw"
body = "{\"linkedBankAccountId\":\"<linkedBankAccountId>\",\"amount\":\"<amount>\",\"fast\":false,\"instant\":false,\"allowBorrow\":false,\"reference\":\"<reference>\"}"  # send exactly the string you sign
timestamp = str(int(time.time() * 1000))

signature = hmac.new(
    API_SECRET.encode(), (timestamp + method + path + body + SUBACCOUNT_ID).encode(), hashlib.sha512
).hexdigest()

headers = {"X-VALR-API-KEY": API_KEY, "X-VALR-SIGNATURE": signature, "X-VALR-TIMESTAMP": timestamp}
if SUBACCOUNT_ID:
    headers["X-VALR-SUB-ACCOUNT-ID"] = SUBACCOUNT_ID
headers["Content-Type"] = "application/json"

response = requests.request(method, "https://api.valr.com" + path, headers=headers, data=body.encode())
print(response.status_code, response.text)
```

## Errors

| HTTP | Code | Name | When |
|---|---|---|---|
| 400 | `-113` | `INVALID_JSON` | The body isn't valid JSON. |
| 400 | `-11` | `INVALID_REQUEST` | The body is empty or a field fails validation, or `reference` was rejected, or the currency isn't recognised; `validationErrors` lists each failing field. |
| 400 | `-13415` | `WITHDRAWALS_TEMPORARILY_SUSPENDED` | Withdrawals are paused for a while after a security change on your account, such as a password reset or a new device; the message says when they're re-enabled. |
| 400 | `-32765` | `WITHDRAWAL_RESTRICTION_APPLIED` | The withdrawal would take your portfolio below the minimum value it must keep. |
| 400 | `-15875` | `FIAT_WITHDRAWALS_TO_BANK_BRANCH_RESTRICTED` | Withdrawals to the bank account's branch code aren't supported. Use another bank account or contact support. |
| 400 | `-15307` | `FIAT_WITHDRAWAL_AMOUNT_BELOW_MINIMUM` | `amount` is below the minimum withdrawal for this currency. |
| 400 | `-15318` | `FIAT_WITHDRAWAL_CURRENCY_MISMATCH` | The bank account was linked for a different currency. |
| 400 | `-6` | `INSUFFICIENT_BALANCE` | The account's available balance doesn't cover `amount` plus the fee. |
| 400 | `-15322` | `CAN_NOT_WITHDRAW_TO_A_DELETED_BANK_ACCOUNT` | The bank account has been deleted. Link it again to withdraw to it. |
| 400 | `-15321` | `CAN_NOT_WITHDRAW_TO_AN_UNCONFIRMED_BANK_ACCOUNT` | The bank account was never confirmed. |
| 400 | `-15309` | `CAN_NOT_WITHDRAW_TO_AN_UNVERIFIED_BANK_ACCOUNT` | This currency only pays out to verified bank accounts, and this one hasn't been verified yet or failed verification. |
| 400 | `-19243` | `BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE` | `allowBorrow` was set, but borrowing for withdrawals is unavailable at the moment. |
| 400 | `-19244` | `BORROW_FOR_WITHDRAWAL_NOT_AVAILABLE_FOR_SELECTED_CURRENCY` | `allowBorrow` was set, but this currency can't be borrowed for a withdrawal. |
| 400 | `-19213` | `MARGIN_NOT_ENABLED_FOR_ACCOUNT` | `allowBorrow` was set, but margin isn't enabled on the account. |
| 400 | `-11533` | `CURRENCY_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING` | Borrowing the shortfall would exceed the account's borrow limit for this currency. |
| 400 | `-11534` | `ACCOUNT_BORROW_EXCEEDED_FOR_COLLATERALIZED_LENDING` | Borrowing the shortfall would exceed the account's total borrow limit. |
| 404 | `-14203` | `COULD_NOT_GET_LINKED_ACCOUNT` | No bank account with `linkedBankAccountId` exists. |
| 451 | `-15320` | `FIAT_WITHDRAWALS_NOT_ALLOWED_FOR_CURRENCY` | Your business's region doesn't allow withdrawals in this currency. |
| 500 | `-19202` | `INSUFFICIENT_LIQUIDITY_FOR_BORROW` | `allowBorrow` was set, but the amount to borrow isn't available right now. Try again later. |
| 503 | `-12015` | `WITHDRAWALS_NOT_AVAILABLE` | Withdrawals are unavailable at the moment. Try again later. |

Plus the [errors common to all signed endpoints](/guides/errors#common-to-all-endpoints).