VALR Business APIs

APIs for building on VALR's business payments platform — getting paid (collections), funding, disbursements, scheduled withdrawals and settlements. The reference is organised by feature, so you can find what you need without knowing which backend service serves it.

The APIs we expose

API	Who it's for	Auth	Where	Status
Web API	The business dashboard / frontend	Logged-in session	api-dev.valr.world/institution/payments/*	Live
v2 API	Programmatic / partner integrations	API key (not a session)	api-dev.valr.world/v2/payments/* (same host, key-based)	Coming soon / Beta
Admin API	VALR operators	Session + operator role	Internal admin surface	Live
Internal API	Service-to-service	HMAC-signed	Not publicly routable	Live

The Web API and the v2 API expose payments functionality — the difference is how you authenticate: the Web API rides the logged-in user's session (what the dashboard uses today), while v2 allows partners and institutions to call /v2/payments/* using signed API keys with RBAC permissions. Both are documented under API Reference.

v2 API Surface (/v2/payments/*)

Key-based endpoints with RBAC permissions:

Collections (COLLECTIONS_READ)

• GET /v2/payments — List payments (paged)
• GET /v2/payments/{id} — Get payment by ID
• GET /v2/payments/funding/history — Funding history (paged)
• GET /v2/payments/collections/history — Collections history (paged)
• GET /v2/payments/collect/schedules — Collection schedules
• GET /v2/payments/collect/upcoming — Upcoming collection schedule runs
• GET /v2/payments/collect/events — Collection events (paged)
• GET /v2/payments/collect/events/{id} — Get collection event by ID
• GET /v2/payments/collect/history — Collection payment history (paged)
• GET /v2/payments/collect/runs/history — Collection run history (paged)
• GET /v2/payments/collect/runs/{id} — Get collection run by ID
• GET /v2/payments/collect/runs/{id}/payments — Get collection run payments (paged)
• GET /v2/payments/collect/settlements — List settlements (paged)
• GET /v2/payments/collect/settlements/wallet — Settlement wallet balance
• GET /v2/payments/collect/settlements/{id} — Get settlement by ID
• GET /v2/payments/collect/settlements/{id}/payments — Get settlement payments (paged)

Disbursements & Withdrawals

• GET /v2/payments/bulk-withdrawals/withdrawals — List withdrawals (paged, DISBURSEMENTS_READ)
• GET /v2/payments/bulk-withdrawals/banks — List supported banks (DISBURSEMENTS_READ)
• GET /v2/payments/bulk-withdrawals/beneficiaries — List beneficiaries (paged, DISBURSEMENTS_READ)
• GET /v2/payments/bulk-withdrawals/beneficiaries/{id} — Get beneficiary by ID (DISBURSEMENTS_READ)
• POST /v2/payments/bulk-withdrawals/beneficiaries — Create beneficiary (DISBURSEMENTS_CREATE)
• POST /v2/payments/bulk-withdrawals/beneficiaries/bulk — Bulk create beneficiaries (DISBURSEMENTS_CREATE)
• PUT /v2/payments/bulk-withdrawals/beneficiaries/{id} — Update beneficiary (DISBURSEMENTS_UPDATE)
• DELETE /v2/payments/bulk-withdrawals/beneficiaries/{id} — Delete beneficiary (DISBURSEMENTS_DELETE)
• GET /v2/payments/bulk-withdrawals/batches — List withdrawal batches (paged, DISBURSEMENTS_READ)
• GET /v2/payments/bulk-withdrawals/batches/{id} — Get batch by ID (DISBURSEMENTS_READ)
• GET /v2/payments/bulk-withdrawals/batches/{id}/withdrawals — List batch withdrawals (paged, DISBURSEMENTS_READ)
• GET /v2/payments/bulk-withdrawals/batches/{id}/fee-quote — Get batch fee quote (DISBURSEMENTS_READ)
• POST /v2/payments/bulk-withdrawals/batches — Create batch (DISBURSEMENTS_CREATE, DISBURSEMENTS_APPROVE)
• PUT /v2/payments/bulk-withdrawals/batches/{id}/label — Update batch label (DISBURSEMENTS_UPDATE)
• POST /v2/payments/bulk-withdrawals/batches/{id}/cancel — Cancel batch (DISBURSEMENTS_UPDATE)
• POST /v2/payments/bulk-withdrawals/fee-quote — Get fee quote (DISBURSEMENTS_READ)
• GET /v2/payments/payout/history — Payout history (paged, DISBURSEMENTS_READ)
• GET /v2/payments/payout/history/{id} — Get payout history by ID (DISBURSEMENTS_READ)

Creating a batch (POST /v2/payments/bulk-withdrawals/batches)

• The X-VALR-Idempotency-Key header is required (max 128 characters).
• 202 Accepted: the batch was created and execution started. 200 OK: the key was used before and the existing batch id is returned; nothing new is created.
• Replay rules for a reused key:
  • Same key: returns the existing batch (200). The body is not compared, so use a new key for each distinct request.
  • The earlier batch was cancelled: 409. It will not be processed; retry with a new key.
  • The earlier batch failed after the fee was charged and is awaiting support: 409, with the batch id in the message. Do not retry.
• If execution fails after the fee was charged, the response is an error that includes batchId. Do not retry with a new key: contact support with that batch id.

Balances

• GET /v2/payments/account/balances/{type} — Get subaccount balances by designation

Start here

• API Reference — the public, frontend-facing endpoints, grouped by feature: Getting paid, Funding records, Scheduled withdrawals, Settlements, Disbursements, Payout history, Account balances and Configuration.
• Admin API — operator endpoints (require an operator role).
• Internal API — service-to-service endpoints.
• How these docs work — where the specs come from, the /institution gateway, and how to regenerate them.

Prefer a raw spec? Download the Web API OpenAPI spec — one file covering the whole Web API, ready for Postman or code generation.