Skip to main content

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:
  1. You collect the customer’s details, ID numbers, and document images in your app
  2. You call Create or Update a Customer with those details and the currencies you want (e.g. ["USD"])
  3. Payaza verifies the customer — this can take minutes, or a few days if manual review is needed
  4. Once the customer is ACTIVE, the account returns payment instructions you show to the customer
Virtual bank accounts are not issued instantly. The account starts as PENDING and only becomes ACTIVE after the customer passes verification. Build your app to handle the waiting period.

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.
Contact the Payaza Integration/Support team at support@payaza.africa to start the whitelisting process before you begin integration.

2. Request headers

Keep API keys on your server. Never put them in browser or mobile app code.

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. The Idempotency-Key header makes sure that retrying a request doesn’t create duplicate work.
  • 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 5xx error
  • 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_reference stable — it is how Payaza identifies the customer
A readable pattern is {customer}-{action}-{attempt}, but any unique string works. For example:Idempotency-Key: john-doe-001-create-2

Step 1 — Create or Update a Customer

Registers a customer and requests their virtual accounts in a single call. Sending the same customer_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

Save data.id, data.customer_reference, and each accounts[].id against your own customer record immediately. You will use customer_reference for every later lookup and update.
Always check status in the response body. If status is false, treat the request as failed — even when the HTTP status code is 200. Read the message field to see why.
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 their customer_reference. Use this to monitor verification progress and to fetch the payment instructions once the account is ACTIVE.
Query parameters Sample response (abbreviated — the real response contains more fields)

Payment instructions

When the customer and account are both ACTIVE, 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_codes may contain ACH or wire routing numbers where the provider supplies them
  • If reference is present, the payer must include it when making the payment
API reference: Get a Customer

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).
Query parameters Sample response (customer records abbreviated; the API returns the full structure)
Pagination is zero-based in your request but one-based in the response. Sending page_number=0 returns page: 1. Don’t be thrown by this — it is expected.
Response fields 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
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_reference is your identifier and must stay stable — it is how you get and update the customer. data.id is Payaza’s own customer ID.
  • Creating and updating are the same call. Reusing a customer_reference updates 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 account array is optional on creation, but it is how you request currencies such as ["USD"].
  • A customer can be ACTIVE before 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 using Test, 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.