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

  1. Navigate to the Dodo Payments Dashboard

  2. Create a product (one-time payment or subscription)

  3. 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
  4. Generate your API key:

    • Go to Settings > API
    • Detailed Guide
    • Copy the API key the in env named DODO_PAYMENTS_API_KEY
  5. Configure webhooks:

    • Go to Settings > Webhooks
    • Create a webhook URL for payment notifications
    • Detailed Guide
    • Copy the webhook secret key in env

API Integration

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.

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.

1

Construct your payment link

Start with the base URL and append your product ID:

https://checkout.dodopayments.com/buy/{productid}
2

Add core parameters

Include essential query parameters:

  • quantity
    integer
    default:"1"
    Number of items to purchase.
  • redirect_url
    string
    required
    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

3

Pre-fill customer information (optional)

Add customer or billing fields as query parameters to streamline checkout.

4

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:

&email=alice@example.com&disableEmail=true
FieldDisable FlagRequired Parameter
Full NamedisableFullNamefullName
First NamedisableFirstNamefirstName
Last NamedisableLastNamelastName
EmaildisableEmailemail
CountrydisableCountrycountry
Address LinedisableAddressLineaddressLine
CitydisableCitycity
StatedisableStatestate
ZIP CodedisableZipCodezipCode

Disabling fields helps prevent accidental changes and ensures data consistency.

5

Add advanced controls (optional)

  • paymentCurrency
    string
    Specifies the payment currency. Defaults to the billing country’s currency.
  • showCurrencySelector
    boolean
    default:"true"
    Show or hide the currency selector.
  • paymentAmount
    integer
    Amount in cents (for Pay What You Want pricing only).
  • metadata_*
    string
    Custom metadata fields (e.g., metadata_orderId=123).
6

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.

Created via API call or our sdk with customer details. Here’s an example:

There are two APIs for creating dynamic payment links:

The guide below is for one-time payment link creation.

For detailed instructions on integrating subscriptions, refer to this Subscription Integration Guide.

Make sure you are passing payment_link = true to get payment link
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
bearerToken: process.env['DODO_PAYMENTS_API_KEY'], // This is the default and can be omitted
});

async function main() {
const payment = await client.payments.create({
payment_link: true,
billing: { city: 'city', country: 'AF', state: 'state', street: 'street', zipcode: 0 },
customer: { email: 'email@email.com', name: 'name' },
product_cart: [{ product_id: 'product_id', quantity: 0 }],
});

console.log(payment.payment_id);
}

main();

You can see all our available SDKs on Dodo Payments SDK page.

For detailed API request body requirements, consult our API Reference.

After creating the payment link, redirect your customers to complete their payment.

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:

import { Webhook } from "standardwebhooks";
import { headers } from "next/headers";
import { WebhookPayload } from "@/types/api-types";

const webhook = new Webhook(process.env.DODO_WEBHOOK_KEY!); // Replace with your secret key generated from the Dodo Payments Dashboard

export async function POST(request: Request) {
  const headersList = headers();
  const rawBody = await request.text();

  const webhookHeaders = {
    "webhook-id": headersList.get("webhook-id") || "",
    "webhook-signature": headersList.get("webhook-signature") || "",
    "webhook-timestamp": headersList.get("webhook-timestamp") || "",
  };

  await webhook.verify(rawBody, webhookHeaders);
  const payload = JSON.parse(rawBody) as WebhookPayload;
  
  // Process the payload according to your business logic
}

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.

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

  1. Navigate to the Dodo Payments Dashboard

  2. Create a product (one-time payment or subscription)

  3. 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
  4. Generate your API key:

    • Go to Settings > API
    • Detailed Guide
    • Copy the API key the in env named DODO_PAYMENTS_API_KEY
  5. Configure webhooks:

    • Go to Settings > Webhooks
    • Create a webhook URL for payment notifications
    • Detailed Guide
    • Copy the webhook secret key in env

API Integration

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.

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.

1

Construct your payment link

Start with the base URL and append your product ID:

https://checkout.dodopayments.com/buy/{productid}
2

Add core parameters

Include essential query parameters:

  • quantity
    integer
    default:"1"
    Number of items to purchase.
  • redirect_url
    string
    required
    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

3

Pre-fill customer information (optional)

Add customer or billing fields as query parameters to streamline checkout.

4

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:

&email=alice@example.com&disableEmail=true
FieldDisable FlagRequired Parameter
Full NamedisableFullNamefullName
First NamedisableFirstNamefirstName
Last NamedisableLastNamelastName
EmaildisableEmailemail
CountrydisableCountrycountry
Address LinedisableAddressLineaddressLine
CitydisableCitycity
StatedisableStatestate
ZIP CodedisableZipCodezipCode

Disabling fields helps prevent accidental changes and ensures data consistency.

5

Add advanced controls (optional)

  • paymentCurrency
    string
    Specifies the payment currency. Defaults to the billing country’s currency.
  • showCurrencySelector
    boolean
    default:"true"
    Show or hide the currency selector.
  • paymentAmount
    integer
    Amount in cents (for Pay What You Want pricing only).
  • metadata_*
    string
    Custom metadata fields (e.g., metadata_orderId=123).
6

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.

Created via API call or our sdk with customer details. Here’s an example:

There are two APIs for creating dynamic payment links:

The guide below is for one-time payment link creation.

For detailed instructions on integrating subscriptions, refer to this Subscription Integration Guide.

Make sure you are passing payment_link = true to get payment link
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
bearerToken: process.env['DODO_PAYMENTS_API_KEY'], // This is the default and can be omitted
});

async function main() {
const payment = await client.payments.create({
payment_link: true,
billing: { city: 'city', country: 'AF', state: 'state', street: 'street', zipcode: 0 },
customer: { email: 'email@email.com', name: 'name' },
product_cart: [{ product_id: 'product_id', quantity: 0 }],
});

console.log(payment.payment_id);
}

main();

You can see all our available SDKs on Dodo Payments SDK page.

For detailed API request body requirements, consult our API Reference.

After creating the payment link, redirect your customers to complete their payment.

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:

import { Webhook } from "standardwebhooks";
import { headers } from "next/headers";
import { WebhookPayload } from "@/types/api-types";

const webhook = new Webhook(process.env.DODO_WEBHOOK_KEY!); // Replace with your secret key generated from the Dodo Payments Dashboard

export async function POST(request: Request) {
  const headersList = headers();
  const rawBody = await request.text();

  const webhookHeaders = {
    "webhook-id": headersList.get("webhook-id") || "",
    "webhook-signature": headersList.get("webhook-signature") || "",
    "webhook-timestamp": headersList.get("webhook-timestamp") || "",
  };

  await webhook.verify(rawBody, webhookHeaders);
  const payload = JSON.parse(rawBody) as WebhookPayload;
  
  // Process the payload according to your business logic
}

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.