Accounts, Balances & Transactions

This guide covers three related areas:

• Balances — how much you hold, per currency.
• Virtual accounts — the account details you share to receive funds.
• Transactions — the ledger of every balance change.

clientId scope

In the CA system, both Clients and Customers are identified by a clientId. On the endpoints below:

• As a query parameter — pass a Customer's clientId to scope the results to that Customer. Omit it to query your own (Client) data.
• In response objects — the clientId field identifies which Client or Customer the record belongs to.

See Understanding Your Account for the full model.

Balances

Retrieve your 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" \
  -H "Authorization: Bearer <token>"

Query parameters

Parameter	Required	Description
currencyCodes	No	Comma-separated ISO 4217 codes, e.g. AUD,USD
clientId	No	Customer's clientId — scope results to that Customer; omit for your own balances
skip / limit	No	Pagination (defaults 0 / 10)

Balance object

Each currency you hold is returned as a single balance figure.

Field	Type	Description
id	string	Balance record ID
clientId	string	The Client or Customer this 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) that you give to a payer so they can send you funds. 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 or Customer 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	The Client or Customer this virtual account is created for
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, your domain must first be reviewed and verified by CA. Once approved, all PayIDs issued to your virtual accounts will be generated under that verified domain. CA currently supports email-type PayIDs only (e.g. collections@yourdomain.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 your account and to trace how a balance reached its current value.

curl "https://api.sandbox.capay.com.au/transactions?currencyCode=AUD&transactionType=PAYMENT" \
  -H "Authorization: Bearer <token>"

Query parameters

Parameter	Description
currencyCode	Filter by ISO 4217 currency
clientId	Customer's clientId — scope results to that Customer; omit for your own transactions
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	The Client or Customer this 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.