API docs by Redocly

API Reference (1.0.0)

Download OpenAPI specification:Download

E-mail: support@blip-pay.com URL: https://blip-pay.com

Authentication

All APIs use API keys to authenticate requests. You can view and manage your API keys in the Admin Console.

Authentication to the API is performed via HTTP Basic Authentication. Provide your Journey's Client ID and Client Secret as the username and password, respectively. The following shows the supported types of Basic Authentication.

Name Description
BasicAuthAIS Using credentials from an AIS journey
BasicAuthPIS Using credentials from a PIS journey

For example: Create Customer supports both BasicAuthAIS and BasicAuthPIS while Generate AIS Connect URL only supports BasicAuthAIS.

Additionally, all Data and Payment APIs will also require a Consent Token to be sent via x-open-consent-token header in order to retrieve banking information for the respective customer consent. This token will be provided as part of a successful consent journey.

Initiation

Payments and recurring payments can be initiated automatically or manually depending on the desired use case. See each type below:

Manual

By default payments and recurring payments will be set to manual. A consent will first need to be created and actioned. Upon obtaining a successful consent the Initiate Payment or Initiate Recurring Payment API can be called to complete the payment or recurring payment. The payment or recurring payment should be initiated immediately upon receiving the consent token, as it will expire shortly after being issued, if not used.

Automatic

Automatic initiation will complete the payment or recurring payments upon obtaining a successful consent. To opt-in to automatic payment initiation, you should set the initiation option to automatic.

The automatic initiation flow differs from the manual initiation flow (discussed above) in two key ways:

  1. A payment summary screen will be displayed to the user, indicating the status of the payment (success, failure, or pending)
  2. When the user is redirected to the redirectUrl, this will not be appended with any query parameters

If you wish to be notified of the success or failure of a payment, you must set up a webhook.

Webhooks

To be notified when a payment or recurring payments instruction has been processed, you can configure webhook URLs under your Payment journey in the Admin Console. You should then provide one of the configured URLs as the webhookUrl in the payment or Recurring Payments request body. Blip Pay send a POST request to the webhookUrl once the bank processes the payment or recurring payment instruction.

See Developer Guides: Configuring a Payments Webhook for a step by step guide on setting up a payments webhook.

Webhook request body

{
  "jwt": "<signed jwt payload>"
}

The JWT payload should be verified and decoded with your unique public key, which was generated when the webhook URL was added to the Payment journey in the Admin Console. NOTE: We highly recommend to always verify the JWT payload before decoding it. For extra security, you can also verify the aud matches Payment journey's clientId and the iss is "open-fintechio".

Example decoded JWT payload

{
  "consentId": "8e94e715-0a95-4bb3-91bf-f7891caff821",
  "customer": {
    "customerId": "b49481b8-2ffb-4514-9f50-f881180bd724",
    "identifier": "your unique customer identifier"
  },
  "institutionId": "OB_MODELO_SANDBOX",
  "paymentDetails": {
    "amount": {
      "amount": 0.99,
      "currency": "GBP"
    },
    "payee": {
      "accountIdentifications": {
        "ACCOUNT_NUMBER": "12345678",
        "SORT_CODE": "123456"
      },
      "name": "Example Name",
      "address": {
        "country": "GB",
        "postCode": "NW1 4BB"
      }
    },
    "paymentDateTime": "2024-09-28T12:43:07.770Z",
    "frequency": {
      "executionDay": 7,
      "type": "WEEKLY"
    },
    "reference": "example payment",
  },
  "paymentId": "377830e7-90ec-49aa-897e-bd501733c315",
  "status": "COMPLETED",
  "iat": 1661962149,
  "iss": "open-fintechio",
  "aud": "your Payment journey clientId"
}

Responding to the request

To indicate the webhook request has been processed, you should respond with a status code of 200 or 201 (body or headers are not required). Blip Pay attempt to call your webhook URL until it returns the appropriate HTTP status code, up to a maximum of five attempts. Furthermore, if the webhook request takes more than 10 seconds to respond, the process will be timed out and re-attempted. After the fifth unsuccessfully attempt, the system will stop trying to send to the webhook url.

Customers

Create Customer

Register a new customer with Blip Pay. This is required in order to generate a connect URL using any of the following APIs:

Upon a successful call to this endpoint, you will be able to carry out further requests against the customer using the customerId from the response.

The endpoint optionally accepts an identifier which will allow you to use this value in place of the customerId. If you choose to provide an identifier, please ensure that this is unique to a customer. This is extremely important, as using a non-unique identifier may lead you to mistakenly display sensitive data to another customer. Additionally, please ensure that you do not use personally identifying information as the identifier - we recommend a randomly generated UUID.

Authorizations:
BasicAuthAISBasicAuthPIS
Request Body schema: application/json

Create customer payload

identifier
string

Optional. Unique identifier for the customer

Responses

Request samples

Content type
application/json
{
  • "identifier": "a3a9a899-6639-4bfb-8a4a-41970834ea63"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Consent

Data

Get Identity

Get the identity information for a given consent token that was provided as part of a successful customer Open Banking consent journey.

Authorizations:
(BasicAuthAISConsentToken)

Responses

Request samples 

curl --location --request GET 'https://api.blip-pay.com/data/identity' \
--header 'Authorization: Basic {basicAuthToken}' \
--header 'x-open-consent-token: {consentToken}' \
--header 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Categories

Get a list of transaction categories returned by the categorisation engine. New categories and subcategories may be added in future.

Responses

Request samples 

curl --location --request GET 'https://api.blip-pay.com/data/categories' \
--header 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Accounts

Get a list of account details for all consented accounts embedded in a given consent that was provided as part of a successful customer Open Banking consent journey.

Authorizations:
(BasicAuthAISConsentToken)

Responses

Request samples 

curl --location --request GET 'https://api.blip-pay.com/data/accounts' \
--header 'Authorization: Basic {basicAuthToken}' \
--header 'x-open-consent-token: {consentToken}' \
--header 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Aggregated Balances

Get all balances for all consented accounts embedded in a given consent that was provided as part of a successful customer Open Banking consent journey.

Authorizations:
(BasicAuthAISConsentToken)

Responses

Request samples 

curl --location --request GET 'https://api.blip-pay.com/data/accounts/aggregated/balances' \
--header 'Authorization: Basic {basicAuthToken}' \
--header 'x-open-consent-token: {consentToken}' \
--header 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Aggregated Transactions

Get all transactions for all consented accounts embedded in a given consent token that was provided as part of a successful customer Open Banking consent journey.

Authorizations:
(BasicAuthAISConsentToken)

Responses

Request samples 

curl --location --request GET 'https://api.blip-pay.com/data/accounts/aggregated/transactions' \
--header 'Authorization: Basic {basicAuthToken}' \
--header 'x-open-consent-token: {consentToken}' \
--header 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Aggregated Categorisation

Get all transactions along with enrichment data such as categories and merchant details for all consented accounts embedded in a given consent token that was provided as part of a successful customer Open Banking consent journey.

To obtain a list of transaction categories, see the Get Categories API.

Authorizations:
(BasicAuthAISConsentToken)

Responses

Request samples 

curl --location --request GET 'https://api.blip-pay.com/data/accounts/aggregated/categorisation' \
--header 'Authorization: Basic {basicAuthToken}' \
--header 'x-open-consent-token: {consentToken}' \
--header 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Aggregated Statements

Get statement metadata for all consented accounts embedded in a given consent that was provided as part of a successful customer Open Banking consent journey.

Statements files can be retrieved using the Get Statement File API.

Authorizations:
(BasicAuthAISConsentToken)

Responses

Request samples 

curl --location --request GET 'https://api.blip-pay.com/data/accounts/aggregated/statements' \
--header 'Authorization: Basic {basicAuthToken}' \
--header 'x-open-consent-token: {consentToken}' \
--header 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Aggregated Direct Debits

Get all direct debits for all consented accounts embedded in a given consent token that was provided as part of a successful customer Open Banking consent journey.

Authorizations:
(BasicAuthAISConsentToken)

Responses

Request samples 

curl --location --request GET 'https://api.blip-pay.com/data/accounts/aggregated/direct-debits' \
--header 'Authorization: Basic {basicAuthToken}' \
--header 'x-open-consent-token: {consentToken}' \
--header 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Aggregated Scheduled Payments

Get all scheduled payments for all consented accounts embedded in a given consent token that was provided as part of a successful customer Open Banking consent journey.

Authorizations:
(BasicAuthAISConsentToken)

Responses

Request samples 

curl --location --request GET 'https://api.blip-pay.com/data/accounts/aggregated/scheduled-payments' \
--header 'Authorization: Basic {basicAuthToken}' \
--header 'x-open-consent-token: {consentToken}' \
--header 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Aggregated Periodic Payments

Get all periodic payments for all consented accounts embedded in a given consent token that was provided as part of a successful customer Open Banking consent journey.

Authorizations:
(BasicAuthAISConsentToken)

Responses

Request samples 

curl --location --request GET 'https://api.blip-pay.com/data/accounts/aggregated/periodic-payments' \
--header 'Authorization: Basic {basicAuthToken}' \
--header 'x-open-consent-token: {consentToken}' \
--header 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Account Balances

Get the balance for a consented account embedded in a given consent that was provided as part of a successful customer Open Banking consent journey.

Account IDs can be retrieved using the Get Accounts API.

Authorizations:
(BasicAuthAISConsentToken)

Responses

Request samples 

curl --location --request GET 'https://api.blip-pay.com/data/accounts/890af999-d4f3-4ba4-ab3f-c2daba43d081/balances' \
--header 'Authorization: Basic {basicAuthToken}' \
--header 'x-open-consent-token: {consentToken}' \
--header 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Account Transactions

Get all transactions for a given account ID.

Account IDs can be retrieved using the Get Accounts API.

Authorizations:
(BasicAuthAISConsentToken)

Responses

Request samples 

curl --location --request GET 'https://api.blip-pay.com/data/accounts/890af999-d4f3-4ba4-ab3f-c2daba43d081/transactions' \
--header 'Authorization: Basic {basicAuthToken}' \
--header 'x-open-consent-token: {consentToken}' \
--header 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Account Categorisation

Get all transactions along with enrichment data (such as categories and merchant details) for a given account ID

To obtain a list of transaction categories, see the Get Categories API.

Account IDs can be retrieved using the Get Accounts API.

Authorizations:
(BasicAuthAISConsentToken)

Responses

Request samples 

curl --location --request GET 'https://api.blip-pay.com/data/accounts/890af999-d4f3-4ba4-ab3f-c2daba43d081/categorisation' \
--header 'Authorization: Basic {basicAuthToken}' \
--header 'x-open-consent-token: {consentToken}' \
--header 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Account Periodic Payments

Get all periodic payments for a given account ID.

Account IDs can be retrieved using the Get Accounts API.

Authorizations:
(BasicAuthAISConsentToken)

Responses

Request samples 

curl --location --request GET 'https://api.blip-pay.com/data/accounts/890af999-d4f3-4ba4-ab3f-c2daba43d081/periodic-payments' \
--header 'Authorization: Basic {basicAuthToken}' \
--header 'x-open-consent-token: {consentToken}' \
--header 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Account Statements

Get statement metadata for all consented accounts embedded in a given consent that was provided as part of a successful customer Open Banking consent journey.

Statements files can be retrieved using the Get Statement File API.

Statement IDs can be retrieved using the Get Statements API which will also return the corresponding account IDs.

Authorizations:
(BasicAuthAISConsentToken)

Responses

Request samples 

curl --location --request GET 'https://api.blip-pay.com/data/accounts/890af999-d4f3-4ba4-ab3f-c2daba43d081/statements' \
--header 'Authorization: Basic {basicAuthToken}' \
--header 'x-open-consent-token: {consentToken}' \
--header 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Account Statement File

Get statement file for a given account ID and statement ID.

Statement IDs can be retrieved using the Get Statements API which will also return the corresponding account IDs.

Authorizations:
(BasicAuthAISConsentToken)

Responses

Request samples 

curl --location --request GET 'https://api.blip-pay.com/data/accounts/890af999-d4f3-4ba4-ab3f-c2daba43d081/statements/890af999-d4f3-4ba4-ab3f-c2daba43d081/file' \
--header 'Authorization: Basic {basicAuthToken}' \
--header 'x-open-consent-token: {consentToken}' \
--header 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "message": "Unauthorized",
  • "statusCode": 401
}

Get Account Direct Debits

Get all direct debits for a given account ID.

Account IDs can be retrieved using the Get Accounts API.

Authorizations:
(BasicAuthAISConsentToken)

Responses

Request samples 

curl --location --request GET 'https://api.blip-pay.com/data/accounts/890af999-d4f3-4ba4-ab3f-c2daba43d081/direct-debits' \
--header 'Authorization: Basic {basicAuthToken}' \
--header 'x-open-consent-token: {consentToken}' \
--header 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Account Scheduled Payments

Get all scheduled payments for a given account ID.

Account IDs can be retrieved using the Get Accounts API.

Authorizations:
(BasicAuthAISConsentToken)

Responses

Request samples 

curl --location --request GET 'https://api.blip-pay.com/data/accounts/890af999-d4f3-4ba4-ab3f-c2daba43d081/scheduled-payments' \
--header 'Authorization: Basic {basicAuthToken}' \
--header 'x-open-consent-token: {consentToken}' \
--header 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "data": {
    }
}

Payments

Initiate Domestic Single Payment

Trigger an authorised payment to be processed. Upon calling this API, the authorised payment will transition to a processing payment. In the UK it is possible for payment to take up to two hours (due to bank processing) for the bank to confirm intent to action the instruction - though often this process is immediate. If the payment does not immediately transition to a processed state, a "PENDING" status will be returned. Otherwise a "FAILED" or "COMPLETED" status will be returned.

Authorizations:
(BasicAuthPISConsentToken)

Responses

Request samples 

curl --location --request POST 'https://api.blip-pay.com/payments' \
--header 'Authorization: Basic {basicAuthToken}' \
--header 'x-open-consent-token: {consentToken}' \
--header 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "data": {
    }
}

Initiate Domestic Recurring Payment

Trigger a recurring payment to be processed. Upon calling this API, the authorised recurring payment instruction will transition to a processing instruction. In the UK it is possible for instruction to take up to two hours (due to bank processing) for the bank to confirm intent to action the instruction - though often this process is immediate. If the instruction does not immediately transition to a processed state, a "PENDING" status will be returned by the bank. Otherwise a "FAILED" or "COMPLETED" status will be returned by the bank.

Note: Blip-Pay does not currently provide the ability to modify or cancel recurring payment. In addition, it is not possible to receive confirmation of whether each payment from a recurring payment was successfully credited to the payee's bank account.

Authorizations:
(BasicAuthPISConsentToken)

Responses

Request samples 

curl --location --request POST 'https://api.blip-pay.com/payments/initiate/domestic/recurring-payment' \
--header 'Authorization: Basic {basicAuthToken}' \
--header 'x-open-consent-token: {consentToken}' \
--header 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "data": {
    }
}