Virtual Accounts Quickstart

This quickstart walks through the most common virtual account flows with NGN.

Prerequisites

• A live organization with MPC configured.
• A live API key passed as PLANBOK-X-API-KEY.

1. Create an organization-custody virtual account

Code
curl -X POST https://api.planbok.io/v2/virtual-accounts \
  -H "PLANBOK-X-API-KEY: YOUR_LIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "0191a1b2-c3d4-7e8f-9a0b-1c2d3e4f5a6b",
    "encryptedOrganizationSecret": "base64(RSA-encrypted-secret)",
    "count": 1,
    "metadata": [
      {
        "name": "Operations NGN Account",
        "refId": "ops-ngn-001",
        "currencies": ["NGN"],
        "holderDetails": {
          "firstName": "John",
          "lastName": "Doe",
          "phoneNumber": "+2348012345678",
          "email": "john.doe@example.com",
          "address": "123 Lagos Street",
          "dateOfBirth": "1990-01-01",
          "bvn": "12345678901",
          "nin": "12345678901"
        }
      }
    ]
  }'

The currencies array is optional for organization-custody accounts and defaults to ["NGN"].

2. Create a customer-custody virtual account challenge

Code
curl -X POST https://api.planbok.io/v2/customers/:id/virtual-accounts/create \
  -H "PLANBOK-X-API-KEY: YOUR_LIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "redirectUrl": "https://gateway.example.com/pin/verify",
    "currencies": ["NGN"],
    "holderDetails": {
      "firstName": "Jane",
      "lastName": "Doe",
      "phoneNumber": "+2348098765432",
      "email": "jane.doe@example.com",
      "address": "456 Abuja Road",
      "dateOfBirth": "1992-05-15",
      "bvn": "10987654321",
      "nin": "10987654321"
    }
  }'

The response contains a challengeId and redirectUrl. The customer completes PIN verification at the gateway, after which the virtual account is created.

3. Look up supported banks

Code
curl -X GET "https://api.planbok.io/v2/virtual-accounts/banks?order=ASC&searchTerm=Access" \
  -H "PLANBOK-X-API-KEY: YOUR_LIVE_API_KEY"

4. Transfer from an organization-custody account

Code
curl -X POST https://api.planbok.io/v2/virtual-accounts/:id/transfer \
  -H "PLANBOK-X-API-KEY: YOUR_LIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "0191a1b2-c3d4-7e8f-9a0b-1c2d3e4f5a6c",
    "encryptedOrganizationSecret": "base64(RSA-encrypted-secret)",
    "amount": "5000.00",
    "destinationType": "other-banks",
    "destination": {
      "accountNumber": "1234567890",
      "sortCode": "000014",
      "accountName": "Jane Doe"
    },
    "narration": "Invoice payment"
  }'

5. Read a transaction

Use the provider transaction ID when you have it, or the reference when that is all the provider or your own records gave you. Both return the same shape.

Code
curl -X GET "https://api.planbok.io/v2/virtual-accounts/{id}/transactions/{txnId}" \
  -H "PLANBOK-X-API-KEY: YOUR_LIVE_API_KEY"

Code
curl -X GET "https://api.planbok.io/v2/virtual-accounts/{id}/transactions/reference/{reference}" \
  -H "PLANBOK-X-API-KEY: YOUR_LIVE_API_KEY"

A transaction that belongs to a different virtual account is refused with 403, not returned.

Next steps

• See the Virtual Accounts API reference for the full endpoint specification.
• Read the custody models guide to choose the right model for your use case.