Retail customers

FSCS-protected deposits are a part of our embedded banking proposition. An FSCS-protected deposit is a physical account held with ClearBank and is only available to our embedded banking customers for the purpose of sending and/or receiving payments. The balance of an FSCS-protected deposit is held by ClearBank and can be viewed via the ClearBank Portal and the API. Additionally, FSCS-protected deposits are reconciled for you by ClearBank.

Create a retail customer

post/v1/customers/retail

This endpoint is used to create a new retail customer.

Once you have created a retail customer, create a new FSCS protected current account using the retail customer’s unique Id.

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)

firstName string, Required
The first name of the retail customer.
Maximum length
255
middleName string
The middle name of the retail customer.
Maximum length
255
surname string, Required
The surname name of the retail customer.
Maximum length
255
dateOfBirth string, Required
The date of birth of the retail customer in date format.
email string, Required
The primary email address used by the retail customer.
idCountryOfIssue string
ISO Alpha3 representation of the country where the Id was issued.
Maximum length
3
Enum array
ABW, AFG, AGO, AIA, ALA, ALB, AND, ARE, ARG, ARM, ASM, ATA, ATF, ATG, AUS, AUT, AZE, BDI, BEL, BEN, BES, BFA, BGD, BGR, BHR, BHS, BIH, BLM, BLR, BLZ, BMU, BOL, BRA, BRB, BRN, BTN, BVT, BWA, CAF, CAN, CCK, CHE, CHL, CHN, CIV, CMR, COD, COG, COK, COL, COM, CPV, CRI, CUB, CUW, CXR, CYM, CYP, CZE, DEU, DJI, DMA, DNK, DOM, DZA, ECU, EGY, ERI, ESH, ESP, EST, ETH, FIN, FJI, FLK, FRA, FRO, FSM, GAB, GBR, GEO, GGY, GHA, GIB, GIN, GLP, GMB, GNB, GNQ, GRC, GRD, GRL, GTM, GUF, GUM, GUY, HKG, HMD, HND, HRV, HTI, HUN, IDN, IMN, IND, IOT, IRL, IRN, IRQ, ISL, ISR, ITA, JAM, JEY, JOR, JPN, KAZ, KEN, KGZ, KHM, KIR, KNA, KOR, KWT, LAO, LBN, LBR, LBY, LCA, LIE, LKA, LSO, LTU, LUX, LVA, MAC, MAF, MAR, MCO, MDA, MDG, MDV, MEX, MHL, MKD, MLI, MLT, MMR, MNE, MNG, MNP, MOZ, MRT, MSR, MTQ, MUS, MWI, MYS, MYT, NAM, NCL, NER, NFK, NGA, NIC, NIU, NLD, NOR, NPL, NRU, NZL, OMN, PAK, PAN, PCN, PER, PHL, PLW, PNG, POL, PRI, PRK, PRT, PRY, PSE, PYF, QAT, REU, ROU, RUS, RWA, SAU, SDN, SEN, SGP, SGS, SHN, SJM, SLB, SLE, SLV, SMR, SOM, SPM, SRB, SSD, STP, SUR, SVK, SVN, SWE, SWZ, SXM, SYC, SYR, TCA, TCD, TGO, THA, TJK, TKL, TKM, TLS, TON, TTO, TUN, TUR, TUV, TWN, TZA, UGA, UKR, UMI, URY, USA, UZB, VAT, VCT, VEN, VGB, VIR, VNM, VUT, WLF, WSM, YEM, ZAF, ZMB, ZWE
idType string
The type of identification document provided by the retail customer for identification purposes. Valid options include: Passport, DrivingLicence, NationalInsurance, NationalId, SocialSecurity. Optional unless information for other ID fields such as idCountryOfIssue, idNumber and/or idExpiryDate is specified.
Maximum length
255
Enum array
Passport, DrivingLicence, NationalInsurance, NationalId, SocialSecurity
idNumber string
The identification number on the identification document provided by the retail customer. Optional unless information for other ID fields such as idCountryOfIssue, idType, and/or idExpiryDate is specified.
Maximum length
255
idExpiryDate string
The expiry date of the identification document provided by the retail customer in date-time format. Optional unless information for other ID fields such as idCountryOfIssue, IdType and/or idNumber is specified.
countryOfResidence string
ISO Alpha3 Country code.
Maximum length
3
Enum array
ABW, AFG, AGO, AIA, ALA, ALB, AND, ARE, ARG, ARM, ASM, ATA, ATF, ATG, AUS, AUT, AZE, BDI, BEL, BEN, BES, BFA, BGD, BGR, BHR, BHS, BIH, BLM, BLR, BLZ, BMU, BOL, BRA, BRB, BRN, BTN, BVT, BWA, CAF, CAN, CCK, CHE, CHL, CHN, CIV, CMR, COD, COG, COK, COL, COM, CPV, CRI, CUB, CUW, CXR, CYM, CYP, CZE, DEU, DJI, DMA, DNK, DOM, DZA, ECU, EGY, ERI, ESH, ESP, EST, ETH, FIN, FJI, FLK, FRA, FRO, FSM, GAB, GBR, GEO, GGY, GHA, GIB, GIN, GLP, GMB, GNB, GNQ, GRC, GRD, GRL, GTM, GUF, GUM, GUY, HKG, HMD, HND, HRV, HTI, HUN, IDN, IMN, IND, IOT, IRL, IRN, IRQ, ISL, ISR, ITA, JAM, JEY, JOR, JPN, KAZ, KEN, KGZ, KHM, KIR, KNA, KOR, KWT, LAO, LBN, LBR, LBY, LCA, LIE, LKA, LSO, LTU, LUX, LVA, MAC, MAF, MAR, MCO, MDA, MDG, MDV, MEX, MHL, MKD, MLI, MLT, MMR, MNE, MNG, MNP, MOZ, MRT, MSR, MTQ, MUS, MWI, MYS, MYT, NAM, NCL, NER, NFK, NGA, NIC, NIU, NLD, NOR, NPL, NRU, NZL, OMN, PAK, PAN, PCN, PER, PHL, PLW, PNG, POL, PRI, PRK, PRT, PRY, PSE, PYF, QAT, REU, ROU, RUS, RWA, SAU, SDN, SEN, SGP, SGS, SHN, SJM, SLB, SLE, SLV, SMR, SOM, SPM, SRB, SSD, STP, SUR, SVK, SVN, SWE, SWZ, SXM, SYC, SYR, TCA, TCD, TGO, THA, TJK, TKL, TKM, TLS, TON, TTO, TUN, TUR, TUV, TWN, TZA, UGA, UKR, UMI, URY, USA, UZB, VAT, VCT, VEN, VGB, VIR, VNM, VUT, WLF, WSM, YEM, ZAF, ZMB, ZWE
currentAddress array, Required
previousAddresses array

request

{
  "firstName": "John",
  "middleName": "Henry",
  "surname": "Smith",
  "dateOfBirth": "2019-08-24",
  "email": "user@example.com",
  "idCountryOfIssue": "GBR",
  "idType": "Passport",
  "idNumber": 123456789,
  "idExpiryDate": "2019-08-24T14:15:22Z",
  "countryOfResidence": "GBR",
  "currentAddress": [
    {
      "addressType": "TradingAddress",
      "validFrom": "2019-08-24T14:15:22Z",
      "validTo": "2019-08-24T14:15:22Z",
      "countryCode": "GBR",
      "buildingNameNumber": "16",
      "streetName": "Sea Road",
      "city": "Enfield",
      "county": "London",
      "postalCode": "N12 4NS"
    }
  ],
  "previousAddresses": [
    {
      "addressType": "TradingAddress",
      "validFrom": "2019-08-24T14:15:22Z",
      "validTo": "2019-08-24T14:15:22Z",
      "countryCode": "GBR",
      "buildingNameNumber": "Judge House",
      "streetName": "High St",
      "city": "Northleach",
      "county": "Gloucestershire",
      "postalCode": "GL55 3NJ"
    }
  ]
}

Code copied

Response (application/json)

201 Created successfully.
400 Invalid or incomplete customer details.
403 Forbidden

Created successfully.

{
  "id": "900b30fb-711c-4820-a910-07d31cfe06a5"
}

Code copied

Create an account

post/v4/Accounts

This endpoint is used to create a new FSCS-protected current account.

Currently, this endpoint only supports the creation of current accounts.

Parameters

Authorization string, header, Required
Your API Token, obtained from the ClearBank 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; valid for 24 hours, max length 83.

Request Payload (application/json)

owner object
Set of elements used to identify a person or an organisation.
sortCode string, Required
The sort code that the current account should be created under.
Pattern
^\d{6}$
productId string, Required
The product identifier of the current account. It is used to determine the behaviour of the account.
Pattern
^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$
customerId string, Required
The unique identifier of the customer that holds the current account.
Pattern
^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$
minimumBalance number
The minimum allowable balance of the account (example: -£1000). Note that you must send a negative number to create an overdraft. This field can only be used if your organisation is an embedded banking client with an overdraft agreement in place; otherwise the request will be rejected.

request

{
  "owner": {
    "name": "John Smith"
  },
  "sortCode": "010203",
  "productId": "01234567-89ab-cdef-0123-456789abcdef",
  "customerId": "01234567-89ab-cdef-0123-456789abcdef",
  "minimumBalance": 0
}

Code copied

Response (application/json)

201 Created
400 Bad Request
403 Forbidden
409 Conflict

Created

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "Current Account",
  "label": "John Smith",
  "type": "CACC",
  "currency": "GBP",
  "balances": [
    {
      "name": "Current Account",
      "amount": 0,
      "currency": "GBP",
      "status": "VALU"
    }
  ],
  "productId": "01234567-89ab-cdef-0123-456789abcdef",
  "customerId": "01234567-89ab-cdef-0123-456789abcdef",
  "minimumBalance": 0,
  "iban": "GB12CLBK01020312345678",
  "bban": "CLBK01020312345678",
  "upic": "string",
  "cuid": "string"
}

Code copied

Bad Request

{
  "type": "../dictionary",
  "title": "string",
  "status": 100,
  "detail": "string",
  "instance": "../dictionary",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Code copied

Associated Webhooks

Account Created webhook

This webhook confirms the account has been created.

Request body

{
    "Type":"AccountCreated",
    "Version":1,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`AccountId`	Account identifier used to uniquely identify the account. Type: `string` Format: `GUID`
`AccountName`	Name of the account. Type: `string` Max. length: `128`
`AccountHolderLabel`	The account description. Type: `string` Max. length: `100`
`AccountIdentifiers`	Account identifier details. Type: `object` `IBAN`: International Bank Account Number associated with the account. Type: `string` Max. length: `34` `BBAN`: Basic Bank Account number associated with the account. Type: `string` Max. length: `30`
`TimestampCreated`	The date and time the account was created. Type: `string` Time Zone: `UTC` Format: `DateTime`
`AccountType`	Type of account. Type: `string` Examples: `CurrentAccount`, `DepositAccount`, `ControlAccount`, `SegregatedClientAccount`, `InstitutionAccount`
`Nonce`	Cryptographically secure number generated by ClearBank® for every single webhook. A nonce number is generated randomly and should not be used as a check for duplication.

Example account created webhook request body

{
    "Type":"AccountCreated",
    "Version":1,
    "Payload":{
        "AccountId":"56de3483-a569-42eb-90cc-acf59661356f",
        "AccountName":"JOHN DOE",
        "AccountHolderLabel":"JOHN DOE",
        "AccountIdentifiers":{
            "IBAN":"GB00CUBK11223312345678",
            "BBAN":"CUBK11223312345678"
        },
        "TimestampCreated":"2018-07-19T13:31:30.8789344Z",
        "AccountType":"CurrentAccount"
    },
    "Nonce":1082937278
}

Example webhook response

{
    "Nonce": 1082937278
}

Update an existing retail customer’s personal information

patch/v1/customers/retail/{customerId}

This endpoint is used to update the details of an existing retail customer.

Parameters

customerId string, path, Required
The retail customer id that is being updated.
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)

firstName string
The first name of the retail customer.
Maximum length
255
middleName string
The middle name of the retail customer.
Maximum length
255
surname string
The surname of the retail customer.
Maximum length
255
dateOfBirth string
The date of birth of the retail customer in date format.
email string
The primary email address used by the retail customer.
idCountryOfIssue string
ISO Alpha3 Country code.
Maximum length
3
Enum array
ABW, AFG, AGO, AIA, ALA, ALB, AND, ARE, ARG, ARM, ASM, ATA, ATF, ATG, AUS, AUT, AZE, BDI, BEL, BEN, BES, BFA, BGD, BGR, BHR, BHS, BIH, BLM, BLR, BLZ, BMU, BOL, BRA, BRB, BRN, BTN, BVT, BWA, CAF, CAN, CCK, CHE, CHL, CHN, CIV, CMR, COD, COG, COK, COL, COM, CPV, CRI, CUB, CUW, CXR, CYM, CYP, CZE, DEU, DJI, DMA, DNK, DOM, DZA, ECU, EGY, ERI, ESH, ESP, EST, ETH, FIN, FJI, FLK, FRA, FRO, FSM, GAB, GBR, GEO, GGY, GHA, GIB, GIN, GLP, GMB, GNB, GNQ, GRC, GRD, GRL, GTM, GUF, GUM, GUY, HKG, HMD, HND, HRV, HTI, HUN, IDN, IMN, IND, IOT, IRL, IRN, IRQ, ISL, ISR, ITA, JAM, JEY, JOR, JPN, KAZ, KEN, KGZ, KHM, KIR, KNA, KOR, KWT, LAO, LBN, LBR, LBY, LCA, LIE, LKA, LSO, LTU, LUX, LVA, MAC, MAF, MAR, MCO, MDA, MDG, MDV, MEX, MHL, MKD, MLI, MLT, MMR, MNE, MNG, MNP, MOZ, MRT, MSR, MTQ, MUS, MWI, MYS, MYT, NAM, NCL, NER, NFK, NGA, NIC, NIU, NLD, NOR, NPL, NRU, NZL, OMN, PAK, PAN, PCN, PER, PHL, PLW, PNG, POL, PRI, PRK, PRT, PRY, PSE, PYF, QAT, REU, ROU, RUS, RWA, SAU, SDN, SEN, SGP, SGS, SHN, SJM, SLB, SLE, SLV, SMR, SOM, SPM, SRB, SSD, STP, SUR, SVK, SVN, SWE, SWZ, SXM, SYC, SYR, TCA, TCD, TGO, THA, TJK, TKL, TKM, TLS, TON, TTO, TUN, TUR, TUV, TWN, TZA, UGA, UKR, UMI, URY, USA, UZB, VAT, VCT, VEN, VGB, VIR, VNM, VUT, WLF, WSM, YEM, ZAF, ZMB, ZWE
idType string
The type of identification document provided by the retail customer for identification purposes. Valid options include: Passport, DrivingLicence, NationalInsurance, NationalId, SocialSecurity. Optional unless information for other ID fields such as idCountryOfIssue, idNumber and/or idExpiryDate is specified.
Maximum length
255
Enum array
Passport, DrivingLicence, NationalInsurance, NationalId, SocialSecurity
idNumber string
The identification number on the identification document provided by the retail customer. Optional unless information for other ID fields such as idCountryOfIssue, idType, and/or idExpiryDate is specified.
Maximum length
255
idExpiryDate string
The expiry date of the identification document provided by the retail customer in date-time format. Optional unless information for other ID fields such as idCountryOfIssue, IdType and/or idNumber is specified.
countryOfResidence string
ISO Alpha3 Country code.
Maximum length
3
Enum array
ABW, AFG, AGO, AIA, ALA, ALB, AND, ARE, ARG, ARM, ASM, ATA, ATF, ATG, AUS, AUT, AZE, BDI, BEL, BEN, BES, BFA, BGD, BGR, BHR, BHS, BIH, BLM, BLR, BLZ, BMU, BOL, BRA, BRB, BRN, BTN, BVT, BWA, CAF, CAN, CCK, CHE, CHL, CHN, CIV, CMR, COD, COG, COK, COL, COM, CPV, CRI, CUB, CUW, CXR, CYM, CYP, CZE, DEU, DJI, DMA, DNK, DOM, DZA, ECU, EGY, ERI, ESH, ESP, EST, ETH, FIN, FJI, FLK, FRA, FRO, FSM, GAB, GBR, GEO, GGY, GHA, GIB, GIN, GLP, GMB, GNB, GNQ, GRC, GRD, GRL, GTM, GUF, GUM, GUY, HKG, HMD, HND, HRV, HTI, HUN, IDN, IMN, IND, IOT, IRL, IRN, IRQ, ISL, ISR, ITA, JAM, JEY, JOR, JPN, KAZ, KEN, KGZ, KHM, KIR, KNA, KOR, KWT, LAO, LBN, LBR, LBY, LCA, LIE, LKA, LSO, LTU, LUX, LVA, MAC, MAF, MAR, MCO, MDA, MDG, MDV, MEX, MHL, MKD, MLI, MLT, MMR, MNE, MNG, MNP, MOZ, MRT, MSR, MTQ, MUS, MWI, MYS, MYT, NAM, NCL, NER, NFK, NGA, NIC, NIU, NLD, NOR, NPL, NRU, NZL, OMN, PAK, PAN, PCN, PER, PHL, PLW, PNG, POL, PRI, PRK, PRT, PRY, PSE, PYF, QAT, REU, ROU, RUS, RWA, SAU, SDN, SEN, SGP, SGS, SHN, SJM, SLB, SLE, SLV, SMR, SOM, SPM, SRB, SSD, STP, SUR, SVK, SVN, SWE, SWZ, SXM, SYC, SYR, TCA, TCD, TGO, THA, TJK, TKL, TKM, TLS, TON, TTO, TUN, TUR, TUV, TWN, TZA, UGA, UKR, UMI, URY, USA, UZB, VAT, VCT, VEN, VGB, VIR, VNM, VUT, WLF, WSM, YEM, ZAF, ZMB, ZWE

request

{
  "firstName": "string",
  "middleName": "string",
  "surname": "string",
  "dateOfBirth": "2019-08-24",
  "email": "user@example.com",
  "idCountryOfIssue": "GBR",
  "idType": "Passport",
  "idNumber": "string",
  "idExpiryDate": "2019-08-24T14:15:22Z",
  "countryOfResidence": "GBR"
}

Code copied

Response (application/json)

204 Successfully updated the specified retail customer.
400 Invalid value(s) provided in the update request.
403 Forbidden.
404 Retail customer with specified customerId does not exist.

Update an existing retail customer’s address

put/v1/customers/retail/{customerId}/currentaddress

This endpoint is used to update the address of an existing retail customer.

Parameters

customerId string, path, Required
The retail customer id that is being updated.
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)

addressType string
The type of address used by the retail customer. Valid options include: TradingAddress, RegisteredAddress, ResidentialAddress.
Maximum length
255
Enum array
TradingAddress, RegisteredAddress, ResidentialAddress
validFrom string
The date from when the retail customer started using the current address in date-time format.
validTo string
The expiry date of the retail customer’s current address in date-time format. Leave this field blank if the current address is still valid.
countryCode string, Required
ISO Alpha3 Country code.
Maximum length
3
Enum array
ABW, AFG, AGO, AIA, ALA, ALB, AND, ARE, ARG, ARM, ASM, ATA, ATF, ATG, AUS, AUT, AZE, BDI, BEL, BEN, BES, BFA, BGD, BGR, BHR, BHS, BIH, BLM, BLR, BLZ, BMU, BOL, BRA, BRB, BRN, BTN, BVT, BWA, CAF, CAN, CCK, CHE, CHL, CHN, CIV, CMR, COD, COG, COK, COL, COM, CPV, CRI, CUB, CUW, CXR, CYM, CYP, CZE, DEU, DJI, DMA, DNK, DOM, DZA, ECU, EGY, ERI, ESH, ESP, EST, ETH, FIN, FJI, FLK, FRA, FRO, FSM, GAB, GBR, GEO, GGY, GHA, GIB, GIN, GLP, GMB, GNB, GNQ, GRC, GRD, GRL, GTM, GUF, GUM, GUY, HKG, HMD, HND, HRV, HTI, HUN, IDN, IMN, IND, IOT, IRL, IRN, IRQ, ISL, ISR, ITA, JAM, JEY, JOR, JPN, KAZ, KEN, KGZ, KHM, KIR, KNA, KOR, KWT, LAO, LBN, LBR, LBY, LCA, LIE, LKA, LSO, LTU, LUX, LVA, MAC, MAF, MAR, MCO, MDA, MDG, MDV, MEX, MHL, MKD, MLI, MLT, MMR, MNE, MNG, MNP, MOZ, MRT, MSR, MTQ, MUS, MWI, MYS, MYT, NAM, NCL, NER, NFK, NGA, NIC, NIU, NLD, NOR, NPL, NRU, NZL, OMN, PAK, PAN, PCN, PER, PHL, PLW, PNG, POL, PRI, PRK, PRT, PRY, PSE, PYF, QAT, REU, ROU, RUS, RWA, SAU, SDN, SEN, SGP, SGS, SHN, SJM, SLB, SLE, SLV, SMR, SOM, SPM, SRB, SSD, STP, SUR, SVK, SVN, SWE, SWZ, SXM, SYC, SYR, TCA, TCD, TGO, THA, TJK, TKL, TKM, TLS, TON, TTO, TUN, TUR, TUV, TWN, TZA, UGA, UKR, UMI, URY, USA, UZB, VAT, VCT, VEN, VGB, VIR, VNM, VUT, WLF, WSM, YEM, ZAF, ZMB, ZWE
buildingNameNumber string, Required
The building name and/or number of the retail customer’s current address.
Maximum length
255
streetName string, Required
The street name of the retail customer’s current address.
Maximum length
255
city string
The city/town of the retail customer’s current address.
Maximum length
255
county string
The county of the retail customer’s current address.
Maximum length
255
postalCode string, Required
The post code of the retail customer’s current address.
Maximum length
255

request

{
  "addressType": "TradingAddress",
  "validFrom": "2019-08-24T14:15:22Z",
  "validTo": "2019-08-24T14:15:22Z",
  "countryCode": "ABW",
  "buildingNameNumber": "string",
  "streetName": "string",
  "city": "string",
  "county": "string",
  "postalCode": "string"
}

Code copied

Response (application/json)

201 Successfully set the current address for the specified retail customer.
400 Invalid value(s) provided in the update request.
403 Forbidden
404 Retail customer with specified customerId does not exist.

API

GBP Accounts

GBP Payments

Multi-currency/FX

Embedded Banking

Retail customers