Stripe Payment Provider
Create Payment orders with Stripe Checkout and issue Credits after a paid webhook.
const payment = new PaymentService({
providers: [stripePaymentProvider()],
resolve_topup: ({ topup_amount_minor }) => ({ credits: topup_amount_minor * 10_000 }),
on_paid: async (record, fulfillment) => {
if (fulfillment.entitlement.kind !== "topup") {
throw new Error("This integration supports topups only");
}
await credits.topup({
card: { kind: "primary", user_id: record.user_id },
credits: record.credits,
source: "payment",
ref: record.payment_id,
idempotency_key: `payment:${record.payment_id}`,
});
},
});Configure both STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET. Without webhook verification configuration the Provider is disabled and webhook requests are rejected. Send webhooks to /v1/payment/webhook?provider=stripe.
The example handles free-amount topups only. Paid status and wallet fulfillment are independent; on_paid(record, fulfillment) uses the order's entitlement snapshot. Verified events are persisted and enqueued before acknowledgment. For signed Checkout events, the credited principal is amount_subtotal - total_details.amount_discount. All amount components must be nonnegative safe integers, and amount_total must equal principal plus amount_tax and amount_shipping; separate tax and shipping never buy Credits. Currency and principal must match the local order, and an external transaction ID is required. Missing components, mismatches, or tax-inclusive/mixed pricing that cannot satisfy this projection cause a 422 failure and move the event to review. PaymentIntent events without the required principal breakdown cannot independently authorize fulfillment. Request metadata is not proof of payment, and no automatic currency conversion is performed. See Payment crediting for recovery, diagnostics, and administrator replay.
await city.payment.method("stripe").invoke({
topup_amount_minor: 500,
idempotency_key: "order_123",
});