API Integration Guide
This guide will help you integrate the Dodo Payments API into your website.
Prerequisites
To integrate the Dodo Payments API, you’ll need:
- A Dodo Payments merchant account
- API Credentials (API key and webhook secret key) from dashboard
If you don’t have an account yet, you can get your business approved by contacting the founder or by filling out this form.
Dashboard Setup
-
Navigate to the Dodo Payments Dashboard
-
Create a product (one-time payment or subscription)
-
Test the checkout flow:
- Click the share button on the product page
- Open the link in your browser
- Use test card number:
4242 4242 4242 4242
- Enter any future expiration date and any 3-digit CVV
-
Generate your API key:
- Go to Settings > API
- Detailed Guide
- Copy the API key the in env named DODO_PAYMENTS_API_KEY
-
Configure webhooks:
- Go to Settings > Webhooks
- Create a webhook URL for payment notifications
- Detailed Guide
- Copy the webhook secret key in env
API Integration
Payment Links
Dodo Payments supports two types of payment links:
1. Static Payment Links
Simple to create by appending your product ID to the base URL:
This link accepts query parameters that are processed through our Query Collector System. When parameters are provided, they are stored in session storage with a unique ID (e.g., sess_1a2b3c4d
) and made available throughout the checkout flow.
The supported query parameters are:
Core Parameters:
-
quantity
: The quantity of the product to be purchased. Default is 1. -
redirect_url
: URL to redirect after payment completion.Note: The redirect URL will include payment details as query parameters:
Customer Information:
fullName
: Customer’s full name (ignored if firstName or lastName is provided)firstName
: Customer’s first namelastName
: Customer’s last nameemail
: Customer’s email addresscountry
: Customer’s countryaddressLine
: Customer’s street addresscity
: Customer’s citystate
: Customer’s state/provincezipCode
: Customer’s postal/ZIP code
Form Field Controls: The following flags can disable form fields, but only take effect when the associated field data is also provided:
disableFullName
: Disables fullName field (requires fullName parameter)disableFirstName
: Disables fullName field (requires fullName parameter)disableLastName
: Disables fullName field (requires fullName parameter)disableEmail
: Disables email field (requires email parameter)disableCountry
: Disables country field (requires country parameter)disableAddressLine
: Disables address field (requires addressLine parameter)disableCity
: Disables city field (requires city parameter)disableState
: Disables state field (requires state parameter)disableZipCode
: Disables ZIP code field (requires zipCode parameter)
Custom Data:
- Metadata fields can be passed using the
metadata_
prefix Example:metadata_orderId=123
ormetadata_customerNote=Special instructions
When a customer visits the payment link, all query parameters are collected and stored with a session ID. The URL is then simplified to include just the session parameter (e.g., ?session=sess_1a2b3c4d
). The stored information persists through page refreshes and is accessible throughout the checkout process.
2. Dynamic Payment Links
Created via API call or our sdk with customer details. Here’s an example:
There are two APIs for creating dynamic payment links:
- One-time Payment Link API API reference
- Subscription Payment Link API API reference
The guide below is for one-time payment link creation.
For detailed instructions on integrating subscriptions, refer to this Subscription Integration Guide.
payment_link = true
to get payment link Node.js SDK is available on GitHub.
Python SDK is available on GitHub.
Go SDK is available on GitHub.
For detailed API request body requirements, consult our API Reference.
Implementing Webhooks
Set up an API endpoint to receive payment notifications. Here’s an example using Next.js:
Our webhook implementation follows the Standard Webhooks specification. For webhook type definitions, refer to our API Reference.
You can refer to this project with demo implementation on GitHub using Next.js and TypeScript.
You can check out the live implementation here.