VertexBridge API

Technology infrastructure for businesses in Africa, delivered as an HTTP API. You integrate once; your users never learn we are there.

What you can call today

These are every endpoint that exists. They let you prove your key works, read your prepaid balance, check who owns a bank account, send a payout to it and read how it ended, browse the bills and VTU catalogue, list your transactions and find one by your own reference, check your API agreement, and verify the signature of, inspect and replay the webhooks we will send you — none are sent yet. Sending a payout moves real money; read Idempotency and Indeterminate transactions before you call it.

Live traffic goes to https://api.vertexbridge.io (not serving yet) and test traffic to https://sandbox.vertexbridge.io (not serving yet). Every API server accepts only its own environment's keys, so a test key can never move real money.

The products

VertexBridge offers five products. Payouts are published — see the Payouts guide. Bills & VTU are published too — the catalogue and buying; see the Bills & VTU guide. Nothing is published yet for the others:

• Crypto rails — your users buy and sell crypto with naira.
• Identity / KYC — BVN and NIN verification and name matching.
• Virtual accounts — a dedicated account number per customer, for inbound transfers.
• Bills & VTU — airtime, data, electricity, cable TV and exam PINs.

A payout is also only enabled once we have switched it on for your account — /v1/partner/me lists what is enabled. Each product gets its own guide here when its endpoints can be called. To talk about a product before then, contact us.

Conventions

Money is an integer, in a string

Every amount is an object with amount_minor — the amount in the currency's smallest unit, kobo for naira — and currency. amount_minor is a string of digits, never a JSON number and never a decimal:

{
  "partner": "your-platform",
  "balance": { "amount_minor": "5000000", "currency": "NGN" },
  "min_balance": { "amount_minor": "0", "currency": "NGN" },
  "held": { "amount_minor": "0", "currency": "NGN" },
  "next_clears_at": null
}

That balance is ₦50,000.00. Parse amount_minor into an integer type that cannot lose precision — BigInt in JavaScript, int in Python — and format it for display only at the edge of your own interface. A JSON number would be rounded silently by most parsers once it passes 2⁵³.

Your balance is prepaid

Your balance is money you have paid us in advance, drawn down as you transact, and it comes from our double-entry ledger. balance does not include money reserved for a transaction that is still in progress, so it can never be spent twice. min_balance is the floor agreed for your account — a transaction that would take you below it is refused rather than run on credit.

Money you have just added may be held for a clearing period. It is already part of balance and can pay for reversible products, but it cannot fund a payout or anything else that cannot be undone until it clears. next_clears_at is the earliest time some of it clears — not necessarily all of it, because each top-up clears on its own schedule. When nothing is held, held is zero and next_clears_at is null.

Every response carries a correlation id

Quote it when you contact us about a request. Errors explains where to find it and how to send your own.

Where to start

• AuthenticationYour API key, the header it goes in, and what each scope allows.
• ErrorsThe one error shape, every code you can receive, and what to do about each.
• WebhooksHow deliveries are signed and retried, with a verifier and a test vector.
• Indeterminate transactionsThe state that is not a failure — and what never to do when you see it.