Planbok V2 API

Virtual Accounts

Endpoint

List virtual accounts

GET

https://api.planbok.io

/v2/virtual-accounts

Returns a paginated list of virtual accounts for the organization.

List virtual accounts › query Parameters

refId

string

Reference ID of the virtual account. If provided, only the virtual account with this reference ID will be returned.

customerIds

string

Comma separated list of customer IDs

page

integer

Default: 1

limit

integer

Default: 20

List virtual accounts › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

List 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 virtual accounts

GET

https://api.planbok.io

/v2/virtual-accounts

Returns a paginated list of virtual accounts for the organization.

List virtual accounts › query Parameters

refId

string

Reference ID of the virtual account. If provided, only the virtual account with this reference ID will be returned.

customerIds

string

Comma separated list of customer IDs

page

integer

Default: 1

limit

integer

Default: 20

List virtual accounts › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

List 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