Panduan Integrasi

Buat checkout sessions, payment links, dan webhooks untuk menerima pembayaran dengan Dodo Payments. Mulai dengan SDK atau REST API.

Checkout Sessions

Buat checkout yang aman dan di-host untuk pembayaran satu kali dan subscription.

Payment Links

Bagikan URL untuk mengumpulkan pembayaran tanpa kode.

Webhooks

Dengarkan payment events dan penuhi pesanan.

API Reference

Dokumentasi endpoint lengkap dan pengujian langsung.

​

Prasyarat

Sebelum memulai, Anda memerlukan:

• Akun Dodo Payments.
• Setidaknya satu produk. Buat produk di Products pada dashboard. Produk subscription dengan harga non-zero harus memenuhi minimum subscription untuk mata uang yang digunakan pelanggan: $1.00 untuk USD. Mata uang selain USD, EUR, dan GBP juga harus bernilai setidaknya $1.00. Subscription sebesar $0 juga didukung.
• API key. Buat API key di Developer → API Keys dan simpan di environment variable DODO_PAYMENTS_API_KEY. Buat key dalam test mode selama proses pengembangan: contoh di halaman ini menggunakan test mode, dan key test mode hanya berfungsi dengan test mode. Lihat Authentication.
• SDK untuk bahasa Anda. Node.js SDK memerlukan Node.js 20 atau yang lebih baru, Python SDK memerlukan Python 3.9 atau yang lebih baru, dan Go SDK memerlukan Go 1.22 atau yang lebih baru. Contoh cURL tidak memerlukan SDK.

Node.js

npm install dodopayments

Contoh webhook juga menggunakan package standardwebhooks. Instal dengan npm install standardwebhooks.

​

Pilih Jalur Integrasi

Jalur	Gunakan jika	Panduan
Checkout sessions	Anda ingin membuat checkout yang di-host dari server Anda. Ini adalah jalur yang direkomendasikan untuk sebagian besar integrasi.	Checkout Sessions
Overlay checkout	Anda ingin checkout terbuka sebagai modal di halaman web Anda.	Overlay Checkout
Inline checkout	Anda ingin checkout disematkan dalam tata letak halaman, di samping ringkasan pesanan Anda sendiri.	Inline Checkout
Static payment links	Anda ingin URL yang dapat dibagikan tanpa kode.	Payment Links
Mobile checkout SDKs	Anda sedang membuat aplikasi native Android, iOS, React Native, atau Flutter.	Mobile Integration

Overlay checkout dan inline checkout hanya berjalan di halaman web. Dalam aplikasi mobile native, buat checkout session di server Anda dan buka checkout_url dengan mobile checkout SDK.

Untuk meminta coding agent membangun integrasi ini untuk Anda, instal Agent Plugin.

​

Checkout Sessions

Buat pengalaman checkout yang aman dan di-host. Anda membuat session di server, lalu mengarahkan pelanggan ke checkout_url yang dikembalikan.

Setiap checkout_url hanya dapat digunakan sekali dan kedaluwarsa setelah 24 jam, atau setelah 15 menit jika Anda meneruskan confirm: true. Dengan confirm: true, Anda juga harus menyediakan setiap field yang wajib diisi. Buat session baru untuk setiap pelanggan dan setiap percobaan pembayaran.

​

Buat Checkout Session

Node.js SDK

import DodoPayments from 'dodopayments';

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

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  customer: { email: '[e-mail]', name: 'John Doe' },
  return_url: 'https://yourapp.com/checkout/success',
});

console.log(session.checkout_url);

Python SDK

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",  # defaults to "live_mode"
)

session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_123", "quantity": 1}],
    customer={"email": "[e-mail]", "name": "John Doe"},
    return_url="https://yourapp.com/checkout/success",
)

print(session.checkout_url)

cURL

curl -X POST https://test.dodopayments.com/checkouts \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_cart": [{"product_id": "pdt_123", "quantity": 1}],
    "customer": {"email": "[e-mail]", "name": "John Doe"},
    "return_url": "https://yourapp.com/checkout/success"
  }'

​

Arahkan ke Checkout

Setelah membuat session, arahkan pelanggan ke checkout_url:

window.location.href = session.checkout_url;

Untuk kustomisasi tingkat lanjut, lihat panduan lengkap Checkout Sessions dan API Reference.

​

Tangani Error

Saat request gagal, API mengembalikan HTTP status code dan body JSON dengan code dan message. Buat percabangan penanganan error berdasarkan code, bukan message. Untuk setiap code, penyebabnya, dan cara mengatasinya, lihat Error Codes. Pembayaran yang gagal dilaporkan secara terpisah: status pembayaran adalah failed, error_code memberikan alasannya, dan Anda menerima webhook payment.failed. Untuk menentukan apakah perlu mencoba lagi, lihat Handle Payment Failures.

​

Payment Links

Payment link adalah URL yang membuka checkout untuk suatu produk, sehingga Anda dapat menerima pembayaran tanpa menulis kode. Query parameters mengisi detail pelanggan terlebih dahulu dan mengontrol formulir checkout. Saat pelanggan membuka link, checkout menyimpan parameter dalam session dan memperpendek URL menjadi parameter session, sehingga parameter tetap ada saat halaman dimuat ulang.

​

Static Payment Links

Static payment link adalah URL yang Anda buat sekali dan bagikan berkali-kali. Base URL-nya adalah:

https://checkout.dodopayments.com/buy/{product_id}

Tambahkan query parameters untuk menyesuaikan checkout:

quantity · integer · default: "1"

Jumlah item yang akan dibeli.

redirect_url · string · wajib

Payment links menggunakan redirect_url. Checkout Sessions API menggunakan return_url untuk tujuan yang sama.

URL untuk mengarahkan pelanggan setelah pembayaran. Dodo Payments menambahkan detail pembayaran sebagai query parameters, misalnya https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded&email=customer%40example.com. Jika produk menerbitkan license keys, parameter license_key juga ditambahkan, dengan beberapa key dipisahkan oleh koma.

paymentCurrency · string

Menentukan mata uang pembayaran. Default-nya adalah mata uang negara penagihan.

showCurrencySelector · boolean · default: "true"

Menampilkan atau menyembunyikan pemilih mata uang.

showDiscounts · boolean · default: "true"

Menampilkan atau menyembunyikan bagian diskon. Atur ke false untuk mencegah pelanggan memasukkan kode kupon.

paymentAmount · number

Menetapkan jumlah yang ditagihkan, dalam unit utama mata uang, misalnya 12.5 untuk $12.50. Hanya berfungsi dengan produk Pay What You Want dan diabaikan jika nilainya di bawah harga minimum produk.

paymentAmount menggunakan unit utama mata uang (12.5 adalah $12.50). Field Checkout Sessions API product_cart[].amount menggunakan unit terkecil mata uang (1250 adalah $12.50). Lihat Dynamic Pricing.

metadata_* · string

Field metadata khusus, misalnya metadata_orderId=123.

​

Isi Otomatis Informasi Pelanggan

Tambahkan field pelanggan sebagai query parameters untuk mempercepat checkout:

fullName · string

Nama lengkap pelanggan (diabaikan jika firstName atau lastName disediakan).

firstName · string

Nama depan pelanggan.

lastName · string

Nama belakang pelanggan.

email · string

Alamat email pelanggan.

country · string

Negara pelanggan (kode ISO 3166-1 alpha-2).

addressLine · string

Alamat jalan.

city · string

Kota.

state · string

Negara bagian atau provinsi.

zipCode · string

Kode pos atau ZIP.

​

Nonaktifkan Field Formulir

Untuk mencegah pelanggan mengubah informasi yang telah diisi, nonaktifkan field dengan memberikan nilainya dan mengatur flag disable... yang sesuai ke true:

?email=[e-mail]&disableEmail=true

Field	Flag Penonaktifan	Parameter Wajib
Nama Lengkap	disableFullName	fullName
Nama Depan	disableFirstName	firstName
Nama Belakang	disableLastName	lastName
Email	disableEmail	email
Negara	disableCountry	country
Baris Alamat	disableAddressLine	addressLine
Kota	disableCity	city
Negara Bagian	disableState	state
Kode ZIP	disableZipCode	zipCode

​

Contoh Static Payment Link

https://checkout.dodopayments.com/buy/pdt_123?quantity=1&email=[e-mail]&disableEmail=true&redirect_url=https://example.com/success

Menonaktifkan field mencegah perubahan yang tidak disengaja dan memastikan konsistensi data.

​

Dynamic Payment Links (Deprecated)

Endpoint POST /payments dan POST /subscriptions sudah deprecated. Gunakan Checkout Sessions untuk integrasi baru.

Untuk integrasi yang sudah ada dan menggunakan dynamic payment links, teruskan payment_link: true ke Create One-Time Payment atau Create Subscription untuk membuat link. Contoh di bawah membuat one-time payment link. Untuk subscription, lihat Subscription Integration Guide.

Node.js SDK

import DodoPayments from 'dodopayments';

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

const payment = await client.payments.create({
  payment_link: true,
  billing: {
    city: 'San Francisco',
    country: 'US',
    state: 'CA',
    street: '123 Main St',
    zipcode: '94102',
  },
  customer: { email: '[e-mail]', name: 'John Doe' },
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
});

console.log(payment.payment_link);

Python SDK

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",
)

payment = client.payments.create(
    payment_link=True,
    billing={
        "city": "San Francisco",
        "country": "US",
        "state": "CA",
        "street": "123 Main St",
        "zipcode": "94102",
    },
    customer={"email": "[e-mail]", "name": "John Doe"},
    product_cart=[{"product_id": "pdt_123", "quantity": 1}],
)

print(payment.payment_link)

Go SDK

package main

import (
	"context"
	"fmt"

	"github.com/dodopayments/dodopayments-go"
	"github.com/dodopayments/dodopayments-go/option"
)

func main() {
	// Reads DODO_PAYMENTS_API_KEY from the environment.
	client := dodopayments.NewClient(option.WithEnvironmentTestMode())

	payment, err := client.Payments.New(context.Background(), dodopayments.PaymentNewParams{
		PaymentLink: dodopayments.F(true),
		Billing: dodopayments.F(dodopayments.BillingAddressParam{
			City:    dodopayments.F("San Francisco"),
			Country: dodopayments.F(dodopayments.CountryCodeUs),
			State:   dodopayments.F("CA"),
			Street:  dodopayments.F("123 Main St"),
			Zipcode: dodopayments.F("94102"),
		}),
		Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](dodopayments.NewCustomerParam{
			Email: dodopayments.F("[e-mail]"),
			Name:  dodopayments.F("John Doe"),
		}),
		ProductCart: dodopayments.F([]dodopayments.OneTimeProductCartItemParam{{
			ProductID: dodopayments.F("pdt_123"),
			Quantity:  dodopayments.F(int64(1)),
		}}),
	})
	if err != nil {
		panic(err.Error())
	}

	fmt.Println(payment.PaymentLink)
}

​

Webhooks

Webhooks memberi tahu server Anda saat pembayaran berhasil atau gagal, sehingga Anda dapat memenuhi pesanan.

​

Buat Webhook Endpoint

Buka Developer → Webhooks di dashboard dan tambahkan URL endpoint Anda. Salin signing secret endpoint ke environment variable DODO_PAYMENTS_WEBHOOK_KEY.

Berikut contoh menggunakan Next.js:

app/api/webhooks/dodo/route.ts

import { Webhook } from "standardwebhooks";

const webhook = new Webhook(process.env.DODO_PAYMENTS_WEBHOOK_KEY!);

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

  const webhookHeaders = {
    "webhook-id": request.headers.get("webhook-id") ?? "",
    "webhook-signature": request.headers.get("webhook-signature") ?? "",
    "webhook-timestamp": request.headers.get("webhook-timestamp") ?? "",
  };

  try {
    await webhook.verify(rawBody, webhookHeaders);
  } catch {
    return new Response("Invalid signature", { status: 400 });
  }

  const payload = JSON.parse(rawBody);

  switch (payload.type) {
    case "payment.succeeded":
      // Fulfill the order
      break;
    case "payment.failed":
      // Notify the customer
      break;
  }

  return new Response(null, { status: 200 });
}

Implementasi webhook kami mengikuti spesifikasi Standard Webhooks.

​

Event yang Perlu Didengarkan

Setidaknya, dengarkan event berikut dalam alur one-time payment:

Event	Kapan dipicu	Tindakan
payment.succeeded	Pembayaran berhasil diproses.	Penuhi pesanan — berikan akses, sediakan produk, dan kirim tanda terima.
payment.failed	Percobaan pembayaran gagal (kartu ditolak, error, dan sebagainya).	Beri tahu pelanggan dan minta mereka mencoba lagi.
payment.processing	Pembayaran diterima tetapi masih diproses (metode async).	Tunggu payment.succeeded atau payment.failed sebelum memenuhi pesanan.
payment.cancelled	Pembayaran dibatalkan sebelum selesai.	Lepaskan state yang ditahan dan tandai pesanan sebagai abandoned.

Selalu penuhi pesanan berdasarkan payment.succeeded dari webhook, bukan berdasarkan browser redirect. Redirect dapat terlewat jika pelanggan menutup tab, sedangkan webhook akan dicoba kembali sampai diakui.

Jika Anda menjual produk dengan license keys, tangani juga license_key.created. Untuk daftar lengkap event, termasuk event subscription, entitlement, credit, recovery, dan dunning, lihat Webhook Event Guide.

Untuk contoh Next.js dan TypeScript lengkap, lihat demo repository dan live deployment-nya.

​

Mata Uang dan Alamat Penagihan

Untuk menagih dalam mata uang tertentu, teruskan billing_currency dan billing_address.country saat membuat checkout session. Jika tidak disertakan, Adaptive Currency memilih mata uang dan negara berdasarkan alamat IP pelanggan, yang mungkin bukan mata uang yang ingin Anda gunakan untuk penagihan.

Jumlah Pay What You Want menggunakan mata uang dasar produk, yang harus berupa USD, GBP, atau EUR. Untuk menagih jumlah tetap dalam mata uang lain, gunakan Adaptive Currency, yang mengonversi harga dasar berdasarkan nilai tukar terkini, atau Localized Pricing, yang menetapkan harga tetap untuk setiap mata uang. Localized Pricing tidak berfungsi dengan Pay What You Want.

​

Pembelian Ulang Sekali Klik

Untuk menagih pelanggan yang kembali menggunakan metode pembayaran tersimpan, teruskan payment_method_id bersama confirm: true. payment_method_id hanya diterima jika confirm adalah true, dan Anda juga harus meneruskan customer_id milik pelanggan yang sudah ada. Karena confirm adalah true, Anda juga harus meneruskan billing_address lengkap, atau hanya country dan zipcode saat minimal_address adalah true. Session langsung menagih metode pembayaran tersimpan, sehingga tidak mengembalikan checkout_url. Gunakan webhooks untuk mengetahui apakah pembayaran berhasil.

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  customer: { customer_id: 'cus_123' },
  payment_method_id: 'pm_123',
  billing_address: {
    country: 'US',
    state: 'CA',
    city: 'San Francisco',
    street: '123 Main St',
    zipcode: '94102',
  },
  confirm: true,
});

​

Halaman Terkait

Checkout Sessions

Panduan lengkap dengan opsi kustomisasi tingkat lanjut.

Overlay Checkout

Sematkan checkout sebagai overlay modal di halaman Anda.

Inline Checkout

Sematkan checkout langsung dalam tata letak halaman Anda.

Subscription Integration

Siapkan penagihan berulang.

Webhook Event Guide

Daftar lengkap semua event webhook.

API Reference

Dokumentasi Checkout Sessions API.