Payments

When sending payments via the ClearBank® API, Faster Payments are initiated via the POST/Payments/FPS endpoint, while a confirmation of settlement is provided to you via the Transaction Settled webhook. Please refer to Webhooks for more information.

ClearBank® accounts support inbound and outbound Faster Payments. You can receive Faster Payments of up to £1,000,000. The transaction limit for an outbound Faster Payment transaction is £250,000. Faster Payments are not subject to a cut-off time and can be sent or received as and when required.

Faster Payments Validation

Element	Type	Validation	Description
`name`	string	maxLength: 140 minLength: 1 pattern: `^[a-zA-Z0-9\/\-?:().,'+\s#=!"%&<>;{@\r\n]$`	Also known as Account Holder Name This the Creditor’s name. If max length exceeds 35 characters, this will be truncated before sending to scheme.
`reference`	string	maxLength: 35 minLength: 0 pattern: `^[a-zA-Z0-9\/\-?:().,'+\s#=!"%&<>;{@\r\n]$`	Also known as the Payment Reference This is the Payment reference under remittance information. If the max length exceeds 18 characters, this will be truncated before sending to scheme.

Pattern: Alphanumeric (uppercase and lowercase) and special characters*.
*Special characters: / (forward slash), - (hyphen), ? (question mark), : (colon), ( (left parenthesis), ) (right parenthesis), . (full stop), , (comma), ’ (right single quote), + (plus sign), (blank space), # (hash), = (equals), ! (exclamation mark), ” (right double quote), % (percentage), & (ampersand), * (asterisk), < (less than), > (greater than), ; (semi colon), { (left curly bracket), @ (commercial at), CrLf (carriage return line feed).

This endpoint uses the endToEndIdentification field as a duplicate check to ensure the request is idempotent.

Initiate an FPS payment

post/v3/Payments/FPS

Initiate a payment using the faster payments scheme. This endpoint is FTR compliant.

This endpoint works on a partial acceptance basis - meaning that you can submit 10 payments and only 6 of them may be accepted for processing. Each payment instruction is validated against the scheme specific rules as well as the ISO20022 specification. Currently, only payments through GBP are supported. We have listed possible currencies for future proofing of the API. The remittance information must be scheme compatible. Values exceeding the length limits of the scheme will be truncated. Missing remittance information will be replaced by a blank string.

Parameters

Authorization string, header, Required
Your API Token, retrieved from the web portal.
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key.
X-Request-Id string, header, Required
A unique identifier for the request.

Request Payload (application/json)

paymentInstructions array, Required
Details of the payments to be made.
Minimum length
1
Maximum length
10

request

{
  "paymentInstructions": [
    {
      "debtor": {
        "legalEntityIdentifier": "string",
        "address": "string"
      },
      "paymentInstructionIdentification": "string",
      "debtorAccount": {
        "identification": {
          "iban": "string",
          "other": {
            "issuer": "string",
            "identification": "string",
            "schemeName": {
              "code": "BBAN",
              "proprietary": "string"
            }
          }
        }
      },
      "creditTransfers": [
        {
          "paymentIdentification": {
            "instructionIdentification": "string",
            "endToEndIdentification": "string"
          },
          "amount": {
            "currency": "ALL",
            "instructedAmount": 0
          },
          "creditor": {
            "name": "string",
            "legalEntityIndentifier": "string"
          },
          "creditorAccount": {
            "identification": {
              "iban": "string",
              "other": {
                "issuer": "string",
                "identification": "string",
                "schemeName": {
                  "code": "BBAN",
                  "proprietary": "string"
                }
              }
            }
          },
          "remittanceInformation": {
            "structured": {
              "creditorReferenceInformation": {
                "reference": "string"
              }
            }
          }
        }
      ]
    }
  ]
}

Code copied

Response (application/json)

202 Accepted
400 Bad Request
404 Not Found

Accepted

{
  "transactions": [
    {
      "endToEndIdentification": "string",
      "response": "Accepted"
    }
  ],
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Associated Webhooks

Initiate a single Faster Payment Originated Overseas

post/v2/payments/fps/singlepayment

To initiate an outbound payment originated overseas, use the single payment endpoint.

Parameters

Authorization string, header, Required
Your API Token, retrieved from the web portal.
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key.
X-Request-Id string, header, Required
A unique identifier for the request.

Request Payload (application/json)

paymentInstruction object, Required
Information about the single payment.

request

{
  "paymentInstruction": {
    "debtor": {
      "legalEntityIdentifier": "string"
    },
    "debtorAccount": {
      "identification": {
        "iban": "string",
        "other": {
          "identification": "string",
          "schemeName": {
            "code": "BBAN",
            "proprietary": "string"
          }
        }
      }
    },
    "ultimateDebtor": {
      "name": "string",
      "address": "string"
    },
    "ultimateDebtorAccount": {
      "identification": {
        "bic": "stringst",
        "accountNumber": "string"
      }
    },
    "creditTransfer": {
      "paymentIdentification": {
        "endToEndIdentification": "string"
      },
      "amount": {
        "originalCurrency": "ALL",
        "originalAmount": 0,
        "exchangeRate": 0,
        "instructedAmount": 0
      },
      "creditor": {
        "name": "string",
        "legalEntityIdentifier": "string",
        "address": "string"
      },
      "creditorAccount": {
        "identification": {
          "iban": "string",
          "other": {
            "identification": "string",
            "schemeName": {
              "code": "BBAN",
              "proprietary": "string"
            }
          }
        }
      },
      "remittanceInformation": {
        "structured": {
          "creditorReferenceInformation": {
            "reference": "string"
          }
        },
        "unstructured": {
          "additionalReferenceInformation": {
            "reference": "string"
          }
        }
      }
    }
  }
}

Code copied

Response (application/json)

202 Success
400 Bad Request
404 Not Found

Success

{
  "transaction": {
    "endToEndIdentification": "string",
    "response": "Accepted"
  },
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Associated Webhooks

When sending payments via the ClearBank® API, CHAPS are initiated via the POST/Payments/CHAPS endpoint, while a confirmation of settlement is provided to you via the Transaction Settled webhook. Please refer to Webhooks for more information.

ClearBank® accounts support inbound and outbound CHAPS payments. Being that CHAPS is the UK’s high value payment scheme, there is no amount limit associated with inbound or outbound CHAPS payments. However, you can only send CHAPS payments between 08:00 – 17:00 Monday to Friday (excluding UK public holidays).

CHAPS Validation

Element	Type	Validation	Description
`name`	string	maxLength: 140 minLength: 1 pattern: `^[a-zA-Z0-9\/-?:().,'+\s]*$`	Also known as Account Holder Name This the Creditor’s name. If max length exceeds 35 characters, this will be truncated before sending to scheme.
`reference`	string	maxLength: 35 minLength: 0 pattern: `^[a-zA-Z0-9\/-?:().,'+\s]*$`	Also known as the Payment Reference This is the Payment reference under remittance information.

Pattern: The character set has been extended to include all SWIFT allowed characters. Alphanumeric (uppercase and lowercase) and special characters*.
*Special characters: / (forward slash), - (hyphen), ? (question mark), : (colon), ( (left parenthesis), ) (right parenthesis), . (full stop), , (comma), ' (apostrophe), + (plus sign), (blank space).

This endpoint uses the endToEndIdentification field as a duplicate check to ensure the request is idempotent.

Initiate a CHAPS payment

post/v3/Payments/CHAPS

Initiate a payment using the chaps payment scheme. This endpoint is FTR compliant.

Parameters

Authorization string, header, Required
Your API Token, retrieved from the web portal.
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key.
X-Request-Id string, header, Required
A unique identifier for the request.

Request Payload (application/json)

paymentInstructions array, Required
Details of the payments to be made.

request

{
  "paymentInstructions": [
    {
      "paymentInstructionIdentification": "string",
      "schemeChannelName": "string",
      "requestedExecutionDate": "2022-06-01T16:35:41Z",
      "debtor": {
        "legalEntityIdentifier": "string",
        "name": "string",
        "address": "string"
      },
      "debtorAccount": {
        "identification": {
          "iban": "string",
          "other": {
            "identification": "string",
            "schemeName": {
              "code": "BBAN",
              "proprietary": "string"
            },
            "issuer": "string"
          }
        }
      },
      "creditTransfers": [
        {
          "paymentIdentification": {
            "instructionIdentification": "string",
            "endToEndIdentification": "string"
          },
          "amount": {
            "instructedAmount": 0,
            "currency": "AED"
          },
          "creditor": {
            "name": "string",
            "legalEntityIdentifier": "string"
          },
          "creditorAccount": {
            "identification": {
              "iban": "string",
              "other": {
                "identification": "string",
                "schemeName": {
                  "code": "BBAN",
                  "proprietary": "string"
                },
                "issuer": "string"
              }
            }
          },
          "remittanceInformation": {
            "structured": {
              "creditorReferenceInformation": {
                "reference": "string"
              }
            }
          }
        }
      ]
    }
  ]
}

Code copied

Response (application/json)

202 Success
400 Bad Request
404 Not Found

Success

{
  "transactions": [
    {
      "endToEndIdentification": "string",
      "response": "Accepted"
    }
  ],
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": {},
  "property2": {}
}

Code copied

Associated Webhooks

ClearBank® accounts accept inbound Bacs Direct Credit payments. Bacs Direct Credit payments work on a three-day cycle and settles on the third day.

Settling Inbound Bacs Direct Credit Payments

You are notified of an inbound Direct Credit payment via the Bacs Direct Credit Inbound Payment Created webhook on Day 2 of the three-day cycle. Confirmation of settlement will be provided via the Transaction Settled webhook on Day 3.

If the payment cannot be applied to the account, ClearBank® will automatically raise an Automated Return of Unapplied Credits Service (ARUCS). If the payment has been applied, but you still want to return it, you should use these endpoints and specify the reason for return. ClearBank® will notify you with a Bacs Direct Credit Return Created webhook. Returns can only be initiated until 15:30 (UTC) the working day after settlement. The payment will be applied to your Bacs Suspense account on the same day and returned on Day 5.

Return Direct Credit payment for an account

post/v1/Accounts/{accountId}/Transactions/Returns

Creates a return of one or more Direct Debit or Direct Credit transactions for the account. This is only valid on the Entry Day, or the working day after before 15:30 UTC.

Parameters

accountId string, path, Required
The unique identifier for the account. This can be retrieved from GET /v1/Accounts
Authorization string, header, Required
Your API Token, retrieved from the web portal
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key
X-Request-Id string, header, Required
A unique identifier for the request

Request Payload (application/json)

returns array, Required
Array of transactions to be returned

request

{
  "returns": [
    {
      "transactionId": "string",
      "reasonCode": "string"
    }
  ]
}

Code copied

Response (application/json)

202 Success
400 Bad Request
404 Not Found

Success

{
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Code copied

Return Direct Credit payment for a virtual account

post/v1/Accounts/{accountId}/Virtual/{virtualAccountId}/Transactions/Returns

Creates a return of one or more Direct Debit or Direct Credit transactions for the virtual account

Parameters

accountId string, path, Required
The unique identifier for the account. This can be retrieved from GET /v1/Accounts
virtualAccountId string, path, Required
The unique identifier for the virtual account. This can be retrieved from GET /v1/Accounts/{accountId}/Virtual
Authorization string, header, Required
Your API Token, retrieved from the web portal
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key
X-Request-Id string, header, Required
A unique identifier for the request

Request Payload (application/json)

returns array, Required
Array of transactions to be returned

request

{
  "returns": [
    {
      "transactionId": "string",
      "reasonCode": "string"
    }
  ]
}

Code copied

Response (application/json)

202 Success
400 Bad Request
404 Not Found

Success

{
  "halLinks": [
    {
      "name": "string",
      "href": "string",
      "templated": true
    }
  ]
}

Code copied

Bad Request

{
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Code copied

Payments

Faster Payments

Initiate an FPS payment

Parameters

Request Payload (application/json)

Response (application/json)

Associated Webhooks

Initiate a single Faster Payment Originated Overseas

Parameters

Request Payload (application/json)

Response (application/json)

Associated Webhooks

CHAPS

Initiate a CHAPS payment

Parameters

Request Payload (application/json)

Response (application/json)

Associated Webhooks

Bacs Inbound Direct Credit

Settling Inbound Bacs Direct Credit Payments

Return Direct Credit payment for an account

Parameters

Request Payload (application/json)

Response (application/json)

Return Direct Credit payment for a virtual account

Parameters

Request Payload (application/json)

Response (application/json)