The Complete Production SOP: How to Deploy and Run Dodo Payments Global Merchant & Tax in Autonomous AI Agents
Step-by-step SOP to install and run Dodo Payments in Codex, Claude Code, and Cursor. Automate multi-currency checkout, MoR tax, and webhook security.
Technical Overview & Architectural Context
Autonomous coding agents frequently fail when implementing global Merchant of Record (MoR) billing workflows. Without deterministic guardrails, LLMs routinely confuse standard payment gateways (like direct Stripe integrations) with Merchant of Record lifecycles handled by Dodo Payments. Agents often make critical errors such as manually attempting to calculate regional tax rates (VAT/GST) instead of letting Dodo Payments handle tax compliance, inventing non-existent SDK methods, or exposing raw webhook payloads to JSON parsers before cryptographically verifying incoming signatures. Furthermore, agents frequently mismanage multi-currency edge cases—such as mixing localized ISO currency codes with unit-based pricing—and fail to persist the essential customer tax identifier attributes required for cross-border B2B invoicing. The Dodo Payments Global Merchant & Tax skill enforces strict procedural boundaries, instructing Codex, Claude Code, Cursor, and Windsurf to strictly consume official SDK patterns from the `dodopayments` package, execute mandatory raw-body cryptographic webhook verification, and isolate API credentials safely within environment variables. By leveraging this SKILL.md specification, your autonomous agent bypasses speculative hallucination and executes verified, test-driven implementations: creating checkout sessions, attaching recurring subscription meters, and processing idempotent webhook dispatching without ever risking compliance violations or financial leakage.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Create the local skill manifest directory and inject verified procedural rules into your agent runtime.
To empower agents like Claude Code, Codex, Cursor, or Windsurf to natively discover Dodo Payments implementation rules, mount the SKILL.md file into the workspace root under `.agents/skills/dodo-payments` or runtime-specific system paths (`.cursor/rules` or `.claude/skills`). Agent runtimes scan these paths during context ingestion, reading frontmatter metadata and strict SOP instructions before parsing task prompts.
mkdir -p .agents/skills/dodo-payments && curl -fsSL https://askills.dev/api/skills/dodo-payments/raw -o .agents/skills/dodo-payments/SKILL.md---
name: "dodo-payments"
description: "Integrate Dodo Payments multi-currency checkout, global sales tax compliance, and webhooks."
category: "fullstack"
triggers:
- "dodo payments"
- "create checkout session"
- "dodo webhook"
- "dodopayments sdk"
---
# Dodo Payments Global Merchant & Tax Rules
1. Always initialize SDK with `new DodoPayments({ bearerToken: process.env.DODO_PAYMENTS_API_KEY })`.
2. Never calculate tax manually; Dodo Payments is the Merchant of Record handling global tax remittance automatically.
3. Webhook endpoints MUST preserve raw request bodies for signature verification via `dodopayments.webhooks.constructEvent()`.
4. Ensure idempotency keys are passed on mutable mutation calls.Keep the SKILL.md file under 500 tokens. Concise operational directives prevent agent context degradation during long refactoring chains.
Ensure that the agent sandbox has file-read permissions for `.agents/skills` or `.cursor/rules`. In restricted containers, hidden dot-directories may be ignored unless explicitly declared in settings.
Environment Secrets & Dependency Validation
Inject required environment variables safely and install official SDK dependencies without exposing secrets to LLM logs.
Dodo Payments requires a bearer authentication key and a webhook signing secret. You must configure these within `.env.local` or environment vaults. Instruct your agent to install the official `dodopayments` package and verify environment variable presence without echoing key values to standard output.
npm install dodopayments && test -f .env.local || touch .env.local && echo 'DODO_PAYMENTS_API_KEY=test_api_key_xxxxxxxx\nDODO_PAYMENTS_WEBHOOK_KEY=whsec_xxxxxxxx' >> .env.localDirect the agent to reference `process.env.DODO_PAYMENTS_API_KEY` exclusively. Never hardcode fallback strings or mock keys directly inside production files.
Verify that `.env` and `.env.local` are tracked in `.gitignore`. If an agent stages an untracked `.env` file, git history can leak private test keys to upstream remotes.
Intent Matching & Trigger Invocation
Prompt the agent using deterministic triggers that execute standard Dodo Payments session creation.
Trigger the installed skill using targeted commands such as 'create checkout session with Dodo Payments' or 'implement Dodo Payments webhook handler'. The agent reads the frontmatter triggers, loads the SDK SOP, and constructs deterministic route handlers conforming to modern Next.js App Router, Express, or Fastify patterns.
Reference the exact product billing model (e.g., 'usage-based', 'recurring subscription', or 'one-time checkout') in your prompt so the agent selects the exact Dodo Payments payload shape.
Do not instruct the agent to use Stripe or LemonSqueezy modules alongside Dodo Payments in the same route file; mixing SDK primitives leads to hallucinated method calls.
Verification, Linting & Output Quality Gate
Execute automated self-healing checks and run test suites to validate webhook signature and session logic.
Instruct the agent to run your project's test suite and type checker (e.g., `tsc --noEmit`). This forces the agent to self-heal any syntax errors, unresolved SDK imports, or unhandled promise rejections before terminating the session.
npx tsc --noEmit && npm test -- --runInBandRequire the agent to output the `git diff` after running verification commands to confirm no extraneous workspace files were touched.
Ensure mock payloads for Dodo Payments webhooks include valid headers (`webhook-id`, `webhook-timestamp`, and `webhook-signature`) in your integration tests, or cryptographic checks will deliberately fail.
Real-World Scenario: Building a Multi-Currency Subscription Checkout and Webhook Listener
“Using Dodo Payments, create a Next.js App Router checkout endpoint in `app/api/checkout/route.ts` that creates a customer subscription for a $29/mo SaaS plan. Then create a verified webhook route in `app/api/webhooks/dodo/route.ts` handling `payment.succeeded` and `subscription.active` events.”
Runtime Troubleshooting & Failure Modes
Root Cause: The agent passed an already-parsed JSON body (via `req.json()`) or an altered string stream to the webhook verification function instead of the intact, raw payload string.
// Inside app/api/webhooks/dodo/route.ts
const rawBody = await req.text();
const signature = req.headers.get('webhook-signature') || '';
const webhookSecret = process.env.DODO_PAYMENTS_WEBHOOK_KEY!;
const event = client.webhooks.constructEvent(rawBody, signature, webhookSecret);Root Cause: The SDK was instantiated without a valid bearer token or evaluated before the runtime loaded environment variables from `.env.local`.
import DodoPayments from 'dodopayments';
if (!process.env.DODO_PAYMENTS_API_KEY) {
throw new Error('DODO_PAYMENTS_API_KEY is not defined in environment variables');
}
export const dodo = new DodoPayments({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
environment: process.env.NODE_ENV === 'production' ? 'live_mode' : 'test_mode'
});Frequently Asked Questions (Dodo Payments Global Merchant & Tax SOP)
Q:Can I use Dodo Payments Global Merchant & Tax across Codex, Claude Code, and Cursor simultaneously?
Yes. This skill adheres strictly to the universal SKILL.md specification. Whether placed in `.agents/skills/dodo-payments/SKILL.md` or linked into `.cursor/rules` / Claude Code memory, the deterministic prompt triggers and SOP rules operate identically across all modern LLM runtimes.
Q:How does Dodo Payments Global Merchant & Tax prevent context window overflow during long agent sessions?
By isolating the operational boundaries to four explicit phases and using compact, declarative trigger rules rather than entire API documentation dumps. The agent references only the exact SDK methods needed (`payments`, `subscriptions`, and `webhooks`), drastically reducing input token usage.
Q:Does this skill require escalated root or container permissions?
No. The skill scored 98/100 on security auditing. It operates entirely within standard non-root workspace boundaries, requiring only standard Node.js dependency installation and environment variable reading permissions.
Ready to equip your autonomous agent with Dodo Payments Global Merchant & Tax?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.