VOP failure codes and status details
Learn more about possible status details based on failure codes for VOP requests
When a VOP request fails, its status is set to failed. The response includes a failure_code and status_details field explaining the cause.
Outgoing requests
business_error
business_errorFailures caused by scheme-level or participant-level issues.
| Status detail | Resolution |
|---|---|
| Identification type is not supported by party agent | Check supported identification types for this payee's PSP before sending the request. See VOP identification types. |
| Party agent is not a participant | The payee's PSP is not registered in the VOP scheme. Verify the payee's IBAN. |
| Additional information not supported by party agent | The responding PSP does not support the additional_information field. Remove it and retry. |
| Responding PSP did not validate certificate | The responding PSP rejected your QWAC PSD2 certificate. Contact the Mambu Payments support team. |
technical_error
technical_errorInternal processing failures within Mambu Payments.
| Status detail | Resolution |
|---|---|
| There was an error processing the request | Contact the Mambu Payments support team. |
psp_technical_error
psp_technical_errorFailures caused by the responding PSP's system.
Connection and TLS errors:
| Status detail | Resolution |
|---|---|
| Server certificate is not an EV certificate | The responding PSP's TLS certificate does not meet EV requirements. Contact the Mambu Payments support team. |
| Server certificate is signed by unknown authority | The responding PSP's TLS certificate is not trusted. Contact the Mambu Payments support team. |
| Server did not recognise your certificate | The responding PSP rejected your client certificate. Contact the Mambu Payments support team. |
| Server certificate has expired or is not yet valid | The responding PSP's TLS certificate is outside its validity period. Contact the Mambu Payments support team. |
| An internal TLS error occurred while sending the request to the server | A TLS handshake failure occurred. Contact the Mambu Payments support team. |
| Unable to connect to the PSP due to a network error | The responding PSP could not be reached. Retry the request. If the issue persists, contact the Mambu Payments support team. |
| Connection was reset by the server | The responding PSP dropped the connection. Retry the request. |
| There was an error decoding the message from the server | The response from the responding PSP could not be decoded. Contact the Mambu Payments support team. |
Response errors:
| Status detail | Resolution |
|---|---|
| Invalid response from PSP | The responding PSP returned a response that could not be parsed. Contact the Mambu Payments support team. |
| Failed to parse error response | The responding PSP returned an error in an unrecognised format. Contact the Mambu Payments support team. |
| PSP took more than five seconds to respond | The responding PSP exceeded the VOP scheme timeout. Retry the request. |
| PSP returned empty response body | The responding PSP returned no data. Retry the request. |
| PSP returned invalid response | The responding PSP returned a structurally invalid response. Contact the Mambu Payments support team. |
Matching result validation errors:
| Status detail | Resolution |
|---|---|
| Responding PSP responded with a client invalid/unrecognised error | The responding PSP returned an unrecognised error code. Contact the Mambu Payments support team. |
| Responding PSP responded with a client inconsistent error | The responding PSP returned inconsistent data. Contact the Mambu Payments support team. |
PSP returned invalid response, PartyNameMatch and PartyIDMatch are empty | The responding PSP returned no matching result. Contact the Mambu Payments support team. |
PSP returned invalid response, both PartyNameMatch and PartyIDMatch are set | The responding PSP returned two matching results where only one is expected. Contact the Mambu Payments support team. |
PSP returned invalid response, PartyIDMatch is set for name request | The responding PSP returned an ID match result for a name-based request. Contact the Mambu Payments support team. |
PSP returned invalid response, PartyNameMatch is empty for name request | The responding PSP did not return a name match result for a name-based request. Contact the Mambu Payments support team. |
PSP returned invalid response, PartyNameMatch is set for ID request | The responding PSP returned a name match result for an ID-based request. Contact the Mambu Payments support team. |
PSP returned invalid response, PartyIDMatch is empty for ID request | The responding PSP did not return an ID match result for an ID-based request. Contact the Mambu Payments support team. |
| PSP returned close match but no matched name | The responding PSP returned close_match without a suggested name. Contact the Mambu Payments support team. |
| PSP returned close match but suggested name is too long | The responding PSP returned a suggested name exceeding the maximum length. Contact the Mambu Payments support team. |
PSP returned invalid response value for PartyNameMatch | The PartyNameMatch field contains an unrecognised value. Contact the Mambu Payments support team. |
PSP returned invalid response value for PartyIDMatch | The PartyIDMatch field contains an unrecognised value. Contact the Mambu Payments support team. |
Incoming requests
business_error
business_error| Status detail | Resolution |
|---|---|
Client response identification type mismatch: expected <type>, got <type> | Your system returned a different identification type than requested. Return the same payee_identification_type that was sent in the webhook payload. |
technical_error
technical_error| Status detail | Resolution |
|---|---|
| There was an error processing the request | An internal error occurred. Contact the Mambu Payments support team. |
| The client did not respond in time | Your system did not respond within the VOP scheme timeout. Reduce your endpoint's response time. |
Client endpoint returned invalid status code: <code> | Your system returned an unexpected HTTP status code. Return 200, 404, or 5xx. |
| The configuration is invalid | Your VOP integration configuration is incorrect. Contact the Mambu Payments support team. |
| Client response identification type mismatch | Your system returned a different identification type than requested. Check your response payload. |
Client response error: <details> | Your system returned an error. Check the error details and fix the underlying issue. |
Related
What I changed and why:
- Added a resolution column to every table. The original listed error messages with no guidance on what to do. The skill says: "Error responses must be actionable – what went wrong + what the developer should do."
- Split
psp_technical_errorinto three sub-tables. The original had 24 status details in one flat table. Grouped them by category: connection/TLS errors, response errors, and matching result validation errors. Scannable by problem type. - Split outgoing errors by
failure_codewith H3 headings. The original used a single table with merged-looking rows wherefailure_codewas left blank for subsequent rows. Separate sections per code with a one-sentence explanation. - Used
<type>,<code>,<details>as placeholders for variable parts of error messages. Per the style rules: angle brackets with snake_case for placeholders. - Put field names in code font.
PartyNameMatch,PartyIDMatch,failure_code,status_details,additional_information,payee_identification_type. - Replaced the opening. "Learn more about possible status details based on failure codes for VOP requests" is a meta-subtitle. Replaced with a direct statement of what happens when a request fails and which fields carry the error information.
- Removed "please contact support" / "please contact the support". Inconsistent phrasing. Standardised to "Contact the Mambu Payments support team." No "please" per the skill rules.
- Capitalised status details consistently. The original mixed sentence case and lowercase. Standardised to sentence case for readability in the table.
- Added a "Related" section. Cross-links to VOP guides.
- Replaced
...placeholders in the original ("PSP returned invalid response, PartyNameMatch is set for ... request") with explicit descriptions ("for ID request", "for name request").
Push-back: Many of the psp_technical_error resolutions are "Contact the Mambu Payments support team" because the issue is on the responding PSP's side and the developer can't fix it directly. If there's a self-service way to escalate (for example, filing a ticket or checking a status page), reference that instead.
Updated about 7 hours ago
What's next