BorderPay API Platform

One API for compliant cross-border payments.

Build customer onboarding, stablecoin wallets, virtual accounts, cross-border transfers, supplier payouts, webhook automation, and signed partner-branded onboarding through BorderPay.

Start integration View API reference

POST /v1/transfers

{
  "source": {
    "payment_rail": "bridge_wallet",
    "currency": "USDC",
    "amount": "2500.00",
    "bridge_wallet_id": "wlt_source_..."
  },
  "destination": {
    "payment_rail": "bridge_wallet",
    "currency": "USDC",
    "bridge_wallet_id": "wlt_destination_..."
  },
  "idempotency_key": "transfer_INV_2049"
}

Private access

Business API keys are not public signup keys. BorderPay issues sandbox and production access after KYB, use-case review, and route approval.

Provider-neutral

Your integration calls BorderPay. BorderPay manages the underlying payment partners, compliance status, route selection, and provider fail-closed behavior.

Production controls

Every money movement request uses authentication, idempotency, verification gates, country restrictions, and signed webhooks.

Quickstart

Make the first request

Use a sandbox key issued by BorderPay. Never place API keys in browser code, mobile apps, public repos, screenshots, or support tickets.

Request a private developer tenant from BorderPay.
Create a sandbox API key from the business dashboard.
Send your first authenticated request with a bearer token.
Register a webhook endpoint before testing money movement flows.

export BORDERPAY_API_KEY="bpk_test_..."

curl https://sandbox.api.borderpayafrica.com/v1/health \
  -H "Authorization: Bearer $BORDERPAY_API_KEY" \
  -H "x-borderpay-mode: sandbox"

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

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

Authentication

Bearer keys, scopes, and idempotency

Every request is tenant-scoped. Mutating requests must include an idempotency key so retries cannot create duplicate customers, virtual accounts, transfers, or payouts.

Header	Required	Description
`Authorization`	Yes	`Bearer bpk_test_...` or `Bearer bpk_live_...`
`x-borderpay-mode`	Recommended	Use `sandbox` or `production`. Mode mismatches are rejected.
`Idempotency-Key`	POST/PATCH	Unique key per business operation. Reuse only for safe retries of the same request.

Unauthorized response

{"success":false,"error":{"code":"unauthorized","message":"API key bearer token is required"}}

This means the request reached the API without a bearer token. It is not a provider failure.

API Status

Health, sandbox, and production

Use the health endpoint for API availability and mode checks. Provider route availability is returned by the route itself and may differ by tenant, country, currency, and environment.

Sandbox

sandbox.api.borderpayafrica.com

Test keys, test webhooks, provider sandbox simulations, and non-live balance flows.

Production

api.borderpayafrica.com

Live keys only after KYB/KYC, use-case review, route enablement, risk limits, and webhook verification.

API Reference

Resources and endpoints

Readable reference for developers. Contract files are available in tools, but the primary docs are designed for humans.

Integration tools

GET/v1/health

Health

Check gateway readiness, API mode, tenant status, and rate-limit state.

POST/v1/customers

Customers

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

POST/v1/onboarding-authorizations

Onboarding authorizations

Issue a signed, short-lived, single-use onboarding link for an end user allowed by your tenant policy.

POST/v1/wallets

Wallets

Create stablecoin wallets for approved customers and supported chains.

POST/v1/virtual-accounts

Virtual accounts

Create USD, EUR, or GBP account details for eligible customers and route deposits to stablecoin wallets.

POST/v1/transfers

Transfers

Move USDC or USDT between tenant-owned wallets using the same currency.

POST/v1/payouts

Payouts

Pay an approved external account through ACH, wire, SEPA, or Faster Payments where enabled.

POST/v1/webhooks

Webhooks

Virtual Accounts

Fiat account details that settle to stablecoins

BorderPay virtual accounts support USD, EUR, and GBP account details for eligible customers. Fiat deposits into a virtual account are monitored, reviewed when required, and routed to the customer's stablecoin wallet.

USD account details EUR SEPA details GBP Faster Payments details

Create virtual account

curl https://api.borderpayafrica.com/v1/virtual-accounts \
  -X POST \
  -H "Authorization: Bearer $BORDERPAY_API_KEY" \
  -H "Idempotency-Key: va_2026_07_15_001" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_...",
    "currency": "EUR",
    "destination": {
      "payment_rail": "base",
      "currency": "USDC",
      "bridge_wallet_id": "wlt_..."
    }
  }'

Transfers & Payouts

Cross-border supplier payment flow

Create a customer, create a wallet, collect funds through an eligible virtual account, then use transfers and payouts to convert stablecoins into the recipient rail where the route is enabled.

Customer Virtual account Stablecoin wallet Supplier payout

Create payout

curl https://api.borderpayafrica.com/v1/payouts \
  -X POST \
  -H "Authorization: Bearer $BORDERPAY_API_KEY" \
  -H "Idempotency-Key: payout_INV_2049" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "payment_rail": "bridge_wallet",
      "currency": "USDC",
      "amount": "2500.00",
      "bridge_wallet_id": "wlt_..."
    },
    "destination": {
      "payment_rail": "ach",
      "currency": "USD",
      "external_account_id": "ext_..."
    },
    "idempotency_key": "payout_INV_2049"
  }'

African Corridors

Public API v1 coverage is route-specific

BorderPay serves African businesses, but the current public payout API exposes approved external accounts only. Country classification elsewhere in BorderPay does not make a local rail available through API v1.

Current payout currencies

The destination must be an approved external account in one of these currencies.

Current payout rails

The tenant and external account must be approved for the selected rail.

Local African rails

Local-bank and mobile-money payouts are not exposed by the current public API contract. Do not build against them until they appear in a later version.

Route truth

API keys, tenant approval, an approved transfer cap, owned wallet resources, and an approved destination external account are all required. Availability remains fail-closed.

Compliance

Restricted and unavailable jurisdictions

Restrictions can apply to signup, onboarding, deposits, payouts, counterparties, or local rails. Production calls fail closed when a jurisdiction or route is not approved.

Prohibited jurisdictions

BorderPay API restrictions follow the current compliance source of truth. ISO alpha-3 country codes are used in this list.

Unavailable onboarding jurisdictions

Services are unavailable for individuals and businesses located in Algeria, Burundi, China, Japan, and Tunisia.

Route-specific restrictions

Additional restrictions can apply by tenant, customer, counterparty, country, amount, currency, external account, or payment rail. A listed country is not proof that a specific API operation is enabled.

Webhooks

Automate every state change

Register signed webhooks before going live. Event types follow the owned resource lifecycle and the data object contains only the projected partner-safe fields available for that event.

customer.* wallet.* virtual_account.* external_account.* transfer.completed transfer.failed

Verify signature

const payload = await request.text();
const signature = request.headers.get("x-borderpay-signature");
const timestamp = request.headers.get("x-borderpay-timestamp");

const result = await verifyBorderPayWebhook({
  rawBody: payload,
  signatureHeader: signature ?? "",
  timestamp: timestamp ?? "",
  signingSecret: process.env.BORDERPAY_WEBHOOK_SECRET,
});

Errors

Predictable API failures

400invalid_request

The request body or route-specific fields failed validation.

401unauthorized

The bearer API key is missing, invalid, or revoked.

403forbidden

The tenant, mode, scope, IP, policy, or release gate does not permit the operation.

409idempotency_replay_mismatch

The same idempotency key was reused with a different request payload.

429rate_limited

Retry after the current response window resets.

500internal_error

The gateway could not complete the operation. Retain the request identifier for support.

SDKs & Tools

Integration accelerators

These are supporting artifacts, not the primary documentation experience.

Postman Collection Import requests, environments, and sample payloads. cURL Cookbook Copyable command recipes for backend teams. API Contract Machine-readable contract for code generation.

White Label

Partner-branded signed onboarding

An authorized white-label tenant can issue a short-lived, single-use signup link. On that signed signup screen, BorderPay renders the operator-approved app name, HTTPS logo, and primary color. Branding does not currently extend to the authenticated BorderPay application.

Supported branding

App name, HTTPS logo URL, and six-digit hexadecimal primary color are validated before signup renders them.

Private signup

Use POST /v1/onboarding-authorizations with onboarding:write; the resulting bearer link is short-lived and single-use.

Operator controlled

Partners cannot self-publish branding. Custom-domain routing and full-application theming are not currently available.

Go Live

Production readiness checklist

These are partner-specific approval gates, not claims that your integration has already passed them.

Business KYB and use case approved Production access and required API scopes explicitly issued Webhook endpoint registered and v1= signature verified Idempotency implemented on every mutating call Forbidden, unavailable-route, and rate-limit failures handled Webhook-driven reconciliation tested against captured sandbox results