Let’s get started

This page contains the information and tools needed to begin the integration of the Banking Circle API into your systems. To start with, please read the 'Connecting to our API' section below to learn more about the authorization process and how to get the credentials and certificate.

If your company is an AISP or a PISP, you also must register and comply with the rules set by your local Financial Supervisory Authority (FSA). You can read more in the AISP and PISP access section.

Connecting to the API

You can use the below hosts for testing and going live with your application:

HostsTypeURL
Sandbox
Requests
Authorization
Live
Requests
Authorization

After receiving approval from our KYC department, your Implementation Manager will create a user for you and request a certificate from our trusted provider, GlobalSign. After receiving your initial passphrase, please use this to reset the password. After changing the password, download the certificate that contains the ThumbPrint. With the certificate file and credentials, you are ready to request an access token – this will be a standard JWT OAuth 2.0 signed token.

To get the access token, you can use the Authorization endpoint and send your certificate details, username and password encoded in Base64 using Basic Authentication scheme.

To access Banking Circle’s API functionality, you need to send the access token in the Authorization request header field, using the Bearer Authentication scheme.

AISP and PISP access

The API functionality exposes details of the request accounts, their balances, bookings and transactions and it includes Accounts, Payments, Fees, and FX. This data can be accessed by licensed Account Information Service Providers and Payment Initiation Service Providers by providing a valid certificate and credentials.

To get onboarded as AISP or PISP, you’ll have to provide our Client Services team with your company name, username, email address, phone number, IP address that will be used for sending requests to us, and Qualified Certificate (QSEAL). Get in touch with us here.

Connecting to our APIs as an AISP and PISP

To get the access token, AISPs and PISPs should include in the Authorization call these headers:

HeaderDescription
AuthorizationHTTP Basic Authentication (username and password)
X-ARR-ClientCert or X-BC-ClientCertAISP or PISP QSEAL Type Certificate

For sending requests, the following headers need to be included in all API calls:

HeaderDescription
X-Request-ID (Unique): MandatoryID of the request (in UUID format), unique to the call (generated by the initiating party, who must ensure uniqueness)
DigestBase64 encoded hash of body (SHA-256 and SHA-512 supported). Use an empty string if there is no body.
Signature
Comma separated list of values for keyId, algorithm, headers and signature:
  • keyId: Certificate Serial Number, Issuer
  • algorithm: rsa-sha256 or rsa-sha512
  • headers: List of values present in the Request Header: Digest, X-Request-ID, PSU-ID
  • signature: Base64 encoded signed value of Digest, X-Request-ID and PSU-ID
TPP-Signature-CertificateBase64 encoded Qualified Certificate (QSEAL) used for signing
PSU-ID: OptionalPayment Service User ID. If PSU-ID is specified as part of the Signature headers, it must be specified in the Request header

AISP access

As an AISP, you will be able to make the following calls:

Accounts

EndpointsSupported HTTP Method
/api/v1/accountsGET
/api/v1/accounts/{account-id}GET
/api/v1/accounts/{account-id}/balancesGET
/api/v1/accounts/{account-id}/bookingsGET

Fees

EndpointsSupported HTTP Method
/api/v1/feesGET
/api/v1/fees/{fee-id}GET

FX

EndpointsSupported HTTP Method
/api/v1/fxGET
/api/v1/fx/{foreign-exchange-id}GET

Payments

EndpointsSupported HTTP Method
/api/v1/payments/bulksGET
/api/v1/payments/bulks/{payment-bulk-id}GET
/api/v1/payments/bulks/{payment-bulk-id}/statusGET
/api/v1/payments/singlesGET
/api/v1/payments/singles/{payment-id}GET
/api/v1/payments/singles/{payment-id}/statusGET

PISP access

As an PISP, you will be able to make the following call:

Payments

EndpointsSupported HTTP Method
/api/v1/payments/singlePOST

Unique request ID

We have implemented a RequestID Uniqueness Check. This means that if you are an AISP or a PISP you need to send a unique ID with each call. The request header must contain a unique X-Request-ID for each request. If the X-Request-ID is found not to be unique, a 400 Bad Request Inavalid X-Request-ID is returned.

Concurrency Handling

Attempts to modify, approve or change the state of a changeable resource will be handled by using optimistic concurrency checking. This implies that a user needs to first obtain a token for the update operation, and can only update a resource if the token is still valid.

Responses for changeable resources it will return concurrencyToken property containing a value unique to the state of the resource.
Any change request made using a PUT or DELETE action will require the If-Match HTTP Request Header to be populated with the concurrency token value.
The change request will be successfully processed only if the resource concurrency token value has not changed. If the resource state has changed, 412 - Precondition Failed will be returned.

Large Data Sets

HTTP GET Requests

Several resources allow users to request potentially large data sets. To accommodate these requests, pagination is enforced via the two query-parameters pageSize and pageNumber. Both must be larger than zero and have a resource specific default value if not provided.
Paginated responses have pageInfo object with pageSize and currentPage. The latter two are equal to the request pageSize and pageNumber provided in the query parameters.

HTTP POST Requests

Some resources allow for users to send requests for bulk creation with potentially large data sets. There is a maximum size limit of 20MB and in cases where the limit is breached 413 - Payload too large is returned.

Response to errors

The API uses HTTP response codes for requests: 2xx codes for success, 4xx codes for endpoint specific errors concerning e.g. permissions, missing parameters or other failure(s), data errors and 5xx codes for internal server errors.

HTTP codeMeaningDescription
200OKRequest has been processed with success
201CreatedNew resource has been created
400Bad requestRequest is not correctly formulated. Goes for both Header, Query and Body. Verify the error description an properties.
401UnauthorizedThe request requires user authentication
403ForbiddenThe server understood the request, but is refusing it or the access is not allowed, i.e. if resource exists but calling user does not have rights to access it
404Not foundThere is no resource behind the URL, i.e. requesting data on an account that does not exist
412Precondition failedConcurrency token check failed – Header criteria “If-Match” (concurrency token) is no longer valid
413Payload too largeSize of request or response is too big and therefore rejected
415Unsupported media typeIncorrect media type provided in Request Header “Accept” parameter
500Internal server errorSomething unexpected happened on BC Connect side

400 Bad Request response returns a description of the specific error(s), and each return of a code 400 will contain a collection of errors with elements having properties as element number (which value in the csv), field index (the number of the filed), line index (the number of the line), etc. indicating where a rule was broken or what value is incorrect.

Single Payment initiation (JSON)

  • propertyName - Incorrect or invalid attribute
  • errorCode - Unique code
  • errorDescription - Error description message

Bulk Payment initiation (CSV)

  • findIndex - The field number as per Payment Bulk template documenation
  • elementIndex - The line number of the file (payment number) omitting empty lines. First line/payment has Element Index 1
  • errorCode - Unique code of the validation error
  • errorDescription - Error description message