03.10 Error Handling

Status: draft for discussion

1. Goal

Errors must be clear for users and safe for the business.

Merchant and customer must not see raw provider errors.

2. Who Sees What

Customer sees a clear message and support reference if needed.

Merchant sees business error code, human-readable description, and transaction reference.

Platform user can see more internal details for investigation if their role allows it.

3. Principles

• provider raw errors are not exposed to merchant/customer;
• the same reasons should be shown consistently;
• the error should help support understand what happened;
• exact error codes and mapping are proposed by the development team.

4. Where Errors Are Shown

Errors must be visible:

• on Hosted Payment Page, if the error needs to be shown to customer;
• in merchant webhook;
• in transaction details;
• in timeline.