Payee verification request object

Learn how to send and respond to payee verification requests with Mambu Payments (formerly Numeral)

Attribute

Description

object

Always payee_verification_request.

id

The ID of the payee verification request.

status

The status of the payee verification request. See

Payee verification request lifecycle

for more details.

failure_code

Failure code in case of failed request. One of:

  • business_error
  • technical_error
  • psp_technical_error
See

Failure codes and status details

for more details.

status_details

Status details in case of failed request. See

Failure codes and status details

for more details.

direction

The direction of the request. Can be outgoing or incoming.

scheme

The payee verification scheme used. Only vop is supported.

request

An object containing key information about the request.

payee_identification_type

The type of identification used in the request. See

Get supported identification types for a payee account

for more information.

payee_identification

The identification of the payee.

party_account_number

The account number of the payee.

additional_information

Additional information about the payee.

requesting_agent_bank_code

The BIC of the agent which sent the request.

responding_agent_bank_code

The BIC of the agent at which the request is aimed, i.e. the agent of the payee.

matching_result

The result of the verification. Can be match, close_match, no_match, or impossible_match. Note that close_match is only possible when payee_identification_type = name.

payee_suggested_name

In case of matching_result = close_match, name suggested as correct by the responding agent.

matching_details

Details of the request processing in case direction = incoming.

cleaned_identification

Payee identification after data cleaning (removing double spaces, honorific titles, etc.)

retrieved_identification

Payee identification retrieved in your account database (in Mambu Payments (formerly Numeral) or in your systems), using payee_account_number as a search key.

internal_account_id

If your account database is held in Mambu Payments (formerly Numeral) using internal accounts, the ID of the internal account matching payee_account_number.

matching_score

The score, from 0 to 100, of the matching algorithm configured for your entity when executed with cleaned_identification and retrieved_identification.

scheme_data

An object containing technical information about the request.

scheme_request_id

The unique ID of the request on the scheme. Different from id.

request_timestamp

The timestamp of the creation of the request.

response_timestamp

The timestamp of the answer to the request.

metadata

Additional data in JSON key:value format. See

Metadata

.

response_received_at

The UTC timestamp of the reception of the response to the request. Only available for outgoing requests.

created_at

The UTC timestamp of the creation of the VOP request.

{
  "object": "payee_verification_request",
  "id": "c39d1eff-c5ed-4197-8f24-28a68bd0eee6",
  "status": "completed",
	"failure_code": "null",
  "status_details": null,
  "direction": "incoming",
  "scheme": "vop",
  "request": {
    "payee_identification_type": "name",
    "payee_identification": "Jean Dupont",
    "payee_account_number": "FR5012739000308682265435N36",
    "payee_additional_information": "Mr. Jean Dupont",
    "requesting_agent_bank_code": "SOMEBICXXX",
    "responding_agent_bank_code": "BANKITPPXXX"
  },
  "matching_result": "match",
  "payee_suggested_name": null,
  "matching_details": {
    "cleaned_identification": "Jean Dupont",
    "retrieved_identification": "Jean Dupont",
    "internal_account_id": "e5cf0c31-c5fb-4e00-80fe-4338838d7493",
    "matching_score": 100
  },
  "scheme_data": {
    "scheme_request_id": "c3d79e5a-2058-4301-8b36-353cb9eb0ca5",
    "request_timestamp": "2025-01-26T13:51:10Z",
    "response_timestamp": "2025-01-26T13:51:15Z",
  },
  "metadata": {
		"payment_reference": "123-ABC"
  },
  "created_at": "2025-02-12T01:34:24Z"
}
{
  "object": "payee_verification_request",
  "id": "2af40267-67b1-4140-9e67-2f65ff11655e",
  "status": "completed",
  "status_details": null,
  "direction": "outgoing",
  "scheme": "vop",
  "request": {
    "payee_identification_type": "name",
    "payee_identification": "Jean Dupont",
    "payee_account_number": "FR5012739000308682265435N36",
    "payee_additional_information": "Mr. Jean Dupont",
    "requesting_agent_bank_code": "SOMEBICXXX",
    "responding_agent_bank_code": "BANKITPPXXX"
  },
  "matching_result": "match",
  "payee_suggested_name": null,
  "matching_details": null,
  "scheme_data": {
    "scheme_request_id": "76e64988-1d5e-4fd0-ad0a-142bb1f9b837",
    "request_timestamp": "2025-01-26T13:51:10Z",
    "response_timestamp": "2025-01-26T13:51:15Z",
  },
  "response_received_at": "2025-01-26T13:51:16Z",
  "created_at": "2025-01-01T12:00:00Z"
}