Overview
The CardCash API uses a two-layer authentication system:
- Application Identity — The
x-cc-app header identifies your partner application
- Session Token — A JWT Bearer token that authenticates each request
Every API request must include:
| Header | Value | Description |
|---|
x-cc-app | Your application ID | Provided by your CardCash account manager |
Authorization | Bearer <token> | JWT session token (except for POST /session) |
Content-Type | application/json | Required for POST/PUT requests |
Creating a Session
To get a session token, call POST /session with only the x-cc-app header:
curl -X POST https://sandbox-api.cardcash.com/v3/session \
-H "x-cc-app: YOUR_APP_ID" \
-H "Content-Type: application/json"
Response
{
"access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresInSeconds": 3600,
"sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"renderAssets": true
}
| Header | Description |
|---|
authorization | The JWT token (same as access_token in body) |
x-token-exp-seconds | Seconds until token expires |
x-session-id | Session identifier |
Using the Token
Include the token as a Bearer token on all subsequent requests:
curl https://sandbox-api.cardcash.com/v3/merchants/buy \
-H "x-cc-app: YOUR_APP_ID" \
-H "Authorization: Bearer eyJhbGciOiJFUzI1NiIs..."
Token Auto-Refresh
The API automatically refreshes your token when it is close to expiration (within approximately 5 minutes of expiry). When a refresh occurs, the response headers will contain the new token:
authorization — Contains the updated token. Store and use this for subsequent requests.x-token-exp-seconds — Seconds remaining on the new token.
Most responses will NOT include a new token — only those where the server detects the token is near expiry. Your client should check for the authorization header on every response and store the new token when present.
If you ignore the refreshed token in the response headers, your session will expire and you’ll need to call POST /session again.
Token Expiration
When a token expires, the API responds with:
{
"message": ["no Authorization token was found"]
}
400
To recover, call POST /session again to get a fresh token.
Login
After establishing a session, log in to access account-specific features (orders, wallet, payment methods):
curl -X POST https://sandbox-api.cardcash.com/v3/customers/login \
-H "x-cc-app: YOUR_APP_ID" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"customer": {
"email": "partner@example.com",
"password": "SecurePass123"
}
}'
Authentication Errors
| Status | Message | Cause |
|---|
| 400 | "no Authorization token was found" | Token expired or missing |
| 401 | "Unauthorized" | Missing x-cc-app header or User-Agent header |
| 400 | "no x-cc-app was found" | x-cc-app header missing from session request |
