API reference

Every operation BitriPay publishes, in the order you will meet them: what it does, which scope it needs, what it takes and what it returns. This page and the OpenAPI document are generated from the same table, so they cannot disagree.

Version 2026-09-01Operations 116Groups 28Webhook events 45OpenAPI 3.1 JSON Signing keys Status

Before the first call

Base URL

https://www.bitripay.com/api/v1

https://www.bitripay.com/v1

Test and live keys share it; the key decides which world you are in.

Authentication

Authorization: Bearer sk_test_… on every call.

sk_live_/sk_test_ secret keys, rk_ restricted keys with scopes, pk_ publishable keys.

The 40 scopes, and which operation each one opens.

Idempotency

Operations marked Idempotency-Key require that header. A replay returns the same object; the same key with a different body is refused with idempotency_key_reused. Keys expire after 24 hours.

Amounts

Integers in minor units, with the currency beside them: 250000 + CDF is 2 500,00 CDF. No floating point anywhere in the API.

Errors

Every failure returns the same envelope: error.code, error.bp and error.message. Branch on bp — it is stable across releases.

Acting for a customer

Send BitriPay-Account: acct_… with your own key to run any operation for a connected account. Your scopes still apply, and the customer stays the merchant of record.

No operation matches that filter.

Payment intents

10 operations.

GET/payment_intentspayment_intents:read

List payment intents

Parameters (2)

Name	In	Type	Required
`status`	query	string	optional
`limit`	query	string	optional

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/payment_intents?status=&limit= \
  -H "Authorization: Bearer sk_test_..."

POST/payment_intentspayment_intents:writeIdempotency-Key

Create a payment intent (returns checkout_url, qr_payload and client_secret)

Request body (17 fields)

Field	Type	Accepted values	Notes
`amount_minor`	integer	—	—
`currency`	string	—	—
`rails`	array of string	—	—
`capture_method`	string	`automatic` · `manual`	—
`payment_method_policy`	string	`smart` · `cheapest` · `fastest` · `most_reliable`	—
`reference`	string	—	—
`description`	string	—	—
`purpose_code`	string	`GENERAL_MERCHANT` · `SCHOOL` · `HEALTH` · `RENT` · `UTILITY` · `CONSTRUCTION` · `GOVERNMENT_FEE` · `TAX` · `DONATION` · `REMITTANCE` · `TRANSPORT` · `MARKET`	—
`expires_in_minutes`	integer	—	—
`metadata`	object	—	—
`customer_msisdn`	string	—	—
`customer_country`	string	—	—
`success_url`	string	—	—
`cancel_url`	string	—	—
`qr`	boolean	—	—
`splits`	array of object { recipient, bps, fixed_minor, label }	—	—
`application_fee_minor`	integer	—	Platform fee kept when acting for a connected account (BitriPay-Account header); defaults to the account rate

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/payment_intents \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
       "amount_minor": 250000,
       "currency": "CDF",
       "rails": [
         "national_switch"
       ],
       "capture_method": "automatic",
       "payment_method_policy": "smart",
       "reference": "order-1042",
       "description": "Order 1042",
       "purpose_code": "GENERAL_MERCHANT",
       "expires_in_minutes": 30,
       "metadata": {
         "order": "A-1042"
       },
       "customer_msisdn": "+243810000000",
       "customer_country": "CD",
       "success_url": "https://example.com/return",
       "cancel_url": "https://example.com/return",
       "qr": true,
       "splits": [
         {
           "recipient": "acct_...",
           "bps": 150,
           "fixed_minor": 250000,
           "label": "Order 1042"
         }
       ],
       "application_fee_minor": 250000
     }'

GET/payment_intents/{id}payment_intents:read

Retrieve a payment intent

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/payment_intents/{id} \
  -H "Authorization: Bearer sk_test_..."

POST/payment_intents/{id}/cancelpayment_intents:write

Cancel an intent that has not been captured

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/payment_intents/{id}/cancel \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

POST/payment_intents/{id}/capturepayment_intents:writeIdempotency-Key

Capture an AUTHORISED intent (capture_method manual); optional partial amount, the rest returns to the payer

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Request body (1 fields)

Field	Type	Accepted values	Notes
`amount_minor`	integer	—	—

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/payment_intents/{id}/capture \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
       "amount_minor": 250000
     }'

GET/payment_intents/{id}/methodspayment_intents:read

Payment methods available to the payer for this intent

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/payment_intents/{id}/methods \
  -H "Authorization: Bearer sk_test_..."

GET/payment_intents/{id}/split_refundspayment_intents:read

What each split recipient gave back on the refunds of an intent (pro_rata) or kept (merchant_absorbs)

Parameters (2)

Name	In	Type	Required
`id`	path	string	required
`refund`	query	string	optional

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/payment_intents/{id}/split_refunds?refund= \
  -H "Authorization: Bearer sk_test_..."

POST/payment_intents/{id}/split_refunds/retrypayment_intents:write

Retry failed split refund recoveries

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/payment_intents/{id}/split_refunds/retry \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

GET/payment_intents/{id}/splitspayment_intents:read

Split payouts made from a captured intent

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/payment_intents/{id}/splits \
  -H "Authorization: Bearer sk_test_..."

GET/payment_intents/{id}/timelinepayment_intents:read

Every state change and attempt of an intent

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/payment_intents/{id}/timeline \
  -H "Authorization: Bearer sk_test_..."

Refunds

5 operations.

GET/payment_intents/{id}/refundablerefunds:read

Amount still refundable on an intent

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/payment_intents/{id}/refundable \
  -H "Authorization: Bearer sk_test_..."

GET/refundsrefunds:read

List refunds

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/refunds \
  -H "Authorization: Bearer sk_test_..."

POST/refundsrefunds:writeIdempotency-Key

Refund a captured intent (atomic reservation; wallet or processor)

Request body (3 fields)

Field	Type	Accepted values	Notes
`payment_intent`	string	—	—
`amount_minor`	integer	—	—
`reason`	string	—	—

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/refunds \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
       "payment_intent": "pi_...",
       "amount_minor": 250000,
       "reason": "Order 1042"
     }'

GET/refunds/{id}refunds:read

Retrieve a refund

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/refunds/{id} \
  -H "Authorization: Bearer sk_test_..."

POST/refunds/{id}/rejectrefunds:write

Reject a refund awaiting execution (REQUESTED / APPROVED): reservation released, intent keeps its prior state

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Request body (1 fields)

Field	Type	Accepted values	Notes
`reason`	string	—	at least 3 characters, at most 200 characters

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/refunds/{id}/reject \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
       "reason": "Order 1042"
     }'

Checkout

4 operations.

GET/checkout_sessionspayment_intents:read

List checkout sessions

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/checkout_sessions \
  -H "Authorization: Bearer sk_test_..."

POST/checkout_sessionscheckout_sessions:writeIdempotency-Key

Create a hosted checkout session with line items

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/checkout_sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" -d '{}'

GET/checkout_sessions/{id}payment_intents:read

Retrieve a checkout session

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/checkout_sessions/{id} \
  -H "Authorization: Bearer sk_test_..."

POST/checkout_sessions/{id}/expirecheckout_sessions:write

Expire an open session

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/checkout_sessions/{id}/expire \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

Payment links

3 operations.

GET/payment_linkspayment_links:write

List payment links

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/payment_links \
  -H "Authorization: Bearer sk_test_..."

POST/payment_linkspayment_links:writeIdempotency-Key

Create a single-use or reusable payment link

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/payment_links \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" -d '{}'

POST/payment_links/{id}/deactivatepayment_links:write

Deactivate a link

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/payment_links/{id}/deactivate \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

QR

8 operations.

GET/keysno scope

Public signing-key registry (ed25519, ETag cached)

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/keys \
  -H "Authorization: Bearer sk_test_..."

POST/locationsqr_codes:write

Create a merchant location

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/locations \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

POST/locations/{id}/terminalsqr_codes:write

Add a terminal to a location

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/locations/{id}/terminals \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

GET/qr_codesqr_codes:read

List QR codes

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/qr_codes \
  -H "Authorization: Bearer sk_test_..."

POST/qr_codesqr_codes:write

Create a static BitriQR (EMVCo + signed extension)

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/qr_codes \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

POST/qr_codes/{id}/revokeqr_codes:write

Revoke a code (lost, stolen, tampered, replaced, retired)

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/qr_codes/{id}/revoke \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

GET/qr_codes/analyticsqr_codes:read

Scan analytics

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/qr_codes/analytics \
  -H "Authorization: Bearer sk_test_..."

POST/resolveno scope

Resolve any scanned payload (public; trust from the key registry)

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/resolve \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

Verifications (KODA)

3 operations.

GET/payment_resolutionverifications:write

Did this payment happen? CONFIRMED (ledger posting), PENDING, AMBIGUOUS or NOT_FOUND, with the matches

Parameters (5)

Name	In	Type	Required
`reference`	query	string	optional
`msisdn`	query	string	optional
`amount_minor`	query	string	optional
`currency`	query	string	optional
`window_hours`	query	string	optional

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/payment_resolution?reference=&msisdn=&amount_minor=&currency=&window_hours= \
  -H "Authorization: Bearer sk_test_..."

POST/verificationsverifications:write

Scan-to-Verify: did a payment reach me? (reference, or MSISDN + amount)

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/verifications \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

GET/verifications/quotaverifications:write

Free quota and price

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/verifications/quota \
  -H "Authorization: Bearer sk_test_..."

Wallets

1 operation.

GET/walletswallets:read

Wallet balances with the available amount after holds

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/wallets \
  -H "Authorization: Bearer sk_test_..."

Transfers

3 operations.

POST/transferstransfers:writeIdempotency-Key

Send from the wallet to another BitriPay account

Request body (4 fields)

Field	Type	Accepted values	Notes
`to`	string	—	—
`amount_minor`	integer	—	—
`currency`	string	—	—
`note`	string	—	—

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/transfers \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
       "to": "...",
       "amount_minor": 250000,
       "currency": "CDF",
       "note": "Order 1042"
     }'

GET/transfers/{id}transfers:read

Retrieve a transfer

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/transfers/{id} \
  -H "Authorization: Bearer sk_test_..."

POST/transfers/quotetransfers:write

Quote a transfer with the full fee and FX disclosure, plus rails ranked by the smart router

Request body (6 fields)

Field	Type	Accepted values	Notes
`amount_minor`	integer	—	—
`currency`	string	—	—
`target_currency`	string	—	—
`destination`	object	—	—
`source_method`	string	`wallet` · `card` · `mobile_money` · `bank`	—
`policy`	string	`smart` · `cheapest` · `fastest` · `most_reliable`	—

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/transfers/quote \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
       "amount_minor": 250000,
       "currency": "CDF",
       "target_currency": "CDF",
       "destination": {
         "order": "A-1042"
       },
       "source_method": "wallet",
       "policy": "smart"
     }'

Cross-border routes

7 operations.

GET/routesroutes:read

List routes

Parameters (1)

Name	In	Type	Required
`limit`	query	string	optional

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/routes?limit= \
  -H "Authorization: Bearer sk_test_..."

POST/routesroutes:writeIdempotency-Key

Create a route: the funding leg runs through the processor (card / bank / mobile money) or the wallet, the payout leg follows automatically once funds are confirmed

Request body (8 fields)

Field	Type	Accepted values	Notes
`amount_minor`	integer	—	—
`currency`	string	—	—
`target_currency`	string	—	—
`source`	object	—	—
`destination`	object	—	—
`note`	string	—	—
`quote_id`	string	—	—
`source_of_funds`	string	—	—

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/routes \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
       "amount_minor": 250000,
       "currency": "CDF",
       "target_currency": "CDF",
       "source": {
         "order": "A-1042"
       },
       "destination": {
         "order": "A-1042"
       },
       "note": "Order 1042",
       "quote_id": "...",
       "source_of_funds": "..."
     }'

GET/routes/{id}routes:read

Retrieve a route with its stage, quote, funding payment and payout

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/routes/{id} \
  -H "Authorization: Bearer sk_test_..."

POST/routes/{id}/cancelroutes:write

Cancel before the payout is executed (funds return; card funding refunded where the processor allows)

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Request body (1 fields)

Field	Type	Accepted values	Notes
`reason`	string	—	—

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/routes/{id}/cancel \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
       "reason": "Order 1042"
     }'

GET/routes/{id}/receiptroutes:read

Receipt for a settled route

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/routes/{id}/receipt \
  -H "Authorization: Bearer sk_test_..."

POST/routes/payout-currenciesroutes:read

Which currencies the recipient can receive for a destination right now (corridor rules, licence, liquidity)

Request body (4 fields)

Field	Type	Accepted values	Notes
`amount_minor`	integer	—	—
`currency`	string	—	—
`destination`	object	—	—
`requested`	string	—	—

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/routes/payout-currencies \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
       "amount_minor": 250000,
       "currency": "CDF",
       "destination": {
         "order": "A-1042"
       },
       "requested": "..."
     }'

POST/routes/quoteroutes:read

Quote any → any: fund from the wallet or any card / bank / mobile money, deliver to a wallet, QR, bank account, mobile money number or agent anywhere, in the currency the recipient will receive; rate, margin and every fee disclosed

Request body (5 fields)

Field	Type	Accepted values	Notes
`amount_minor`	integer	—	—
`currency`	string	—	—
`target_currency`	string	—	—
`source`	object { method, gateway, operator_id }	—	—
`destination`	object { method }	—	—

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/routes/quote \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
       "amount_minor": 250000,
       "currency": "CDF",
       "target_currency": "CDF",
       "source": {
         "method": "wallet",
         "gateway": "...",
         "operator_id": "..."
       },
       "destination": {
         "method": "wallet"
       }
     }'

Remittances

3 operations.

GET/remittancesremittances:read

List remittances

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/remittances \
  -H "Authorization: Bearer sk_test_..."

POST/remittancesremittances:writeIdempotency-Key

Send an international transfer to a wallet, bank account, mobile money number or cash pickup in the recipient currency; add a `source` (any card, bank or mobile money) to fund it through a processor instead of the wallet

Request body (7 fields)

Field	Type	Accepted values	Notes
`amount_minor`	integer	—	—
`currency`	string	—	—
`target_currency`	string	—	—
`payout_method`	string	`wallet` · `bank` · `mobile_money` · `cash_pickup`	—
`recipient`	object { name, country, phone, tag, operator_id, bank_name, account_number, bank_account_id }	—	—
`source`	object { method, card, saved_card_id, gateway, operator_id, phone }	—	—
`note`	string	—	—

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/remittances \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
       "amount_minor": 250000,
       "currency": "CDF",
       "target_currency": "CDF",
       "payout_method": "wallet",
       "recipient": {
         "name": "...",
         "country": "CD",
         "phone": "+243810000000",
         "tag": "...",
         "operator_id": "...",
         "bank_name": "...",
         "account_number": "acct_...",
         "bank_account_id": "acct_..."
       },
       "source": {
         "method": "wallet",
         "card": {
           "order": "A-1042"
         },
         "saved_card_id": "...",
         "gateway": "...",
         "operator_id": "...",
         "phone": "+243810000000"
       },
       "note": "Order 1042"
     }'

GET/remittances/quoteremittances:read

Quote an international transfer

Parameters (3)

Name	In	Type	Required
`amount_minor`	query	string	optional
`currency`	query	string	optional
`target_currency`	query	string	optional

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/remittances/quote?amount_minor=&currency=&target_currency= \
  -H "Authorization: Bearer sk_test_..."

Bulk payouts

6 operations.

GET/payouts/batchespayouts:read

List payout batches

Parameters (2)

Name	In	Type	Required
`status`	query	string	optional
`limit`	query	string	optional

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/payouts/batches?status=&limit= \
  -H "Authorization: Bearer sk_test_..."

POST/payouts/batchespayouts:writeIdempotency-Key

Upload a payout batch (rows or CSV); every row is validated and the totals are returned before approval

Request body (6 fields)

Field	Type	Accepted values	Notes
`currency`	string	—	—
`rows`	array of object	—	—
`csv`	string	—	—
`reference`	string	—	—
`note`	string	—	—
`skip_invalid`	boolean	—	—

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/payouts/batches \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
       "currency": "CDF",
       "rows": [
         {
           "order": "A-1042"
         }
       ],
       "csv": "...",
       "reference": "order-1042",
       "note": "Order 1042",
       "skip_invalid": true
     }'

GET/payouts/batches/{id}payouts:read

Retrieve a batch with its rows and readiness (funds, invalid rows, approval rule)

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/payouts/batches/{id} \
  -H "Authorization: Bearer sk_test_..."

POST/payouts/batches/{id}/approvepayouts:approve

Approve and execute a batch: four-eyes by another account holder, or the creator under PIN / passkey step-up

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Request body (1 fields)

Field	Type	Accepted values	Notes
`pin`	string	—	—

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/payouts/batches/{id}/approve \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
       "pin": "0000"
     }'

POST/payouts/batches/{id}/cancelpayouts:write

Cancel a batch awaiting approval

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/payouts/batches/{id}/cancel \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

GET/payouts/batches/columnspayouts:read

CSV columns accepted for a batch upload

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/payouts/batches/columns \
  -H "Authorization: Bearer sk_test_..."

Agents

2 operations.

POST/ai/{agent}ai:run

Run an agent (canonical names such as RouteOptimiser, FraudScorer, SavingsAdvisor accepted); metered in ACU, provider and model never disclosed

Parameters (1)

Name	In	Type	Required
`agent`	path	string	required

Request body (4 fields)

Field	Type	Accepted values	Notes
`input`	string	—	—
`context`	object	—	—
`depth`	string	`standard` · `deep`	—
`wait`	boolean	—	—

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/ai/{agent} \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
       "input": "...",
       "context": {
         "order": "A-1042"
       },
       "depth": "standard",
       "wait": true
     }'

GET/ai/runs/{id}ai:run

Retrieve an agent run

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/ai/runs/{id} \
  -H "Authorization: Bearer sk_test_..."

Subscriptions

9 operations.

GET/invoicessubscriptions:read

List invoices

Parameters (1)

Name	In	Type	Required
`limit`	query	string	optional

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/invoices?limit= \
  -H "Authorization: Bearer sk_test_..."

GET/planssubscriptions:read

List your subscription plans

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/plans \
  -H "Authorization: Bearer sk_test_..."

POST/planssubscriptions:write

Create a plan (interval, trial, tax, metered usage)

Request body (11 fields)

Field	Type	Accepted values	Notes
`name`	string	—	—
`currency`	string	—	—
`amount_minor`	integer	—	—
`interval`	string	`day` · `week` · `month` · `year`	—
`interval_count`	integer	—	—
`trial_days`	integer	—	—
`tax_bps`	integer	—	—
`tax_label`	string	—	—
`usage_unit`	string	—	—
`usage_price_minor`	integer	—	—
`code`	string	—	—

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/plans \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
       "name": "...",
       "currency": "CDF",
       "amount_minor": 250000,
       "interval": "day",
       "interval_count": 20,
       "trial_days": 1,
       "tax_bps": 150,
       "tax_label": "Order 1042",
       "usage_unit": "...",
       "usage_price_minor": 250000,
       "code": "..."
     }'

GET/plans/{id}subscriptions:read

Retrieve a plan

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/plans/{id} \
  -H "Authorization: Bearer sk_test_..."

POST/plans/{id}/archivesubscriptions:write

Stop offering a plan (existing subscriptions continue)

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/plans/{id}/archive \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

GET/subscriptionssubscriptions:read

List subscriptions with a billing overview (recurring revenue, collections, dunning)

Parameters (2)

Name	In	Type	Required
`status`	query	string	optional
`limit`	query	string	optional

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/subscriptions?status=&limit= \
  -H "Authorization: Bearer sk_test_..."

GET/subscriptions/{id}subscriptions:read

Retrieve a subscription with its invoices

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/subscriptions/{id} \
  -H "Authorization: Bearer sk_test_..."

POST/subscriptions/{id}/cancelsubscriptions:write

Cancel at period end (or immediately)

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Request body (1 fields)

Field	Type	Accepted values	Notes
`immediately`	boolean	—	—

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/subscriptions/{id}/cancel \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
       "immediately": true
     }'

POST/subscriptions/{id}/usagesubscriptions:write

Record metered usage for the current period

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Request body (2 fields)

Field	Type	Accepted values	Notes
`quantity`	integer	—	—
`note`	string	—	—

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/subscriptions/{id}/usage \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
       "quantity": 1,
       "note": "Order 1042"
     }'

Credit readiness

1 operation.

GET/credit_readiness/{code}credit:read

Read a consented credit-readiness signal (score, band, factors); never the transactions, never a lending decision

Parameters (1)

Name	In	Type	Required
`code`	path	string	required

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/credit_readiness/{code} \
  -H "Authorization: Bearer sk_test_..."

Payouts

2 operations.

GET/payoutspayouts:read

List payouts

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/payouts \
  -H "Authorization: Bearer sk_test_..."

POST/payoutspayouts:writeIdempotency-Key

Pay out to a bank account or mobile-money number

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/payouts \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" -d '{}'

Balance

2 operations.

GET/balancebalance:read

Balance classes: available, pending, reserved, settlement_pending, held, disputed, frozen

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/balance \
  -H "Authorization: Bearer sk_test_..."

GET/transactions/{id}balance:read

A ledger transaction with its balanced entries and the payment intent it settled

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/transactions/{id} \
  -H "Authorization: Bearer sk_test_..."

Settlement

10 operations.

GET/settlement_calendarsettlements:read

Upcoming cut-offs, obligations and recent cycles

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/settlement_calendar \
  -H "Authorization: Bearer sk_test_..."

GET/settlement_cyclessettlements:read

List cycles

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/settlement_cycles \
  -H "Authorization: Bearer sk_test_..."

POST/settlement_cyclessettlements:write

Close the running period now (optionally pay)

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/settlement_cycles \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

POST/settlement_cycles/{id}/paysettlements:write

Pay a closed cycle to its destination

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/settlement_cycles/{id}/pay \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

GET/settlement_cycles/{id}/statementsettlements:read

Numbered, hashed statement (format=json|csv|pdf)

Parameters (2)

Name	In	Type	Required
`id`	path	string	required
`format`	query	string	optional

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/settlement_cycles/{id}/statement?format= \
  -H "Authorization: Bearer sk_test_..."

GET/settlement_profilessettlements:read

Settlement profiles per rail and currency

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/settlement_profiles \
  -H "Authorization: Bearer sk_test_..."

POST/settlement_profilessettlements:write

Create or update a profile (T0/T1/T2/weekly/manual, cut-off, destination, minimum)

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/settlement_profiles \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

GET/settlement_profiles/{id}settlements:read

Retrieve a settlement profile (settlement_currency, auto_convert)

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/settlement_profiles/{id} \
  -H "Authorization: Bearer sk_test_..."

GET/settlement_profiles/{id}/previewsettlements:read

What the next cycle of a profile would settle now: collection-currency totals with the fee lines, and the conversion into the settlement currency (rate, mid rate, margin bps)

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/settlement_profiles/{id}/preview \
  -H "Authorization: Bearer sk_test_..."

GET/settlements/{id}settlements:read

A settlement (cycle) with its items and statement summary: provider fee, BitriPay fee and tax on it as separate lines, plus the disclosed conversion when the settlement currency differs

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/settlements/{id} \
  -H "Authorization: Bearer sk_test_..."

Disputes

3 operations.

GET/disputesdisputes:read

Disputes against my payments

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/disputes \
  -H "Authorization: Bearer sk_test_..."

POST/disputesdisputes:write

Open a dispute on a payment I received

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/disputes \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

POST/disputes/{id}/responddisputes:write

Respond with evidence before the deadline

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/disputes/{id}/respond \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

Webhooks

6 operations.

GET/eventsevents:read

Event log

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/events \
  -H "Authorization: Bearer sk_test_..."

POST/events/{id}/replaywebhooks:manage

Replay an event to every endpoint

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/events/{id}/replay \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

POST/webhook_deliveries/{id}/replaywebhooks:manage

Replay a delivery

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/webhook_deliveries/{id}/replay \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

POST/webhook_endpointswebhooks:manage

Create an endpoint (returns whsec_ secret once)

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

GET/webhook_endpoints/{id}/deliverieswebhooks:manage

Deliveries with attempts and status

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/webhook_endpoints/{id}/deliveries \
  -H "Authorization: Bearer sk_test_..."

GET/webhook_events/typesno scope

Event catalogue with the receiver rules (`notes`): at-least-once, dedupe by event id

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/webhook_events/types \
  -H "Authorization: Bearer sk_test_..."

Keys

3 operations.

GET/api_keysno scope

List API keys (session only; keys cannot mint keys)

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/api_keys \
  -H "Authorization: Bearer sk_test_..."

POST/api_keysno scope

Create sk_ / rk_ / pk_ key with scopes

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/api_keys \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

POST/api_keys/{id}/rotateno scope

Rotate a key (same label, kind, scopes, allowlist; old secret revoked). Live keys need PIN / passkey step-up (403 step_up_required)

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Request body (1 fields)

Field	Type	Accepted values	Notes
`pin`	string	—	—

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/api_keys/{id}/rotate \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
       "pin": "0000"
     }'

Sandbox

1 operation.

GET/sandboxno scope

Magic MSISDNs and simulated outcomes

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/sandbox \
  -H "Authorization: Bearer sk_test_..."

Offline

5 operations.

POST/offline/devicesno scope

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/offline/devices \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

POST/offline/noncesno scope

Prefetch nonces for a merchant device

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/offline/nonces \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

GET/offline/promisesno scope

My offline promises

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/offline/promises \
  -H "Authorization: Bearer sk_test_..."

POST/offline/qrqr_codes:write

Server-signed offline QR with nonce

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/offline/qr \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

POST/offline/syncno scope

Submit signed promises in order; each is SETTLED, REJECTED (with restoreMinor) or DUPLICATE

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/offline/sync \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

Diaspora-Direct

4 operations.

POST/diaspora/quotesno scope

Purpose-locked quote at the current rate card

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/diaspora/quotes \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

POST/diaspora/quotes/{id}/payno scope

Pay a quote from the source-currency wallet

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/diaspora/quotes/{id}/pay \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

GET/diaspora/rate-cardsno scope

Published, platform-signed rate cards (≤ 4h validity)

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/diaspora/rate-cards \
  -H "Authorization: Bearer sk_test_..."

GET/institutionsno scope

Verified institutions and their purpose codes

Parameters (3)

Name	In	Type	Required
`country`	query	string	optional
`purpose`	query	string	optional
`q`	query	string	optional

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/institutions?country=&purpose=&q= \
  -H "Authorization: Bearer sk_test_..."

National switch

3 operations.

POST/paymentspayments:createIdempotency-Key

Create an interinstitutional payment (IDM-001/002/003; route computed server-side)

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/payments \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" -d '{}'

GET/payments/{id}payments:read

Five status dimensions and journal

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/payments/{id} \
  -H "Authorization: Bearer sk_test_..."

POST/payments/{id}/cancelpayments:cancel

Cancel before emission (never after)

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/payments/{id}/cancel \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

Platform

1 operation.

GET/statusno scope

Operating state (guardian mode, degraded flags)

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/status \
  -H "Authorization: Bearer sk_test_..."

FX

2 operations.

POST/fx/quotestransfers:write

Lock an FX quote (mid-market rate, margin, fee, recipient amount); usable as quote_id on transfers and routes

Request body (3 fields)

Field	Type	Accepted values	Notes
`amount_minor`	integer	—	—
`currency`	string	—	—
`target_currency`	string	—	—

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/fx/quotes \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
       "amount_minor": 250000,
       "currency": "CDF",
       "target_currency": "CDF"
     }'

GET/fx/quotes/{id}transfers:read

Retrieve an FX quote (LOCKED, INDICATIVE or EXPIRED)

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/fx/quotes/{id} \
  -H "Authorization: Bearer sk_test_..."

Money requests

3 operations.

POST/money_requestspayment_intents:writeIdempotency-Key

Request a payment from a named payer (@tag, phone or email)

Request body (5 fields)

Field	Type	Accepted values	Notes
`payer`	string	—	—
`amount_minor`	integer	—	—
`currency`	string	—	—
`description`	string	—	—
`expires_in_minutes`	integer	—	—

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/money_requests \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
       "payer": "...",
       "amount_minor": 250000,
       "currency": "CDF",
       "description": "Order 1042",
       "expires_in_minutes": 30
     }'

GET/money_requests/{code}payment_intents:read

Retrieve a money request (requester or payer)

Parameters (1)

Name	In	Type	Required
`code`	path	string	required

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/money_requests/{code} \
  -H "Authorization: Bearer sk_test_..."

POST/money_requests/{code}/cancelpayment_intents:write

Cancel an unpaid money request

Parameters (1)

Name	In	Type	Required
`code`	path	string	required

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/money_requests/{code}/cancel \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

Connected accounts

6 operations.

GET/accountsaccounts:read

List your connected accounts

Parameters (2)

Name	In	Type	Required
`status`	query	string	optional
`limit`	query	string	optional

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/accounts?status=&limit= \
  -H "Authorization: Bearer sk_test_..."

POST/accountsaccounts:write

Create a customer's merchant account (user, organisation, wallets) that your key can act for with the BitriPay-Account header

Request body (7 fields)

Field	Type	Accepted values	Notes
`business_name`	string	—	—
`type`	string	`merchant` · `corporate` · `ngo` · `government` · `developer`	—
`email`	string	—	—
`phone`	string	—	—
`country`	string	—	—
`application_fee_bps`	integer	—	Default platform fee in basis points, kept from each payment at capture (0–5000)
`metadata`	object	—	—

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/accounts \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
       "business_name": "Pharmacie Lumiere",
       "type": "merchant",
       "email": "owner@example.com",
       "phone": "+243810000000",
       "country": "CD",
       "application_fee_bps": 150,
       "metadata": {
         "order": "A-1042"
       }
     }'

GET/accounts/{id}accounts:read

A connected account: status, verification, onboarding, balances

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl https://www.bitripay.com/api/v1/accounts/{id} \
  -H "Authorization: Bearer sk_test_..."

PATCH/accounts/{id}accounts:write

Change the default application fee or metadata

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Request body (2 fields)

Field	Type	Accepted values	Notes
`application_fee_bps`	integer	—	—
`metadata`	object	—	—

Responses

Status	Body
`200`	The object, or a list under `data`.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X PATCH https://www.bitripay.com/api/v1/accounts/{id} \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
       "application_fee_bps": 150,
       "metadata": {
         "order": "A-1042"
       }
     }'

POST/accounts/{id}/account_linksaccounts:write

A one-time claim link (7 days) the customer opens to set a password and own the account

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/accounts/{id}/account_links \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

POST/accounts/{id}/detachaccounts:write

End your access; the account, its keys and its money stay the customer's

Parameters (1)

Name	In	Type	Required
`id`	path	string	required

Request body

A JSON object. The fields this operation reads are listed in the guide for its tag; unknown fields are refused rather than ignored.

Responses

Status	Body
`200`	The object, or a list under `data`.
`201`	Created; the new object is returned in full.
`4XX`	Error envelope: `error.code`, `error.bp` (stable family) and `error.message`.

Example request

curl -X POST https://www.bitripay.com/api/v1/accounts/{id}/detach \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" -d '{}'

Webhooks

BitriPay posts every event to your endpoint at least once and signs it twice. Deduplicate on the event id; answer 2xx quickly and do your work afterwards.

Signature

BitriPay-Signature: t=<unix>,v1=<hex hmac-sha256(secret, `${t}.${rawBody}`)> and BitriPay-Signature-Ed25519: keyId,t,sig (platform key)

Retries

10s, 30s, 2m, 10m, 30m, then every 2h for 24h

Events (45)

Event	Sent when
`payout_batch.created`	A bulk payout batch was uploaded and validated; it waits for approval.
`subscription.created`	A customer subscribed to one of your plans (mandate confirmed).
`subscription.cancelled`	A subscription was cancelled by the customer, by you, or after dunning.
`invoice.paid`	A subscription invoice was collected from the customer wallet.
`invoice.payment_failed`	A collection attempt failed; dunning retries follow (1, 3, 7 days).
`payout_batch.executed`	A bulk payout batch ran: paid, partial or failed, with per-row outcomes on the batch.
`payment_intent.created`	An intent was created (API, QR, link, checkout session or USSD).
`payment_intent.requires_action`	The payer must authorise the payment (PIN, prompt, redirect).
`payment_intent.processing`	An attempt is in flight on a rail. Do not create a second payment.
`payment_intent.authorised`	The payer authorised the payment and the funds are held (capture_method manual). Capture it with POST /payment_intents/{id}/capture, or cancel to void.
`payment_intent.succeeded`	Captured and posted to the ledger. Ship the goods.
`payment_intent.settled`	Funds settled to the merchant balance.
`payment_intent.failed`	The intent ended without a capture (declined, expired, cancelled).
`payment_intent.cancelled`	The merchant cancelled the intent before capture.
`payment_intent.expired`	The intent expired without capture.
`payment_intent.ambiguous_hold`	The provider could not say whether money moved. Funds are in suspense; a human or reconciliation resolves it. Do not retry.
`payment_intent.disputed`	A dispute or chargeback was opened on the payment.
`dispute.opened`	A dispute object was created on one of your payments (same moment as payment_intent.disputed; carries the dispute).
`refund.created`	A refund object was created.
`refund.updated`	A refund moved state. `status` is the stored value (REQUESTED, PENDING, MANUAL, SUCCEEDED, FAILED, REJECTED); `lifecycle` maps it to REQUESTED → APPROVED → PROCESSING → SUCCEEDED \| FAILED \| REJECTED, plus REVERSED.
`refund.succeeded`	The refund was executed and posted.
`refund.failed`	The refund could not be executed.
`checkout.session.completed`	A hosted checkout session was paid.
`checkout.session.expired`	A hosted checkout session expired unpaid.
`verification.completed`	A Scan-to-Verify (KODA) request produced a result.
`verification.confirmed`	A Scan-to-Verify (KODA) request found the payment settled on the ledger (VERIFIED). Sent next to verification.completed.
`payout.created`	A payout request was accepted.
`payout.processing`	The payout was handed to the payout network (queued to a prefunded account or agent) and is being executed.
`payout.completed`	A payout was paid out.
`payout.succeeded`	The payout was paid out (same moment as payout.completed).
`payout.settled`	The payout left the platform ledger for good: the withdrawal posted to the treasury and the funds are with the recipient rail.
`payout.failed`	A payout was rejected or failed.
`settlement.created`	A settlement cycle was closed: the collections of the period were netted (gross, fees, refunds, splits, holds) and the statement is available.
`settlement.completed`	A settlement cycle was paid to its destination (or kept available in the wallet for wallet settlement).
`payment.completed`	Legacy event: a payment request was paid (kept for existing integrations).
`payment_request.created`	Legacy event: an API or link payment request was created.
`reconciliation.exception`	Reconciliation found a discrepancy involving one of your payments.
`payment.created`	National switch payment created (durable intent received).
`payment.action_required`	National switch payment needs payer consent or authentication before it can be sent.
`payment.pending`	National switch payment transmitted or technically acknowledged; confirmation in progress.
`payment.unknown`	National switch payment outcome uncertain after transmission: do not repeat the payment; an inquiry is running.
`payment.rejected`	National switch payment definitively rejected.
`payment.cancelled`	National switch payment cancelled locally before any transmission.
`payment.expired`	National switch payment expired before any possible transmission.
`ping`	Test event sent from the dashboard or the API.

Error codes

The descriptive code tells a human what happened; the numeric bp family is what your code should branch on.

Family	Meaning	When you see it
`BP-1xxx`	Authentication and authorisation	The key, the session, the role or the scope does not allow the call.
`BP-2xxx`	Validation	The request itself is wrong: a field, an amount, a JSON body, a reused idempotency key.
`BP-3xxx`	Ledger	The money cannot move: balance, freeze, limit, fee or a Guardian halt.
`BP-4xxx`	Rail	No rail can carry the payment right now, or the route was refused.
`BP-5xxx`	Compliance	Risk, velocity, cooling-off, KYC tier or sanctions stopped the operation.
`BP-6xxx`	Intelligence	A metered assistant operation could not run (units, policy, model).

Code	BP
`unauthorized`	`BP-1001`
`invalid_credentials`	`BP-1002`
`invalid_pin`	`BP-1003`
`pin_required`	`BP-1004`
`two_factor_required`	`BP-1005`
`scope_denied`	`BP-1006`
`forbidden`	`BP-1007`
`role_required`	`BP-1008`
`step_up_required`	`BP-1010`
`validation_error`	`BP-2001`
`bad_request`	`BP-2002`
`invalid_amount`	`BP-2003`
`invalid_json`	`BP-2004`
`idempotency_key_reused`	`BP-2005`
`not_found`	`BP-2006`
`conflict`	`BP-2007`
`insufficient_funds`	`BP-3001`
`wallet_frozen`	`BP-3002`
`limit_exceeded`	`BP-3003`
`daily_limit_exceeded`	`BP-3004`
`invalid_fee`	`BP-3005`
`guardian_halt`	`BP-3006`
`hold_released`	`BP-3007`
`cycle_not_payable`	`BP-3008`
`payout_unavailable`	`BP-4001`
`connector_unavailable`	`BP-4002`
`rail_unavailable`	`BP-4003`
`route_refused`	`BP-4004`
`degraded_mode`	`BP-4005`
`risk_blocked`	`BP-5001`
`velocity_limit`	`BP-5002`
`cooling_off`	`BP-5003`
`kyc_required`	`BP-5004`
`kyc_tier_limit`	`BP-5005`
`monthly_limit_exceeded`	`BP-5006`
`kyb_required`	`BP-5007`
`sanctions_hit`	`BP-5008`
`fraud_review`	`BP-5009`
`destination_cooling`	`BP-5010`
`destination_locked`	`BP-5011`
`compliance_hold`	`BP-5012`
`module_disabled`	`BP-5013`
`margin_protection_violation`	`BP-6001`
`neural_quota_exceeded`	`BP-6002`
`provider_unavailable`	`BP-6003`
`output_schema_invalid`	`BP-6004`
`rate_limited`	`BP-6005`
`addon_required`	`BP-6006`

Scopes

A restricted key (rk_) holds only the scopes you choose; a missing scope returns scope_denied. Secret keys (sk_) carry them all.

Scope	Operations
`wallets:read`	`GET /wallets`
`transfers:read`	`GET /transfers/{id}` `GET /fx/quotes/{id}`
`transfers:write`	`POST /transfers` `POST /transfers/quote` `POST /fx/quotes`
`remittances:read`	`GET /remittances` `GET /remittances/quote`
`remittances:write`	`POST /remittances`
`payouts:approve`	`POST /payouts/batches/{id}/approve`
`ai:run`	`POST /ai/{agent}` `GET /ai/runs/{id}`
`subscriptions:read`	`GET /invoices` `GET /plans` `GET /plans/{id}` `GET /subscriptions` `GET /subscriptions/{id}`
`subscriptions:write`	`POST /plans` `POST /plans/{id}/archive` `POST /subscriptions/{id}/cancel` `POST /subscriptions/{id}/usage`
`credit:read`	`GET /credit_readiness/{code}`
`routes:read`	`GET /routes` `GET /routes/{id}` `GET /routes/{id}/receipt` `POST /routes/payout-currencies` `POST /routes/quote`
`routes:write`	`POST /routes` `POST /routes/{id}/cancel`
`payment_intents:read`	`GET /payment_intents` `GET /payment_intents/{id}` `GET /payment_intents/{id}/methods` `GET /payment_intents/{id}/split_refunds` `GET /payment_intents/{id}/splits` `GET /payment_intents/{id}/timeline` `GET /checkout_sessions` `GET /checkout_sessions/{id}` `GET /money_requests/{code}`
`payment_intents:write`	`POST /payment_intents` `POST /payment_intents/{id}/cancel` `POST /payment_intents/{id}/capture` `POST /payment_intents/{id}/split_refunds/retry` `POST /money_requests` `POST /money_requests/{code}/cancel`
`checkout_sessions:write`	`POST /checkout_sessions` `POST /checkout_sessions/{id}/expire`
`payment_links:write`	`GET /payment_links` `POST /payment_links` `POST /payment_links/{id}/deactivate`
`qr_codes:read`	`GET /qr_codes` `GET /qr_codes/analytics`
`qr_codes:write`	`POST /locations` `POST /locations/{id}/terminals` `POST /qr_codes` `POST /qr_codes/{id}/revoke` `POST /offline/qr`
`refunds:read`	`GET /payment_intents/{id}/refundable` `GET /refunds` `GET /refunds/{id}`
`refunds:write`	`POST /refunds` `POST /refunds/{id}/reject`
`verifications:write`	`GET /payment_resolution` `POST /verifications` `GET /verifications/quota`
`payouts:read`	`GET /payouts/batches` `GET /payouts/batches/{id}` `GET /payouts/batches/columns` `GET /payouts`
`payouts:write`	`POST /payouts/batches` `POST /payouts/batches/{id}/cancel` `POST /payouts`
`balance:read`	`GET /balance` `GET /transactions/{id}`
`webhooks:manage`	`POST /events/{id}/replay` `POST /webhook_deliveries/{id}/replay` `POST /webhook_endpoints` `GET /webhook_endpoints/{id}/deliveries`
`events:read`	`GET /events`
`payments:create`	`POST /payments`
`payments:read`	`GET /payments/{id}`
`payments:cancel`	`POST /payments/{id}/cancel`
`refunds:create`	—
`participants:read`	—
`qr:create`	—
`reconciliation:read`	—
`bindings:manage`	—
`settlements:read`	`GET /settlement_calendar` `GET /settlement_cycles` `GET /settlement_cycles/{id}/statement` `GET /settlement_profiles` `GET /settlement_profiles/{id}` `GET /settlement_profiles/{id}/preview` `GET /settlements/{id}`
`settlements:write`	`POST /settlement_cycles` `POST /settlement_cycles/{id}/pay` `POST /settlement_profiles`
`disputes:read`	`GET /disputes`
`disputes:write`	`POST /disputes` `POST /disputes/{id}/respond`
`accounts:read`	`GET /accounts` `GET /accounts/{id}`
`accounts:write`	`POST /accounts` `PATCH /accounts/{id}` `POST /accounts/{id}/account_links` `POST /accounts/{id}/detach`