API Authentication & Request Hygiene

Core Headers

Example

curl -X POST "$PAYCA_BASE_URL/v1/users" \
  -H "Content-Type: application/json" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET" \
  -H "Idempotency-Key: user-uuid-20250601" \
  -H "X-Request-ID: onboarding-0001" \
  -d '{"userId":"..."}'

PayCA stores Idempotency-Key for 24 hours per endpoint and tenant. Replays with the same key return the original response body and status.

Authentication Lifecycle

1. Sandbox – Keys are emailed after contracting. Rotate them if teammates leave the project.
2. Production – Keys are issued after a successful go-live review. Store them in a secrets manager; never commit to source control.
3. Rotation – Request new secrets via support. Old keys remain valid for 48 hours to allow smooth cutover.

Error Catalogue

PayCA wraps every error payload in a consistent envelope:

{
  "error": {
    "code": "ErrInvalidArg",
    "message": "cardId is required",
    "details": {
      "field": "cardId"
    }
  },
  "requestId": "7b4318c2-7d25-4f79-8393-f5e3d78a0c8d"
}

PayCA never reuses error codes for different classes of problems. Log the requestId for escalation.

Pagination

Most list endpoints accept limit (max 100) and cursor. Example:

curl -s "$PAYCA_BASE_URL/v1/users?limit=50&cursor=MjAyNS0wNi0wMlQxMzo0MjoyMVoi" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET"

Responses include nextCursor. Continue until it is empty. Avoid offset pagination for large datasets to prevent race conditions.

Rate Limiting & Retries

• Burst limit: 50 requests per second per client ID.
• Sustained limit: 1,500 requests per minute averaged over 5 minutes.
• Implement exponential backoff starting at 200ms up to 5 retries. Include jitter to avoid thundering herds.
• Webhook redelivery occurs automatically with a geometric backoff (5s → 10s → 20s → … up to 30 minutes).

Request Signing (Advanced)

For regulated tenants, PayCA can enforce HMAC body signatures. When enabled you must provide:

x-signature: sha256=<hex signature>

Construct the signature with HMAC-SHA256(secret, method + path + body). Support will specify when this is required.

Transport Security

• Enforce TLS 1.2 or higher.
• Pin PayCA certificates via DNS CAA or Mutual TLS (available on request).
• Whitelist PayCA IP ranges for webhook ingress.

Logging & Observability

• Capture requestId, status, duration, and error.code for every response.
• Tag events with environment so you can segregate sandbox noise.
• Alert on repeated ErrInternal or ErrRateLimited within a 1 minute window.

Testing Checklist

Master these conventions before wiring business logic. They protect your programme from accidental double posting, help us support your integration faster, and keep regulators satisfied with traceability.