Sending verification of payee checks

To send a name check request, please connect to the Verify Payee API

API fields required

To submit a verification of payee check, a name and IBAN must be provided. You must include one of the paymentAccountID or customerID identifiers - depending on how you're using the service:

API field	status	Description
name	required	The payee account name. This should include both first name(s) and last name(s) and they should be separated by a space. You should not include titles or honorifics. Up to 140 characters and can include diacritics as appropriate.
iban	required	The payee's IBAN number, used to identify individual accounts. Made up of up to 34 letters and numbers.
paymentAccountId	optional	The Modulr payment account id where your SEPA payment will be initiated from.
customerId	optional	The Modulr customer ID you are assigned to.

⚠️

Important - paymentAccountID or customerID

• Only include one of the two, submitting more than one will cause the request to fail.

paymentAccountId
Use this if the request is linked to a payment from a Modulr account. This is the most typical usage.

customerId
Use this if you're using the service independently of a payment (using Modulr as a technical VoP provider). Note: you must have a contractual agreement with Modulr for this service; an error will be returned if not in place.

Testing your integration within the sandbox environment

The sandbox environment is loaded with specific data that allows you to test the four scenarios as listed below by providing the respective inputs for different outcomes.

• Match
• No match
• Close match
• Check not possible

Note❗️: The example request below a fictitious account ID. Replace this with your account ID(s) in the sandbox.

• You must use the example name and IBAN in the sample requests as follows, checks against any other names or IBAN than the ones listed will return a service error.

Match request

{
  "name": "Isabelle Marie",
  "iban": "FR9317569000707197247234A34",
  "paymentAccountId": "A123AAA4"
}

Match response

{
  "id":"VOP0000001",
  "result": { 
    "code": "MATCH"
    }
}

No match request

{
  "name": "Jhon Nowak",
  "iban": "FR9317569000707197247234A34",
  "paymentAccountId": "A123AAA4"
}

No match response

{
  "id":"VOP0000001",
  "result": { 
    "code": "NO_MATCH"
    }
}

Close match request

{
  "name": "Isabelle Marie",
  "iban": "FR9317569000707197247234A34",
  "paymentAccountId": "A123AAA4"
}

Close match response

{
  "id":"VOP0000001",
  "result": { 
    "code": "CLOSE_MATCH",
    "matchedName": "Isabelle Marie Dubois"
    }
}

Check not possible request

{
  "name": "TinTin",
  "iban": "NL19INGB2128949858",
	"paymentAccountId": "A123AAA4"
}

Check not possible response

{
  "id":"VOP0000001",
  "result": { 
    "code": "CHECK_NOT_POSSIBLE"
    }
}

Interpreting name check responses

There are four outcomes of a successful request:

MATCH

The account details (name and IBAN) provided matched the information held by the payee bank. You can proceed with making your payment if you would like this in scenario.

NO MATCH

The account details (name or IBAN) do not match the account details of the payee bank. Proceeding with the payment could lead to the funds being sent to the wrong account and you may not be able to recover the money. You are advised to double check the details of the payment.

If there are updated account details, a new check will be run again.

CLOSE MATCH

The provided payee name closely resemble the payee holder name. In this scenario, we will also return the name held at the payer bank. In this case, you should still double check the details of the payment before proceeding. Proceeding with the payment could lead to the funds being sent to the wrong account and you may not be able to recover the money.

CHECK NOT POSSIBLE

Payee verification check is not possible or applicable at this time. You may choose to retry later or double check the details of payment before proceeding. Proceeding with the payment could lead to the funds being sent to the wrong account and you may not be able to recover the money.

Result codes

The table list the possible results of a verification check and the action we recommend you take in each scenario:

code	HTTP status code	Description	Recommended action
MATCH	200	The details provided matched the payee bank details.	You can proceed with the payment. Remember, you should still exercise caution when sending payments. The service is an account name checking service and does not protect against all types of fraud.
NO_MATCH	200	The account details provided do not match the payee bank details.	The account details should be checked carefully, you are advised not to proceed with the payment. Authorising the payment could result in transferring the funds to a payment account not held by your intended recipient. You should edit the details if possible, and submit another account verification check request before proceeding.
CLOSE_MATCH	200	The name provided is similar to the payee account name. The actual name is provided in matchedName.	The account details should be checked carefully. If you decide to continue with the payment you should update the details before proceeding.
CHECK_NOT_POSSIBLE	200	The verification check is not possible.	You should check the account details carefully and proceed only if you are satisfied that they are correct.
INVALID	400	The request was malformed, missing or non-compliant JSON body or URL parameters.	You should check the account details carefully and proceed only if you are satisfied that they are correct.
GENERAL	500	There is a technical error when trying to process the request.	You should check the account details carefully and proceed only if you are satisfied that they are correct.

Recording of VoP check being made against payment

It’s important to record that a VoP check was completed for each payment, as this may be needed if the requestor raises a challenge in future. Each VoP check generates a unique ID, which Modulr can use to retrieve the check details, including the outcome. It is highly recommended you store this within your platform, and mandated for Partners identified as required to implement VoP as part of IPR compliance.

The Payments endpoint will also be updated with an optional field that can accept the unique ID of a VoP (or CoP) check shortly; this page will be updated when available. This field when populated is used to allow straightforward linking of a particular VoP check to a payment - as this involves a change to your payment logic in addition, it is recommended (but not mandated) to use.