Overview

Before a payment is executed, our platform performs a Confirmation of Payee (CoP) validation to verify that the beneficiary's name matches the destination bank account.

The validation result is returned in the confirmationOfPayee object.

Payments are processed only when the validation result is considered successful. If the validation fails, the payment request is rejected synchronously with HTTP status 422 Unprocessable Entity.

Validation Flow

1. Client submits a payment request.
2. The platform performs beneficiary verification.
3. The verification result is returned in confirmationOfPayee.validationOutcome.
4. The payment is:
   1. accepted if the beneficiary validation succeeds.
   2. rejected if the validation fails.

Validation happens before the payment is executed.

Successful Validation

A payment can proceed only when the beneficiary verification produces a successful match.

Example:

{
  "confirmationOfPayee": {
    "id": "7810092c-28cc-43d8-9adb-2b32e270199a",
    "validationOutcome": "ExactMatch",
    "externalPayeeName": "John Smith",
    "interpretedPayeeName": "John Smith"
  }
}

Failed Validation

If the beneficiary verification does not produce an exact match, the payment request is rejected with: 422 Unprocessable Entity.

Please take a look on next properties:

• errorMsgs
• confirmationOfPayee.validationOutcome

to determine the reason for rejection.

Example:

{
  "errorMsgs": [
    "Please double check the beneficiary’s details before proceeding with the transfer"
  ],
  "confirmationOfPayee": {
    "id": "7810092c-28cc-43d8-9adb-2b32e270199a",
    "validationOutcome": "NoMatch",
    "externalPayeeName": "Lance Henry",
    "interpretedPayeeName": null
  }
}

You still execute a payment by adding explicit confirmation via userAgreed = true:

{
    "payments": [
        {
            "to": {
                "provider": "bankwire",
                "identity": {
                    "beneficiaryType": "Individual",
                    "beneficiaryFirstName": "Lance",
                    "beneficiaryLastName": "Henry",
                    "beneficiaryCountryCode": "826",
                    "beneficiaryCity": "London",
                    "beneficiarySortCode": "302414",
                    "beneficiaryStateOrProvince": "Sussex",
                    "beneficiaryAddress": "Test address",
                    "beneficiaryAccount": {
                        "account": "33264517"
                    },
                    "purposeOfPayment": "Education expenses"
                },
                "currency": "GBP"
            },
            "from": {
                "provider": "ewallet",
                "identity": "{{SenderEWalletId}}",
                "amount": 50,
                "currency": "GBP"
            },
            "confirmationOfPayee": {
                "id": "b07e7b4c-56af-4a24-849c-7d15373b81f1",
                "userAgreed": true
            },
            "details": "Test Payment to Individual"
        }
    ]
}

Integration Recommendations

Recommended handling flow:

1. Submit payment request.
2. If HTTP 422 is returned:
   1. inspect errorMsgs;
   2. inspect confirmationOfPayee.validationOutcome;
3. Decide how the payment should be processed:
   1. Review beneficiary details and correct their details,
   2. Or set userAgreed = true and bypass CoP validation.
4. Resubmit the payment after correction.
5. Make sure that the payment has been accepted for processing, HTTP status response = 200.