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.
`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",
  "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",
  },
  "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"
}