Adding a New Gateway

Audience: Backend developers Scope: Enum, adapter, registration, env config, tests, docs

Required Steps

1. Add gateway name to PAYMENT_GATEWAYS in packages/db/src/schema/payment.ts.
2. Create gateway adapter under apps/api/src/modules/payment/gateways/.
3. Register adapter in PaymentModule providers.
4. Register adapter in PaymentService constructor map.
5. Add env keys to apps/api/src/config/env.validation.ts and apps/api/sample.env.
6. Add gateway tests:
   • gateway adapter unit tests
   • payment service registration/flow tests
   • order integration tests for checkout/buy-now initiation payload expectations
7. Update payment fumadocs pages and payment/meta.json navigation.

Keep Existing Contracts Stable

When adding gateways, do not change these contracts:

• payment events: payment.completed, payment.failed
• order jobs: order.payment_success, order.payment_failed
• checkout/buy-now response shape: paymentId, initiationType, redirectUrl, gatewayPayload

Webhook-Capable Gateway Guidance

If the gateway provides signed webhooks (for example Stripe):

• add public webhook controller endpoint
• verify signature using raw request body
• process webhook idempotently in PaymentService
• retain redirect reconciliation endpoints for browser UX

Definition of Done

• Gateway is selectable in checkout/buy-now DTO validation.
• Gateway initiate flow returns valid redirect/form payload.
• Payment status finalization is idempotent.
• Existing legacy gateways continue to function.
• Payment and order test suites cover the new path.