API Authentication & Request Hygiene

Core Headers

Header	Required	Purpose
`x-client-id`	Always	Identifies your tenant; unique per environment.
`x-client-secret`	Always	Shared secret for API authentication and webhook HMAC verification.
`Idempotency-Key`	Recommended	Deduplicates write calls (`POST`/`PUT`/`PATCH`).
`X-Request-ID`	Optional	Trace identifier echoed in responses and webhooks.
`Content-Type`	Required for JSON payloads	Always `application/json`.

Example

curl -X POST "$PAYCA_BASE_URL/v1/cards" \
  -H "Content-Type: application/json" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET" \
  -H "Idempotency-Key: issue-20260212-001" \
  -H "X-Request-ID: bootstrap-0001" \
  -d '{
    "accountId": "94d3f571-a726-4cb5-9691-f471ed49b5bd",
    "bin": "411111",
    "balance": "50.00"
  }'

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

Sandbox: Keys are issued during onboarding.
Production: Keys are issued after go-live readiness review.
Rotation: Request new secrets via support; old keys remain valid for a controlled overlap period.

Error Catalogue

Error envelope:

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

Code	HTTP	Description	Retry?
`ErrInvalidArg`	400	Payload validation failure.	No
`ErrUnauthorized`	401	Missing or invalid credentials.	No
`ErrForbidden`	403	Credential lacks permission for action/environment.	No
`ErrNotFound`	404	Resource not present or not visible to tenant.	No
`ErrConflict`	409	Constraint violation or stale state.	Maybe
`ErrRateLimited`	429	Rate limit exceeded.	Yes, with backoff
`ErrInternal`	500	Unexpected server error.	Yes

Pagination

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

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

Continue until nextCursor is empty.

Rate Limiting & Retries

Burst: 50 requests/sec per client ID.
Sustained: 1,500 requests/min averaged over 5 minutes.
Use exponential backoff starting at 200ms (with jitter) up to 5 retries.
Webhooks are retried automatically with geometric backoff.

Request Signing (Advanced)

For regulated tenants, PayCA can enforce HMAC body signatures:

x-signature: sha256=<hex signature>

Signature formula: HMAC-SHA256(secret, method + path + body).

Transport Security

Enforce TLS 1.2+.
Use mTLS when required.
Whitelist PayCA IP ranges for webhook ingress.

Logging & Observability

Capture requestId, status, duration, and error.code.
Tag all events by environment.
Alert on repeated ErrInternal or ErrRateLimited spikes.

Testing Checklist

Scenario	Expectation
Missing credentials	401 + `ErrUnauthorized`.
Duplicate idempotency key replay	Same response body returned.
Pagination exhaustion	`nextCursor` becomes empty.
Rate limit exceeded	429 with `Retry-After`; client backs off.
Invalid signature	401 + `ErrUnauthorized`.

These conventions prevent double posting, simplify support escalations, and improve audit traceability.