Accounts, Balances & Transactions

This guide covers three related areas:

• Balances — how much each client holds, per currency.
• Virtual accounts — the account details shared to receive funds.
• Transactions — the ledger of every balance change.

clientId scope

On the endpoints below, clientId always refers to the Client's ID — the entity you manage as a Program Manager:

• As a query parameter — pass a Client's clientId to scope the results to that Client. Omit it to query across all clients you manage.
• In response objects — the clientId field identifies which Client the record belongs to.

See Understanding Your Role for the full model.

Balances

Retrieve available balances with GET /accounts/balances. Deposits are added to the available balance once processed, including any settled conversion bought in that currency.

curl "https://api.sandbox.capay.com.au/accounts/balances?currencyCodes=AUD,USD&clientId=401f4647-8372-495f-8de0-aafb3e1eaf93" \
  -H "Authorization: Bearer <token>"

Query parameters

Parameter	Required	Description
currencyCodes	No	Comma-separated ISO 4217 codes, e.g. AUD,USD
clientId	No	Client's clientId — scope results to that Client; omit to query across all clients
skip / limit	No	Pagination (defaults 0 / 10)

Balance object

Each currency a client holds is returned as a single balance figure.

Field	Type	Description
id	string	Balance record ID
clientId	string	Client the balance belongs to
currencyCode	string	ISO 4217 currency code
balance	number	Available balance in that currency
createdTime	string	ISO 8601 timestamp

info

Balances are a single available figure per currency—there is no separate pending or total breakdown. Funds in flight are reflected once they settle.

Virtual accounts

A virtual account is a set of real bank account details (account number, routing information, and optionally a PayID) given to a payer so they can send funds to a client. Incoming money credited to a virtual account becomes a deposit.

List virtual accounts

curl "https://api.sandbox.capay.com.au/accounts/virtual" \
  -H "Authorization: Bearer <token>"

Virtual account object

Field	Type	Description
id	string	Virtual account ID
clientId	string	The Client this virtual account belongs to
currencyCode	string | null	ISO 4217 code; null for a multi-currency account
accountName	string	Account holder name
bankName / bankCountryCode / bankAddress	—	Bank details
bankType	enum	SWIFT or LOCAL
routingNoType	enum	Routing identifier type (e.g. BSB, IBAN, SWIFT)
accountNumber / routingNumber	string	Account and routing numbers
payId	string | null	PayID, if assigned
status	enum	ACTIVE or INACTIVE
createdTime	string	ISO 8601 timestamp

Create a virtual account

curl -X POST "https://api.sandbox.capay.com.au/accounts/virtual" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "401f4647-8372-495f-8de0-aafb3e1eaf93",
    "currencyCode": "AUD",
    "payidEmail": "collections@yourcompany.com"
  }'

Field	Required	Description
clientId	Yes	Client the virtual account belongs to
currencyCode	Yes	Collection currency (ISO 4217)
payidEmail	No	PayID email to assign at creation

Manage a virtual account

Action	Endpoint
Assign / update PayID	PATCH /accounts/virtual/{id}/payid
Disable (stop collecting)	PATCH /accounts/virtual/{id}/disable
Activate	PATCH /accounts/virtual/{id}/activate

PayID setup

To use PayID, the client's domain must first be reviewed and verified by CA. Once approved, all PayIDs issued to that client's virtual accounts will be generated under that verified domain. CA currently supports email-type PayIDs only (e.g. collections@clientdomain.com). Contact your Account Manager to initiate the domain verification process.

Transactions

The transaction ledger (GET /transactions) records every movement that changes a balance—payments, deposits, conversions, fees, and internal transfers. Use it to reconcile a client's account and to trace how a balance reached its current value.

curl "https://api.sandbox.capay.com.au/transactions?clientId=401f4647-8372-495f-8de0-aafb3e1eaf93&transactionType=PAYMENT" \
  -H "Authorization: Bearer <token>"

Query parameters

Parameter	Description
currencyCode	Filter by ISO 4217 currency
clientId	Client's clientId — scope results to that Client; omit to query across all clients
transactionType	One of the types below
transactionTimeFrom / transactionTimeTo	ISO 8601 time range
skip / limit	Pagination (defaults 0 / 10)

Transaction types

Type	Meaning
PAYMENT	An outbound payment
DEPOSIT	An inbound deposit
CONVERSION	A currency conversion (FX)
TRANSFER	An internal transfer between accounts
ACCOUNT FEE	A fee charged to the account
DRAWDOWN	A drawdown movement
TRADE CLOSE OUT	A trade close-out

Deprecated

OPTION CLOSE OUT and DRAWDOWN REPAYMENT are deprecated and should not be relied upon for new integrations.

Transaction object

Field	Type	Description
transactionType	enum	See types above
currencyCode	string	ISO 4217 currency code
clientId	string	Client the transaction belongs to
amount	number	Movement amount—positive or negative
balance	number	Balance after this transaction
relatedTransactionId	string	CAPAY reference to the source record (e.g. the payment or deposit)
relatedTransactionReferenceNo	string	Human-readable reference of the related record
referenceId	string | null	Your external reference, if supplied
transactionTime	string	ISO 8601 time the balance was updated

Reconciliation

Use relatedTransactionId / relatedTransactionReferenceNo to jump from a ledger line back to the underlying payment or deposit that caused it. The balance field lets you verify the running balance at each step.