Adding a New Gateway

Audience: Backend developers Scope: Registry, gateway implementation, env config, validation

Checklist

1. Add gateway name to PAYMENT_GATEWAYS in packages/db/src/schema/payment.ts.
2. Implement gateway adapter in apps/api/src/modules/payment/gateways/.
3. Register adapter in PaymentModule providers.
4. Register adapter in PaymentService constructor map.
5. Add env keys to validation + sample env.
6. Verify order checkout/buy-now initiation works with new gateway.

Minimal Adapter Template

@Injectable()
export class NewGateway implements PaymentGateway {
  readonly name = "new_gateway";

  async initiate(params: InitiatePaymentParams): Promise<InitiatePaymentResult> {
    return {
      gatewayTransactionId: `${params.referenceId}-${Date.now()}`,
      initiationType: "redirect",
      redirectUrl: "https://gateway.example.com/pay",
      gatewayPayload: {
        referenceId: String(params.referenceId),
        amount: String(params.amountNpr),
      },
    };
  }

  async verify(params: VerifyPaymentParams): Promise<VerifyPaymentResult> {
    return {
      success: true,
      amountNpr: 100,
    };
  }
}

Module Registration

• Add provider in payment.module.ts.
• Inject and this.gateways.set(adapter.name, adapter) in payment.service.ts.

Env & Validation

• Add required gateway env vars to apps/api/src/config/env.validation.ts.
• Add examples to apps/api/sample.env.

Verification

• API build passes.
• New gateway appears in user-facing allowed gateway list (excluding admin_grant).
• Initiation returns valid initiationType, redirectUrl, and gatewayPayload.
• Redirect callback verification updates payment status correctly.