Payments

The Payments API lets you initiate fund transfers to a beneficiary and manage them through their whole lifecycle—from creation to settlement.

Before you start

Every payment needs a beneficiary (the account being paid). Either create one first (see Beneficiary Management) and pass its beneficiaryId, or create the beneficiary and payment together in a single call (see Pay a new beneficiary in one call).

clientId is required

As a Program Manager you are the Tenant administrator — clientId identifies which Client within your Tenant this payment is for. See Understanding Your Role.

Two payment scenarios

Scenario	When	Extra requirement
Standard	The payment currency matches the currency held	None
FX	The payment currency differs from the currency held	A quotationId to lock the rate

For FX payments, request a firm rate first with POST /payments/quotation and pass the returned quotationId. See FX Rates.

How it works

Create a payment

curl -X POST "https://api.sandbox.capay.com.au/payments" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "x-idempotency-key: unique-key-12345" \
  -d '{
    "clientId": "401f4647-8372-495f-8de0-aafb3e1eaf93",
    "beneficiaryId": "501f4647-8372-495f-8de0-aafb3e1eaf93",
    "currencyCode": "USD",
    "amount": 10000.55,
    "chargeType": "SHARED",
    "purposeCode": "GOODS",
    "paymentReference": "Invoice-123",
    "paymentDate": "2024-07-30"
  }'

Request fields

Field	Required	Description
clientId	Yes	The client the payment is made for
beneficiaryId	Yes	The beneficiary to pay
currencyCode	Yes	Payment currency (ISO 4217)
amount	Yes	Amount in payment currency, max 2 decimals
chargeType	Yes	SHARED or OURS (SWIFT only—see below)
purposeCode	Yes	Reason for the payment (see table)
paymentReference	Yes	Reference shown to the beneficiary, max 64 chars
paymentDate	Yes	YYYY-MM-DD
sellCurrencyCode	FX	Currency held, if converting
quotationId	FX	Locked rate from POST /payments/quotation
sourceOfFunds	Conditional	Required for local payments, or POBO SWIFT payments to personal beneficiaries
invoiceNumber / invoiceDate	Conditional	Required for local INR payments to business beneficiaries
referenceId	Optional	Your unique reference for idempotency (see below)

Payment capabilities

Capay supports paying 30+ currencies, and follows international standard (ISO 4217 ) for representation of currencies.

Currency Code	Currency Name	Country	Global Payment	Local Payment
AED	United Arab Emirates Dirham	United Arab Emirates	√	√
AUD	Australian Dollar	Australia	√	√
BHD	Bahraini Dinar	Bahrain	√
BRL	Brazilian Real	Brazil		√
CAD	Canadian Dollar	Canada	√	√
CHF	Swiss Franc	Switzerland	√
CNH	Chinese Yuan (Offshore)	China	√
CNY	Chinese Yuan	China		√
CZK	Czech Koruna	Czech Republic	√	√
DKK	Danish Krone	Denmark	√	√
EUR	Euro	SEPA Countries	√	√
GBP	Pound Sterling	United Kingdom	√	√
HKD	Hong Kong Dollar	Hong Kong	√	√
HUF	Hungarian Forint	Hungary	√	√
IDR	Indonesian Rupiah	Indonesia		√
ILS	Israeli Shekel	Israel	√
INR	Indian Rupee	India		√
JPY	Japanese Yen	Japan	√
KES	Kenyan Shilling	Kenya	√
KRW	South Korean Won	South Korea		√
KWD	Kuwaiti Dinar	Kuwait	√
MXN	Mexican Peso	Mexico	√
MYR	Malaysian Ringgit	Malaysia		√
NOK	Norwegian Krone	Norway	√	√
NZD	New Zealand Dollar	New Zealand	√	√
OMR	Omani Rial	Oman	√
PHP	Philippine Peso	Philippines		√
PLN	Polish Złoty	Poland	√	√
QAR	Qatari Rial	Qatar	√
RON	Romanian Leu	Romania	√	√
SAR	Saudi Riyal	Saudi Arabia	√
SEK	Swedish Krona	Sweden	√	√
SGD	Singapore Dollar	Singapore	√	√
THB	Thai Baht	Thailand	√	√
TRY	Turkish Lira	Turkey	√	√
UGX	Ugandan Shilling	Uganda	√
USD	US Dollar	United States	√	√
VND	Vietnamese Dong	Vietnam		√
ZAR	South African Rand	South Africa	√

The table above lists the currencies technically supported by our API. The final capability of money collection available is subject to the valid commercial agreement.

Fees and payment methods

Two distinct concepts are easy to confuse:

• chargeType is a field you set, and applies only to SWIFT payments. It decides who bears the SWIFT/intermediary fees:

  chargeType	Meaning
  SHARED	Fees are shared—deducted from both the payment amount and the payment fee
  OURS	The sender bears all fees—deducted from the payment fee only

• Payment method (the rail used) is determined automatically from the beneficiary and currency, not set by you:

  Method	Notes
  SWIFT	Global payments; chargeType applies
  Local	Local rails; fees deducted from the payment fee
  Inner	The beneficiary is also a CAPAY client (identified by uniquePayId / CAPAY FastID)—no fee is charged

Purpose codes

purposeCode describes the nature of the payment. Choose the code that matches both the transaction type and the payment's purpose.

Code	Description	B2B	B2C	C2B	C2C	Common scenarios
GOODS	Payment for goods	✅	✅	✅	❌	Purchasing inventory, buying equipment, product orders
SERVICES	Payment for services	✅	✅	✅	❌	Consulting fees, professional services, service contracts
SAVING	Transfer of savings (own account)	❌	❌	❌	✅	Moving funds to savings, internal account transfers
FAMILY	Transfer to friends / family	❌	❌	❌	✅	Sending money to family, gifts to friends, personal support
INTER_GROUP_TRANSFER	Inter-company transfer / repatriation of funds	✅	❌	❌	❌	Inter-company transfers, group fund movements, repatriation of profits
HIGH_VALUE_ITEM	High-value items (property, jewellery, vehicles)	✅	✅	✅	✅	Property purchases, jewelry transactions, vehicle purchases, luxury goods
INVESTMENT	Investment	✅	✅	✅	❌	Investment deposits, portfolio funding, capital investments
DEBT	Debt / debt repayment	✅	✅	✅	✅	Loan repayments, debt settlements, credit payments
COMPANY_MANAGE	Company management expenses (salary, rent, utilities)	✅	✅	❌	❌	Salary payments, rent payments, utility bills, office expenses
FREIGHT	Logistics / freight	✅	✅	✅	❌	Shipping fees, freight charges, logistics services, transportation costs

Transaction types

B2B Business to Business · B2C Business to Consumer · C2B Consumer to Business · C2C Consumer to Consumer

Applicability is product guidance for choosing the right code; it is not enforced by the schema.

Pay a new beneficiary in one call

POST /payments/with-beneficiary creates the payment and the beneficiary together. If a matching beneficiary already exists it is reused; otherwise a new one is created. Duplicate detection uses clientId + routing number + account number + account name + currency code.

Idempotency

Payment creation is a mutating operation—protect against duplicates:

• Send an x-idempotency-key header (≤ 36 chars) on the request. A repeated key returns 409 Duplicate idempotency key detected.
• Optionally set referenceId in the body for business-level deduplication; creation fails if a payment with the same referenceId already exists.

Payment status lifecycle

A payment moves through several states. All status changes trigger a webhook notification at least once.

Status	Cancelable	Description
PENDING APPROVAL	✅	Awaiting internal approval within the client's organisation (see below)
SCHEDULED	✅	Approved and queued for execution on the payment date
WAITING FUNDS	✅	Needs funding before it can be sent
SENDING	❌	Actively being transmitted through the payment network
COMPLETED	❌	[Final] Funds delivered to the beneficiary
CANCELLED	❌	[Final] Cancelled before sending (auto-refunded if funds were deducted)
FAILED	❌	[Final] Could not be completed (auto-refunded)
REJECTED	❌	[Final] Did not pass internal approval

Internal approval

PENDING APPROVAL is a client-side internal approval — it is not a CA review. It reflects the client's own authorisation workflow, for example a company user creates the payment and a company admin approves it before it proceeds.

CA supports two approval models, configured in the Client Portal under Risk Control → Limits Settings:

• Single-layer approval — one approver is required to authorise the payment.
• Dual-layer approval — two approvers must authorise the payment in sequence.

The applicable model and the payment amount thresholds that trigger approval are defined in Limits Settings. A payment enters PENDING APPROVAL when its amount exceeds the creator's approval limit under whichever model applies. If REJECTED by an approver, the payment moves to a final REJECTED state and is not processed.

Update or cancel a payment

• Update (PUT /payments/{id}) — amend paymentReference, paymentDate, purposeCode, sourceOfFunds, or invoice fields while the payment is still in progress.
• Cancel (PUT /payments/cancel/{id}) — only possible in SCHEDULED or WAITING FUNDS. Once SENDING, a payment cannot be cancelled. Cancelled payments are auto-refunded if funds were already deducted.

Retrieve payments

• GET /payments — list with filters (clientId, referenceNo, currencyCode, beneficiaryId, status, date/time ranges, pagination).
• GET /payments/{id} — fetch a single payment by ID or referenceId.