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

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
[
  • {
    }
]

createSavingsAccount

header Parameters
Authorization
required
string

Access Token

Request Body schema: application/json

accountDto

currency
required
object

Account currency type

customerId
required
object

Customer Id

description
string
name
required
object

Account Alias

parentAccount
required
object

Only required for Virtual Account type

type
required
object

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

header Parameters
Authorization
required
string

Access Token

Responses

Get Organization Settlement Account

header Parameters
Authorization
required
string

Access Token

Responses

Get all Virtual(Wallet) Account

query Parameters
page
integer <int32>
Default: 0

page

size
integer <int32>
Default: 100

size

header Parameters
Authorization
required
string

Access Token

Responses

Get Account by Account number

path Parameters
accountNumber
required
string

accountNumber

header Parameters
Authorization
required
string

Access Token

Responses

Get Account balance

path Parameters
accountNumber
required
string

accountNumber

header Parameters
Authorization
required
string

Access Token

Responses

Block Account

path Parameters
accountNumber
required
string

accountNumber

header Parameters
Authorization
required
string

Access Token

Responses

Close Account

path Parameters
accountNumber
required
string

accountNumber

header Parameters
Authorization
required
string

Access Token

Responses

Reopen Account

path Parameters
accountNumber
required
string

accountNumber

header Parameters
Authorization
required
string

Access Token

Responses

Generate Account Statement

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

Responses

Get Account Status

path Parameters
accountNumber
required
string

accountNumber

header Parameters
Authorization
required
string

Access Token

Responses

Unblock Account

path Parameters
accountNumber
required
string

accountNumber

header Parameters
Authorization
required
string

Access Token

Responses

Get Customer list of Accounts

path Parameters
customerId
required
string

customerId

header Parameters
Authorization
required
string

Access Token

Responses

Authentication

Authentication

Authenticate Client

header Parameters
client-id
required
string

client-id

secret-key
required
string

secret-key

Responses

Bank

Retrieve all banks' details

query Parameters
pageNumber
integer <int32>
Default: 0

pageNumber

pageSize
integer <int32>
Default: 100

pageSize

Responses

Retrieve a bank's details by bank name

path Parameters
bankName
required
string

bankName

Responses

Response samples

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

Customer

Get ALL Customer

Get ALL Customer

query Parameters
pageNumber
integer <int32>
Default: 0

pageNumber

pageSize
integer <int32>
Default: 100

pageSize

Responses

Create Customer

Create Customer

Request Body schema: application/json

customerDto

address1
required
object

address1 is required for both RETAIL and BUSINESS customers

address2
object
businessAlias
required
object

businessAlias is required only for a BUSINESS customer

businessDescription
required
object

businessDescription is required only for a BUSINESS customer

businessName
required
object

businessName is required only for a BUSINESS customer

bvn
object
cityOfResidence
required
object

cityOfResidence is required only for a RETAIL customer

companyRegistrationNumber
required
object

companyRegistrationNumber is required only for a BUSINESS customer

contactFirstName
required
object

contactFirstName is required only for a BUSINESS customer

contactLastName
required
object

contactLastName is required only for a BUSINESS customer

contactMiddleName
object
countryOfIncorporation
required
object

countryOfIncorporation is required only for a BUSINESS customer

countryOfResidence
required
object

countryOfResidence is required only for a RETAIL customer

customerType
required
object

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

dateOfBirth
required
object

dateOfBirth is required only for a RETAIL customer

email
required
object

email is required for both RETAIL and BUSINESS customers

firstName
required
object

firstName is required only for a RETAIL customer

gender
required
object

gender is only required for a RETAIL customer

lastName
required
object

lastName is required only for a RETAIL customer

middleName
object
mobile
required
object

mobile is required only for a RETAIL customer

nationality
required
object

nationality is required only for a RETAIL customer

nin
object
phone
required
object

phone is required only for a BUSINESS customer

placeOfBirth
required
object

placeOfBirth is required only for a RETAIL customer

stateOfResidence
required
object

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": "1980-10-25",
  • "email": "izuchukwu@kuznic.bloc",
  • "firstName": "Izuchukwu",
  • "gender": "M",
  • "lastName": "Charles",
  • "middleName": "Kuznic",
  • "mobile": "+2340000000000",
  • "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

path Parameters
customerId
required
string <uuid>

customerId

Responses

Update Customer

Update Customer

path Parameters
customerId
required
string <uuid>

customerId

Request Body schema: application/json

customer

address1
required
object

address1 is required for both RETAIL and BUSINESS customers

address2
object
businessAlias
required
object

businessAlias is required only for a BUSINESS customer

businessDescription
required
object

businessDescription is required only for a BUSINESS customer

businessName
required
object

businessName is required only for a BUSINESS customer

bvn
object
cityOfResidence
required
object

cityOfResidence is required only for a RETAIL customer

companyRegistrationNumber
required
object

companyRegistrationNumber is required only for a BUSINESS customer

contactFirstName
required
object

contactFirstName is required only for a BUSINESS customer

contactLastName
required
object

contactLastName is required only for a BUSINESS customer

contactMiddleName
object
countryOfIncorporation
required
object

countryOfIncorporation is required only for a BUSINESS customer

countryOfResidence
required
object

countryOfResidence is required only for a RETAIL customer

customerType
required
object

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

dateOfBirth
required
object

dateOfBirth is required only for a RETAIL customer

email
required
object

email is required for both RETAIL and BUSINESS customers

firstName
required
object

firstName is required only for a RETAIL customer

gender
required
object

gender is only required for a RETAIL customer

lastName
required
object

lastName is required only for a RETAIL customer

middleName
object
mobile
required
object

mobile is required only for a RETAIL customer

nationality
required
object

nationality is required only for a RETAIL customer

nin
object
phone
required
object

phone is required only for a BUSINESS customer

placeOfBirth
required
object

placeOfBirth is required only for a RETAIL customer

stateOfResidence
required
object

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": "1980-10-25",
  • "email": "izuchukwu@kuznic.bloc",
  • "firstName": "Izuchukwu",
  • "gender": "M",
  • "lastName": "Charles",
  • "middleName": "Kuznic",
  • "mobile": "+2340000000000",
  • "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": "1980-10-25",
  • "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

path Parameters
customerId
required
string <uuid>

customerId

Responses

Response samples

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

KYC

updateBvn

path Parameters
bvn
required
string

bvn

customerId
required
string

customerId

header Parameters
Authorization
required
string

Access Token

Responses

Get KYC Documents

Get KYC Documents

header Parameters
Authorization
required
string

Access Token

Responses

Get Customer Kyc Documents

Get Customer Kyc Documents

path Parameters
customerId
required
string

customerId

header Parameters
Authorization
required
string

Access Token

Responses

Get Document By Document ID

Get Document By Document ID

path Parameters
documentId
required
string

documentId

header Parameters
Authorization
required
string

Access Token

Responses

Upload KYC Document

Upload KYC Document

path Parameters
customerId
required
string

customerId

documentType
required
string

documentType

header Parameters
Authorization
required
string

Access Token

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

Responses

Get Business Customer Kyc

Get Business Customer Kyc

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

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

path Parameters
documentId
required
string

documentId

header Parameters
Authorization
required
string

Access Token

Responses

Transaction

Get All Transaction

Get All Transaction

query Parameters
page
integer <int32>
Default: 0

page

size
integer <int32>
Default: 100

size

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Transaction By Account Number

Get Transaction By Account Number

path Parameters
accountNumber
required
string

accountNumber

query Parameters
page
integer <int32>
Default: 0

page

size
integer <int32>
Default: 100

size

Responses

Response samples

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

Get Transaction By Reference Number

Get Transaction By Reference Number

path Parameters
reference
required
string

reference

Responses

Response samples

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

Reverse Transaction

Reverse Transaction By Reference Number

path Parameters
ref
required
string

ref

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": "CREDIT",
  • "recipient": {
    },
  • "recipientAccountNo": "string",
  • "referenceNo": "string",
  • "sourceAccountNo": "string",
  • "status": "DUPLICATE",
  • "type": "BOOK",
  • "updatedAt": "yyyy-MM-dd'T'hh:mm:ss"
}

Transfer

Get Transfers.

query Parameters
page
integer <int32>
Default: 0

page

size
integer <int32>
Default: 100

size

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Transfer

Request Body schema: application/json

transactionDto

amount
required
object

Amount for this transaction

description
object

Reference for the Transfer

object (Recipient)
recipientAccountNo
required
object

Account to CREDIT for this transaction

referenceNo
required
object

Reference for the Transfer

sourceAccountNo
required
object

Account to DEBIT for this transaction

type
required
object

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

path Parameters
accountNumber
required
string

accountNumber

bankCode
required
string

bankCode

Responses

Response samples

Content type
application/json
{ }

Get Transfer By Reference Number.

path Parameters
referenceNo
required
string

referenceNo

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Reverse Transfer

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": "CREDIT",
  • "recipient": {
    },
  • "recipientAccountNo": "string",
  • "referenceNo": "string",
  • "sourceAccountNo": "string",
  • "status": "DUPLICATE",
  • "type": "BOOK",
  • "updatedAt": "yyyy-MM-dd'T'hh:mm:ss"
}

Get Transfer status.

path Parameters
referenceNo
required
string

referenceNo

Responses

Response samples

Content type
application/json
{ }

cash-code-controller

Cash Code Controller

Get all generated CashCode

Get all generated CashCode

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": "APPROVED",
  • "subscriberId": "string",
  • "tokenLifeTimeInMinutes": "string"
}

createCashCode

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

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

path Parameters
reference
required
string

reference

Responses

Response samples

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

web-hook-controller

Web Hook Controller

Create a WebHook

Create a new webhook

Request Body schema: application/json

webHookDto

createdAt
required
object

createdAt

createdBy
required
object

createdBy

email
required
object

email

organizationUid
required
object

organizationUid

updatedAt
required
object

updatedAt

updatedBy
required
object

updatedBy

version
string
webHookLabel
required
object

webHookLabel

webHookStatus
required
object

webHookStatus

webHookURL
required
object

webHookURL

Responses

Request samples

Content type
application/json
{
  • "createdAt": "createdAt",
  • "createdBy": "Uid of the user",
  • "email": "email",
  • "organizationUid": "organizationUid",
  • "updatedAt": "updatedAt",
  • "updatedBy": "Uid of the user",
  • "version": "string",
  • "webHookLabel": "webHookLabel",
  • "webHookStatus": "webHookStatus",
  • "webHookURL": "webHookURL"
}

Get all WebHooks by Organization ID

Get all WebHooks by Organization ID

path Parameters
orgUid
required
string <uuid>

orgUid

Responses

Enable a webHook

Enable a WebHook

path Parameters
webHookId
required
integer <int64>

webHookId

Responses

Response samples

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

Get a WebHook

Get a webhook

path Parameters
webHookUid
required
string <uuid>

webHookUid

Responses

Update a WebHook

Updates WebHook URL

path Parameters
webHookUid
required
string <uuid>

webHookUid

Request Body schema: application/json

webHookDto

createdAt
required
object

createdAt

createdBy
required
object

createdBy

email
required
object

email

organizationUid
required
object

organizationUid

updatedAt
required
object

updatedAt

updatedBy
required
object

updatedBy

version
string
webHookLabel
required
object

webHookLabel

webHookStatus
required
object

webHookStatus

webHookURL
required
object

webHookURL

Responses

Request samples

Content type
application/json
{
  • "createdAt": "createdAt",
  • "createdBy": "Uid of the user",
  • "email": "email",
  • "organizationUid": "organizationUid",
  • "updatedAt": "updatedAt",
  • "updatedBy": "Uid of the user",
  • "version": "string",
  • "webHookLabel": "webHookLabel",
  • "webHookStatus": "webHookStatus",
  • "webHookURL": "webHookURL"
}

Response samples

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