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"
  }'

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.