Developer ResourcesPayment
Browser Return Flow
Unified browser return flow for order payments with backend-owned verification and shared payment result handling.
Browser Return Flow
Audience: Frontend + backend developers, QA Scope: Redirect callbacks, result-page contract, order flow behavior
Why This Exists
A single browser return flow reduces gateway-specific frontend logic.
Unified path:
Frontend order page
-> Backend payment initiation
-> Gateway checkout
-> Backend success/failure redirect endpoint
-> Shared payment result page
-> Final order destinationEnd-to-End Sequence
Shared Result Page Contract
Redirect target:
PAYMENT_RESULT_PAGE_URLwhen configured- fallback:
${API_PUBLIC_BASE_URL}/api/payments/result
Query parameters:
| Param | Meaning | Example |
|---|---|---|
payment_status | Final verified status | completed |
payment_id | Internal payment row id | 57 |
reference_type | Domain reference type | order |
reference_id | Paid entity id | 128 |
order_id | Convenience field for order flow | 128 |
next | Final frontend destination | https://app.example.com/orders/128 |
Frontend Responsibilities
- Initiate payment.
- Submit gateway payload according to
initiationType. - Render a shared result page (
/payments/result) from backend query params. - Redirect user to
next.
Frontend should not call a public verify endpoint.
QA Checklist
- Success callback updates payment to completed and queues
order.payment_success. - Failure callback updates payment to failed and queues
order.payment_failed. - Callback refresh remains idempotent.
- Result page receives expected query contract.
nextredirect lands on the intended order route.