Bloc API (1.0)

Introduction

Welcome to Bloc! We provide a simple, flexible and seamless way to embed banking capabilities into your app so you can focus on building and launching financial products within weeks. The Bloc API is a JSON RESTful API that uses standard resource-oriented urls, naming conventions, http verbs, response & status codes. It accepts JSON-encoded request bodies and returns JSON-encoded responses.

Authentication

A client_id and secret_key are the required keys used to generate an access_token. These tokens once generated, have a TTL of 60 days after which the developer would be required to use the initial client_id and secret_key to regenerate access_tokens. The Bloc API makes use of Bearer token format for all authentication process. When making requests, they must be included in all requests. An invalid, missing or expired token will result in HTTP 401 Unauthorized responses with matching error codes. For security purposes, the access tokens must never be shared with anyone.

Token Expiration

Access tokens expire over a period of 60 days after which a HTTP 401 Unauthorized status code is thrown. When the token expires, the developer is required to regenerate a token.

Rate Limits

The API limit currently stands at 500 requests per minute after which a client must wait for a minute before their requests can be honoured again. Too many requests in quick succession will result in HTTP status code of 429.

A good way to handle limits is to build a retry mechanism around the 429 status codes when received.

Webhooks

Webhooks are a form of server-to-server communication which enables real-time communication between multiple servers. Leveraging webhooks is a great way of having decoupled communication across various servers and also responding to any event that occurs in real-time. In order to use Bloc API Webhooks, you need to register a webhook url first. Registering a webhook of your choice will determine where we send messages to when any event occurs.

Notification Delivery

Messages are automatically delivered to the registered webhook and expect an acknowledgement from your server. Typically responding with a HTTP 200 OK status is what is required.

Notification Content

Typically, a webhook notification contains two parts

  • Metdata stored in the HTTP header which has an encrypted token that carries some information about the response body
  • The payload stored in the HTTP that contains some event specific data
  • The Metadata field sent along the webhook response is the X-webhook-signature. This field contains an encrypted token which is encoded using HMAC cryptography.

    Retry Mechanism

    The Bloc API has a retry mechanism which occurs at different intervals. The intervals are 10, 20, 40, 80, 160 and 320 minutes respectively.

Status Codes

The Bloc Developer API utilizes the following HTTP status codes to indicate errors and success:

Error Code Meaning
200 OK - Your request is valid
201 Created - Resource created successfully
304 Request Not modified
400 Bad Request - Your request is invalid
401 Unauthorized - Your API Key is wrong
403 Forbidden - Request not allowed
404 Not Found - The specified resource could not be found
405 Method Not Allowed - You tried to access a resource with an invalid method.
409 Request conflict
429 Too Many Requests - You have exceeded our rate limit
500 Internal Server Error - We had a problem with our server. Try again later.
503 Service Unavailable - We're temporarily offline for maintenance. Please try again later

Account

Get list of Accounts

Authorizations:
query Parameters
page
integer <int32>
Default: 0

page

size
integer <int32>
Default: 100

size

header Parameters
Authorization
required
string

Access Token

Example: Bearer access_token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Account

Create Deposit and Virtual Account

Authorizations:
header Parameters
Authorization
required
string

Access Token

Request Body schema: application/json

accountDto

currency
required
string

Account currency type

customerId
required
string

Customer Id

description
string
name
required
string

Account Alias

parentAccount
required
string

Only required for Virtual Account type

type
required
string

Types of Account

Responses

Request samples

Content type
application/json
{
  • "currency": "NGN | USD | BPD | EUR",
  • "customerId": "rwrwr-hdhdhdgdf-ggvsdasg625",
  • "description": "string",
  • "name": "My deposit Account",
  • "parentAccount": 3456786543,
  • "type": "CURRENT | SAVINGS | VIRTUAL"
}

Response samples

Content type
application/json
{ }

Get Organization Revenue Account

Authorizations:
header Parameters
Authorization
required
string

Access Token

Example: Bearer access_token

Responses

Get Organization Settlement Account

Authorizations:
header Parameters
Authorization
required
string

Access Token

Example: Bearer access_token

Responses

Get all Virtual(Wallet) Account

Authorizations:
query Parameters
page
integer <int32>
Default: 0

page

size
integer <int32>
Default: 100

size

header Parameters
Authorization
required
string

Access Token

Example: Bearer access_token

Responses

Get Account by Account number

Authorizations:
path Parameters
accountNumber
required
string

accountNumber

header Parameters
Authorization
required
string

Access Token

Example: Bearer access_token

Responses

Get Account balance

Authorizations:
path Parameters
accountNumber
required
string

accountNumber

header Parameters
Authorization
required
string

Access Token

Example: Bearer access_token

Responses

Block Account

Authorizations:
path Parameters
accountNumber
required
string

accountNumber

header Parameters
Authorization
required
string

Access Token

Example: Bearer access_token

Responses

Close Account

Authorizations:
path Parameters
accountNumber
required
string

accountNumber

header Parameters
Authorization
required
string

Access Token

Example: Bearer access_token

Responses

Reopen Account

Authorizations:
path Parameters
accountNumber
required
string

accountNumber

header Parameters
Authorization
required
string

Access Token

Example: Bearer access_token

Responses

Generate Account Statement

Authorizations:
path Parameters
accountNumber
required
string

accountNumber

query Parameters
from
required
string <date>

from

to
required
string <date>

to

header Parameters
Authorization
required
string

Access Token

Example: Bearer access_token

Responses

Get Account Status

Authorizations:
path Parameters
accountNumber
required
string

accountNumber

header Parameters
Authorization
required
string

Access Token

Example: Bearer access_token

Responses

Unblock Account

Authorizations:
path Parameters
accountNumber
required
string

accountNumber

header Parameters
Authorization
required
string

Access Token

Example: Bearer access_token

Responses

Authentication

Authentication

Authenticate Client

Authorizations:
header Parameters
client-id
required
string

client-id

secret-key
required
string

secret-key

Responses

Bank

Retrieve all banks' details

Authorizations:
query Parameters
pageNumber
integer <int32>
Default: 0

pageNumber

pageSize
integer <int32>
Default: 100

pageSize

header Parameters
Authorization
required
string

Access Token

Responses

Retrieve a bank's details by bank name

Authorizations:
path Parameters
bankName
required
string

bankName

header Parameters
Authorization
required
string

Access Token

Example: BlocBank

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": { },
  • "message": "string"
}

CashCode

Get all generated CashCode

Get all generated CashCode

Authorizations:
header Parameters
Authorization
required
string

Access Token

Responses

Response samples

Content type
application/json
{
  • "accountNumber": "string",
  • "amount": 0,
  • "balance": "string",
  • "currentCount": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "maxCount": "string",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "payWithMobileToken": "string",
  • "reference": "string",
  • "reusable": "string",
  • "status": "CANCEL",
  • "subscriberId": "string",
  • "tokenLifeTimeInMinutes": "string"
}

Create Single CashCode

Create CashCode

Authorizations:
header Parameters
Authorization
required
string

Access Token

Request Body schema: application/json

CashCodeDto

accountNumber
string
amount
number <double>
oneTimePin
string
reference
string

Responses

Request samples

Content type
application/json
{
  • "accountNumber": "string",
  • "amount": 0,
  • "oneTimePin": "string",
  • "reference": "string"
}

Response samples

Content type
application/json
{ }

Get CashCode Status

Get CashCode Status

Authorizations:
header Parameters
Authorization
required
string

Access Token

Request Body schema: application/json

statusRequestDto

accountNumber
string
cashCode
string

Responses

Request samples

Content type
application/json
{
  • "accountNumber": "string",
  • "cashCode": "string"
}

Response samples

Content type
application/json
{
  • "amount": 0,
  • "description": "string",
  • "status": "string",
  • "subscriberId": "string",
  • "tokenLifeTimeInMinutes": "string",
  • "transactionType": "string"
}

Cancel CashCode

Cancel CashCode

Authorizations:
path Parameters
reference
required
string

reference

header Parameters
Authorization
required
string

Access Token

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "description": "string"
}

Customer

Get ALL Customer

Get ALL Customer

Authorizations:
query Parameters
pageNumber
integer <int32>
Default: 0

pageNumber

pageSize
integer <int32>
Default: 100

pageSize

header Parameters
Authorization
required
string

Access Token

Responses

Create Customer

Create Customer

Authorizations:
header Parameters
Authorization
required
string

Access Token

Request Body schema: application/json

customerDto

address1
required
string

address1 is required for both RETAIL and BUSINESS customers

address2
string
businessAlias
required
string

businessAlias is required only for a BUSINESS customer

businessDescription
required
string

businessDescription is required only for a BUSINESS customer

businessName
required
string

businessName is required only for a BUSINESS customer

bvn
string
cityOfResidence
required
string

cityOfResidence is required only for a RETAIL customer

companyRegistrationNumber
required
string

companyRegistrationNumber is required only for a BUSINESS customer

contactFirstName
required
string

contactFirstName is required only for a BUSINESS customer

contactLastName
required
string

contactLastName is required only for a BUSINESS customer

contactMiddleName
string
countryOfIncorporation
required
string

countryOfIncorporation is required only for a BUSINESS customer

countryOfResidence
required
string

countryOfResidence is required only for a RETAIL customer

customerType
required
string

If retail customer, then RETAIL, if business customer then BUSINESS

Value: "BUSINESS or RETAIL"
dateOfBirth
required
string <date-time>

dateOfBirth is required only for a RETAIL customer

email
required
string

email is required for both RETAIL and BUSINESS customers

firstName
required
string

firstName is required only for a RETAIL customer

gender
required
string

gender is only required for a RETAIL customer

Value: "M OR F"
lastName
required
string

lastName is required only for a RETAIL customer

middleName
string
mobile
required
string

mobile is required only for a RETAIL customer

nationality
required
string

nationality is required only for a RETAIL customer

nin
string
phone
required
string

phone is required only for a BUSINESS customer

placeOfBirth
required
string

placeOfBirth is required only for a RETAIL customer

stateOfResidence
required
string

stateOfResidence is required only for a RETAIL customer

Responses

Request samples

Content type
application/json
{
  • "address1": "30 BLoc Drive, Bloc Boulevard",
  • "address2": "TechEstate",
  • "businessAlias": "BlocTech",
  • "businessDescription": "provides IT services",
  • "businessName": "Bloc Tech",
  • "bvn": "00000000000",
  • "cityOfResidence": "Victoria Island",
  • "companyRegistrationNumber": "0009093",
  • "contactFirstName": "James",
  • "contactLastName": "Kent",
  • "contactMiddleName": "Bond",
  • "countryOfIncorporation": "Nigeria",
  • "countryOfResidence": "Nigeria",
  • "customerType": "RETAIL",
  • "dateOfBirth": "2021-10-13T10:09:22.938Z",
  • "email": "izuchukwu@kuznic.bloc",
  • "firstName": "Izuchukwu",
  • "gender": "M",
  • "lastName": "Charles",
  • "middleName": "Kuznic",
  • "mobile": "00000000000",
  • "nationality": "NIGERIAN",
  • "nin": "00000000000",
  • "phone": "004309093",
  • "placeOfBirth": "Lagos",
  • "stateOfResidence": "Lagos"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": { },
  • "message": "string"
}

Get Customer By Id

Get Customer By Id

Authorizations:
path Parameters
customerId
required
string <uuid>

customerId

header Parameters
Authorization
required
string

Access Token

Responses

Update Customer

Update Customer

Authorizations:
path Parameters
customerId
required
string <uuid>

customerId

header Parameters
Authorization
required
string

Access Token

Request Body schema: application/json

customer

address1
required
string

address1 is required for both RETAIL and BUSINESS customers

address2
string
businessAlias
required
string

businessAlias is required only for a BUSINESS customer

businessDescription
required
string

businessDescription is required only for a BUSINESS customer

businessName
required
string

businessName is required only for a BUSINESS customer

bvn
string
cityOfResidence
required
string

cityOfResidence is required only for a RETAIL customer

companyRegistrationNumber
required
string

companyRegistrationNumber is required only for a BUSINESS customer

contactFirstName
required
string

contactFirstName is required only for a BUSINESS customer

contactLastName
required
string

contactLastName is required only for a BUSINESS customer

contactMiddleName
string
countryOfIncorporation
required
string

countryOfIncorporation is required only for a BUSINESS customer

countryOfResidence
required
string

countryOfResidence is required only for a RETAIL customer

customerType
required
string

If retail customer, then RETAIL, if business customer then BUSINESS

Value: "BUSINESS or RETAIL"
dateOfBirth
required
string <date-time>

dateOfBirth is required only for a RETAIL customer

email
required
string

email is required for both RETAIL and BUSINESS customers

firstName
required
string

firstName is required only for a RETAIL customer

gender
required
string

gender is only required for a RETAIL customer

Value: "M OR F"
lastName
required
string

lastName is required only for a RETAIL customer

middleName
string
mobile
required
string

mobile is required only for a RETAIL customer

nationality
required
string

nationality is required only for a RETAIL customer

nin
string
phone
required
string

phone is required only for a BUSINESS customer

placeOfBirth
required
string

placeOfBirth is required only for a RETAIL customer

stateOfResidence
required
string

stateOfResidence is required only for a RETAIL customer

Responses

Request samples

Content type
application/json
{
  • "address1": "30 BLoc Drive, Bloc Boulevard",
  • "address2": "TechEstate",
  • "businessAlias": "BlocTech",
  • "businessDescription": "provides IT services",
  • "businessName": "Bloc Tech",
  • "bvn": "00000000000",
  • "cityOfResidence": "Victoria Island",
  • "companyRegistrationNumber": "0009093",
  • "contactFirstName": "James",
  • "contactLastName": "Kent",
  • "contactMiddleName": "Bond",
  • "countryOfIncorporation": "Nigeria",
  • "countryOfResidence": "Nigeria",
  • "customerType": "RETAIL",
  • "dateOfBirth": "2021-10-13T10:09:22.938Z",
  • "email": "izuchukwu@kuznic.bloc",
  • "firstName": "Izuchukwu",
  • "gender": "M",
  • "lastName": "Charles",
  • "middleName": "Kuznic",
  • "mobile": "00000000000",
  • "nationality": "NIGERIAN",
  • "nin": "00000000000",
  • "phone": "004309093",
  • "placeOfBirth": "Lagos",
  • "stateOfResidence": "Lagos"
}

Response samples

Content type
application/json
{
  • "address1": "30 BLoc Drive, Bloc Boulevard",
  • "address2": "TechEstate",
  • "businessAlias": "BlocTech",
  • "businessDescription": "provides IT services",
  • "businessName": "Bloc Tech",
  • "bvn": "0000000000",
  • "cityOfResidence": "Victoria Island",
  • "companyRegistrationNumber": "000000000",
  • "contactFirstName": "Charles",
  • "contactLastName": "Kuznic",
  • "contactMiddleName": "Izuchukwu",
  • "countryOfIncorporation": "Nigeria",
  • "countryOfResidence": "Nigeria",
  • "createdAt": "string",
  • "createdBy": 6,
  • "customerId": "360204e1-c251-43eb-a93a",
  • "customerType": "RETAIL",
  • "dateOfBirth": "2021-10-13T10:09:22.938Z",
  • "email": "izuchukwu@kuznic.bloc",
  • "firstName": "Charles",
  • "gender": "M",
  • "lastName": "Izuchukwu",
  • "middleName": "Kuznic",
  • "mobile": "00000000000",
  • "nationality": "NIGERIAN",
  • "nin": "0000000000",
  • "organizationId": "4e323-5abc12-343",
  • "phone": "000000000",
  • "placeOfBirth": "Lagos",
  • "stateOfResidence": "Lagos",
  • "updatedAt": "string",
  • "updatedBy": 0
}

Delete Customer

Delete Customer

Authorizations:
path Parameters
customerId
required
string <uuid>

customerId

header Parameters
Authorization
required
string

Access Token

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": { },
  • "message": "string"
}

KYC

updateBvn

Authorizations:
path Parameters
bvn
required
string

bvn

customerId
required
string

customerId

Responses

Get KYC Documents

Get KYC Documents

Authorizations:
header Parameters
Authorization
required
string

Access Token

Responses

Get Customer Kyc Documents

Get Customer Kyc Documents

Authorizations:
path Parameters
customerId
required
string

customerId

header Parameters
Authorization
required
string

Access Token

Responses

Get Document By Document ID

Get Document By Document ID

Authorizations:
path Parameters
documentId
required
string

documentId

header Parameters
Authorization
required
string

Access Token

Responses

Upload KYC Document

Upload KYC Document

Authorizations:
path Parameters
customerId
required
string

customerId

documentType
required
string

documentType

header Parameters
Authorization
required
string

Access Token

Request Body schema: multipart/form-data
file
required
string <binary>

file

Responses

Get Business Customer Kyc

Get Business Customer Kyc

Authorizations:
path Parameters
customerId
required
string

customerId

header Parameters
Authorization
required
string

Access Token

Responses

Response samples

Content type
application/json
{ }

Get Retail Customer KYC

Get Retail Customer KYC

Authorizations:
path Parameters
customerId
required
string

customerId

header Parameters
Authorization
required
string

Access Token

Responses

Response samples

Content type
application/json
{
  • "customer": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "kycDocuments": [
    ],
  • "kycTier": {
    }
}

Delete KYC Document

Delete KYC Document

Authorizations:
path Parameters
documentId
required
string

documentId

header Parameters
Authorization
required
string

Access Token

Responses

Transaction

Get All Transaction

Get All Transaction

Authorizations:
query Parameters
page
integer <int32>
Default: 0

page

size
integer <int32>
Default: 100

size

header Parameters
Authorization
required
string

Access Token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Transaction By Account Number

Get Transaction By Account Number

Authorizations:
path Parameters
accountNumber
required
string

accountNumber

query Parameters
page
integer <int32>
Default: 0

page

size
integer <int32>
Default: 100

size

header Parameters
Authorization
required
string

Access Token

Responses

Response samples

Content type
application/json
{
  • "amount": 0,
  • "createdAt": "yyyy-MM-dd'T'hh:mm:ss",
  • "description": "string",
  • "direction": "DEBIT",
  • "recipient": {
    },
  • "recipientAccountNo": "string",
  • "referenceNo": "string",
  • "sourceAccountNo": "string",
  • "status": "PENDING",
  • "type": "BOOK",
  • "updatedAt": "yyyy-MM-dd'T'hh:mm:ss"
}

Get Transaction By Reference Number

Get Transaction By Reference Number

Authorizations:
path Parameters
reference
required
string

reference

header Parameters
Authorization
required
string

Access Token

Responses

Response samples

Content type
application/json
{
  • "amount": 0,
  • "createdAt": "yyyy-MM-dd'T'hh:mm:ss",
  • "description": "string",
  • "direction": "DEBIT",
  • "recipient": {
    },
  • "recipientAccountNo": "string",
  • "referenceNo": "string",
  • "sourceAccountNo": "string",
  • "status": "PENDING",
  • "type": "BOOK",
  • "updatedAt": "yyyy-MM-dd'T'hh:mm:ss"
}

Reverse Transaction

Reverse Transaction By Reference Number

Authorizations:
path Parameters
ref
required
string

ref

header Parameters
Authorization
required
string

Access Token

Request Body schema: application/json

reason

property name*
string

Responses

Request samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "amount": 0,
  • "createdAt": "yyyy-MM-dd'T'hh:mm:ss",
  • "description": "string",
  • "direction": "DEBIT",
  • "recipient": {
    },
  • "recipientAccountNo": "string",
  • "referenceNo": "string",
  • "sourceAccountNo": "string",
  • "status": "PENDING",
  • "type": "BOOK",
  • "updatedAt": "yyyy-MM-dd'T'hh:mm:ss"
}

Transfer

Get Transfers.

Authorizations:
query Parameters
page
integer <int32>
Default: 0

page

size
integer <int32>
Default: 100

size

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Transfer

Authorizations:
header Parameters
Authorization
required
string

Access Token

Example: Bearer access_token
Request Body schema: application/json

transactionDto

amount
required
number <double>

Amount for this transaction

description
string

Reference for the Transfer

object (Recipient)
recipientAccountNo
required
string

Account to CREDIT for this transaction

referenceNo
required
string

Reference for the Transfer

sourceAccountNo
required
string

Account to DEBIT for this transaction

type
required
string

The Transaction type

Responses

Request samples

Content type
application/json
{
  • "amount": 1500,
  • "description": 34567893467,
  • "recipient": {
    },
  • "recipientAccountNo": 8798764532,
  • "referenceNo": 34567893467,
  • "sourceAccountNo": 6872345672,
  • "type": "INTER | BOOK"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": { },
  • "message": "string"
}

Verify Account Number

Authorizations:
path Parameters
accountNumber
required
string

accountNumber

bankCode
required
string

bankCode

header Parameters
Authorization
required
string

Access Token

Responses

Response samples

Content type
application/json
{ }

Get Transfer By Reference Number.

Authorizations:
path Parameters
referenceNo
required
string

referenceNo

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Reverse Transfer

Authorizations:
path Parameters
referenceNo
required
string

referenceNo

Responses

Response samples

Content type
application/json
{
  • "amount": 0,
  • "createdAt": "yyyy-MM-dd'T'hh:mm:ss",
  • "description": "string",
  • "direction": "DEBIT",
  • "recipient": {
    },
  • "recipientAccountNo": "string",
  • "referenceNo": "string",
  • "sourceAccountNo": "string",
  • "status": "PENDING",
  • "type": "BOOK",
  • "updatedAt": "yyyy-MM-dd'T'hh:mm:ss"
}

Get Transfer status.

Authorizations:
path Parameters
referenceNo
required
string

referenceNo

Responses

Response samples

Content type
application/json
{ }

WebHooks

Create a WebHook

Create a new webhook

Authorizations:
header Parameters
Authorization
required
string

Access Token

Request Body schema: application/json

webHookDto

webHookURL
required
string

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": { },
  • "message": "string"
}

Enable a webHook

Enable a WebHook

Authorizations:
path Parameters
webHookId
required
integer <int64>

webHookId

header Parameters
Authorization
required
string

Access Token

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": { },
  • "message": "string"
}

Get a WebHook

Get a webhook

Authorizations:
path Parameters
webHookUid
required
string <uuid>

webHookUid

header Parameters
Authorization
required
string

Access Token

Responses

Update a WebHook

Updates WebHook URL

Authorizations:
path Parameters
webHookUid
required
string <uuid>

webHookUid

header Parameters
Authorization
required
string

Access Token

Request Body schema: application/json

webHookDto

webHookURL
required
string

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": { },
  • "message": "string"
}