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 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	GET /v2/payments	COLLECTIONS_READ
Get a payment	GET /v2/payments/{id}	COLLECTIONS_READ
List collection activity	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	GET /v2/wallet/fiat/{currency}/payment/references/{referenceCode}	COLLECTIONS_READ
Delete a deposit reference	DELETE /v2/wallet/fiat/{currency}/payment/references/{referenceCode}	COLLECTIONS_DELETE
Update a deposit reference	PUT /v2/wallet/fiat/{currency}/payment/references/{referenceCode}	COLLECTIONS_UPDATE
Create a deposit reference	POST /v2/wallet/fiat/{currency}/payment/references	COLLECTIONS_CREATE
List deposit references	GET /v2/wallet/fiat/{currency}/payment/references	COLLECTIONS_READ
Create deposit references in bulk	POST /v2/wallet/fiat/{currency}/payment/bulk-references	COLLECTIONS_CREATE
Get a bulk reference job	GET /v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}	COLLECTIONS_READ
List bulk reference job items	GET /v2/wallet/fiat/{currency}/payment/bulk-references/{jobId}/items	COLLECTIONS_READ
List credited deposits	GET /v2/wallet/fiat/{currency}/payment/deposits	COLLECTIONS_READ
Unlink a deposit from its reference	DELETE /v2/wallet/fiat/{currency}/payment/deposits/{publicId}/reference	COLLECTIONS_DELETE
Link a deposit to a reference	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	GET /v2/payments/collect/events	COLLECTIONS_READ
Get a scheduled payment	GET /v2/payments/collect/events/{id}	COLLECTIONS_READ
List processed scheduled payments	GET /v2/payments/collect/history	COLLECTIONS_READ
Get a payout run	GET /v2/payments/collect/runs/{id}	COLLECTIONS_READ
List a payout run's payments	GET /v2/payments/collect/runs/{id}/payments	COLLECTIONS_READ
List payout runs	GET /v2/payments/collect/runs/history	COLLECTIONS_READ
List payout schedules	GET /v2/payments/collect/schedules	COLLECTIONS_READ
Get upcoming scheduled payouts	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	GET /v2/payments/collect/settlements	COLLECTIONS_READ
Get a settlement	GET /v2/payments/collect/settlements/{id}	COLLECTIONS_READ
List a settlement's payments	GET /v2/payments/collect/settlements/{id}/payments	COLLECTIONS_READ
Get the settlement wallet	GET /v2/payments/collect/settlements/wallet	COLLECTIONS_READ