Changelog

Release Notes for Client Risk : 15/08/2025

This release includes a risk field in the Client model, which is accepted from the Create Client and Update Client API's and exposed from all Client APIs and Client webhooks. The risk is an optional field that can be one of the following values: low, medium, high, or severe. It indicates the client's risk level.

Here are the client risk details Client API's

POST /clients
{
  "workflow": {
    "code": "direct"
  },
  "data": {
    "client": {
      "identity": {
        "type": "individual",
        "givenName": "Canay",
        "familyName": "Özel",
        "birthDate": "1987-01-01",
        "country": "TR",
        "identifications": [
          {
            "type": "identity-card",
            "identificationNumber": "12345678",
            "issuingCountry": "TR",
            "issueDate": "2022-01-01",
            "expirationDate": "2023-01-01"
          }
        ]
      },
      "risk": "low",
      "profile": {
        "identityType": "individual",
        "residentialAddress": {
          "country": "GB",
          "region": "England",
          "city": "London",
          "street": "Baker Street",
          "houseNumber": "221B",
          "postalCode": "XYZ ABC",
          "refinement": ""
        },
        "phone": "+441234567890",
        "email": "[email protected]"
      }
    }
  },
  "connect": {},
  "metadata": {}

PATCH /clients/<client-id>
{
  "workflow": {
    "code": "direct"
  },
  "data": {
    "client": {
      "identity": {
        "type": "individual",
        "givenName": "Michael",
        "familyName": "Johnson",
        "birthDate": "1953-01-06",
        "country": "GB",
      },
      "risk": "severe",
      "profile": {
        "identityType": "individual",
        "phone": "+4412345678",
        "email": "[email protected]",
        "residentialAddress": {
          "country": "GB",
          "region": "England",
          "city": "London",
          "street": "Baker Street",
          "houseNumber": "221B",
          "postalCode": "EC1Y 1AA"
        }
      }
    }
  },
  "connect": {},
  "metadata": {}
}

GET /clients/<client-id>
"workflow": {},
    "data": {
        "client": {
            "identity": {
                "type": "corporate",
                "legalName": "I.F Technology Ltd",
                "incorporationDate": "1987-01-01",
                "country": "GB"
            },
            "risk": "low", 
            "profile": {
                "identityType": "corporate",
                "registrationAddress": {
                    "country": "GB",
                    "region": "England",
                    "city": "London",
                    "street": "Baker Street",
                    "houseNumber": "221B",
                    "postalCode": "XYZ ABC",
                    "refinement": ""
                },
                "phone": "+441234567890",
                "email": "[email protected]"
            }
        }
    },
    "connect": {},
    "metadata": {
        "includeProfile": true,
        "includePrimaryAddress": true
    }
}

{
  "workflow": {},
  "data": {
    "clients": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "clientNumber": "20663251",
        "status": "active",
        "identity": {
          "type": "corporate",
          "legalName": "I.F Technology Ltd",
          "incorporationDate": "2020-01-01",
          "country": "GB"
        },
        "risk": "severe", 
        "profile": {
          "identityType": "corporate",
          "phone": "+441234567890",
          "email": "[email protected]"
        },
        "fullName": "I.F Technology Ltd"
      },
      {
        "id": "00000000-0000-0000-0000-000000000001",
        "clientNumber": "20663241",
        "status": "active",
        "identity": {
          "type": "individual",
          "givenName": "Canay",
          "familyName": "Özel",
          "birthDate": "1987-01-01",
          "country": "TR"
        },
        "profile": {
          "identityType": "individual",
          "phone": "+441234567890",
          "email": "[email protected]"
        },
        "fullName": "Canay Özel"
      }
    ]
  },
  "connect": {},
  "metadata": {
    "page": {
      "size": 20,
      "totalElements": 2,
      "totalPages": 1,
      "number": 0
    }
  }
}

Release notes for New Card PIN Management Endpoints 05/08/2025

🔓 Reveal Card PIN

Endpoint:
GET /cards/{cardId}/pin

Description:
Retrieves the personal identification number (PIN) of a specified card.

Path Parameters:

  • cardId (UUID, required) – The unique identifier of the card.

Response Example:

{
  "workflow": {},
  "data": {
    "card": {
      "pin": "1234"
    }
  },
  "connect": {},
  "metadata": {}
}

🔓 Set Card PIN

Endpoint:
POST /cards/{cardId}/pin

Description:
Sets or updates the PIN for the specified card.

Path Parameters:

  • cardId (UUID, required) — The unique identifier of the card.

Request Body:

  • workflow.code (string, required) — The workflow code. Allowed value: client.direct
  • data.card.pin (string, required) — The card pin number. It must be a 4 digit number

Response Example:

{
  "workflow": {
    "code": "client.direct"
  },
  "data": {
    "card": {
        "pin":"4321"
    }
  },
  "connect": {},
  "metadata": {}
}

{
    "workflow": {},
    "data": {
        "card": {
            "pin": "4321"
        }
    },
    "connect": {},
    "metadata": {}
}

Release notes for Card Update and User Creation 28/07/2025

Support for Updating Card User: (Card Update API)

  • Added support for updating the userId field on a card.

📥 Example Request Body

{
  "workflow": {
    "code": "client.direct"
  },
  "data": {
    "card": {
      "userId": "00000000-0000-0000-0000-000000000000"
    }
  },
  "connect": {},
  "metadata": {}
}

Note: Please make sure the new user is already connected with the corresponding card provider before updating the card. You can see how to create a user with a specific provider connection below.

Support for Creating User With a Specific Connection: (Create User API)

  • Added support for creating an user with a specific provider connection.

📥 Example Request Body

{
    "workflow": {
        "code": "human.external.direct"
    },
    "data": {
        "user": {
            "email": "[email protected]",
            "identity": {
                "type": "individual",
                "givenName": "bruce",
                "familyName": "wayne",
                "birthDate": "1987-01-01"
            },
            "profile": {
                "phone": "+441234567890",
                "residentialAddress": {
                    "country": "GB",
                    "region": "England",
                    "city": "London",
                    "street": "Baker Street",
                    "houseNumber": "221B",
                    "postalCode": "XYZ ABC",
                    "refinement": ""
                }
            }
        },
        "userClientRelations": [
            {
                "clientId": "00000000-0000-0000-0000-000000000000"
            }
        ]
    },
    "connect": {
        "type": "explicit",
        "serviceProvider": "thredd"
    },
    "metadata": {}
}

Release notes for Card Transactions: 16/07/2025

New fields added to the card transactions (Card Transactions API)

  • authorisationCode (string)

    • Authorisation code generated for approved and declined authorisation requests.

  • paymentToken (object)
    Provides payment toeken information. The following fields were added:

FieldTypeDescription
idstringUnique identifier of the payment token.
creatorstringSource or provider of the token, e.g., MC-MDES, VISA-T.
expiryDatestringExpiry date of the token (YYYY-MM-DD).
typestringType of token (e.g., SE for Secure Element PAN).
statusstringToken status code; e.g., "00" = Active.
creatorStatusstringStatus from token creator’s system, e.g., "A" = Active.
walletstringWallet provider, e.g., APPLE.
deviceTypestringType of device used, e.g., M for Mobile.
languageCodestringDevice’s preferred language, e.g., en.
deviceTelephoneNumberstringTelephone number associated with the device.
deviceIpAddressstringIP address of the device used during token activation. It may arrive in either of 2 formats:

Hex format: FFFFFFFF (255.255.255.255)
Decimal format: A17F001E (081.5.006.255)
deviceIdstringUnique identifier of the device.
deviceNamestringName of the device.
activationCodestringCode used to activate the token.
activationExpiryDateTimestringExpiry date/time of the activation code.
activationMethodDatastringData used in the activation method (e.g., phone number).
activationMethodstringActivation method code (e.g., 1 = SMS).

Release Notes for Idempotency Support: 05/05/2025

We’ve introduced idempotency support for all POST endpoints via the X-Idempotency-Key request header. This helps prevent duplicate processing in case of retries or network issues.

  • Repeated requests with the same key and identical body will return the original response.
  • Responses now include an X-Idempotency-Status header (processed or replayed).
  • A 400 error is returned if a reused key is sent with a different request body.

This makes retrying requests safer and more predictable — especially useful in distributed or unreliable environments. More details can be found at the guides.

Release Notes for Client Attributes: 22/03/2025

This release includes adding an attributes field to the Client model. The attribute field is a key-value map that can store any additional metadata you'd like to link to the client. There are some reserved keys for each service provider.

Here are the client attributes details of creating a client Client Create API

POST /clients
{
    "workflow": {
        "code": "direct"
    },
    "data": {
        "client": {
            "identity": {
                "type": "individual",
                "givenName": "Railsr",
                "familyName": "Rlb",
                "birthDate": "1987-01-01",
                "country": "GB",
                "identifications": [
                    {
                        "type": "identity-card",
                        "identificationNumber": "12345677",
                        "issuingCountry": "GB",
                        "issueDate": "2022-01-01",
                        "expirationDate": "2032-01-01"
                    }
                ]
            },
            "profile": {
                "identityType": "individual",
                "residentialAddress": {
                    "country": "GB",
                    "region": "England",
                    "city": "London",
                    "street": "Baker Street",
                    "houseNumber": "221B",
                    "postalCode": "EC1Y 1AA",
                    "refinement": ""
                },
                "phone": "1012555123",
                "email": "[email protected]"
            },
            "attributes": {
                "accountUsage": "sendAndReceiveMoneyTransfers",
                "riskScore": "low",
                "isPep": "false",
                "expectedVolumeRange": "5001-10000",
                "expectedVolumeType": "monthly",
                "expectedVolumeCurrency": "GBP"
            }
        }
    },
    "connect": {},
    "metadata": {}
}

POST /clients
{
    "workflow": {
        "code": "direct"
    },
    "data": {
        "client": {
            "identity": {
                "type": "corporate",
                "legalName": "Foo Bar Inc.",
                "tradingName": "",
                "country": "GB",
                "identifications": [
                    {
                        "type": "registration-number",
                        "identificationNumber": "12345678"
                    }
                ],
                "incorporationDate": "2019-09-09",
                "corporationType": "ltd"
            },
            "profile": {
                "registrationAddress": {
                    "country": "GB",
                    "region": "Dewsbury Moor",
                    "city": "Dewsbury",
                    "street": "98 Low Rd",
                    "houseNumber": "15",
                    "postalCode": "WF13 3PS",
                    "refinement": ""
                },
                "identityType": "corporate",
                "phone": "1012555123",
                "email": "[email protected]"
            },
            "addresses": {
                "tradingAddress": {
                    "country": "GB",
                    "region": "Dewsbury Moor",
                    "city": "Dewsbury",
                    "street": "92 Low Rd",
                    "houseNumber": "21",
                    "postalCode": "WF13 3PS",
                    "refinement": ""
                }
            },
            "attributes": {
                "accountUsage": "receiveClientFunds",
                "riskScore": "low",
                "expectedVolumeRange": "0-25000",
                "expectedVolumeType": "monthly",
                "expectedVolumeCurrency": "GBP",
                "businessNatures": "20200",
                "companyType": "private",
              	"website": "https//www.abc.com"
            },
            "relatedLegalEntities": [
                {
                    "relation": "director",
                    "identity": {
                        "type": "individual",
                        "givenName": "foo",
                        "familyName": "bar",
                        "birthDate": "1987-01-01",
                        "country": "GB"
                    },
                    "profile": {
                        "phone": "",
                        "addresses": {
                            "residential": {
                                "country": "GB",
                                "postalCode": "12345",
                                "city": "London",
                                "street": "122B Baker street"
                            }
                        }
                    }
                },
                {
                    "relation": "shareholder",
                    "identity": {
                        "type": "corporate",
                        "country": "GB",
                        "identificationNumbers": null,
                        "legalName": "Sub foo bar",
                        "incorporationDate": "2019-09-09",
                        "corporationType": null
                    },
                    "profile": {
                        "phone": "",
                        "addresses": {
                            "registration": {
                                "country": "GB",
                                "postalCode": "12345",
                                "city": "London",
                                "street": "122B Baker street"
                            }
                        }
                    }
                },
                {
                    "relation": "director-and-shareholder",
                    "identity": {
                        "type": "individual",
                        "givenName": "sub 2 foo",
                        "familyName": "bar",
                        "birthDate": "1987-01-01",
                        "country": "GB"
                    },
                    "profile": {
                        "phone": "",
                        "addresses": {
                            "residential": {
                                "country": "GB",
                                "postalCode": "12345",
                                "city": "London",
                                "street": "122B Baker street"
                            }
                        }
                    }
                }
            ]
        }
    },
    "connect": {},
    "metadata": {}
}

Here are the client attributes details of updating a client Client Update API

// the request below only updates the identity & profile & attributes of the individual client
PATCH /clients/<client-id>
{
    "workflow": {
        "code": "direct"
    },
    "data": {
        "client": {
            "identity": {
                "type": "individual",
                "givenName": "Connect Individual",
                "familyName": "Railsbank",
                "birthDate": "1996-01-01",
                "country": "GB",
                "identifications": [
                    {
                        "type": "identity-card",
                        "identificationNumber": "12345677",
                        "issuingCountry": "GB",
                        "issueDate": "2022-01-01",
                        "expirationDate": "2032-01-01"
                    }
                ]
            },
            "profile": {
                "identityType": "individual",
                "residentialAddress": {
                    "country": "GB",
                    "region": "England",
                    "city": "London",
                    "street": "Baker Street",
                    "houseNumber": "221B",
                    "postalCode": "EC1Y 1AA",
                    "refinement": ""
                },
                "phone": "1012555128",
                "email": "[email protected]"
            },
            "attributes": {
                "accountUsage": "sendAndReceiveMoneyTransfers",
                "riskScore": "low",
                "isPep": "false",
                "expectedVolumeRange": "5001-10000",
                "expectedVolumeType": "monthly",
                "expectedVolumeCurrency": "GBP"
            }
        }
    },
    "connect": {},
    "metadata": {}
}

// the request below only updates the identity & the profile & attributes of the corporate client
PATCH /clients/<client-id>
{
    "workflow": {
        "code": "direct"
    },
    "data": {
        "client": {
            "identity": {
                "type": "corporate",
                "legalName": "Foo Bar Inc.",
                "tradingName": "",
                "country": "GB",
                "identifications": [
                    {
                        "type": "registration-number",
                        "identificationNumber": "12345678"
                    }
                ],
                "incorporationDate": "2019-09-09",
                "corporationType": "ltd"
            },
            "profile": {
                "registrationAddress": {
                    "country": "GB",
                    "region": "Dewsbury Moor",
                    "city": "Dewsbury",
                    "street": "98 Low Rd",
                    "houseNumber": "17",
                    "postalCode": "WF13 3PS",
                    "refinement": ""
                },
                "identityType": "corporate",
                "phone": "1012555129",
                "email": "[email protected]"
            },
            "addresses": {
                "trading": {
                    "country": "GB",
                    "region": "Dewsbury Moor",
                    "city": "Dewsbury",
                    "street": "92 Low Rd",
                    "houseNumber": "21",
                    "postalCode": "WF13 3PS",
                    "refinement": ""
                }
            },
            "attributes": {
                "accountUsage": "receiveClientFunds",
                "riskScore": "low",
                "expectedVolumeRange": "0-25000",
                "expectedVolumeType": "monthly",
                "expectedVolumeCurrency": "GBP",
                "businessNatures": "20200",
                "companyType": "private",
              	"website": "https//www.abc.com"
            }
        }
    },
    "connect": {},
    "metadata": {}
}

Release Notes for Account Attributes: 20/03/2025

This release includes adding an attributes field to the Account model. The attribute field is a key value field where additional information to be stored regarding the account can be sent. For example, a key-value whose key is account type and value is salary can be sent. Here, account type indicates the key, while salary is a value that holds the type value of this account. The attribute field is a field that can be sent when calling the Create Account API.

Here are the account attributes details of an account Account Create API

Release Notes for Incoming Transfer Webhook: 24 /01/2025

This release includes a new Webhook for incoming transfers. Below, you'll find the details about new additions that have been included in this release.

  • A new type of webhook for Incoming Transfers: incoming-transfer-updated-webhook
    If the incoming transfer is updated for any reason after it passes to the completed status, this webhook is sent. In this case, a new field called operationType is added under the webhook. This field indicates the operation for which this update was made. Incoming Transfer Webhooks
{
   "webhook":{
      "module":"incoming-transfers",
      "type":"incoming-transfer-updated",
      "operationType":"update-related-transaction-id"
   },
   "data":{
      "incomingTransfer":{
         "id":"00000000-0000-0000-0000-000000000000",
         "clientId":null,
         "accountId":"00000000-0000-0000-0000-000000000000",
         "transactionNumber":"20250120-YG2X8G",
         "status":"completed",
         "currency":"EUR",
         "amount":1000.00,
         "feeAmount":null,
         "feeCurrency":null,
         "outgoingTransferId":null,
         "serviceProviderId":"00000000-0000-0000-0000-000000000000",
         "serviceProviderReference":"00000000-0000-0000-0000-000000000000",
         "senderInformation":null,
         "senderName":"Donald Trump",
         "transferDate":"2025-01-20",
         "totalAmount":null,
         "provisionedAccountCreditId":"00000000-0000-0000-0000-000000000000",
         "serviceProvider":"clearbank-eu",
         "receiverAccount":{
            "bankName":null,
            "accountHolderName":"",
            "alias":"Customer Account",
            "country":"NL",
            "currency":"EUR",
            "routingCodes":{
               "bic":null
            },
            "accountNumber":null,
            "iban":"NL54CLRB0089338401",
            "ledgerNumber":"44579422"
         },
         "senderAccount":{
            "bankName":null,
            "accountHolderName":"Donald Trump",
            "alias":null,
            "country":null,
            "currency":"EUR",
            "routingCodes":{
               
            },
            "accountNumber":null,
            "iban":"NL55SHWG3508008115",
            "ledgerNumber":null
         },
         "scope":"external",
         "scheme":"sepa",
         "owner":"organization",
         "relatedTransaction":{
            "nature":"virtual",
            "id":"00000000-0000-0000-0000-000000000000"
         }
      }
   }
}