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.
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.
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.
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 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.
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.
Typically, a webhook notification contains two parts
X-webhook-signature
. This field contains an encrypted token which is encoded using HMAC cryptography.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 |
page | integer <int32> Default: 0 page |
size | integer <int32> Default: 100 size |
Authorization required | string Access Token |
[- {
- "accountNumber": "string",
- "accountType": "CURRENT",
- "availableBalance": 0,
- "currency": "string",
- "description": "string",
- "holdReason": "string",
- "holdStatus": "ACTIVE",
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "ledgerBalance": 0,
- "name": "string",
- "overderaftAmount": 0,
- "parentAccount": "string",
- "status": "ACTIVE"
}
]
Authorization required | string Access Token |
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 |
{- "currency": "NGN | USD | BPD | EUR",
- "customerId": "rwrwr-hdhdhdgdf-ggvsdasg625",
- "description": "string",
- "name": "My deposit Account",
- "parentAccount": 3456786543,
- "type": "CURRENT | SAVINGS | VIRTUAL"
}
{ }
Create Customer
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 |
{- "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"
}
{- "code": 0,
- "data": { },
- "message": "string"
}
Update Customer
customerId required | string <uuid> customerId |
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 |
{- "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"
}
{- "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
}
Get Retail Customer KYC
customerId required | string customerId |
Authorization required | string Access Token |
{- "customer": {
- "address1": "string",
- "address2": "string",
- "businessAlias": "string",
- "businessDescription": "string",
- "businessName": "string",
- "bvn": "string",
- "cityOfResidence": "string",
- "companyRegistrationNumber": "string",
- "contactFirstName": "string",
- "contactLastName": "string",
- "contactMiddleName": "string",
- "countryOfIncorporation": "string",
- "countryOfResidence": "string",
- "createdAt": "yyyy-MM-dd'T'hh:mm:ss",
- "createdBy": 0,
- "customerType": "BUSINESS",
- "dateOfBirth": "2019-08-24T14:15:22Z",
- "deleted": true,
- "email": "string",
- "firstName": "string",
- "gender": "f",
- "id": 0,
- "lastName": "string",
- "middleName": "string",
- "mobile": "string",
- "nationality": "string",
- "nin": "string",
- "organization": {
- "address": "string",
- "contactEmail": "string",
- "contactFirstName": "string",
- "contactLastName": "string",
- "contactPhone": "string",
- "countryCode": "string",
- "countryOfIncorporation": "string",
- "createdAt": "yyyy-MM-dd'T'hh:mm:ss",
- "createdBy": 0,
- "dba": "string",
- "entityType": "string",
- "id": 0,
- "ipAddress": "string",
- "isEnabled": true,
- "mobileNo": "string",
- "name": "string",
- "organizationRevenueAccount": "string",
- "organizationSettlementAccount": "string",
- "phone": "string",
- "rcNo": "string",
- "type": "string",
- "uid": "07cc67f4-45d6-494b-adac-09b5cbc7e2b5",
- "updatedAt": "yyyy-MM-dd'T'hh:mm:ss",
- "updatedBy": 0,
- "version": 0
}, - "phone": "string",
- "placeOfBirth": "string",
- "stateOfResidence": "string",
- "uid": "07cc67f4-45d6-494b-adac-09b5cbc7e2b5",
- "updatedAt": "yyyy-MM-dd'T'hh:mm:ss",
- "updatedBy": 0,
- "version": 0
}, - "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "kycDocuments": [
- {
- "createdAt": "yyyy-MM-dd'T'hh:mm:ss",
- "createdBy": 0,
- "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
- "documentType": "DRIVER_LICENCE",
- "fileType": "string",
- "id": 0,
- "name": "string",
- "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
- "status": "APPROVED",
- "uid": "07cc67f4-45d6-494b-adac-09b5cbc7e2b5",
- "updatedAt": "yyyy-MM-dd'T'hh:mm:ss",
- "updatedBy": 0,
- "url": "string",
- "version": 0
}
], - "kycTier": {
- "createdAt": "yyyy-MM-dd'T'hh:mm:ss",
- "createdBy": 0,
- "dailyLimit": 0,
- "id": 0,
- "kycRequirements": [
- {
- "createdAt": "yyyy-MM-dd'T'hh:mm:ss",
- "createdBy": 0,
- "description": "string",
- "id": 0,
- "name": "string",
- "status": "ACTIVE",
- "tier_id": 0,
- "uid": "07cc67f4-45d6-494b-adac-09b5cbc7e2b5",
- "updatedAt": "yyyy-MM-dd'T'hh:mm:ss",
- "updatedBy": 0,
- "version": 0
}
], - "maxCumulativeDeposit": 0,
- "maxSingleDeposit": 0,
- "maxTransactionLimit": 0,
- "name": "string",
- "status": "ACTIVE",
- "uid": "07cc67f4-45d6-494b-adac-09b5cbc7e2b5",
- "updatedAt": "yyyy-MM-dd'T'hh:mm:ss",
- "updatedBy": 0,
- "version": 0
}
}
Get All Transaction
page | integer <int32> Default: 0 page |
size | integer <int32> Default: 100 size |
[- {
- "amount": 0,
- "createdAt": "yyyy-MM-dd'T'hh:mm:ss",
- "description": "string",
- "direction": "CREDIT",
- "recipient": {
- "bank": "GTBank",
- "bankCode": "058",
- "firstName": "Adamu",
- "lastName": "Adewale",
- "middleName": "Okafo"
}, - "recipientAccountNo": "string",
- "referenceNo": "string",
- "sourceAccountNo": "string",
- "status": "DUPLICATE",
- "type": "BOOK",
- "updatedAt": "yyyy-MM-dd'T'hh:mm:ss"
}
]
Get Transaction By Account Number
accountNumber required | string accountNumber |
page | integer <int32> Default: 0 page |
size | integer <int32> Default: 100 size |
{- "amount": 0,
- "createdAt": "yyyy-MM-dd'T'hh:mm:ss",
- "description": "string",
- "direction": "CREDIT",
- "recipient": {
- "bank": "GTBank",
- "bankCode": "058",
- "firstName": "Adamu",
- "lastName": "Adewale",
- "middleName": "Okafo"
}, - "recipientAccountNo": "string",
- "referenceNo": "string",
- "sourceAccountNo": "string",
- "status": "DUPLICATE",
- "type": "BOOK",
- "updatedAt": "yyyy-MM-dd'T'hh:mm:ss"
}
Get Transaction By Reference Number
reference required | string reference |
{- "amount": 0,
- "createdAt": "yyyy-MM-dd'T'hh:mm:ss",
- "description": "string",
- "direction": "CREDIT",
- "recipient": {
- "bank": "GTBank",
- "bankCode": "058",
- "firstName": "Adamu",
- "lastName": "Adewale",
- "middleName": "Okafo"
}, - "recipientAccountNo": "string",
- "referenceNo": "string",
- "sourceAccountNo": "string",
- "status": "DUPLICATE",
- "type": "BOOK",
- "updatedAt": "yyyy-MM-dd'T'hh:mm:ss"
}
Reverse Transaction By Reference Number
ref required | string ref |
reason
property name* | string |
{- "property1": "string",
- "property2": "string"
}
{- "amount": 0,
- "createdAt": "yyyy-MM-dd'T'hh:mm:ss",
- "description": "string",
- "direction": "CREDIT",
- "recipient": {
- "bank": "GTBank",
- "bankCode": "058",
- "firstName": "Adamu",
- "lastName": "Adewale",
- "middleName": "Okafo"
}, - "recipientAccountNo": "string",
- "referenceNo": "string",
- "sourceAccountNo": "string",
- "status": "DUPLICATE",
- "type": "BOOK",
- "updatedAt": "yyyy-MM-dd'T'hh:mm:ss"
}
page | integer <int32> Default: 0 page |
size | integer <int32> Default: 100 size |
[- {
- "amount": 0,
- "createdAt": "yyyy-MM-dd'T'hh:mm:ss",
- "description": "string",
- "direction": "CREDIT",
- "recipient": {
- "bank": "GTBank",
- "bankCode": "058",
- "firstName": "Adamu",
- "lastName": "Adewale",
- "middleName": "Okafo"
}, - "recipientAccountNo": "string",
- "referenceNo": "string",
- "sourceAccountNo": "string",
- "status": "DUPLICATE",
- "type": "BOOK",
- "updatedAt": "yyyy-MM-dd'T'hh:mm:ss"
}
]
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 |
{- "amount": 1500,
- "description": 34567893467,
- "recipient": {
- "bank": "GTBank",
- "bankCode": "058",
- "firstName": "Adamu",
- "lastName": "Adewale",
- "middleName": "Okafo"
}, - "recipientAccountNo": 8798764532,
- "referenceNo": 34567893467,
- "sourceAccountNo": 6872345672,
- "type": "INTER | BOOK"
}
{- "code": 0,
- "data": { },
- "message": "string"
}
[- {
- "amount": 0,
- "createdAt": "yyyy-MM-dd'T'hh:mm:ss",
- "description": "string",
- "direction": "CREDIT",
- "recipient": {
- "bank": "GTBank",
- "bankCode": "058",
- "firstName": "Adamu",
- "lastName": "Adewale",
- "middleName": "Okafo"
}, - "recipientAccountNo": "string",
- "referenceNo": "string",
- "sourceAccountNo": "string",
- "status": "DUPLICATE",
- "type": "BOOK",
- "updatedAt": "yyyy-MM-dd'T'hh:mm:ss"
}
]
{- "amount": 0,
- "createdAt": "yyyy-MM-dd'T'hh:mm:ss",
- "description": "string",
- "direction": "CREDIT",
- "recipient": {
- "bank": "GTBank",
- "bankCode": "058",
- "firstName": "Adamu",
- "lastName": "Adewale",
- "middleName": "Okafo"
}, - "recipientAccountNo": "string",
- "referenceNo": "string",
- "sourceAccountNo": "string",
- "status": "DUPLICATE",
- "type": "BOOK",
- "updatedAt": "yyyy-MM-dd'T'hh:mm:ss"
}
{- "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"
}
CashCodeDto
accountNumber | string |
amount | number <double> |
oneTimePin | string |
reference | string |
{- "accountNumber": "string",
- "amount": 0,
- "oneTimePin": "string",
- "reference": "string"
}
{ }
Get CashCode Status
statusRequestDto
accountNumber | string |
cashCode | string |
{- "accountNumber": "string",
- "cashCode": "string"
}
{- "amount": 0,
- "description": "string",
- "status": "string",
- "subscriberId": "string",
- "tokenLifeTimeInMinutes": "string",
- "transactionType": "string"
}
Create a new webhook
webHookDto
createdAt required | object createdAt |
createdBy required | object createdBy |
email required | object |
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 |
{- "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"
}
Updates WebHook URL
webHookUid required | string <uuid> webHookUid |
webHookDto
createdAt required | object createdAt |
createdBy required | object createdBy |
email required | object |
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 |
{- "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"
}
{- "code": 0,
- "data": { },
- "message": "string"
}