Authentication & Headers

All API requests must be authenticated with two headers. Requests without valid credentials will fail.

Required Headers

apiKey:        <YOUR_API_KEY>
x-api-secret:  <YOUR_API_SECRET>

• apiKey – identifies your account (safe to log on server).
• x-api-secret – proves the request is authorized (treat as a password; never expose in browsers/mobile apps).

Tip: Keep secrets server-side only. Use environment variables or a secret manager.

Example (cURL)

curl -X POST "$BASE_URL/checkout/session" \
  -H "apiKey: $API_KEY" \
  -H "x-api-secret: $API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 125.50,
    "currencyType": "USDT-TRC20",
    "callbackUrl": "https://your-domain.com/payments/callback"
  }'

Example (HTTP request)

POST {BASE_URL}/checkout/session
Headers:
  apiKey: <YOUR_API_KEY>
  x-api-secret: <YOUR_API_SECRET>
  Content-Type: application/json

Body:
{
  "amount": 125.50,
  "currencyType": "USDT-TRC20",
  "callbackUrl": "https://your-domain.com/payments/callback"
}

Environments & Keys

• Sandbox base URL: https://sandbox.pay.3pa-y.com
• Production base URL: https://pay.3pa-y.com

You’ll have separate key pairs for Sandbox and Production. Generate/rotate keys in the Dashboard. Do not reuse Sandbox keys in Production.

Security Best Practices

• Do not place x-api-secret in client-side code, public repos, or logs.
• Rotate secrets immediately if you suspect exposure.
• Lock down your callbackUrl to HTTPS and validate the request origin.
• Prefer allowlisting your server IPs (if your infrastructure supports it).

If you enable webhook signatures in your account, verify them on receipt (see Webhooks & Callbacks → Signature Verification).

Common Auth Errors

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "INVALID_AUTH",
    "message": "Missing or invalid credentials",
    "details": {}
  }
}

403 Forbidden

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Key not allowed for this environment",
    "details": {}
  }
}

How to resolve

• Confirm you’re using the correct base URL for the key (Sandbox vs Production).
• Check both headers are present and spelled exactly: apiKey, x-api-secret.
• Ensure the key pair is active and not revoked/rotated.