Overview
The vIBAN APIs (also called the Payaza Customer API) let you create virtual bank accounts(USD,GBP,EUR) for your end customers — the people who use your platform. Each customer is registered, verified (KYC), and then given one or more virtual accounts with real payment instructions they can share with payers. How it works in four steps:- You collect the customer’s details, ID numbers, and document images in your app
- You call Create or Update a Customer with those details and the currencies you want (e.g.
["USD"]) - Payaza verifies the customer — this can take minutes, or a few days if manual review is needed
- Once the customer is
ACTIVE, the account returns payment instructions you show to the customer
Key Requirements
Retrieve your API keys from your dashboard by following the steps on our
Authentication page. Use your public API key for
all vIBAN requests. The key must be Base64-encoded and sent with the
Payaza
scheme.1. IP whitelisting is mandatory
You must give Payaza the public outbound IP address(es) of the server(s) that will call these APIs. Requests from IPs that have not been whitelisted will fail.2. Request headers
3. Supported currencies
Virtual accounts can be requested in USD, GBP and EUR.Base URL and operations
All three operations use a single endpoint. The operation is chosen by the HTTP method and query string.How the customer lifecycle works
A customer moves through verification before their account can be used. Understanding these statuses before you build will save you debugging time.Customer statuses
Account statuses
An account can stay
PENDING while the customer is UNDER_REVIEW. The
account only becomes ACTIVE after the customer does.Idempotency — avoiding duplicate requests
Network failures happen. TheIdempotency-Key header makes sure that retrying a request doesn’t create duplicate work.
Rules for using Idempotency-Key
Rules for using Idempotency-Key
- Generate a new, unique key for every intended customer operation
- Reuse the same key only when retrying the same request after a timeout or a
5xxerror - Store the key alongside the outbound request so a retry after an app crash uses the same key
- Use a new key every time you make a new change to a customer
- Keep
customer_referencestable — it is how Payaza identifies the customer
Example key format
Example key format
A readable pattern is
{customer}-{action}-{attempt}, but any unique string works. For example:Idempotency-Key: john-doe-001-create-2Step 1 — Create or Update a Customer
Registers a customer and requests their virtual accounts in a single call. Sending the samecustomer_reference again updates the existing customer. Use this to submit additional information or a missing document during verification.
Request body parameters
Address object
Individual object
Identification object (each item in
identifications)
Document object (each item in
documents)
Which ID does each country need?
Sample response
date_of_birth, the full identification number, and issued_on are accepted
in the request but are not echoed back in any response. Identification
numbers are masked to the last four characters.Handling ACTION_REQUIRED
If the customer status is ACTION_REQUIRED, something is missing. Check requirements[] to see what, then resubmit using the same customer_reference and a new Idempotency-Key.
Each item in requirements[] looks like this:
API reference: Create or Update a Customer
Step 2 — Get a Customer
Retrieves one customer by theircustomer_reference. Use this to monitor verification progress and to fetch the payment instructions once the account is ACTIVE.
Sample response (abbreviated — the real response contains more fields)
Payment instructions
When the customer and account are bothACTIVE, accounts[].payment_instructions[] holds the bank details payers need. This is an example for a USD account:
How to show payment instructions to the payer:
- Display every non-null field
routing_codesmay contain ACH or wire routing numbers where the provider supplies them- If
referenceis present, the payer must include it when making the payment
Step 3 — List Customers
Retrieves a paginated list of all your customers. Use this for dashboards and for nightly reconciliation — not for tracking a single customer’s progress (use Get a Customer for that).
Sample response (customer records abbreviated; the API returns the full structure)
How to fetch everything: start at
page_number=0, increase by 1 each time, and stop when you have data.total records or a page comes back empty.
API reference: List Customers
Recommended integration flow
1
Collect customer details
Gather the customer’s profile, ID numbers, and document images in your app.
2
Host the documents
Upload documents to storage you control and generate HTTPS URLs Payaza can
reach. Short-lived signed URLs are safest.
3
Create the customer
Call Create or Update a Customer with a fresh
Idempotency-Key and the
currencies in the account array.4
Save the identifiers
Store
data.id, customer_reference, and each accounts[].id against your
customer record.5
Act on the status
ACTIVE → show the payment instructions. UNDER_REVIEW → show
“verification in progress” and keep polling. ACTION_REQUIRED → collect the
items in requirements[] and resubmit.6
Poll until active
Keep calling Get a Customer until both the customer and the account are
ACTIVE, then display payment_instructions.Error handling
The source specification doesn’t include failed-response examples for these endpoints, so use these rules instead.Security and data handling
- Store API keys in a secrets manager and rotate them if they appear in tickets, chats, or logs
- Send ID numbers only through the API. Payaza returns just the last four characters, so if you need the full number, store it encrypted
- Use short-lived signed HTTPS URLs for documents rather than permanently public links
- Use real customer data only in the Live environment; use test identities elsewhere
- Never expose credentials in browser or mobile code
Developer notes
customer_referenceis your identifier and must stay stable — it is how you get and update the customer.data.idis Payaza’s own customer ID.- Creating and updating are the same call. Reusing a
customer_referenceupdates the existing customer rather than making a new one. - A new change to a customer needs a new
Idempotency-Key; only retries of the same request reuse the old key. - Verification can take minutes or days. Never promise customers instant account details.
- The
accountarray is optional on creation, but it is how you request currencies such as["USD"]. - A customer can be
ACTIVEbefore their account is. Always check both statuses before showing payment instructions. - Environment settings are worth confirming with Payaza before go-live: the source material shows the tenant header as
Live(capitalised) with an earlier test request usingTest, so confirm the exact values for your environment.
What’s next
Authentication
How to encode your public API key and format the
Authorization header.Virtual Accounts
Collect NGN payments for your own business with Dynamic and Reserved accounts.
Webhooks
Receive real-time notifications for payment events.
Getting Started
Set up your account, API keys, and go-live checklist.