List payments

GET

/v2/payments

Requires COLLECTIONS_READ, granted by PAYMENTS_READ or COLLECTIONS_WRITE (bundles)

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.

Parameters

Query Parameters

limit

Maximum number of payments to return.

Type

integer

Example50

Default

50

offset

Number of payments to skip, for paging.

Type

integer

Example0

Default

0

type

COLLECTION for payments from payers, DISBURSEMENT for deposits that fund disbursements.

Type

string

Example"COLLECTION"

status

Settlement status: PENDING, SETTLED or FAILED.

Type

string

Example"SETTLED"

from

Only include payments received at or after this time, in Unix milliseconds.

Type

integer

Example1792627200000

Format

"int64"

to

Only include payments received before this time, in Unix milliseconds.

Type

integer

Example1792713600000

Format

"int64"

minAmount

Smallest deposit amount to include, as a decimal string.

Type

string

Example"100.00"

maxAmount

Largest deposit amount to include, as a decimal string.

Type

string

Example"5000.00"

currency

Only include payments with this currency on any leg: deposit, conversion or payout.

Type

string

Example"ZAR"

reference

Payer reference, or part of one. Not case-sensitive.

Type

string

Example"VLR4F7K2"

referenceCodes

Comma-separated payer references. Only payments with one of these exact references are included.

Type

string

Example"VLR4F7K2Q9,VLR8M3N6P1"

payer

Same as referenceCodes; ignored when referenceCodes is sent.

Type

string

Example"VLR4F7K2Q9"

query

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.

Type

string

Example"2026-10-22"

tz

IANA time zone used to interpret a date in query, e.g. Africa/Johannesburg.

Type

string

Example"Africa/Johannesburg"

Responses

OK

Content-Type

application/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

}

Samples

Errors

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

Plus the errors common to all signed endpoints.