Browser Return Flow

Audience: Frontend + backend developers Scope: Browser redirect UX, webhook-first truth, no frontend verify calls

Contract

Frontend should do exactly two payment actions:

1. Initiate payment (checkout or buy-now).
2. Redirect user to gateway based on initiation payload.

Frontend should not call manual verify endpoints.

End-to-End Sequence

Result Page Query Contract

Redirect target:

• PAYMENT_RESULT_PAGE_URL when configured
• fallback: ${API_PUBLIC_BASE_URL}/api/payments/result

Query params:

• payment_status
• payment_id
• reference_type
• reference_id
• order_id
• next

Gateway Differences, Same Frontend Pattern

• Stripe usually uses initiationType: "redirect" and sessionId payload.
• Other gateways may return form_post payload fields.
• Frontend remains gateway-agnostic by honoring initiationType only.

QA Checklist

• Stripe webhook marks payment completed/failed.
• Redirect callbacks stay idempotent for already-terminal payment rows.
• payment.completed and payment.failed events still trigger order worker flows.
• Shared payment result page receives expected query params.