Counterparty Validation

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

Before you initiate outbound payments 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 or similar checks for IBANs.

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

Validate external counterparty

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

Path parameters

customerId*string

Header parameters

Body

application/json

identifierType*enum

UK_ACCOUNTIBAN

contactName*string

sortCode*nullable string

The sort code of the UK bank account

Example: "010102"

accountNumber*nullable string

The account number of the UK bank account

Example: "12345678"

iban*nullable string

The IBAN of the account

Example: "GB33BUKB20201555555555"

bic*nullable string

The BIC of the account

Example: "BUKBGB22"

accountType*enum

BUSINESSPERSONAL

secondaryAccountId*nullable string

Response

200400403422

Returns external counterparty validation

Body

application/json

counterpartyBeneficiaryStatus*nullable enum

MATCHPARTIAL_MATCHNO_MATCHBUSINESS_ACCOUNT_NAME_MATCHEDPERSONAL_ACCOUNT_NAME_MATCHEDBUSINESS_ACCOUNT_CLOSE_MATCHPERSONAL_ACCOUNT_CLOSE_MATCHACCOUNT_DOES_NOT_EXISTSECONDARY_ACCOUNT_ID_NOT_FOUNDACCOUNT_NOT_SUPPORTEDACCOUNT_SWITCHEDWRONG_PARTICIPANTNO_RESPONSENOT_ENROLLED

counterpartyValidationResult*nullable enum

UK_ACCOUNT_VALIDUK_ACCOUNT_INVALIDIBAN_VALIDIBAN_INVALIDUNKNOWNDISABLED

similarName*nullable string

Request

JavaScriptCurlPythonHTTP

const response = await fetch('api-url/v1/partner/payments/customers/{customerId}/validate-external-counterparty', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "identifierType": "UK_ACCOUNT",
      "contactName": "text",
      "sortCode": "010102",
      "accountNumber": "12345678",
      "iban": "GB33BUKB20201555555555",
      "bic": "BUKBGB22",
      "accountType": "BUSINESS",
      "secondaryAccountId": "text"
    }),
});
const data = await response.json();

Response

200400403422

{
  "counterpartyBeneficiaryStatus": "MATCH",
  "counterpartyValidationResult": "UK_ACCOUNT_VALID",
  "similarName": "text"
}