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.

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.

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.

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.

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