> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payaza.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# vIBAN APIs

> Register your customers for KYC verification and provision virtual bank accounts (USD, GBP, EUR) they can use to receive funds.

## 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

> [!WARNING]
>
> 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

> [!NOTE]
>
> Retrieve your API keys from your dashboard by following the steps on our
> [Authentication](https://docs.payaza.africa/guides/authentication.md) 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.

> [!WARNING]
>
> Contact the Payaza Integration/Support team at
> [support@payaza.africa](mailto:support@payaza.africa) to start the
> whitelisting process **before** you begin integration.

### 2. Request headers

| Header | Required on | Value | Description |
| - | - | - | - |
| `Authorization` | All requests | `Payaza <BASE64_PUBLIC_KEY>` | Authenticates your business |
| `Content-Type` | All requests | `application/json` | Request body format |
| `X-TenantID` | All requests | `Live` or `Test` | Environment the request runs against |
| `Idempotency-Key` | `POST` only | A unique string | A unique value that prevents duplicate processing when retrying the same request. |

```json theme={null}
{
  "Authorization": "Payaza <BASE64_PUBLIC_KEY>",
  "Content-Type": "application/json",
  "X-TenantID": "Live",
  "Idempotency-Key": "john-doe-001-create-1"
}
```

> [!WARNING]
>
> 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.

```text theme={null}
https://api.payaza.africa/live/payaza-account/api/v1/mainaccounts/merchant/customer
```

| Operation | HTTP method | How it is selected |
| - | - | - |
| Create or Update a Customer | `POST` | JSON request body |
| Get a Customer | `GET` | `?operation=GET&customer_reference={ref}` |
| List Customers | `GET` | `?operation=LIST&page_number={n}&page_size={size}` |

***

## 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

| Status | What it means | What you should do |
| - | - | - |
| `UNDER_REVIEW` | Details submitted and being verified | Show "verification in progress" and poll Get Customer |
| `ACTION_REQUIRED` | Verification is blocked — something is missing | Read `requirements[]`, collect the missing items, resubmit with the **same** `customer_reference` |
| `ACTIVE` | Customer verified, accounts can be provisioned | Read and display `accounts[].payment_instructions` |

### Account statuses

| Status | What it means |
| - | - |
| `PENDING` | Account requested but not yet available. `payment_instructions` is empty. The `message` field explains why (e.g. "Waiting for the customer to become ACTIVE") |
| `ACTIVE` | Account is live. `payment_instructions` contains the bank details to share with payers |

> [!NOTE]
>
> 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.

> [accordion] 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 `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

> [accordion] Example key format
>
> 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.

```bash cURL theme={null}
curl --request POST \
  --url https://api.payaza.africa/live/payaza-account/api/v1/mainaccounts/merchant/customer \
  --header 'Content-Type: application/json' \
  --header 'X-TenantID: Live' \
  --header 'Authorization: Payaza <BASE64_PUBLIC_KEY>' \
  --header 'Idempotency-Key: john-doe-001-create-1' \
  --data '{
    "customer_reference": "account_001",
    "type": "individual",
    "email": "johndoe@company.com",
    "phone": "+2348012345679",
    "country_code": "NG",
    "address": {
      "street": "123 Main Street",
      "city": "Lagos",
      "subdivision": "Lagos",
      "postal_code": "100001",
      "country_code": "NG"
    },
    "individual": {
      "first_name": "John",
      "last_name": "Doe",
      "date_of_birth": "1990-01-15"
    },
    "identifications": [
      {
        "type": "PASSPORT",
        "number": "A12345678",
        "issuing_country": "NG",
        "issued_on": "2020-01-15",
        "expires_on": "2030-01-15"
      },
      {
        "type": "TIN",
        "number": "12345678-0001",
        "issuing_country": "NG"
      }
    ],
    "documents": [
      {
        "type": "IDENTITY_DOCUMENT",
        "side": "FRONT",
        "url": "https://your-bucket.s3.amazonaws.com/kyc/john-doe-passport.png"
      }
    ],
    "account": ["USD"]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  "https://api.payaza.africa/live/payaza-account/api/v1/mainaccounts/merchant/customer",
  {
    method: "POST",
    headers: {
      Authorization: "Payaza <BASE64_PUBLIC_KEY>",
      "Content-Type": "application/json",
      "X-TenantID": "Live",
      "Idempotency-Key": "john-doe-001-create-1",
    },
    body: JSON.stringify({
      customer_reference: "account_001",
      type: "individual",
      email: "johndoe@company.com",
      phone: "+2348012345679",
      country_code: "NG",
      address: {
        street: "123 Main Street",
        city: "Lagos",
        subdivision: "Lagos",
        postal_code: "100001",
        country_code: "NG",
      },
      individual: {
        first_name: "John",
        last_name: "Doe",
        date_of_birth: "1990-01-15",
      },
      identifications: [
        {
          type: "PASSPORT",
          number: "A12345678",
          issuing_country: "NG",
          issued_on: "2020-01-15",
          expires_on: "2030-01-15",
        },
        {
          type: "TIN",
          number: "12345678-0001",
          issuing_country: "NG",
        },
      ],
      documents: [
        {
          type: "IDENTITY_DOCUMENT",
          side: "FRONT",
          url: "https://your-bucket.s3.amazonaws.com/kyc/john-doe-passport.png",
        },
      ],
      account: ["USD"],
    }),
  },
);

const result = await response.json();

// IMPORTANT: a 200 HTTP status does not guarantee success
if (result.status === false) {
  console.error("Request failed:", result.message);
} else {
  const customer = result.data;
  console.log(customer.id); // Save this
  console.log(customer.customer_reference); // Save this
  console.log(customer.status); // "UNDER_REVIEW" | "ACTION_REQUIRED" | "ACTIVE"
  console.log(customer.accounts[0].id); // Save this too
}
```

### Request body parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `customer_reference` | String | ✓ | Your unique reference for this customer. Used to retrieve and update them later |
| `type` | String | ✓ | Customer type. Set to `individual` |
| `email` | String | ✓ | Customer's email address |
| `phone` | String | ✓ | Phone number in E.164 format (e.g. `+2348012345679`) |
| `country_code` | String | ✓ | ISO 3166-1 Alpha-2 country code (e.g. `NG`) |
| `address` | Object | ✓ | Customer's residential address — see below |
| `individual` | Object | ✓ | Personal details — see below |
| `identifications` | Array | ✓ | ID records — see below |
| `documents` | Array | ✓ | Supporting documents, supplied as public HTTPS URLs — see below |
| `account` | Array of strings | No | Currencies to provision accounts for (e.g. `["USD"]`) |

**Address object**

| Parameter | Type | Required | Description |
| - | - | - | - |
| `street` | String | ✓ | Street address, line 1 |
| `street2` | String | No | Street address, line 2 |
| `city` | String | ✓ | City |
| `subdivision` | String | ✓ | State or region (e.g. `Lagos`) |
| `postal_code` | String | ✓ | Postal code |
| `country_code` | String | ✓ | ISO Alpha-2 country code |

**Individual object**

| Parameter | Type | Required | Description |
| - | - | - | - |
| `first_name` | String | ✓ | First name |
| `middle_name` | String | No | Middle name |
| `last_name` | String | ✓ | Last name |
| `date_of_birth` | Date | ✓ | Format `YYYY-MM-DD` |

**Identification object** *(each item in `identifications`)*

| Parameter | Type | Required | Description |
| - | - | - | - |
| `type` | String | ✓ | ID type, e.g. `PASSPORT`, `TIN` |
| `number` | String | ✓ | The full ID number. Only the last four characters are ever returned |
| `issuing_country` | String | ✓ | ISO Alpha-2 country code |
| `issued_on` | Date | Where applicable | `YYYY-MM-DD` |
| `expires_on` | Date | Where applicable | `YYYY-MM-DD` |

**Document object** *(each item in `documents`)*

| Parameter | Type | Required | Description |
| - | - | - | - |
| `type` | String | ✓ | Document type, e.g. `IDENTITY_DOCUMENT` |
| `side` | String | For two-sided IDs | `FRONT` or `BACK` |
| `url` | String | ✓ | A publicly reachable HTTPS URL. Payaza downloads the file and stores its SHA-256 hash |

### Which ID does each country need?

| Country | What to collect | Example label |
| - | - | - |
| US | Social Security Number | SSN |
| NG | Bank Verification Number / National ID | BVN / NIN |
| GB | National Insurance Number | NINO |
| CA | Social Insurance Number | SIN |

### Sample response

```json theme={null}
{
  "message": "Customer processed",
  "status": true,
  "retry_count": 0,
  "data": {
    "id": 15,
    "customer_reference": "account_001",
    "type": "individual",
    "name": "John Doe",
    "status": "UNDER_REVIEW",
    "requirements": [],
    "registrations": [
      {
        "provider_reference": "01a1e843-b041-7384-8649-430c0e7abc30",
        "provisioning": "ON_REQUEST",
        "status": "UNDER_REVIEW",
        "programs": [
          {
            "currencies": ["USD"],
            "status": "UNDER_REVIEW",
            "provider_status": "PENDING",
            "requirements": []
          }
        ],
        "documents": [
          {
            "type": "IDENTITY_DOCUMENT",
            "side": "FRONT",
            "status": "UPLOADED",
            "file_name": "1774864420319-pocketapp.png"
          }
        ]
      }
    ],
    "accounts": [
      {
        "id": 8,
        "account_reference": "primary",
        "currency": "USD",
        "status": "PENDING",
        "payment_instructions": [],
        "message": "Waiting for the customer to become ACTIVE"
      }
    ],
    "identifications": [
      {
        "type": "PASSPORT",
        "issuing_country": "NG",
        "last4": "1511",
        "expires_on": "2030-01-15"
      }
    ]
  }
}
```

> [!WARNING]
>
> 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.

> [!WARNING]
>
> 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.

> [!NOTE]
>
> `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:

| Field | Description |
| - | - |
| `code` | The requirement type, e.g. `DOCUMENT_REQUIRED` |
| `field` | Which request field needs attention, e.g. `documents` |
| `document_type` | The type of document expected |
| `message` | A human-readable instruction |
| `url` | A hosted link to complete the step, where provided |
| `expires_at` | When that hosted link expires |
| `provider_code` | Provider-specific requirement code |

**API reference:** [Create or Update a Customer](https://docs.payaza.africa/api-reference/vibans/create-or-update-a-customer.md)

***

## 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`.

```bash cURL theme={null}
curl --request GET \
  --url 'https://api.payaza.africa/live/payaza-account/api/v1/mainaccounts/merchant/customer?operation=GET&customer_reference=account_001' \
  --header 'Content-Type: application/json' \
  --header 'X-TenantID: Live' \
  --header 'Authorization: Payaza <BASE64_PUBLIC_KEY>'
```

```javascript Node.js theme={null}
const customerReference = "account_001";

const response = await fetch(
  `https://api.payaza.africa/live/payaza-account/api/v1/mainaccounts/merchant/customer?operation=GET&customer_reference=${customerReference}`,
  {
    method: "GET",
    headers: {
      Authorization: "Payaza <BASE64_PUBLIC_KEY>",
      "Content-Type": "application/json",
      "X-TenantID": "Live",
    },
  },
);

const result = await response.json();

if (result.status === false) {
  console.error("Request failed:", result.message);
} else {
  const customer = result.data;

  if (customer.status === "ACTIVE") {
    const account = customer.accounts[0];
    if (account.status === "ACTIVE") {
      // Show every non-null field to the payer
      console.log(account.payment_instructions);
    }
  } else if (customer.status === "ACTION_REQUIRED") {
    console.log("Missing:", customer.requirements);
  } else {
    console.log("Still under review");
  }
}
```

**Query parameters**

| Parameter | Type | Required | Description |
| - | - | - | - |
| `operation` | String | ✓ | Must be `GET` |
| `customer_reference` | String | ✓ | The reference you used when creating the customer |

**Sample response** *(abbreviated — the real response contains more fields)*

```json theme={null}
{
  "message": "Customer retrieved",
  "status": true,
  "retry_count": 0,
  "data": {
    "id": 15,
    "customer_reference": "account_001",
    "type": "individual",
    "name": "John Doe",
    "email": "johndoe@company.com",
    "phone": "+2348012345679",
    "country_code": "NG",
    "address": {
      "street": "123 Main Street",
      "street2": null,
      "city": "Lagos",
      "subdivision": "Lagos",
      "postal_code": "100001",
      "country_code": "NG"
    },
    "status": "UNDER_REVIEW",
    "requirements": [],
    "registrations": [
      {
        "provider_reference": "01a1e843-b041-7384-8649-430c0e7abc30",
        "provisioning": "ON_REQUEST",
        "status": "UNDER_REVIEW",
        "programs": [
          {
            "currencies": ["USD"],
            "status": "UNDER_REVIEW",
            "provider_status": "PENDING",
            "requirements": [],
            "updated_at": "2026-11-17T06:48:34.357002564Z"
          }
        ],
        "last_error": null,
        "refreshed_at": "2026-11-17T06:48:34.357003Z"
      }
    ],
    "accounts": [
      {
        "id": 8,
        "account_reference": "primary",
        "customer_id": 15,
        "customer_reference": "account_001",
        "currency": "USD",
        "status": "PENDING",
        "provider_status": null,
        "holder_name": null,
        "payment_instructions": [],
        "message": "Waiting for the customer to become ACTIVE"
      }
    ],
    "individual": {
      "first_name": "John",
      "middle_name": null,
      "last_name": "Doe",
      "nationality": null
    },
    "identifications": [
      {
        "type": "PASSPORT",
        "issuing_country": "NG",
        "last4": "1511",
        "expires_on": "2030-01-15"
      }
    ],
    "created_at": "2026-11-17T06:48:15.891065Z",
    "updated_at": "2026-11-17T06:48:32.137453Z"
  }
}
```

### 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:

```json theme={null}
{
  "method": null,
  "account_number": "1042819270",
  "account_number_type": "ACCOUNT_NUMBER",
  "routing_codes": [],
  "bank_name": "Bank of Nowhere",
  "bank_address": "1800 North Pole St., Orlando, FL 32801",
  "bank_country": null,
  "beneficiary_name": "Chibunkem OJ",
  "reference": null,
  "network": null
}
```

> [!NOTE]
>
> **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](https://docs.payaza.africa/api-reference/vibans/get-or-list-customers.md)

***

## 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).

```bash cURL theme={null}
curl --request GET \
  --url 'https://api.payaza.africa/live/payaza-account/api/v1/mainaccounts/merchant/customer?operation=LIST&page_number=0&page_size=20' \
  --header 'Content-Type: application/json' \
  --header 'X-TenantID: Live' \
  --header 'Authorization: Payaza <BASE64_PUBLIC_KEY>'
```

```javascript Node.js theme={null}
async function listAllCustomers() {
  const pageSize = 20;
  let pageNumber = 0; // requests are zero-based
  let all = [];
  let total = Infinity;

  while (all.length < total) {
    const response = await fetch(
      `https://api.payaza.africa/live/payaza-account/api/v1/mainaccounts/merchant/customer?operation=LIST&page_number=${pageNumber}&page_size=${pageSize}`,
      {
        method: "GET",
        headers: {
          Authorization: "Payaza <BASE64_PUBLIC_KEY>",
          "Content-Type": "application/json",
          "X-TenantID": "Live",
        },
      },
    );

    const result = await response.json();
    if (result.status === false) throw new Error(result.message);

    const customers = result.data.data;
    total = result.data.total;
    if (customers.length === 0) break; // safety stop

    all = all.concat(customers);
    pageNumber += 1;
  }

  return all;
}
```

**Query parameters**

| Parameter | Type | Required | Description |
| - | - | - | - |
| `operation` | String | ✓ | Must be `LIST` |
| `page_number` | Integer | ✓ | Page to fetch. **Zero-based** — `0` is the first page |
| `page_size` | Integer | ✓ | Records per page (e.g. `20`) |

**Sample response** *(customer records abbreviated; the API returns the full structure)*

```json theme={null}
{
  "message": "Customers retrieved",
  "status": true,
  "retry_count": 0,
  "data": {
    "data": [
      {
        "id": 3,
        "customer_reference": "payout-sender",
        "type": "individual",
        "status": "ACTION_REQUIRED"
      },
      {
        "id": 14,
        "customer_reference": "Customer_reference_012",
        "type": "individual",
        "status": "ACTIVE"
      },
      {
        "id": 15,
        "customer_reference": "payaza_account_001",
        "type": "individual",
        "status": "UNDER_REVIEW"
      }
    ],
    "page": 1,
    "size": 20,
    "total": 3
  }
}
```

> [!WARNING]
>
> 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**

| Field | Description |
| - | - |
| `data.data` | The customer records on this page |
| `data.page` | Page number returned (one-based) |
| `data.size` | Page size used |
| `data.total` | Total customers across all pages |

**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](https://docs.payaza.africa/api-reference/vibans/get-or-list-customers.md)

***

## 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.

| Scenario | What to do |
| - | - |
| `status: false` in the response | Treat as failed, even if HTTP status is `200`. Read and log `message` |
| Timeout, connection error, or `5xx` | Retry the `POST` with the **same** `Idempotency-Key` |
| Retry timing | Exponential backoff: 1s, 2s, 4s… up to 5 attempts |
| `4xx` validation error | **Don't** retry as-is. Fix the request payload first |
| Customer or account seems stuck | Check `registrations[].last_error` and `accounts[].message` |
| Requests rejected outright | Confirm your server's outbound IP has been whitelisted by Payaza |
| GBP/EUR account not appearing in development | Expected — GBP/EUR creation is on hold outside production |

***

## 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

> [card] [Authentication](https://docs.payaza.africa/guides/authentication.md)
>
> How to encode your public API key and format the `Authorization` header.

> [card] [Virtual Accounts](https://docs.payaza.africa/guides/virtual-accounts.md)
>
> Collect NGN payments for your own business with Dynamic and Reserved accounts.

> [card] [Webhooks](https://docs.payaza.africa/guides/webhooks.md)
>
> Receive real-time notifications for payment events.

> [card] [Getting Started](https://docs.payaza.africa/guides/getting-started.md)
>
> Set up your account, API keys, and go-live checklist.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.