BorderPay API Docs
OpenAPI Postman Start

BorderPay Public API v1.0.1

Move money with one clean API.

Create customers, wallets, virtual accounts, transfers, payouts, and webhooks through BorderPay. Business developers receive BorderPay tenant API keys; BorderPay handles provider routing, compliance boundaries, idempotency, and white-label metadata.

Make the first request Browse API reference
Why you saw this {"success":false,"error":{"code":"unauthorized","message":"API key bearer token is required"}}

This is expected when an endpoint is opened without Authorization: Bearer <api_key>. Use the authenticated examples below.

Quickstart

Make your first authenticated request

Use a sandbox API key issued by BorderPay. Do not put real keys in frontend code, screenshots, or public repos.

export BORDERPAY_API_KEY="bpk_test_..."

curl --request GET \
  --url https://sandbox.api.borderpayafrica.com/v1/health \
  --header "Authorization: Bearer $BORDERPAY_API_KEY" \
  --header "x-borderpay-mode: sandbox"
const response = await fetch("https://sandbox.api.borderpayafrica.com/v1/health", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.BORDERPAY_API_KEY}`,
    "x-borderpay-mode": "sandbox",
  },
});

console.log(await response.json());

Authentication

Bearer API keys

Every request requires a tenant API key in the Authorization header. Mutating routes also require an Idempotency-Key header so retries cannot duplicate financial operations.

HeaderRequiredPurpose
AuthorizationYesBearer bpk_test_... or bpk_live_...
x-borderpay-modeRecommendedUse sandbox or production; mismatches are rejected.
Idempotency-KeyPOST onlyRequired for customer, wallet, virtual account, transfer, payout, and webhook creation.
401 Missing or invalid API key

Include the bearer token. API keys are shown once when issued.

403 Wrong scope or mode

Use the correct tenant mode and route scopes.

Environments

Use sandbox first, then production

Sandbox

https://sandbox.api.borderpayafrica.com

Test tenant keys, test onboarding, webhook mocks, and dry-run integration work.

Production

https://api.borderpayafrica.com

Live keys only after compliance, KYB, risk limits, and production allowlisting are complete.

API Reference

Endpoints

Provider-neutral routes aligned to the current OpenAPI contract.

OpenAPI YAML
GET/v1/health

Check tenant mode, rate limit state, gateway readiness, and public white-label metadata.

POST/v1/customers

Create an individual or business customer before wallets, virtual accounts, or payouts.

POST/v1/wallets

Create a stablecoin wallet for an eligible customer.

POST/v1/virtual-accounts

Create fiat account details that route deposits to a stablecoin destination.

POST/v1/transfers

Move funds between supported source and destination rails.

POST/v1/payouts

Pay suppliers or beneficiaries using the payout contract.

POST/v1/webhooks

Register an endpoint and receive a signing secret for event verification.

Webhooks

Verify every event

Webhooks use a timestamp and HMAC signature. Store the signing secret safely and verify the raw body before accepting an event.

transfer.completed transfer.failed customer.verification.updated
Headers 
x-borderpay-signature: sha256=<hex>
x-borderpay-timestamp: <unix_seconds>

SDKs & Artifacts

Download integration assets

OpenAPI v1 YAMLReference contract and schemas. Postman CollectionImport sandbox requests. cURL CookbookCopyable command examples. TypeScript SDK StarterTyped client and webhook verifier. Node Sandbox DemoEnd-to-end Node example. ChangelogAPI pack version history.

White Label

Businesses can receive branded API access

BorderPay creates the tenant, uploads the logo to Supabase storage, configures brand colors, sets sandbox or production mode, then issues scoped API keys. The public API health response returns white-label metadata for approved tenants.

  1. Create or approve the business tenant.
  2. Upload tenant logo and brand settings.
  3. Issue sandbox API key first.
  4. Move to production after KYB and risk approval.

Go Live

Production checklist