Client Credentials

Obtaining credentials

Log in to app.xtopay.co
Go to Settings → API Credentials
Click Generate credentials if this is your first time
Copy both the Client ID and Client Secret immediately — the secret is shown only once

If you lose your Client Secret, you must rotate it. The existing secret cannot be retrieved again.

Credential format

Client ID:     cid_{env}_{32 random alphanumeric characters}
Client Secret: csk_{env}_{64 random alphanumeric characters}

Examples:
  cid_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
  csk_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6aa1bb2cc3dd4

The {env} segment is either test (sandbox) or live (production).

Using credentials

SDK (recommended)

import Xtopay from "@xtopay/node";

const xtopay = new Xtopay({
  clientId: process.env.XTOPAY_CLIENT_ID!,
  clientSecret: process.env.XTOPAY_CLIENT_SECRET!,
});

Raw HTTP

Encode client_id:client_secret as Base64 and send in the Authorization header:

const encoded = Buffer.from(
  `${clientId}:${clientSecret}`
).toString("base64");

fetch("https://api.xtopay.co/v1/payments", {
  headers: { "Authorization": `Basic ${encoded}` },
});

import base64, requests

credentials = base64.b64encode(f"{client_id}:{client_secret}".encode()).decode()

requests.post(
    "https://api.xtopay.co/v1/payments",
    headers={"Authorization": f"Basic {credentials}"},
    json={...},
)

curl https://api.xtopay.co/v1/payments \
  -u "$XTOPAY_CLIENT_ID:$XTOPAY_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000, "currency": "GHS", ...}'

You can create multiple credential pairs — for example, one per micro-service or one per team. Each pair is independently revocable. Go to Settings → API Credentials → Add credentials to create additional pairs.

Label each pair clearly (e.g., "Billing service", "Mobile app backend") so you know which to revoke if one is compromised.

Rotating credentials

Rotate a Client Secret without downtime:

Go to Settings → API Credentials
Click Rotate next to the credential pair
Xtopay issues a new secret while the old one stays valid for 15 minutes
Update your environment variables / secrets manager with the new secret
The old secret expires automatically after 15 minutes

If you suspect a secret has been compromised, use Revoke immediately instead of Rotate. This invalidates the old secret instantly.

Security best practices

Store credentials in a secrets manager (AWS Secrets Manager, HashiCorp Vault, Doppler) rather than in plain .env files in production
Never log the full Client Secret — log only the first 8 characters for debugging
Set up alerts for unexpected API usage spikes in the dashboard under Settings → Alerts
Rotate secrets every 90 days as a baseline hygiene practice