// api/src/modules/c1_billing/providers/provider.types.ts
export interface IPaymentAdapter {
provider: PAYMENT_PROVIDER;
capabilities: {
clock: 'provider' | 'c1'; // who triggers renewals
partialRefunds: boolean;
saveCardWithoutCharge: boolean;
};
ensureCustomer(ctx, customer): Promise<string>;
syncPrice(ctx, price): Promise<string>;
startCheckout(ctx, input): Promise<ICheckoutAction>;
startCardSetup(ctx, input): Promise<ICheckoutAction>;
cancelSubscription(ctx, input): Promise<void>;
refund(ctx, input): Promise<IProviderRefund>;
// clock 'c1' only
chargeMandate?(ctx, input): Promise<IProviderPayment>;
notifyPreDebit?(ctx, input): Promise<void>;
// inbound
verifyWebhook(ctx, raw: Buffer, headers): IProviderEvent; // throws
toCanonical(event): ICanonicalEvent[];
fetchSubscription(ctx, externalId): Promise<IProviderSubscription>;
declineCode(providerCode: string): DECLINE_CODE;
}
// providers/index.ts: the only place a provider is registered
export const PAYMENT_ADAPTERS: Record<PAYMENT_PROVIDER, IPaymentAdapter> = {
stripe, razorpay, revolut, payu
};
| Provider | Clock | Recurring via |
|---|
| Stripe | Provider | Billing subscriptions; India cards through Stripe's e-mandate support |
| Razorpay | Provider | Plans and Subscriptions; retries, then halted |
| Revolut | Provider | Merchant API plans with cycle phases; setup order on the hosted page |
| PayU | C1 | Standing instructions and e-mandates; C1 sends each debit and the pre-debit notice |
Canonical events: checkout.completed · payment.succeeded · payment.failed · payment.requires_action · subscription.updated · subscription.canceled · refund.succeeded · refund.failed · dispute.opened · dispute.closed · payment_method.updated
PayU and Revolut field-level details get confirmed in the Phase 0 spike.
Module Layout
shared/modules/c1_billing/ c1_billing.schemas.ts Zod triads and enums for all 12 tables
c1_billing.utils.ts pure: status transitions, decline mapping, refund caps
c1_*.entity.ts query-engine entities (orders, subscriptions, transactions…)
c1_billing.queries.ts admin lists
c1_billing.settings.ts grace_days, retry_days
api/src/modules/c1_billing/ c1_billing.routes.ts · c1_billing.controllers.ts · c1_billing.service.ts
c1_*.model.ts Objection models, @Auditable
c1_billing_webhook.routes.ts · c1_billing.jobs.ts
providers/{stripe,razorpay,revolut,payu}/adapter.ts · providers/index.ts
api/db/migrations/ <ts>_create_c1_billing_tables.js