Authentication
BchainPay uses bearer API keys. Include your key in the Authorization header on every request:
curl https://api.bchainpay.com/v1/payment-intents \
-H "Authorization: Bearer $BCHAINPAY_API_KEY"Mutating endpoints (POST, PUT, PATCH) also require Content-Type: application/json and an Idempotency-Key header — see Idempotency.
Key types
| Field | Type | Required | Description |
|---|---|---|---|
| sk_live_… | Secret | optional | Production key. Full read/write access to the live merchant account. |
| sk_sb_… | Secret | optional | Sandbox key. Full read/write access to the sandbox merchant account. Use this for development and testing. |
| pk_live_… | Public | optional | Production public key. Read-only. Safe to use in client-side code — cannot create or modify resources. |
Obtaining keys
- Sign in to the BchainPay dashboard.
- Navigate to Settings → API Keys.
- Select the environment — Production or Sandbox.
- Click Create key and copy the value immediately. The full key is only shown once.
Rotating keys
Rotate keys without downtime using this procedure:
- Issue a new key in the dashboard (Settings → API Keys → Create key).
- Deploy the new key to your servers alongside the old one.
- Cut over traffic to the new key.
- Revoke the old key from the dashboard.
Revocations take effect immediately. Do not revoke the old key until all in-flight requests have completed.
Required headers
Every API request needs the Authorization header. POST requests need two additional headers:
| Header | Required on | Example |
|---|---|---|
Authorization | All requests | Bearer sk_live_abc123… |
Content-Type | POST, PUT, PATCH | application/json |
Idempotency-Key | POST, PUT, PATCH | 550e8400-e29b-41d4-a716-446655440000 |
Auth errors
| Status | Code | Meaning |
|---|---|---|
401 | missing_authorization | Authorization header is absent or missing the Bearer prefix. |
401 | invalid_api_key | API key is not found, malformed, or revoked. |
403 | forbidden | Key does not have permission for this operation (e.g., a pk_live_ key on a write endpoint). |
429 | rate_limited | Per-merchant rate limit exceeded. Retry with exponential backoff. |
A 401 response returns:
{
"error": {
"code": "invalid_api_key",
"message": "Invalid API key"
},
"request_id": "req_7f2a91bc4e3d"
}