Open API Quickstart

First Steps

• Download Banq mobile application iOS or Android. Speak to your Solutions Engineer about opting into the beta product to test in sandbox.
• Complete sign up and create a user. Typically each integrator's user could have their own user at Banq to receive payments
• Create a business space and pass KYC checks with the compliance team

Authentication

Authentication is performed via the Auth0 platform based on API client_id, client_username, and client_password. Integrators are represented as an M2M Application that that interacts with the Banq API on behalf of the Banq user. Client credentials flow should be used to obtain the access token and use it in the Authorization header with the Bearer prefix to access Banq API.

You need to POST to Auth0 endpoint /oauth/token following values:

• client_id identifier of the M2M Application
• username assigned username for the M2M Application
• password assigned password for the M2M Application
• audience: https://banq.com/open/api/
• grant_type: password

To identify a Banq user we use the unique bearer token passed through on all subsequent calls. All Open API operations are performed on this user's behalf.

📘

Obtaining Authentication Information

In order to authenticate with our Open API, integrators should reach out to the sales or customer operations team and request the following information in order to start working with the Banq Open API:

• API client ID
• API client username/password
• Authentication tenant name
• Banq API host name
• Banq Account GUID
• Banq Space ID

Error Codes

• 200 - the request was performed successfully and the relevant response is returned.
• 201 - the entity was created successfully and is returned in the response. This entity is accessible at the link sent in the Location response header.
• 400 - the request was malformed or some business rules were not satisfied. Returns error message.
• 401 - there were problems with the access token or it is missing.
• 403 - the operation is forbidden for the current user.
• 404 - the entity was not found in the system.
• 422 - due to validation errors or external reasons, the request cannot be processed.

Transaction fail reasons

• None - default transaction fail reason.
• ProcessingFailed - processing failed.
• LimitsExceeded - limits exceeded.
• FingerprintBlacklisted - finger print blacklisted.
• BanqError - the banq error.
• PrimeTrustError - the prime trust error.
• InsufficientBalance - exception is caused by insufficient balance.
• CustodialAccountContactIsNotApproved - the custodial account contact is not approved.
• ExternalAccountIsDeactivated - the external account is deactivated.
• PlaidRequiresReAuthentication - the plaid requires re authentication.
• AccountIsFrozen - the account is frozen.
• Reversed - transaction is reversed.
• Cancelled - transaction is cancelled.

Pagination

Some endpoints return data in pages. They accept the following query parameters that control pagination:

• page - one-based number of the page;
• pageSize - the number of items that will be returned.

The response contains meta property that holds an object with the following data:

• resourceCount - total number of filtered items in the system;
• pageCount - total number of pages calculated using query parameters page and pageSize. The response also contains property data with a collection of entities.

Idempotent headers

The API allows performing idempotent POST requests. To enable this feature one needs to add X-Idempotent-Id header with a unique identifier (GUID). All subsequent requests with this header will return the same response as the first one.

Webhooks

Whenever changes to payment or transaction object are made, a webhook is sent to the URL set in POST/PUT api/v1/accounts/{id}/webhook-config. The webhook structure looks like this:

{
  "accountId": 1, // identifier of the account related to the operation that triggered the webhook
  "action": "Created", // a string representation of what happened to the resource
  "id": "c88d829b-c2c1-4c78-9b07-e7667ee399ff", // unique identifier of this webhook
  "resourceId": "9bf48226-79c3-43d2-9be5-264bfef4660d", // identifier of the entity that has changed
  "resourceType": "Transaction", // the type of the entity
  "createdAtUtc": "2021-01-11T12:12:12.5431424+00:00" // time of webhook creation
}

For now, we send webhooks for resourceType:

Example Cases

Our notification system sends webhooks whenever there are some changes in payments or transactions. For example, let us consider a typical Open API flow:

• Integrator creates a one time request to get paid via api/v1/payments/get-paid-direct: a payment entity is created in Banq system; webhook with "resourceType": "Payment" and "action": "Created" is scheduled.
• A Banq user accepts this request via mobile app:
  • a payment status changes to "Accepted"; webhook with "resourceType": "Payment" and "action": "Accepted" is scheduled.
  • a transaction is created:
    • if it is successfull, a webhook with "resourceType": "Transaction" and "action": "Created" is scheduled.
    • if it fails, a webhook with "resourceType": "Transaction" and "action": "Failed" is scheduled.
  • a payment status changes to "Completed"; a webhook with "resourceType": "Payment" and "action": "Completed" is scheduled.

Webhook message authentication

To enable integrity and authenticity verification of a HTTP webhook message, we append a X-Banq-Webhook-Hmac header with base 64 encoded HMAC value. This HMAC value is calculated over the webhook request body using SharedSecret. SharedSecret is set in the request body to POST api/v1/accounts/{id}/webhook-config endpoint. HMAC value is calculated with SHA256 hashing algorithm.