Authentication

Every CAPAY API request—except the /authenticate call itself—must carry a short-lived access token. You obtain that token by exchanging your API credentials (apiUser + apiKey), then send it as a Bearer token on all subsequent requests.

Environments

The authentication flow is identical in both environments; only the base URL changes. Make sure you are pointing at the right one.

Environment	Base URL
Sandbox	https://api.sandbox.capay.com.au
Production	https://api.capay.com.au

Use Sandbox to build and test your integration—no real money moves there. Switch to Production only once your workflow is verified.

Obtaining your credentials

Credentials are issued per environment by your Integration Support team, once your commercial agreement and KYB process are complete. The two sets are not interchangeable.

Sandbox. CA opens your Sandbox after the integration kickoff meeting. Your Sandbox apiUser and apiKey are sent to the developer email you nominate on your requirements sheet. That address cannot be changed afterwards, so we recommend a shared team inbox rather than one person's address.

Production. Once CA has reviewed and signed off your Sandbox integration, your Company Admin requests Production credentials by email. They must be an authorised user on your CA account, and CA issues the Production apiUser and apiKey to them—never to the developer email that received your Sandbox credentials. Your Company Admin then passes them to your technical team.

See the Integration Process for the full sequence.

Treat the apiKey like a password—it grants full access to your account.

Step 1 — Request an access token

Exchange your credentials at the /authenticate endpoint.

curl -X POST https://api.sandbox.capay.com.au/authenticate \
  -H "Content-Type: application/json" \
  -d '{
    "apiUser": "your-api-user",
    "apiKey": "your-api-key"
  }'

Success response (200 OK):

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresInSeconds": 3600
}

Field	Type	Description
accessToken	string	JWT bearer token to use on all authenticated requests
expiresInSeconds	number	Token lifetime in seconds (currently 3600 = 60 minutes)

Step 2 — Call an authenticated endpoint

Pass the token in the Authorization header, prefixed with Bearer .

curl https://api.sandbox.capay.com.au/accounts/balances \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Token lifecycle

Tokens expire 60 minutes after issue. When a request returns 401 Unauthorized, request a new token and retry.

note

There is no separate refresh endpoint. Re-authenticate with your apiUser and apiKey to obtain a fresh token.

Best practices

• Cache the token in memory and reuse it until it expires, rather than authenticating on every request.
• Re-authenticate reactively on a 401, and proactively shortly before the expiresInSeconds window elapses.
• Never expose your apiKey in client-side code, logs, or version control.
• Keep Sandbox and Production credentials separate—they are not interchangeable.