Dodo Payments integration

Connect Dodo Payments to see which acquisition sources and onboarding paths lead to paying customers, subscription renewals, refunds, and churn.

Connect Dodo Payments

Create an API key in the Dodo Payments dashboard under Developer → API Keys.
Open your OnRamp project's Integrations → Revenue page and select Dodo Payments.
Paste your API key and select Live mode or Test mode to match the key's environment. Keep test payments in a separate OnRamp project.
Choose how to match customers, then select Validate and connect.
In Dodo Payments, open Developer → Webhooks and add the endpoint URL shown in OnRamp. Keep the integration_id query parameter.
Select the events listed in OnRamp: payment.succeeded, refund.succeeded, and the subscription lifecycle events. These refresh subscription MRR after activations, renewals, plan changes, holds, pauses, and cancellations.
Copy Dodo Payments' webhook signing secret into OnRamp and save it.
Run Sync now to import historical payments and refunds. Scheduled syncs reconcile history every six hours.

OnRamp verifies webhook signatures against the raw request body using Dodo Payments' Standard Webhooks headers. Use the signing secret issued by Dodo Payments for this endpoint, including its whsec_ prefix when present.

Match revenue to users

Email matching is the default. Identify signed-in users with the email used for their Dodo Payments customer:

javascript

onramp.identify({ email: user.email });

You can also add onramp_anonymous_id to Dodo Payments payment or subscription metadata. OnRamp uses that value directly to attach payments to the matching journey. For other customer IDs, see identity resolution.

What OnRamp records

Successful payments, including subscription starts and renewals
Successful refunds, including partial refunds
Subscription cancellation and expiration events received through webhooks
Payment currency, amount, product, customer reference, and event time
Current subscription MRR, normalized by billing interval and grouped by currency

Revenue comes from successful payment records. Subscription activation and renewal webhooks refresh current MRR without adding a second copy of the payment. Manual sync, scheduled sync, and webhook retries use the same payment and refund identifiers.

Current MRR uses active subscriptions' recurring amounts before tax. Trials, on-demand subscriptions, paused or ended subscriptions, and subscriptions scheduled to cancel are excluded. Usage charges are recorded as payment revenue and are excluded from recurring MRR. History reconciliation imports payments and refunds; past cancellations require webhook delivery.

Test the connection

Use the Dodo Payments webhook endpoint's Testing tab to send a signed example. Unsigned mock events cannot pass signature verification. Check the delivery result, then run a manual sync in OnRamp.

Connect through the CLI or API

Use provider dodo with api_key, environment (live_mode or test_mode), and optionally webhook_secret in the credentials object:

bash

onramp integrations connect --provider dodo --credentials @dodo-credentials.json --identity-strategy email

json

{
  "api_key": "your-dodo-api-key",
  "environment": "live_mode",
  "webhook_secret": "your-dodo-webhook-signing-secret"
}

Omitting environment selects live mode. Keep credential files private.

Troubleshooting

The API key is rejected. Confirm that the selected environment matches the key and that it can read payments, refunds, and subscriptions.

A payment has no matching journey. Check the customer email, your identity strategy, or the onramp_anonymous_id metadata. Unmatched payments can be attached on a later sync after the identity becomes available.

Webhook verification fails. Check the endpoint's signing secret and URL. Webhook deliveries must include webhook-id, webhook-timestamp, and webhook-signature; timestamps must be within five minutes of the server clock.

See Dodo Payments' API documentation and webhook setup guide for provider configuration.