Payments 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 for integrating payments into your website:
- Static Payment Links: Instantly shareable URLs for quick, no-code payment collection.
- Dynamic Payment Links: Programmatically generate payment links with custom details using the API or SDKs.
For a seamless in-page experience, you can use our Overlay Checkout integration, which embeds the Dodo Payments checkout on your site by leveraging these payment links.
1. Static Payment Links
Static payment links let you quickly accept payments by sharing a simple URL. You can customize the checkout experience by passing query parameters to pre-fill customer details, control form fields, and add custom metadata.
Construct your payment link
Start with the base URL and append your product ID:
Add core parameters
Include essential query parameters:
-
Number of items to purchase.
-
URL to redirect after payment completion.
The redirect URL will include payment details as query parameters, for example:
https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded
Pre-fill customer information (optional)
Add customer or billing fields as query parameters to streamline checkout.
Supported Customer Fields
Supported Customer Fields
-
Customer’s full name (ignored if firstName or lastName is provided).
-
Customer’s first name.
-
Customer’s last name.
-
Customer’s email address.
-
Customer’s country.
-
Street address.
-
City.
-
State or province.
-
Postal/ZIP code.
-
true or false
Control form fields (optional)
You can disable specific fields to make them read-only for the customer. This is useful when you already have the customer’s details (e.g., logged-in users).
To disable a field, provide its value and set the corresponding disable…
flag to true
:
Field | Disable Flag | Required Parameter |
---|---|---|
Full Name | disableFullName | fullName |
First Name | disableFirstName | firstName |
Last Name | disableLastName | lastName |
disableEmail | email | |
Country | disableCountry | country |
Address Line | disableAddressLine | addressLine |
City | disableCity | city |
State | disableState | state |
ZIP Code | disableZipCode | zipCode |
Field | Disable Flag | Required Parameter |
---|---|---|
Full Name | disableFullName | fullName |
First Name | disableFirstName | firstName |
Last Name | disableLastName | lastName |
disableEmail | email | |
Country | disableCountry | country |
Address Line | disableAddressLine | addressLine |
City | disableCity | city |
State | disableState | state |
ZIP Code | disableZipCode | zipCode |
Disabling fields helps prevent accidental changes and ensures data consistency.
Add advanced controls (optional)
-
Specifies the payment currency. Defaults to the billing country’s currency.
-
Show or hide the currency selector.
-
Amount in cents (for Pay What You Want pricing only).
-
Custom metadata fields (e.g.,
metadata_orderId=123
).
Share the link
Send the completed payment link to your customer. When they visit, 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.
The customer’s checkout experience is now streamlined and personalized based on your parameters.
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 You can see all our available SDKs on Dodo Payments SDK page.
For detailed API request body requirements, consult our API Reference.
3. Overlay Checkout
For a seamless in-page checkout experience, explore our Overlay Checkout integration that allows customers to complete payments without leaving your website.
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 Webhook Event Guide.
You can refer to this project with demo implementation on GitHub using Next.js and TypeScript.
You can check out the live implementation here.