Stripe Gateway

Summary

• Gateway name: stripe
• Initiation type: redirect
• Finalization source of truth: Stripe webhook events
• Redirect endpoints: retained for browser UX/idempotent reconciliation

Endpoints

• Initiation: existing order checkout/buy-now endpoints
• Webhook: POST /api/payments/stripe/webhook (@Public())
• Browser callbacks:
  • GET|POST /api/payments/redirect/:paymentId/success
  • GET|POST /api/payments/redirect/:paymentId/failure

Environment

Required for Stripe runtime:

• STRIPE_SECRET_KEY
• STRIPE_WEBHOOK_SECRET

Initiation Payload Example

{
  "gateway": "stripe",
  "returnUrl": "https://example.com/payment/return"
}

Initiation Response Example

{
  "orderId": 101,
  "status": "payment_pending",
  "paymentId": 9001,
  "gatewayTransactionId": "cs_test_a1b2c3d4",
  "initiationType": "redirect",
  "redirectUrl": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4",
  "gatewayPayload": {
    "sessionId": "cs_test_a1b2c3d4"
  }
}

Webhook Event Mapping

• checkout.session.completed -> mark completed + emit payment.completed
• checkout.session.async_payment_succeeded -> mark completed + emit payment.completed
• checkout.session.expired -> mark failed + emit payment.failed
• checkout.session.async_payment_failed -> mark failed + emit payment.failed

Idempotency rule:

• If payment status is already terminal (completed or failed), webhook replay exits without changing state.

Frontend Behavior

Frontend should:

1. Call checkout/buy-now once.
2. Redirect user to Stripe checkout URL.

Frontend should not call manual verification endpoints.

Backward Compatibility

Legacy gateways remain available:

• esewa
• fonepay
• connect_ips

Stripe is preferred in docs/examples but does not remove existing gateways.