Native payment provider integration for usage-based billing.

Why We Want to Integrate with Lago?

Dodo Payments serves global markets with Merchant of Record capabilities. This integration would:

• Complement Lago's existing providers (Stripe, Adyen, GoCardless) with coverage in underserved regions.

• Follow the partnership model established with MoneyHash for regional payment processors.

This aligns with Lago's stated goal of supporting local payment processors alongside global providers.

Summary:

This issue tracks building a first-class integration between Lago (usage-based billing) and Dodo Payments to support automatic invoice charging, realtime webhook sync, and refunds. The integration should be usable either as a native Ruby (Rails) plugin for Lago or as a lightweight TypeScript/Bun microservice.

Goals:

• Create payment intents in Dodo when Lago emits .

• Update Lago invoice/payment state on Dodo webhook events (, , ).

• Support refund flows by creating Lago credit notes when Dodo reports refunds.

• Provide secure, idempotent webhook handling with HMAC verification.

• Provide clear setup docs and example code for both native and microservice approaches.

Acceptance Criteria

• When an invoice is created in Lago, a Dodo payment intent is created with in metadata.

• marks the Lago invoice as .

• marks the Lago invoice as and triggers retry logic per config.

• creates a Lago credit note and links to the original invoice.

• All webhooks validated via HMAC; log & retry on transient failures.

• Integration can be deployed as a Docker container and run with env vars only.

• README and docs include setup, testing, and troubleshooting steps.

Requirements

Auth / Headers:

Webhook mapping:

Source: Lago

• Event: invoice.created

• Action: Create a Dodo payment intent (with metadata lago_invoice_id)

Source: Dodo

• Event: payment.succeeded

• Action: Mark the Lago invoice as paid

Source: Dodo

• Event: payment.failed

• Action: Mark the Lago invoice as failed and trigger retry logic

Source: Dodo

• Event: payment.refunded

• Action: Create a Lago credit note and link it to the invoice

Webhook endpoints:

• Dodo → Integration:

• Lago → Integration:

Retry & Idempotency:

• Persist ↔ mapping to prevent double-processing.

• Use Dodo idempotency keys for create payment intent requests (e.g., ).

• Webhook handler should:

• Verify HMAC signature.

• Check if event has been processed (by event id).

• Acknowledge 2xx on success; return 5xx for transient errors to allow retries.

Security:

• Validate webhooks using Dodo's HMAC signature and configured secret.

• Store API keys in env variables / secrets manager (never commit).

• Minimum permissions for API keys: only required scopes for payments and webhooks.

Implementation tasks (checklist):

• Design DB schema for mapping and event dedupe (microservice).

• Implement handler → create Dodo payment intent.

• Implement Dodo webhook handler with HMAC verification.

• Implement Lago API updates for payment status and credit notes.

• Add retry/exponential backoff for transient failures.

• Add configuration entries to Lago admin UI (API key, mode, webhook secret).

• Write unit & integration tests (bun test / rspec).

• Create Dockerfile & Helm chart (optional) for deployment.

• Write README / install & troubleshooting docs.

Testing:

• Run local service and expose with (or use sandbox webhook tools).

• Test flow:

1. Create a test invoice in Lago (sandbox).

2. Verify integration creates a Dodo payment intent (checkout URL).

3. Complete the sandbox payment; check Dodo emits .

4. Verify Lago invoice updates to .

• Commands:

bun test

npx localtunnel --port 3000