Developer ResourcesPayment
Gateway Interface
Contract for payment gateway implementations used by the order payment flow.
Gateway Interface
Audience: Backend developers implementing or consuming gateway adapters Scope: Method contracts, payload shapes, verification expectations
Interface Contract
export type InitiationType = "form_post" | "redirect" | "sdk";
export interface PaymentGateway {
readonly name: string;
initiate(params: InitiatePaymentParams): Promise<InitiatePaymentResult>;
verify(params: VerifyPaymentParams): Promise<VerifyPaymentResult>;
}initiate()
Called after order payment intent is created.
export interface InitiatePaymentParams {
amountNpr: number;
referenceId: number | string;
referenceType: string; // current runtime: "order"
userId: string;
returnUrl: string;
}
export interface InitiatePaymentResult {
gatewayTransactionId: string;
initiationType: InitiationType;
redirectUrl: string;
gatewayPayload: Record<string, string>;
}Frontend behavior is driven only by initiationType, not by hardcoded gateway-specific branching.
verify()
Called from backend redirect handlers.
export interface VerifyPaymentParams {
gatewayTransactionId: string;
gatewayResponse: Record<string, unknown>;
}
export interface VerifyPaymentResult {
success: boolean;
amountNpr: number;
}Required verification posture:
- Validate callback signature/checksum when provided by gateway.
- Perform server-to-server status verification where available.
- Return trusted success/failure + amount for reconciliation.
Example Lifecycle (Order Payment)
Practical Notes
- Keep gateway payloads lean and gateway-native.
- Use deterministic transaction IDs for troubleshooting.
- Never expose secret keys to frontend clients.
- Keep gateway implementations stateless and constructor-configured via env-backed config.