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

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

Create a challenge for customer custody virtual account creation

POST

https://api.planbok.io

/customers/{id}/v2/virtual-accounts/create

Creates a challenge for a customer to create a virtual account. This endpoint is only available for customers with custody enabled.

Create a challenge for customer custody virtual account creation › path Parameters

id

string · required

Create a challenge for customer custody virtual account creation › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

Create a challenge for customer custody virtual account creation › Request Body

redirectUrl

string · required

currencies

string[] · required

object · required

Create a challenge for customer custody virtual account creation › Responses

200

Challenge created

success

boolean

message

string

object

POST/customers/{id}/v2/virtual-accounts/create

curl --request POST \
  --url https://api.planbok.io/customers/:id/v2/virtual-accounts/create \
  --header 'Content-Type: application/json' \
  --header 'PLANBOK-X-API-KEY: <string>' \
  --data '
{
  "redirectUrl": "redirectUrl",
  "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

{
  "redirectUrl": "redirectUrl",
  "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": {
    "challengeId": "challengeId",
    "redirectUrl": "redirectUrl",
    "status": "status",
    "expiresAt": "2024-08-25T15:00:00Z"
  }
}

json

application/json

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

Create a challenge for a customer-custody virtual account transfer

POST

https://api.planbok.io

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

Creates a challenge for a customer to initiate a transfer from their virtual account. This endpoint is only available for customers with custody enabled.

Create a challenge for a customer-custody virtual account transfer › path Parameters

id

string · required

Create a challenge for a customer-custody virtual account transfer › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

Create a challenge for a customer-custody virtual account transfer › Request Body

redirectUrl

string · required

amount

string · required

destinationType

string · enum · required

Enum values:

other-banks

same-bank

object · required

narration

string

Create a challenge for a customer-custody virtual account transfer › Responses

200

Transfer challenge created

success

boolean

message

string

object

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

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

shell

Example Request Body

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

json

Example Responses

{
  "success": true,
  "message": "message",
  "data": {
    "challengeId": "challengeId",
    "redirectUrl": "redirectUrl",
    "status": "status",
    "expiresAt": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Transactions Challenges

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

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

Create a challenge for customer custody virtual account creation

POST

https://api.planbok.io

/customers/{id}/v2/virtual-accounts/create

Creates a challenge for a customer to create a virtual account. This endpoint is only available for customers with custody enabled.

Create a challenge for customer custody virtual account creation › path Parameters

id

string · required

Create a challenge for customer custody virtual account creation › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

Create a challenge for customer custody virtual account creation › Request Body

redirectUrl

string · required

currencies

string[] · required

object · required

Create a challenge for customer custody virtual account creation › Responses

200

Challenge created

success

boolean

message

string

object

POST/customers/{id}/v2/virtual-accounts/create

curl --request POST \
  --url https://api.planbok.io/customers/:id/v2/virtual-accounts/create \
  --header 'Content-Type: application/json' \
  --header 'PLANBOK-X-API-KEY: <string>' \
  --data '
{
  "redirectUrl": "redirectUrl",
  "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

{
  "redirectUrl": "redirectUrl",
  "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": {
    "challengeId": "challengeId",
    "redirectUrl": "redirectUrl",
    "status": "status",
    "expiresAt": "2024-08-25T15:00:00Z"
  }
}

json

application/json

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

Create a challenge for a customer-custody virtual account transfer

POST

https://api.planbok.io

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

Creates a challenge for a customer to initiate a transfer from their virtual account. This endpoint is only available for customers with custody enabled.

Create a challenge for a customer-custody virtual account transfer › path Parameters

id

string · required

Create a challenge for a customer-custody virtual account transfer › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

Create a challenge for a customer-custody virtual account transfer › Request Body

redirectUrl

string · required

amount

string · required

destinationType

string · enum · required

Enum values:

other-banks

same-bank

object · required

narration

string

Create a challenge for a customer-custody virtual account transfer › Responses

200

Transfer challenge created

success

boolean

message

string

object

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

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

shell

Example Request Body

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

json

Example Responses

{
  "success": true,
  "message": "message",
  "data": {
    "challengeId": "challengeId",
    "redirectUrl": "redirectUrl",
    "status": "status",
    "expiresAt": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Transactions Challenges