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:


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.

Requesting access tokens

In order to request data from Banking Circle via the API channel, you must first request an access token by following the steps outlined below.

We encourage API users to only request a new access token when required. You should only request a new access token if your previous access token has expired – this means that you should check the expiration time of any previous token before requesting a new one.

Implementation steps:

  • To authorize and get an access token for data requests, you should make a request to the Authorization endpoint GET /api/v1/authorizations/authorize
  • In the response body, you’ll find the following attributes: access_token (JsonWebToken) and expires_in (The token expires in 300 seconds). Store the access token and expires in values.
  • Check the expiration time of the token before every subsequent request,
    • If the token hasn’t expired (the data requests are less than 300 seconds apart), then use the previously stored token
    • If the token has expired, then follow the implementations steps from the beginning.

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 Sales 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:

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:

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.
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:


EndpointsSupported HTTP Method


EndpointsSupported HTTP Method


EndpointsSupported HTTP Method


EndpointsSupported HTTP Method

PISP access

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


EndpointsSupported HTTP Method


EndpointsSupported HTTP Method

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.

Partial bulk processing

When sending bulk files to /api/v1/payments/bulks endpoint, if some of the payments contain errors, they are caught by our validations. If so, you will receive the following rejection response with a list of errors:

// 400 Bad Request
{ "type": "Csv", "errors": [ { "fieldIndex": 7, "elementIndex": 1, "errorCode": "RequestedExecutionDateDaysInPastThresholdViolation", "errorDescription": "Requested Execution Date exceeds allowed number of days in the past." } ], "canProceedWithErrors": true }

canProceedWithErrors is a Boolean property that informs you if Banking Circle can continue processing the valid payment instructions from your bulk file. When this property is false, you can't proceed, and the file is rejected completely. When it's true, you can choose to continue.

ProceedWithErrors is a Boolean optional header parameter that allows you to continue with your bulk file in case of errors, given that canProceedWithErrors property is true. If you want to continue with the same file, you can resend it to /api/v1/payments/bulks by adding the ProceedWithErrors header parameter as true to signal that we may proceed with uploading the file. This action will initiate the valid payments in the file and disregard the invalid ones.

Check here to check the response schema for 400 Bad Request and the header parameters for the bulk payments endpoint.

The invalid payments can be retrieved from GET /api/v1/payments/singles and filter per bulkId and from the GET /api/v1/reports/rejection-report. You can correct and then reinitiate the payments as singles, or another file can be uploaded only including the corrected payments.

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 documentation
  • 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