Rate Limiting and API Security Best Practices for Paychainly Integrations

Authentication Options

Paychainly supports two authentication methods for the /api/v1/* namespace:

// Option A: Header
x-api-key: pk_live_your_key_here

// Option B: Bearer token
Authorization: Bearer pk_live_your_key_here

Both are equivalent. Use whichever fits your HTTP client library best.

Rate Limits

The global limit is 120 requests per 60 seconds per API key. Auth and payment-creation endpoints have stricter per-route limits. Hitting the limit returns:

HTTP 429 Too Many Requests
{ "success": false, "statusCode": 429, "message": "ThrottlerException: Too Many Requests" }

Handling 429 in Your Client

async function withRetry(fn, maxAttempts = 3) {
  for (let i = 0; i < maxAttempts; i++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status === 429 && i < maxAttempts - 1) {
        await sleep(1000 * Math.pow(2, i)); // exponential backoff
        continue;
      }
      throw err;
    }
  }
}

API Key Best Practices

• Store keys in environment variables — never in source code.
• Use separate keys for production and staging.
• Set key expiry dates in the dashboard under Settings → API Keys.
• Rotate keys quarterly or after any suspected exposure.
• Restrict keys to specific IP ranges if your infrastructure allows it.

Webhook Endpoint Security

• Always verify the HMAC-SHA256 signature (see our signature guide).
• Return 200 OK only after processing — not before.
• Use idempotency keys to handle duplicate deliveries safely.