Planbok V2 API

Virtual Accounts

Endpoint

List organization virtual accounts

GET

https://api.planbok.io

/v2/virtual-accounts

Returns a paginated list of virtual accounts for the organization.

List organization virtual accounts › query Parameters

page

integer

Default: 1

limit

integer

Default: 20

List organization virtual accounts › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

List organization virtual accounts › Responses

200

Paginated list of virtual accounts

success

boolean

object

GET/v2/virtual-accounts

curl --request GET \
  --url https://api.planbok.io/v2/virtual-accounts \
  --header 'PLANBOK-X-API-KEY: <string>'

shell

Example Responses

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "id",
        "name": "name",
        "refId": "refId",
        "controller": "organization",
        "currency": "currency",
        "fundingMethod": "fundingMethod",
        "accountNumber": "accountNumber",
        "accountName": "accountName",
        "bankName": "bankName",
        "bankCode": "bankCode",
        "status": "status",
        "providerCustomerId": "providerCustomerId",
        "providerWalletId": "providerWalletId",
        "createdAt": "2024-08-25T15:00:00Z"
      }
    ],
    "pagination": {
      "total": 0,
      "page": 0,
      "pages": 0
    }
  }
}

json

application/json

Create organization custody virtual accounts

POST

https://api.planbok.io

/v2/virtual-accounts

Creates virtual accounts for the organization. This endpoint is only available for organizations with custody enabled.

Create organization custody virtual accounts › Request Body

idempotencyKey

string · required

count

integer · required

object[] · required

encryptedOrganizationSecret

string

Required only for organizations operating in trustless MPC mode. Must be a base64 encoded ciphertext. Use context verify

Create organization custody virtual accounts › Responses

Virtual accounts created

success

boolean

message

string

object

POST/v2/virtual-accounts

curl --request POST \
  --url https://api.planbok.io/v2/virtual-accounts \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "idempotencyKey",
  "encryptedOrganizationSecret": "",
  "count": 0,
  "metadata": [
    {
      "name": "name",
      "refId": "refId",
      "currencies": [
        "string"
      ],
      "holderDetails": {
        "firstName": "firstName",
        "lastName": "lastName",
        "phoneNumber": "phoneNumber",
        "email": "email",
        "address": "address",
        "dateOfBirth": "1990-12-28",
        "bvn": "bvn",
        "nin": "nin"
      }
    }
  ]
}
'

shell

Example Request Body

{
  "idempotencyKey": "idempotencyKey",
  "encryptedOrganizationSecret": "",
  "count": 0,
  "metadata": [
    {
      "name": "name",
      "refId": "refId",
      "currencies": [
        "string"
      ],
      "holderDetails": {
        "firstName": "firstName",
        "lastName": "lastName",
        "phoneNumber": "phoneNumber",
        "email": "email",
        "address": "address",
        "dateOfBirth": "1990-12-28",
        "bvn": "bvn",
        "nin": "nin"
      }
    }
  ]
}

json

Example Responses

{
  "success": true,
  "message": "message",
  "data": {
    "created": [
      {
        "id": "id",
        "name": "name",
        "refId": "refId",
        "controller": "organization",
        "currency": "currency",
        "fundingMethod": "fundingMethod",
        "accountNumber": "accountNumber",
        "accountName": "accountName",
        "bankName": "bankName",
        "bankCode": "bankCode",
        "status": "status",
        "providerCustomerId": "providerCustomerId",
        "providerWalletId": "providerWalletId",
        "createdAt": "2024-08-25T15:00:00Z"
      }
    ],
    "skipped": [
      {}
    ],
    "failed": [
      {}
    ]
  }
}

json

application/json

Get virtual account

GET

https://api.planbok.io

/v2/virtual-accounts/{id}

Retrieves details of a specific virtual account by its ID.

Get virtual account › path Parameters

id

string · required

Get virtual account › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

Get virtual account › Responses

Virtual account retrieved

success

boolean

object

Get Bank List

GET

https://api.planbok.io

/v2/virtual-accounts/banks

Returns a list of available banks to transact with.

Get Bank List › query Parameters

order

string

searchTerm

string

Get Bank List › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

Get Bank List › Responses

200

List of banks

success

boolean

object

Get virtual account balance

GET

https://api.planbok.io

/v2/virtual-accounts/{id}/balance

Retrieves the balance of a specific virtual account by its ID.

Get virtual account balance › path Parameters

id

string · required

Get virtual account balance › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

Get virtual account balance › Responses

Balance retrieved

success

boolean

object

Get provider-side customer details

GET

https://api.planbok.io

/v2/virtual-accounts/{id}/customer-details

Retrieves customer details associated with a specific virtual account by its ID.

Get provider-side customer details › path Parameters

id

string · required

Get provider-side customer details › Responses

Customer details retrieved

success

boolean

data

object

List virtual account transactions

GET

https://api.planbok.io

/v2/virtual-accounts/{id}/transactions

Retrieves a paginated list of transactions for a specific virtual account by its ID.

List virtual account transactions › path Parameters

id

string · required

List virtual account transactions › query Parameters

page

integer

Default: 1

limit

integer

Default: 20

from

string · date-time

to

string · date-time

List virtual account transactions › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

List virtual account transactions › Responses

Transactions retrieved

success

boolean

object

GET/v2/virtual-accounts/{id}/transactions

curl --request GET \
  --url https://api.planbok.io/v2/virtual-accounts/:id/transactions \
  --header 'PLANBOK-X-API-KEY: <string>'

shell

Example Responses

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "id",
        "amount": "amount",
        "currency": "currency",
        "transType": "transType",
        "entry": "entry",
        "reference": "reference",
        "CustomerReference": "CustomerReference",
        "source": "source",
        "destination": "destination",
        "narration": "narration",
        "status": "status",
        "recipientDetails": "recipientDetails",
        "senderDetails": "senderDetails",
        "senderBank": "senderBank",
        "recipientBank": "recipientBank",
        "provider": "provider",
        "sessionId": "sessionId",
        "accountProvider": "accountProvider",
        "createdAt": "2024-08-25T15:00:00Z",
        "updatedAt": "2024-08-25T15:00:00Z"
      }
    ],
    "pagination": {
      "total": 0,
      "page": 0,
      "pages": 0
    }
  }
}

json

application/json

Get transaction details

GET

https://api.planbok.io

/v2/virtual-accounts/transactions/{id}

Retrieves details of a specific transaction by its ID.

Get transaction details › path Parameters

id

string · required

Get transaction details › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

Get transaction details › Responses

Transaction retrieved

success

boolean

object

Internal Loma account name lookup

GET

https://api.planbok.io

/v2/virtual-accounts/loma-name/enquiry

Retrieves the name associated with a specific Loma account number.

Internal Loma account name lookup › query Parameters

accountNumber

string · required

Internal Loma account name lookup › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

Internal Loma account name lookup › Responses

Loma name enquiry completed

success

boolean

object

External bank account name lookup

GET

https://api.planbok.io

/v2/virtual-accounts/name/enquiry

Retrieves the name associated with a specific external bank account number.

External bank account name lookup › query Parameters

accountNumber

string · required

sortCode

string · required

External bank account name lookup › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

External bank account name lookup › Responses

200

Name enquiry completed

success

boolean

object

Initiate a transfer

POST

https://api.planbok.io

/v2/virtual-accounts/{id}/transfer

Initiates a transfer from an organization-custody virtual account to an external bank account or same bank account. This endpoint is only available for organization-custody virtual accounts.

Initiate a transfer › path Parameters

id

string · required

Initiate a transfer › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

Initiate a transfer › Request Body

idempotencyKey

string · required

amount

string · required

destinationType

string · enum · required

Enum values:

other-banks

same-bank

object · required

encryptedOrganizationSecret

string

Required only for organizations operating in trustless MPC mode. Must be a base64 encoded ciphertext. Use context verify

narration

string

Initiate a transfer › Responses

Transfer initiated

success

boolean

message

string

object

POST/v2/virtual-accounts/{id}/transfer

curl --request POST \
  --url https://api.planbok.io/v2/virtual-accounts/:id/transfer \
  --header 'Content-Type: application/json' \
  --header 'PLANBOK-X-API-KEY: <string>' \
  --data '
{
  "idempotencyKey": "idempotencyKey",
  "encryptedOrganizationSecret": "",
  "amount": "amount",
  "destinationType": "other-banks",
  "destination": {
    "accountNumber": "accountNumber",
    "sortCode": "sortCode",
    "accountName": "accountName"
  },
  "narration": "narration"
}
'

shell

Example Request Body

{
  "idempotencyKey": "idempotencyKey",
  "encryptedOrganizationSecret": "",
  "amount": "amount",
  "destinationType": "other-banks",
  "destination": {
    "accountNumber": "accountNumber",
    "sortCode": "sortCode",
    "accountName": "accountName"
  },
  "narration": "narration"
}

json

Example Responses

{
  "success": true,
  "message": "message",
  "data": {
    "transferId": "transferId",
    "status": "status",
    "amount": "amount",
    "currency": "currency",
    "destinationType": "destinationType",
    "providerReference": "providerReference"
  }
}

json

application/json

Transactions Customers

Planbok V2 API

Virtual Accounts

Endpoint

List organization virtual accounts

GET

https://api.planbok.io

/v2/virtual-accounts

Returns a paginated list of virtual accounts for the organization.

List organization virtual accounts › query Parameters

page

integer

Default: 1

limit

integer

Default: 20

List organization virtual accounts › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

List organization virtual accounts › Responses

200

Paginated list of virtual accounts

success

boolean

object

GET/v2/virtual-accounts

curl --request GET \
  --url https://api.planbok.io/v2/virtual-accounts \
  --header 'PLANBOK-X-API-KEY: <string>'

shell

Example Responses

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "id",
        "name": "name",
        "refId": "refId",
        "controller": "organization",
        "currency": "currency",
        "fundingMethod": "fundingMethod",
        "accountNumber": "accountNumber",
        "accountName": "accountName",
        "bankName": "bankName",
        "bankCode": "bankCode",
        "status": "status",
        "providerCustomerId": "providerCustomerId",
        "providerWalletId": "providerWalletId",
        "createdAt": "2024-08-25T15:00:00Z"
      }
    ],
    "pagination": {
      "total": 0,
      "page": 0,
      "pages": 0
    }
  }
}

json

application/json

Create organization custody virtual accounts

POST

https://api.planbok.io

/v2/virtual-accounts

Creates virtual accounts for the organization. This endpoint is only available for organizations with custody enabled.

Create organization custody virtual accounts › Request Body

idempotencyKey

string · required

count

integer · required

object[] · required

encryptedOrganizationSecret

string

Required only for organizations operating in trustless MPC mode. Must be a base64 encoded ciphertext. Use context verify

Create organization custody virtual accounts › Responses

Virtual accounts created

success

boolean

message

string

object

POST/v2/virtual-accounts

curl --request POST \
  --url https://api.planbok.io/v2/virtual-accounts \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "idempotencyKey",
  "encryptedOrganizationSecret": "",
  "count": 0,
  "metadata": [
    {
      "name": "name",
      "refId": "refId",
      "currencies": [
        "string"
      ],
      "holderDetails": {
        "firstName": "firstName",
        "lastName": "lastName",
        "phoneNumber": "phoneNumber",
        "email": "email",
        "address": "address",
        "dateOfBirth": "1990-12-28",
        "bvn": "bvn",
        "nin": "nin"
      }
    }
  ]
}
'

shell

Example Request Body

{
  "idempotencyKey": "idempotencyKey",
  "encryptedOrganizationSecret": "",
  "count": 0,
  "metadata": [
    {
      "name": "name",
      "refId": "refId",
      "currencies": [
        "string"
      ],
      "holderDetails": {
        "firstName": "firstName",
        "lastName": "lastName",
        "phoneNumber": "phoneNumber",
        "email": "email",
        "address": "address",
        "dateOfBirth": "1990-12-28",
        "bvn": "bvn",
        "nin": "nin"
      }
    }
  ]
}

json

Example Responses

{
  "success": true,
  "message": "message",
  "data": {
    "created": [
      {
        "id": "id",
        "name": "name",
        "refId": "refId",
        "controller": "organization",
        "currency": "currency",
        "fundingMethod": "fundingMethod",
        "accountNumber": "accountNumber",
        "accountName": "accountName",
        "bankName": "bankName",
        "bankCode": "bankCode",
        "status": "status",
        "providerCustomerId": "providerCustomerId",
        "providerWalletId": "providerWalletId",
        "createdAt": "2024-08-25T15:00:00Z"
      }
    ],
    "skipped": [
      {}
    ],
    "failed": [
      {}
    ]
  }
}

json

application/json

Get virtual account

GET

https://api.planbok.io

/v2/virtual-accounts/{id}

Retrieves details of a specific virtual account by its ID.

Get virtual account › path Parameters

id

string · required

Get virtual account › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

Get virtual account › Responses

Virtual account retrieved

success

boolean

object

Get Bank List

GET

https://api.planbok.io

/v2/virtual-accounts/banks

Returns a list of available banks to transact with.

Get Bank List › query Parameters

order

string

searchTerm

string

Get Bank List › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

Get Bank List › Responses

200

List of banks

success

boolean

object

Get virtual account balance

GET

https://api.planbok.io

/v2/virtual-accounts/{id}/balance

Retrieves the balance of a specific virtual account by its ID.

Get virtual account balance › path Parameters

id

string · required

Get virtual account balance › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

Get virtual account balance › Responses

Balance retrieved

success

boolean

object

Get provider-side customer details

GET

https://api.planbok.io

/v2/virtual-accounts/{id}/customer-details

Retrieves customer details associated with a specific virtual account by its ID.

Get provider-side customer details › path Parameters

id

string · required

Get provider-side customer details › Responses

Customer details retrieved

success

boolean

data

object

List virtual account transactions

GET

https://api.planbok.io

/v2/virtual-accounts/{id}/transactions

Retrieves a paginated list of transactions for a specific virtual account by its ID.

List virtual account transactions › path Parameters

id

string · required

List virtual account transactions › query Parameters

page

integer

Default: 1

limit

integer

Default: 20

from

string · date-time

to

string · date-time

List virtual account transactions › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

List virtual account transactions › Responses

Transactions retrieved

success

boolean

object

GET/v2/virtual-accounts/{id}/transactions

curl --request GET \
  --url https://api.planbok.io/v2/virtual-accounts/:id/transactions \
  --header 'PLANBOK-X-API-KEY: <string>'

shell

Example Responses

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "id",
        "amount": "amount",
        "currency": "currency",
        "transType": "transType",
        "entry": "entry",
        "reference": "reference",
        "CustomerReference": "CustomerReference",
        "source": "source",
        "destination": "destination",
        "narration": "narration",
        "status": "status",
        "recipientDetails": "recipientDetails",
        "senderDetails": "senderDetails",
        "senderBank": "senderBank",
        "recipientBank": "recipientBank",
        "provider": "provider",
        "sessionId": "sessionId",
        "accountProvider": "accountProvider",
        "createdAt": "2024-08-25T15:00:00Z",
        "updatedAt": "2024-08-25T15:00:00Z"
      }
    ],
    "pagination": {
      "total": 0,
      "page": 0,
      "pages": 0
    }
  }
}

json

application/json

Get transaction details

GET

https://api.planbok.io

/v2/virtual-accounts/transactions/{id}

Retrieves details of a specific transaction by its ID.

Get transaction details › path Parameters

id

string · required

Get transaction details › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

Get transaction details › Responses

Transaction retrieved

success

boolean

object

Internal Loma account name lookup

GET

https://api.planbok.io

/v2/virtual-accounts/loma-name/enquiry

Retrieves the name associated with a specific Loma account number.

Internal Loma account name lookup › query Parameters

accountNumber

string · required

Internal Loma account name lookup › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

Internal Loma account name lookup › Responses

Loma name enquiry completed

success

boolean

object

External bank account name lookup

GET

https://api.planbok.io

/v2/virtual-accounts/name/enquiry

Retrieves the name associated with a specific external bank account number.

External bank account name lookup › query Parameters

accountNumber

string · required

sortCode

string · required

External bank account name lookup › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

External bank account name lookup › Responses

200

Name enquiry completed

success

boolean

object

Initiate a transfer

POST

https://api.planbok.io

/v2/virtual-accounts/{id}/transfer

Initiates a transfer from an organization-custody virtual account to an external bank account or same bank account. This endpoint is only available for organization-custody virtual accounts.

Initiate a transfer › path Parameters

id

string · required

Initiate a transfer › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

Initiate a transfer › Request Body

idempotencyKey

string · required

amount

string · required

destinationType

string · enum · required

Enum values:

other-banks

same-bank

object · required

encryptedOrganizationSecret

string

Required only for organizations operating in trustless MPC mode. Must be a base64 encoded ciphertext. Use context verify

narration

string

Initiate a transfer › Responses

Transfer initiated

success

boolean

message

string

object

POST/v2/virtual-accounts/{id}/transfer

curl --request POST \
  --url https://api.planbok.io/v2/virtual-accounts/:id/transfer \
  --header 'Content-Type: application/json' \
  --header 'PLANBOK-X-API-KEY: <string>' \
  --data '
{
  "idempotencyKey": "idempotencyKey",
  "encryptedOrganizationSecret": "",
  "amount": "amount",
  "destinationType": "other-banks",
  "destination": {
    "accountNumber": "accountNumber",
    "sortCode": "sortCode",
    "accountName": "accountName"
  },
  "narration": "narration"
}
'

shell

Example Request Body

{
  "idempotencyKey": "idempotencyKey",
  "encryptedOrganizationSecret": "",
  "amount": "amount",
  "destinationType": "other-banks",
  "destination": {
    "accountNumber": "accountNumber",
    "sortCode": "sortCode",
    "accountName": "accountName"
  },
  "narration": "narration"
}

json

Example Responses

{
  "success": true,
  "message": "message",
  "data": {
    "transferId": "transferId",
    "status": "status",
    "amount": "amount",
    "currency": "currency",
    "destinationType": "destinationType",
    "providerReference": "providerReference"
  }
}

json

application/json

Transactions Customers