Dodo Payment Provider

Add dodoPaymentProvider() to PaymentService.providers and configure the Dodo API key, product ID, and webhook key.

await city.payment.method("dodo").invoke({ topup_amount_minor: 500, idempotency_key: "order_123" });

Before creating checkout, the Provider fetches the configured product and requires a one-time pay_what_you_want price in the order currency, with no discount or purchasing power parity (PPP), and tax_inclusive: true. The product minimum price must not exceed the order amount. An incompatible product is rejected before checkout creation.

Confirmation reads total_amount and currency from the signed payment event and requires an external transaction ID. The amount and currency must match the local order. This implementation strictly requires tax-inclusive Dodo pricing; it does not automatically support arbitrary tax, discount, or currency-conversion schemes. Missing, invalid, or mismatched confirmation facts produce a 422 validation failure and move the inbox event to review without issuing Credits.

PaymentService stores orders and events; Credits receives confirmed credits only from on_paid.

Webhooks

Set the webhook URL in the Dodo Dashboard to /v1/payment/webhook?provider=dodo and subscribe to at least these payment lifecycle events:

  • payment.processing
  • payment.succeeded
  • payment.failed
  • payment.cancelled

Dodo follows Standard Webhooks. The provider uses the official SDK and the exact raw request body to verify webhook-id, webhook-timestamp, and webhook-signature, and uses the unique webhook-id strictly for idempotency. Requests with a missing protocol header or an invalid signature are rejected.

One payment can emit several lifecycle events and retries may arrive out of order. Verified events are persisted in the inbox and enqueued; HTTP 200 acknowledges receipt, not fulfillment. payment.succeeded is a payment confirmation signal; fulfillment must validate trusted payment facts against the order, not request metadata. Paid status and wallet fulfillment are independent, and on_paid(record, fulfillment) must be idempotent using payment_id. See Payment crediting for amount-validation requirements, recovery scans, diagnostics, and administrator replay.