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

Your apiUser and apiKey are issued by your Integration Support team after your commercial agreement and KYB process are complete. 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.