Errors and uncertain outcomes
Classify failures before deciding whether to correct, investigate or retry.
Two layers of outcome
Handle HTTP transport/status and the payment response as separate inputs. Store enough redacted context to investigate an attempt without capturing credentials or payment details.
Response handling matrix
The following combines documented status meanings with recommended application actions. Observation Recommended action HTTP 400 with validation detail Correct the request; do not automatically repeat the same invalid body. HTTP 401 Check environment, credential and access configuration. HTTP success with payment response Inspect the payment result; do not equate the transport success with settled funds. Timeout or disconnected response Keep the attempt unresolved until you investigate gateway state. Unexpected or unparsable response Preserve a redacted diagnostic reference and escalate; do not guess success.
Validation error shape
A documented validation failure can contain type, error_code, message, ref_id and details. Field-level details use fieldName and message. Use stable identifiers for program logic; keep explanatory text useful for support. HTTP 400 type: validationError error_code: E_INVALID_SUBMISSION details[].fieldName: amount
Duplicate protection
Payment endpoints document dup_seconds for supported processors. This is not proof of a general Idempotency-Key contract. Recommended application controls are to record attempts before submission, serialize competing operations and investigate unknown results before creating another payment.
Recovery test plan
Simulate a browser double click, two concurrent fulfillment jobs, a dropped response and a gateway validation failure. Your pass condition is a recoverable order record with no unintentional duplicate financial action. These are proposed application tests, not a gateway behavior guarantee.