Securely authorize API requests using your Client ID and Client Secret credentials, and handle error responses.

Authentication & Errors

All Xtopay API requests must be authenticated using secure credentials passed in the HTTP headers. Requests made without authorization will fail.

Client ID & Client Secret

Xtopay uses a Client ID and Client Secret credential pair to identify and authorize API requests on behalf of your business. These keys are scoped by environment (Sandbox/Test Mode and Live Mode):

Credential	Format	Prefix / Length	Scope	Usage
Client ID	Hex String	12 characters	Client-Side / Server-Side	Public identifier for your integration.
Client Secret	Hex String	64 characters	Server-Side	Secure credential used to authorize API actions. Must be kept secret.

To retrieve or roll your API credentials, navigate to the Developer Settings > API Keys section in your dashboard.

[!CAUTION] Keep Client Secrets Safe Your Client Secret grants full access to your Xtopay wallet collections, direct debits, and disbursements. Never commit secrets to version control, expose them in client-side code, or distribute them inside frontend applications.

Authorization Header

Authenticate server-side API requests by combining your Client ID and Client Secret, base64-encoding the result, and passing it in the Authorization header. Xtopay's authentication middleware supports both the Basic and Bearer authorization schemes.

Step-by-Step Authorization Token Generation

Concatenate your Client ID and Client Secret with a colon (:):
```
YOUR_CLIENT_ID:YOUR_CLIENT_SECRET
```

Base64 Encode the concatenated string:

Base64("YOUR_CLIENT_ID:YOUR_CLIENT_SECRET")

Include the encoded token in the HTTP request headers:

Authorization: Basic Y2xpZW50SWQ6Y2xpZW50U2VjcmV0
Content-Type: application/json

Authentication Examples

Choose your language below to see how to programmatically generate the token and authenticate API requests:

# You can pass client_id and client_secret directly via curl basic auth using the -u flag
curl https://api.xtopay.co/v1/payments/pay_cl8z2e8z20000g \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -H "Accept: application/json"

API Key Permissions & Scopes

To enforce the principle of least privilege, you can restrict API keys to specific permissions. When generating keys in the Xtopay Dashboard, you can assign granular scopes:

Scope	Description
`payments:write`	Allowed to create payments, direct debits, bank transfers, and process refunds.
`payments:read`	Allowed to retrieve payments and query transaction history.
`customers:write`	Allowed to create and update customer profiles.
`customers:read`	Allowed to list and retrieve customer information.
`credits:write`	Allowed to grant and deduct credit balances.
`credits:read`	Allowed to retrieve wallet balances and ledgers.
`meters:write`	Allowed to define billing meters and ingest usage events.
`meters:read`	Allowed to view meters and fetch event history.
`licenses:write`	Allowed to create, activate, modify, and revoke license keys.
`licenses:read`	Allowed to read and validate license keys.

Error Handling

Xtopay uses standard HTTP response codes to indicate the success or failure of requests. In general:

Codes in the 2xx range indicate success.
Codes in the 4xx range indicate a client error (e.g. missing parameters, invalid inputs, or authentication failure).
Codes in the 5xx range indicate a server-side error with Xtopay's infrastructure or processor gateways.

Error Response Format

When an API call fails, Xtopay returns a descriptive JSON payload containing a success boolean and an error message detail:

{
  "success": false,
  "error": "amount must be a positive integer."
}

HTTP Status Codes

Status Code	Type	Description / Troubleshooting
`200 OK`	Success	The request succeeded.
`201 Created`	Success	The resource (payment, customer, license) was created successfully.
`400 Bad Request`	Client Error	Missing required fields, invalid parameter types, or malformed JSON payload.
`401 Unauthorized`	Client Error	Invalid, expired, or missing API credentials in the request header.
`403 Forbidden`	Client Error	The credentials are valid but lack the required scope (e.g., trying to write using a read-only key), or request originated from a non-whitelisted IP.
`404 Not Found`	Client Error	The requested resource (e.g., payment ID, customer ID) does not exist.
`409 Conflict`	Client Error	The action conflicts with the current state (e.g., trying to create a customer with an email address that already exists).
`429 Too Many Requests`	Client Error	You have hit the rate limit threshold. Please implement request throttling / backoff.
`500 Server Error`	Server Error	An error occurred on Xtopay's side or with downstream clearing houses. Retry in a few minutes or contact support.

Sample Error Payloads

401 Unauthorized (Invalid Format)

{
  "success": false,
  "message": "Invalid Token Format. Expected base64(clientId:clientSecret)."
}

401 Unauthorized (Invalid Credentials)

{
  "success": false,
  "message": "Invalid API Token or Token Expired"
}

403 Forbidden (Missing Scope)

{
  "success": false,
  "error": "Forbidden. This API key lacks the 'payments:write' scope required to perform this action."
}

404 Not Found (Resource Missing)

{
  "success": false,
  "error": "The requested payment resource 'pay_cl8z2e8z20000g' was not found."
}

429 Too Many Requests (Rate Limited)

{
  "success": false,
  "error": "Rate limit exceeded. You are limited to 100 API requests per second."
}

Authentication & Errors

On this page