dodo-best-practices

Dodo Payments Integration Guide

This skill covers the foundational concepts and setup for Dodo Payments. Use it when starting a new integration, setting up the SDK, or understanding the core payment flow.

When to use this skill

• You're building a new payment integration and need to understand Dodo's architecture
• You need to install and initialize the SDK in your language
• You want to understand the canonical payment flow and webhook verification
• You're choosing between framework adapters or payment methods
• You need to know what Dodo handles versus what you must build

---

What is Dodo Payments

Dodo Payments is a Merchant of Record (MoR). That means Dodo is the legal seller on every transaction, handles sales tax registration and calculation across all jurisdictions, remits taxes to authorities, and manages card-network disputes and chargebacks. As a developer, you don't build a sales-tax engine or dispute-handling system. You create checkout sessions, listen to webhooks, and grant access when payment succeeds.

---

Environment Setup

Base URLs

Only two real base URLs exist:

• Live: https://live.dodopayments.com
• Test: https://test.dodopayments.com

Never use api.dodopayments.com — it has no DNS record and cannot be reached.

API Keys

Keys have two formats:

• Test: dodo_test_...
• Live: dodo_live_...

Environment Variables

DODO_PAYMENTS_API_KEY       # Bearer token for API requests
DODO_PAYMENTS_WEBHOOK_KEY   # Secret for webhook signature verification

Default Environment

The environment parameter defaults to live_mode if omitted. Always pass test_mode explicitly during development.

---

SDK Installation & Initialization

TypeScript/Node.js

npm install dodopayments

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});