Client Management

As a Program Manager, a Client is an entity within your Tenant that you onboard, approve, and serve. You manage Clients through the /clients endpoints. Clients come in two types—business and personal.

Client lifecycle

Status	Meaning
PENDING APPROVAL	Created, awaiting your approval
ACTIVE	Approved and able to transact
INACTIVE	Not currently usable
SUSPENDED	Blocked from transacting

Create a business client

curl -X POST "https://api.sandbox.capay.com.au/clients/business" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "x-idempotency-key: unique-key-12345" \
  -d '{
    "countryCode": "AU",
    "name": "ABC Pty Ltd",
    "tradingName": "ABC",
    "businessType": "Australian Proprietary Company",
    "businessNumber": "66655577888",
    "beneficiaryOwnerFirstName": "John",
    "beneficiaryOwnerLastName": "Doe",
    "address": {
      "street": "19 Victoria Ave", "city": "Sydney",
      "state": "New South Wales", "zip": "2000"
    }
  }'

Required fields

Field	Description
countryCode	ISO 3166-1 alpha-2 country code
name	Registered client name
tradingName	Trading name
businessType	e.g. Australian Proprietary Company
businessNumber	Government business number (ABN — 11 digits in Australia)
beneficiaryOwnerFirstName / beneficiaryOwnerLastName	Beneficial owner
address	Registered address (street, city, state, zip)

Notable optional fields

Field	Description
companyNumber	Government company number (ACN — 9 digits in Australia)
businessNature	Nature of the business
contactEmail / contactNumber / businessPhone	Contact details
registerDate	Business registration date
website	Official website
transactionContinuation	ONEOFF or ONGOING (expected transaction profile)
expectedAnnualTransactionAmount / expectedAnnualTransactionCount	Expected volume when ONGOING
referenceId	Your unique reference for idempotency
note	Free-text note

Create a personal client

Use POST /clients/personal for individuals. Personal clients carry identity details (name, identification type and number) rather than business registration fields.

Approve a client

Newly created business clients start in PENDING APPROVAL and cannot transact until approved. Approval is Program Manager–only:

curl -X PATCH "https://api.sandbox.capay.com.au/clients/401f4647-8372-495f-8de0-aafb3e1eaf93" \
  -H "Authorization: Bearer <token>" \
  -H "x-idempotency-key: unique-key-12345"

On success the client moves to ACTIVE. You can subscribe to the CLIENT webhook event to be notified of status changes.

Retrieve, update, and delete

Action	Business	Personal
List	GET /clients/businesses	GET /clients/personal
Get by ID	GET /clients/business/{id}	GET /clients/personal/{id}
Update	PUT /clients/business/{id}	PUT /clients/personal/{id}
Delete	DELETE /clients/business/{id}	DELETE /clients/personal/{id}

Identifiers

Each client is assigned:

• id — the UUID you pass as clientId on other endpoints.
• clientNo — a human-readable client number (e.g. CAPAYAU-SYD-021233).
• uniquePayId — the CAPAY FastID used for fee-free internal transfers when paying another CAPAY client.

info

The isVerified boolean is deprecated—use status to determine whether a client is approved.