Verification of Payee

A prerequisite for VoP is that you have integrated with the NelloPay flow. To implement this integration, please refer to our payment documentation.

How it works

The validation process begins when a checkout request is created. The API response returned to the merchant includes the payee verification status along with the checkout request fields. There are four possible API responses:

Verified payee details matched
Close match of payee details
Mismatch of payee details
Transaction blocked

Responses two and three are only available if you have an agreement that includes a grace period of 30 days for mismatches and 90 days for close matches.

Verified payee details matched

A successful checkout response is returned when payee details are verified.

Response 200

{
  "redirectUrl": "https://checkout.neonomics.io/api/v1/checkoutrequests/JkuOIJ/app",
  "id": "0a15025d-824a-19c6-8182-7d5ab472002f",
	"payeeVerification": {
        "status": "VALID"
    }
}

Close match of payee details

A successful checkout response is returned with the payeeVerification object indicating a close match status.

Response 200

{
  "redirectUrl": "https://checkout.neonomics.io/api/v1/checkoutrequests/JkuOIJ/app",
  "id": "0a15025d-824a-19c6-8182-7d5ab472002f",
	"payeeVerification": {
        "status": "INVALID",
        "reasons": [
            {
                "code": "CREDITOR_NAME_NEAR_MATCH",
                "message": "Creditor account is valid for receiving funds, name nearly matches the creditor name."
            }
        ]
    }
}

Mismatch of payee details

A successful checkout response is returned with the payeeVerification object showing an INVALID status and a reason with the code CREDITOR_NAME_MISMATCH.

Response 200

{
  "redirectUrl": "https://checkout.neonomics.io/api/v1/checkoutrequests/JkuOIJ/app",
  "id": "0a15025d-824a-19c6-8182-7d5ab472002f",
	"payeeVerification": {
        "status": "INVALID",
        "reasons": [
            {
                "code": "CREDITOR_NAME_MISMATCH",
                "message": "Creditor account is not valid for receiving funds with given creditor name."
            }
        ]
    }
}

Transaction blocked

An unsuccessful checkout request response is returned when the transaction cannot proceed.

Response 400

{
    "id": "fe878207-5082-4589-893c-90b5d7215efa",
    "timestamp": "2025-11-17T12:24:56.609+00:00",
    "status": 400,
    "type": "VALIDATION",
    "message": "Payee verification failed with the following reasons: Creditor account is not valid for receiving funds with given creditor name."
}

How to handle each status

Status	Code	Action
`VALID`	-	🟩 No action needed. Proceed as normal—the payee details are correct.
`INVALID`	`CREDITOR_NAME_NEAR_MATCH`	🟧 Action needed. The creditor's details are nearly correct but must be updated within 90 days.
`INVALID`	`CREDITOR_NAME_MISMATCH`	🟥 Urgent action required. The creditor details do not match and must be corrected within 30 days.

By implementing Verification of Payee correctly, you can significantly reduce payment fraud and ensure your customers' transactions reach their intended recipients securely. 🏦