Authentication

Every Pay-In request uses HTTP Basic authentication:

• Username: your api_key
• Password: your api_secret

You create both in the Developer Portal. All requests go over HTTPS and send and receive JSON.

curl

curl https://sandbox-api.cashela.com/api/v1/pay-in/deposit-creation/countries \
  -u "$CASHELA_API_KEY:$CASHELA_API_SECRET" \
  -H "Accept: application/json"

Node.js

Node.js

const auth = Buffer.from(`${process.env.CASHELA_API_KEY}:${process.env.CASHELA_API_SECRET}`).toString("base64");
const headers = {
  Authorization: `Basic ${auth}`,
  "Content-Type": "application/json",
  Accept: "application/json",
};

Python

# Python (requests)
import os, requests

session = requests.Session()
session.auth = (os.environ["CASHELA_API_KEY"], os.environ["CASHELA_API_SECRET"])
session.headers.update({"Accept": "application/json"})
r = session.get("https://sandbox-api.cashela.com/api/v1/pay-in/deposit-creation/countries")

PHP

// PHP (cURL)
curl_setopt($ch, CURLOPT_USERPWD, getenv('CASHELA_API_KEY') . ':' . getenv('CASHELA_API_SECRET'));

Java

// Java 11+ (java.net.http)
String credentials = System.getenv("CASHELA_API_KEY") + ":" + System.getenv("CASHELA_API_SECRET");
String auth = java.util.Base64.getEncoder()
    .encodeToString(credentials.getBytes(java.nio.charset.StandardCharsets.UTF_8));
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://sandbox-api.cashela.com/api/v1/pay-in/deposit-creation/countries"))
    .header("Authorization", "Basic " + auth)
    .header("Accept", "application/json")
    .GET()
    .build();

If your HTTP client does not build the header for you, send Authorization: Basic <base64(api_key:api_secret)>; the examples above do it for you.

Keep the secret on your server

Your api_secret also signs the notifications Cashela sends to your notification_url (see Webhooks). Anyone who has it can call the API as you and forge notifications. Never put it in a browser, a mobile app, a public repository or a log.

Use the right credentials for each environment

Environment	Base URL	Credentials
Sandbox	https://sandbox-api.cashela.com	A key from the Sandbox card
Production	https://production-api.cashela.com	A key from the Production card

When authentication fails

Response	Typical causes
401 {"success": false, "message": "Unauthorized."}	Missing credentials; wrong key or secret; credentials of the other environment; the key is Disabled or revoked; an old key used after its rotation grace period ended.
403 {"success": false, "message": "IP address is not allowed."}	The key has an IP whitelist and the request came from another address.
403 {"success": false, "message": "Insufficient permissions."}	The key is not allowed to use that endpoint. Contact Cashela support.
429	Too many requests. Wait the number of seconds in the Retry-After header before retrying.

Tip

If requests that used to work start answering 401, check the key’s Status in the Developer Portal first: a key that was disabled by mistake answers 401 Unauthorized. until you enable it again.

Caution

Failed authentication attempts in sandbox count against the Clean authentication go-live check. See Go live.

Trace IDs

Send your own correlation id in the optional X-Trace-Id header on every request (a UUID works well) and log it. Cashela generates one when you do not send it. Quote it, together with the deposit reference, when you contact support.

curl https://sandbox-api.cashela.com/api/v1/pay-in/transactions/210000000000 \
  -u "$CASHELA_API_KEY:$CASHELA_API_SECRET" \
  -H "X-Trace-Id: 6f1c2b7e-3a4d-4e5f-9a8b-1c2d3e4f5a6b"

Rate limits

The API limits how many requests a key can make. When you exceed a limit you get 429 Too Many Requests with a Retry-After header (seconds). Retry after that time, with exponential backoff and jitter for repeated 429s. Some endpoints have their own tighter limits; they are listed on each endpoint’s page.