Skip to content
Developerhome
Product homepage
Banking Service

Authorisations

  Less than to read

Provider APIProvider -> Banking Service

The PATCH authorisations endpoint is used for providers to inform Banking Service of the results of either an onboard or reauthentication session of a bank account.

In the case of onboarding the collection of all accounts which access is granted are to be sent within the request body. Banking Service takes responsibility for determining which account the onboarding session is for through the authorisationId.

In the case of reauthentication no accounts will be specified in the body.

:

Note: You should return all accounts for this user, even if they have been previously onboarded. Banking service can handle if the customer is attempting to onboard an account more than once. The Banking Service uses the bank identifier and account identifier to understand if an account has already been connected.

PATCH/v1/authorisations/{authorisationId}

Request

The following parameters should be provided with your request.

Parameter Description
authorisationId The authorisation ID is sent to the provider by the Banking Service through the authorisation created notification and as a query parameter within the GET /auth request

The following headers should be provided with your request.

Headers Description
x-api-key This value required in validating calls to the Provider API. It should be handled as a secret and not shared. Individual keys of the API may be throttled depending on usage agreements.
Authorization This is the value returned from your call to the /oauth/token endpoint.
Content-Type This should be set as application/json.

This is an example of the payload which should be provided:

{
  "data": {
    "status": "success",
    "bankAccounts":
    [
        {
            "bankAccountExternalId": "string1234",
            "accountName": "string",
            "bankIdentifier": "1234",
            "branchIdentifier": "string",
            "accountIdentifier": "13425"
        },
        {
            "bankAccountExternalId": "string4321",
            "accountName": "string",
            "bankIdentifier": "4321",
            "branchIdentifier": "string",
            "accountIdentifier": "14253"
        }
    ]
  }
}

Description of the fields:

  • bankAccountExternalId: (string) The provider’s own unique identifier for the bank account.
  • accountName: (string) The bank account name that is to be displayed to the customer. Can use account name and masked account number to help customers identify.
  • bankIdentifier: (string) The real-world bank identifier for the specific bank. Banking Service recommends this to be an identifier that represents the customer’s credentials.
  • branchIdentifier: (string) The real-world branch identifier for the bank account. If you do not wish to use please populate with the string ‘n/a’.
  • accountIdentifier: (string) The real-world account number for the bank account. Usually this isn’t the account number but a unique identifier held by the provider.

Response

If the PATCH request is succesfull the Banking Service will return a 204.

The response body will contain no content.

When this Patch has been called, the provider should then redirect back to the Banking Service UI. The redirect URI to be used is available as a query paramater within the GET /auth call previously made by the Banking Service UI to the provider.

Error handling

  • 409 Would be thrown if the authorisation ID you have passed within the query parameter is incorrect.
  • 403 Would be thrown if the header values you are passing are incorrect.

Was this helpful?