# Counterparty Validation

## 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](https://www.wearepay.uk/what-we-do/overlay-services/confirmation-of-payee/), [Vocalink Modulus Validation](https://www.vocalink.com/tools/modulus-checking/) 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. 

{% hint style="success" %}
Please contact to your account manager for more information about expected UX journey for Pay.UK CoP and error handling approaches.
{% endhint %}

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

> Validate external counterparty (v2)

```json
{"openapi":"3.0.0","info":{"title":"Horizon Link - API Docs","version":"1.0"},"servers":[{"url":"api-url"}],"paths":{"/v2/partner/payments/customers/{customerId}/validate-external-counterparty":{"post":{"operationId":"PaymentController_validateExternalCounterpartyV2","summary":"Validate external counterparty (v2)","parameters":[{"name":"customerId","required":true,"in":"path","schema":{"type":"string"}},{"name":"authorization","in":"header","description":"Authorization header containing your API Token","schema":{"type":"string"}},{"name":"x-alg-nonce","in":"header","description":"Nonce used to generate the payload signature","schema":{"type":"string"}},{"name":"x-alg-signature","in":"header","description":"Payload signature","schema":{"type":"string"}},{"name":"date","in":"header","description":"Date of the request un UTC/GMT","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerValidateCounterpartyPayloadV2"}}}},"responses":{"201":{"description":"Returns external counterparty validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerValidateCounterpartyResponseV2"}}}},"400":{"description":"Input validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCommonErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCommonErrorResponse"}}}},"408":{"description":"Request timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCommonErrorResponse"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerPaymentErrorResponse"}}}}},"tags":["Payments"]}}},"components":{"schemas":{"PartnerValidateCounterpartyPayloadV2":{"type":"object","properties":{"identifierType":{"type":"string","description":"Type of account identifier used","enum":["UK_ACCOUNT","IBAN","CUSTODY_ID","OTHER_EXTERNAL","GENERIC_ACCOUNT"]},"contactName":{"type":"string","description":"Full name of the counterparty contact person"},"sortCode":{"type":"string","description":"The sort code of the UK bank account","nullable":true},"accountNumber":{"type":"string","description":"Account number","nullable":true},"iban":{"type":"string","description":"The IBAN (International Bank Account Number) of the account","nullable":true},"bic":{"type":"string","description":"The BIC (Bank Identifier Code) of the account","nullable":true},"routingType":{"type":"string","description":"Primary routing type (required when BIC is not provided)","enum":["ROUTING_CODE","GIRO_ROUTING_CODE","ACH_ROUTING_NUMBER","FAST_ROUTING_CODE","WIRE_ROUTING_NUMBER","MEPS_ROUTING_CODE","ABA_ROUTING_NUMBER","BANK_CODE","BRANCH_CODE","BSB_CODE","CLABE","CNAPS","IFSC","INSTITUTION_NO"],"nullable":true},"routingNumber":{"type":"string","description":"Primary routing number (required when routingType is provided)","nullable":true},"secondaryRoutingType":{"type":"string","description":"Secondary routing type","enum":["ROUTING_CODE","GIRO_ROUTING_CODE","ACH_ROUTING_NUMBER","FAST_ROUTING_CODE","WIRE_ROUTING_NUMBER","MEPS_ROUTING_CODE","ABA_ROUTING_NUMBER","BANK_CODE","BRANCH_CODE","BSB_CODE","CLABE","CNAPS","IFSC","INSTITUTION_NO"],"nullable":true},"secondaryRoutingNumber":{"type":"string","description":"Secondary routing number (required when secondaryRoutingType is provided)","nullable":true},"country":{"type":"string","description":"Country of the counterparty account.","enum":["AFG","ALA","ALB","DZA","ASM","AND","AGO","AIA","ATA","ATG","ARG","ARM","ABW","AUS","AUT","AZE","BHS","BHR","BGD","BRB","BLR","BEL","BLZ","BEN","BMU","BTN","BOL","BES","BIH","BWA","BVT","BRA","IOT","BRN","BGR","BFA","BDI","CPV","KHM","CMR","CAN","CYM","CAF","TCD","CHL","CHN","CXR","CCK","COL","COM","COG","COD","COK","CRI","CIV","HRV","CUB","CUW","CYP","CZE","DNK","DJI","DMA","DOM","ECU","EGY","SLV","GNQ","ERI","EST","SWZ","ETH","FLK","FRO","FJI","FIN","FRA","GUF","PYF","ATF","GAB","GMB","GEO","DEU","GHA","GIB","GRC","GRL","GRD","GLP","GUM","GTM","GGY","GIN","GNB","GUY","HTI","HMD","VAT","HND","HKG","HUN","ISL","IND","IDN","IRN","IRQ","IRL","IMN","ISR","ITA","JAM","JPN","JEY","JOR","KAZ","KEN","KIR","PRK","KOR","KWT","KGZ","LAO","LVA","LBN","LSO","LBR","LBY","LIE","LTU","LUX","MAC","MDG","MWI","MYS","MDV","MLI","MLT","MHL","MTQ","MRT","MUS","MYT","MEX","FSM","MDA","MCO","MNG","MNE","MSR","MAR","MOZ","MMR","NAM","NRU","NPL","NLD","NCL","NZL","NIC","NER","NGA","NIU","NFK","MKD","MNP","NOR","OMN","PAK","PLW","PSE","PAN","PNG","PRY","PER","PHL","PCN","POL","PRT","PRI","QAT","REU","ROU","RUS","RWA","BLM","SHN","KNA","LCA","MAF","SPM","VCT","WSM","SMR","STP","SAU","SEN","SRB","SYC","SLE","SGP","SXM","SVK","SVN","SLB","SOM","ZAF","SGS","SSD","ESP","LKA","SDN","SUR","SJM","SWE","CHE","SYR","TWN","TJK","TZA","THA","TLS","TGO","TKL","TON","TTO","TUN","TUR","TKM","TCA","TUV","UGA","UKR","ARE","GBR","USA","UMI","URY","UZB","VUT","VEN","VNM","VGB","VIR","WLF","ESH","YEM","ZMB","ZWE","XXK","XKX"],"nullable":true},"currency":{"type":"string","description":"Currency of the counterparty account.","enum":["AFN","EUR","ALL","DZD","USD","AOA","XCD","ARS","AMD","AWG","AUD","AZN","BSD","BHD","BDT","BBD","BYN","BZD","XOF","BMD","INR","BTN","BOB","BOV","BAM","BWP","NOK","BRL","BND","BGN","BIF","CVE","KHR","XAF","CAD","KYD","CLP","CLF","CNY","COP","COU","KMF","CDF","NZD","CRC","HRK","CUP","CUC","ANG","CZK","DKK","DJF","DOP","EGP","SVC","ERN","SZL","ETB","FKP","FJD","XPF","GMD","GEL","GHS","GIP","GTQ","GBP","GNF","GYD","HTG","HNL","HKD","HUF","ISK","IDR","XDR","IRR","IQD","ILS","JMD","JPY","JOD","KZT","KES","KPW","KRW","KWD","KGS","LAK","LBP","LSL","ZAR","LRD","LYD","CHF","MOP","MKD","MGA","MWK","MYR","MVR","MRU","MUR","XUA","MXN","MXV","MDL","MNT","MAD","MZN","MMK","NAD","NPR","NIO","NGN","OMR","PKR","PAB","PGK","PYG","PEN","PHP","PLN","QAR","RON","RUB","RWF","WST","STN","SAR","RSD","SCR","SLL","SGD","XSU","SBD","SOS","SSP","LKR","SDG","SRD","SEK","CHE","CHW","SYP","TWD","TJS","THB","TOP","TTD","TND","TRY","TMT","UGX","UAH","AED","USN","UYU","UYI","UYW","UZS","VUV","VES","VND","YER","ZMW","ZWL","XBA","XBB","XBC","XBD","XTS","XXX","XAU","XPD","XPT","XAG","AFA","FIM","ADP","ESP","FRF","AOK","AOR","RUR","ATS","AYM","AZM","BYB","BYR","BEC","BEF","BEL","BAD","BRB","BRR","BGJ","CYP","CSK","ECS","ECV","GQE","EEK","XEU","GEK","DDM","DEM","GHC","GHP","GRD","GWE","ITL","IEP","LVL","ZAL","LTL","LUC","LUF","LUL","MGF","MLF","MTL","MRO","MZE","NLG","PLZ","PTE","ROK","STD","CSD","SKK","SIT","RHD","ESA","ESB","SDD","SRG","TJR","TPE","TRL","TMM","UAK","USS","VEB","VEF","YUD","ZRN","ZMK","ZWN","ZWR"],"nullable":true},"accountType":{"type":"string","description":"Specifies the type of account","enum":["BUSINESS","PERSONAL","UNKNOWN"]},"secondaryAccountId":{"type":"string","description":"Unique identifier for a secondary account","nullable":true},"address":{"description":"Required for non-UK accounts (IBAN / GENERIC)","nullable":true,"allOf":[{"$ref":"#/components/schemas/PartnerPaymentAddressPayload"}]}},"required":["identifierType","contactName","accountType"]},"PartnerPaymentAddressPayload":{"type":"object","properties":{"buildingName":{"type":"string","description":"Building name","nullable":true},"buildingNumber":{"type":"string","description":"Building number","nullable":true},"state":{"type":"string","description":"State / region","nullable":true},"street":{"type":"string","description":"Street / address line"},"town":{"type":"string","description":"Town / city"},"postcode":{"type":"string","description":"Postal / ZIP code"},"country":{"type":"string","description":"Country code","enum":["AFG","ALA","ALB","DZA","ASM","AND","AGO","AIA","ATA","ATG","ARG","ARM","ABW","AUS","AUT","AZE","BHS","BHR","BGD","BRB","BLR","BEL","BLZ","BEN","BMU","BTN","BOL","BES","BIH","BWA","BVT","BRA","IOT","BRN","BGR","BFA","BDI","CPV","KHM","CMR","CAN","CYM","CAF","TCD","CHL","CHN","CXR","CCK","COL","COM","COG","COD","COK","CRI","CIV","HRV","CUB","CUW","CYP","CZE","DNK","DJI","DMA","DOM","ECU","EGY","SLV","GNQ","ERI","EST","SWZ","ETH","FLK","FRO","FJI","FIN","FRA","GUF","PYF","ATF","GAB","GMB","GEO","DEU","GHA","GIB","GRC","GRL","GRD","GLP","GUM","GTM","GGY","GIN","GNB","GUY","HTI","HMD","VAT","HND","HKG","HUN","ISL","IND","IDN","IRN","IRQ","IRL","IMN","ISR","ITA","JAM","JPN","JEY","JOR","KAZ","KEN","KIR","PRK","KOR","KWT","KGZ","LAO","LVA","LBN","LSO","LBR","LBY","LIE","LTU","LUX","MAC","MDG","MWI","MYS","MDV","MLI","MLT","MHL","MTQ","MRT","MUS","MYT","MEX","FSM","MDA","MCO","MNG","MNE","MSR","MAR","MOZ","MMR","NAM","NRU","NPL","NLD","NCL","NZL","NIC","NER","NGA","NIU","NFK","MKD","MNP","NOR","OMN","PAK","PLW","PSE","PAN","PNG","PRY","PER","PHL","PCN","POL","PRT","PRI","QAT","REU","ROU","RUS","RWA","BLM","SHN","KNA","LCA","MAF","SPM","VCT","WSM","SMR","STP","SAU","SEN","SRB","SYC","SLE","SGP","SXM","SVK","SVN","SLB","SOM","ZAF","SGS","SSD","ESP","LKA","SDN","SUR","SJM","SWE","CHE","SYR","TWN","TJK","TZA","THA","TLS","TGO","TKL","TON","TTO","TUN","TUR","TKM","TCA","TUV","UGA","UKR","ARE","GBR","USA","UMI","URY","UZB","VUT","VEN","VNM","VGB","VIR","WLF","ESH","YEM","ZMB","ZWE","XXK","XKX"]}},"required":["street","town","postcode","country"]},"PartnerValidateCounterpartyResponseV2":{"type":"object","properties":{"validation":{"description":"Validation details","allOf":[{"$ref":"#/components/schemas/PartnerValidateCounterpartyValidation"}]},"bankMetadata":{"description":"Bank metadata","allOf":[{"$ref":"#/components/schemas/PartnerValidateCounterpartyBankMetadata"}]},"nameCheck":{"description":"Name check details","allOf":[{"$ref":"#/components/schemas/PartnerValidateCounterpartyNameCheck"}]}},"required":["validation"]},"PartnerValidateCounterpartyValidation":{"type":"object","properties":{"valid":{"type":"boolean","description":"Overall validation outcome"},"checksPassed":{"type":"array","description":"List of validation checks that passed","items":{"type":"string","enum":["SORTCODE_VERIFICATION","MODULUS_CHECK","NAME_CHECK_COP","NAME_CHECK_VOP","STRUCTURE_CHECK_IBAN","STRUCTURE_CHECK_BIC","BIC_VERIFICATION","SCHEME_VALIDATION"]}},"checksFailed":{"type":"array","description":"List of validation checks that failed","items":{"type":"string","enum":["SORTCODE_VERIFICATION","MODULUS_CHECK","NAME_CHECK_COP","NAME_CHECK_VOP","STRUCTURE_CHECK_IBAN","STRUCTURE_CHECK_BIC","BIC_VERIFICATION","SCHEME_VALIDATION"]}},"errors":{"description":"Additional error details","type":"array","items":{"type":"string"}}},"required":["valid"]},"PartnerValidateCounterpartyBankMetadata":{"type":"object","properties":{"source":{"type":"string"},"sourceId":{"type":"string"},"bankName":{"type":"string"},"branchName":{"type":"string"},"bic":{"type":"string","description":"BIC"}}},"PartnerValidateCounterpartyNameCheck":{"type":"object","properties":{"assertion":{"type":"string","enum":["REQUIRED","NOT_REQUIRED","UNKNOWN"],"description":"Indicates assertion for name confirmation requirement"},"state":{"type":"string","enum":["MATCH","PARTIAL_MATCH","NO_MATCH","BUSINESS_ACCOUNT_NAME_MATCHED","PERSONAL_ACCOUNT_NAME_MATCHED","BUSINESS_ACCOUNT_CLOSE_MATCH","PERSONAL_ACCOUNT_CLOSE_MATCH","ACCOUNT_DOES_NOT_EXIST","SECONDARY_ACCOUNT_ID_NOT_FOUND","ACCOUNT_NOT_SUPPORTED","ACCOUNT_SWITCHED","WRONG_PARTICIPANT","NO_RESPONSE","NOT_ENROLLED"],"description":"Name check state (when CoP/VoP is available)"}},"required":["assertion"]},"PartnerCommonErrorResponse":{"type":"object","properties":{"errorType":{"type":"string","enum":["VALIDATION_ERROR","FORBIDDEN","NOT_FOUND","UNAUTHORIZED","PRECONDITION_FAILED","REQUEST_TIMEOUT","SERVICE_UNAVAILABLE","UNIDENTIFIED","TECHNICAL_ERROR"]},"reason":{"type":"string","nullable":true},"validationFailures":{"nullable":true,"type":"array","items":{"$ref":"#/components/schemas/PartnerValidationFieldError"}}},"required":["errorType"]},"PartnerValidationFieldError":{"type":"object","properties":{"message":{"type":"string"},"path":{"type":"string","nullable":true}},"required":["message"]},"PartnerPaymentErrorResponse":{"type":"object","properties":{"errorType":{"type":"string","enum":["ALREADY_PROCESS","AML_BLOCKED_INBOUND_TRANSFER","AML_BLOCKED_OUTBOUND_TRANSFER","EXCEEDS_LIMIT","INSUFFICIENT_BALANCE","INVALID_COUNTERPARTY","RAIL_NOT_SUPPORTED","RESTRICTED_INBOUND_TRANSFER","RESTRICTED_OUTBOUND_TRANSFER","TECHNICAL_ERROR","INSUFFICIENT_FUNDS","PAYMENT_NOT_RETURNABLE","UNDEFINED"]},"reason":{"type":"string","nullable":true},"validationFailures":{"nullable":true,"type":"array","items":{"$ref":"#/components/schemas/PartnerValidationFieldError"}}},"required":["errorType"]}}}}
```

***

{% hint style="warning" %}
This endpoint is discontinued and will no longer receive updates or support. Please migrate to the new v2 endpoint.
{% endhint %}

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

> Validate external counterparty

```json
{"openapi":"3.0.0","info":{"title":"Horizon Link - API Docs","version":"1.0"},"servers":[{"url":"api-url"}],"paths":{"/v1/partner/payments/customers/{customerId}/validate-external-counterparty":{"post":{"operationId":"PaymentController_validateExternalCounterparty","summary":"Validate external counterparty","parameters":[{"name":"customerId","required":true,"in":"path","schema":{"type":"string"}},{"name":"authorization","in":"header","description":"Authorization header containing your API Token","schema":{"type":"string"}},{"name":"x-alg-nonce","in":"header","description":"Nonce used to generate the payload signature","schema":{"type":"string"}},{"name":"x-alg-signature","in":"header","description":"Payload signature","schema":{"type":"string"}},{"name":"date","in":"header","description":"Date of the request un UTC/GMT","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerValidateCounterpartyPayload"}}}},"responses":{"201":{"description":"Returns external counterparty validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerValidateCounterpartyResponse"}}}},"400":{"description":"Input validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCommonErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCommonErrorResponse"}}}},"408":{"description":"Request timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCommonErrorResponse"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerPaymentErrorResponse"}}}}},"tags":["Payments"]}}},"components":{"schemas":{"PartnerValidateCounterpartyPayload":{"type":"object","properties":{"identifierType":{"type":"string","description":"Type of account identifier used","enum":["UK_ACCOUNT","IBAN","CUSTODY_ID","OTHER_EXTERNAL","GENERIC_ACCOUNT"]},"contactName":{"type":"string","description":"Full name of the counterparty contact person"},"sortCode":{"type":"string","description":"The sort code of the UK bank account","nullable":true},"accountNumber":{"type":"string","description":"The account number of the UK bank account","nullable":true},"iban":{"type":"string","description":"The IBAN (International Bank Account Number) of the account","nullable":true},"bic":{"type":"string","description":"The BIC (Bank Identifier Code) of the account","nullable":true},"accountType":{"type":"string","description":"Specifies the type of account","enum":["BUSINESS","PERSONAL","UNKNOWN"]},"secondaryAccountId":{"type":"string","description":"Unique identifier for a secondary account","nullable":true}},"required":["identifierType","contactName","accountType"]},"PartnerValidateCounterpartyResponse":{"type":"object","properties":{"counterpartyBeneficiaryStatus":{"type":"string","description":"Validation status of the counterparty beneficiary","enum":["MATCH","PARTIAL_MATCH","NO_MATCH","BUSINESS_ACCOUNT_NAME_MATCHED","PERSONAL_ACCOUNT_NAME_MATCHED","BUSINESS_ACCOUNT_CLOSE_MATCH","PERSONAL_ACCOUNT_CLOSE_MATCH","ACCOUNT_DOES_NOT_EXIST","SECONDARY_ACCOUNT_ID_NOT_FOUND","ACCOUNT_NOT_SUPPORTED","ACCOUNT_SWITCHED","WRONG_PARTICIPANT","NO_RESPONSE","NOT_ENROLLED"],"nullable":true},"counterpartyValidationResult":{"type":"string","description":"Result of counterparty validation check","enum":["UK_ACCOUNT_VALID","UK_ACCOUNT_INVALID","IBAN_VALID","IBAN_INVALID","UNKNOWN"],"nullable":true},"similarName":{"type":"string","description":"Closest matching name suggested if counterparty name differs","nullable":true}}},"PartnerCommonErrorResponse":{"type":"object","properties":{"errorType":{"type":"string","enum":["VALIDATION_ERROR","FORBIDDEN","NOT_FOUND","UNAUTHORIZED","PRECONDITION_FAILED","REQUEST_TIMEOUT","SERVICE_UNAVAILABLE","UNIDENTIFIED","TECHNICAL_ERROR"]},"reason":{"type":"string","nullable":true},"validationFailures":{"nullable":true,"type":"array","items":{"$ref":"#/components/schemas/PartnerValidationFieldError"}}},"required":["errorType"]},"PartnerValidationFieldError":{"type":"object","properties":{"message":{"type":"string"},"path":{"type":"string","nullable":true}},"required":["message"]},"PartnerPaymentErrorResponse":{"type":"object","properties":{"errorType":{"type":"string","enum":["ALREADY_PROCESS","AML_BLOCKED_INBOUND_TRANSFER","AML_BLOCKED_OUTBOUND_TRANSFER","EXCEEDS_LIMIT","INSUFFICIENT_BALANCE","INVALID_COUNTERPARTY","RAIL_NOT_SUPPORTED","RESTRICTED_INBOUND_TRANSFER","RESTRICTED_OUTBOUND_TRANSFER","TECHNICAL_ERROR","INSUFFICIENT_FUNDS","PAYMENT_NOT_RETURNABLE","UNDEFINED"]},"reason":{"type":"string","nullable":true},"validationFailures":{"nullable":true,"type":"array","items":{"$ref":"#/components/schemas/PartnerValidationFieldError"}}},"required":["errorType"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.algbralabs.com/partner-banking/concepts/payments/counterparty-validation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.