Counterparty Validation

This section explains how to validate external counterparty information before initiating outbound payments.

Introduction

Counterparty validation process is an integral part of outbound payment operations. Depending on the model and the jurisdictions involved for the accounts provided to you, there will be specific requirements and validation steps to reduce possible processing errors. Equally, this process aims to reduce possible fraud or misleading payment instructions.

Before you initiate outbound payments to comply with relevant local regulations, we strongly recommend to use this API to check validity of the counterparty values. Our platform applies necessary checks as per respective regulations including Pay.UK Confirmation of Payee, Vocalink Modulus Validation for UK payments or similar checks for IBANs for international payments.

Payments to UK Accounts

Algbra is a direct participant in Pay.UK’s Confirmation of Payee (CoP) service, an industry initiative designed to help prevent misdirected payments and reduce fraud. CoP verifies that the account name provided by a payer matches the name and type of the account held by the payee’s financial institution before a payment is sent.

This ensures that name-matching checks are seamlessly performed in real time, providing enhanced security, accuracy, and customer protection across Algbra’s payment ecosystem.

For inbound payments initiated to Algbra-issued accounts, the CoP validation is automatically applied as part of the account feature set, no separate integration or configuration is required as long as customer information is valid on the platform.

For outbound payments initiated from Algbra-issued accounts, you need to implement the API below to ensure you follow the compliant process with your UI journey.

Please contact to your account manager for more information about expected UX journey for Pay.UK CoP and error handling approaches.

Validate external counterparty (v2)

post

Path parameters

customerIdstringRequired

Header parameters

authorizationstringOptional

Authorization header containing your API Token

x-alg-noncestringOptional

Nonce used to generate the payload signature

x-alg-signaturestringOptional

Payload signature

datestringOptional

Date of the request un UTC/GMT

Body

application/json

identifierTypestring · enumRequired

Type of account identifier used

Example: UK_ACCOUNTPossible values:

contactNamestringRequired

Full name of the counterparty contact person

Example: John Doe

sortCodestring · nullableOptional

The sort code of the UK bank account

Example: 010102

accountNumberstring · nullableOptional

Account number

Example: 1234567890

ibanstring · nullableOptional

The IBAN (International Bank Account Number) of the account

Example: GB33BUKB20201555555555

bicstring · nullableOptional

The BIC (Bank Identifier Code) of the account

Example: BUKBGB22

routingTypestring · enum · nullableOptional

Primary routing type (required when BIC is not provided)

Example: ABA_ROUTING_NUMBERPossible values:

routingNumberstring · nullableOptional

Primary routing number (required when routingType is provided)

Example: 026009593

secondaryRoutingTypestring · enum · nullableOptional

Secondary routing type

Example: ROUTING_CODEPossible values:

secondaryRoutingNumberstring · nullableOptional

Secondary routing number (required when secondaryRoutingType is provided)

Example: GB33BUKB20201555555555

countrystring · enum · nullableOptional

Country of the counterparty account.

Example: GBRPossible values:

currencystring · enum · nullableOptional

Currency of the counterparty account.

Example: GBPPossible values:

accountTypestring · enumRequired

Specifies the type of account

Example: PERSONALPossible values:

secondaryAccountIdstring · nullableOptional

Unique identifier for a secondary account

Example: e0cab2dd-739f-43de-b131-3e423e935bf1

Responses

200

Returns external counterparty validation

application/json

400

Input validation error

application/json

403

Forbidden

application/json

408

Request timeout

application/json

422

Unprocessable entity

application/json

post

/v2/partner/payments/customers/{customerId}/validate-external-counterparty

HTTPcURLJavaScriptPython

POST /v2/partner/payments/customers/{customerId}/validate-external-counterparty HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 592

{
  "identifierType": "UK_ACCOUNT",
  "contactName": "John Doe",
  "sortCode": "010102",
  "accountNumber": "1234567890",
  "iban": "GB33BUKB20201555555555",
  "bic": "BUKBGB22",
  "routingType": "ABA_ROUTING_NUMBER",
  "routingNumber": "026009593",
  "secondaryRoutingType": "ROUTING_CODE",
  "secondaryRoutingNumber": "GB33BUKB20201555555555",
  "country": "GBR",
  "currency": "GBP",
  "accountType": "PERSONAL",
  "secondaryAccountId": "e0cab2dd-739f-43de-b131-3e423e935bf1",
  "address": {
    "buildingName": "Eiffel Tower",
    "buildingNumber": "10",
    "state": "Île-de-France",
    "street": "Av. Gustave Eiffel",
    "town": "Paris",
    "postcode": "75007",
    "country": "FRA"
  }
}

{
  "validation": {
    "valid": true,
    "checksPassed": [
      "SORTCODE_VERIFICATION",
      "MODULUS_CHECK",
      "NAME_CHECK_COP"
    ],
    "checksFailed": [],
    "errors": [
      "Invalid bank details provided with account reference."
    ]
  },
  "bankMetadata": {
    "source": "EISCD",
    "sourceId": "04",
    "bankName": "HSBC",
    "branchName": "HSBC Branch",
    "bic": "undefinedundefined"
  },
  "nameCheck": {
    "assertion": "REQUIRED",
    "state": "ACCOUNT_DOES_NOT_EXIST"
  }
}

---

This endpoint is discontinued and will no longer receive updates or support. Please migrate to the new v2 endpoint.

Validate external counterparty

post

Path parameters

customerIdstringRequired

Header parameters

authorizationstringOptional

Authorization header containing your API Token

x-alg-noncestringOptional

Nonce used to generate the payload signature

x-alg-signaturestringOptional

Payload signature

datestringOptional

Date of the request un UTC/GMT

Body

application/json

identifierTypestring · enumRequired

Type of account identifier used

Example: UK_ACCOUNTPossible values:

contactNamestringRequired

Full name of the counterparty contact person

Example: John Doe

sortCodestring · nullableOptional

The sort code of the UK bank account

Example: 010102

accountNumberstring · nullableOptional

The account number of the UK bank account

Example: 12345678

ibanstring · nullableOptional

The IBAN (International Bank Account Number) of the account

Example: GB33BUKB20201555555555

bicstring · nullableOptional

The BIC (Bank Identifier Code) of the account

Example: BUKBGB22

accountTypestring · enumRequired

Specifies the type of account

Example: PERSONALPossible values:

secondaryAccountIdstring · nullableOptional

Unique identifier for a secondary account

Example: e0cab2dd-739f-43de-b131-3e423e935bf1

Responses

200

Returns external counterparty validation

application/json

counterpartyBeneficiaryStatusstring · enum · nullableOptional

Validation status of the counterparty beneficiary

Example: PARTIAL_MATCHPossible values:

counterpartyValidationResultstring · enum · nullableOptional

Result of counterparty validation check

Possible values:

similarNamestring · nullableOptional

Closest matching name suggested if counterparty name differs

Example: John Doe

400

Input validation error

application/json

403

Forbidden

application/json

408

Request timeout

application/json

422

Unprocessable entity

application/json

post

/v1/partner/payments/customers/{customerId}/validate-external-counterparty

HTTPcURLJavaScriptPython

POST /v1/partner/payments/customers/{customerId}/validate-external-counterparty HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 237

{
  "identifierType": "UK_ACCOUNT",
  "contactName": "John Doe",
  "sortCode": "010102",
  "accountNumber": "12345678",
  "iban": "GB33BUKB20201555555555",
  "bic": "BUKBGB22",
  "accountType": "PERSONAL",
  "secondaryAccountId": "e0cab2dd-739f-43de-b131-3e423e935bf1"
}

{
  "counterpartyBeneficiaryStatus": "PARTIAL_MATCH",
  "counterpartyValidationResult": "UK_ACCOUNT_VALID",
  "similarName": "John Doe"
}