Hướng dẫn tích hợp

Tạo các phiên checkout, liên kết thanh toán và webhook để chấp nhận thanh toán với Dodo Payments. Bắt đầu với SDK hoặc REST API.

Checkout Sessions

Tạo checkout bảo mật, được lưu trữ để xử lý các khoản thanh toán một lần và gói đăng ký.

Payment Links

Chia sẻ URL để thu tiền mà không cần viết code.

Webhooks

Lắng nghe các sự kiện thanh toán và hoàn tất đơn hàng.

API Reference

Tài liệu endpoint đầy đủ và kiểm thử trực tiếp.

​

Điều kiện tiên quyết

Trước khi bắt đầu, bạn cần:

• Một tài khoản Dodo Payments.
• Ít nhất một sản phẩm. Tạo sản phẩm trong Products trên dashboard. Sản phẩm subscription có mức giá khác 0 phải đáp ứng mức tối thiểu cho subscription của loại tiền khách hàng thanh toán: $1.00 đối với USD. Các loại tiền khác USD, EUR và GBP cũng phải có giá trị ít nhất $1.00. Subscription $0 cũng được hỗ trợ.
• Một API key. Tạo API key trong Developer → API Keys và lưu vào biến môi trường DODO_PAYMENTS_API_KEY. Tạo key ở test mode trong quá trình xây dựng: các ví dụ trên trang này sử dụng test mode và key ở test mode chỉ hoạt động với test mode. Xem Authentication.
• SDK cho ngôn ngữ của bạn. Node.js SDK yêu cầu Node.js 20 trở lên, Python SDK yêu cầu Python 3.9 trở lên và Go SDK yêu cầu Go 1.22 trở lên. Các ví dụ cURL không cần SDK.

Node.js

npm install dodopayments

Ví dụ webhook cũng sử dụng package standardwebhooks. Cài đặt package bằng npm install standardwebhooks.

​

Chọn hướng tích hợp

Hướng	Sử dụng khi	Hướng dẫn
Checkout sessions	Bạn muốn tạo checkout được lưu trữ từ server của mình. Đây là hướng được khuyến nghị cho hầu hết các tích hợp.	Checkout Sessions
Overlay checkout	Bạn muốn checkout mở dưới dạng modal trên trang web của mình.	Overlay Checkout
Inline checkout	Bạn muốn nhúng checkout vào bố cục trang, bên cạnh phần tóm tắt đơn hàng của mình.	Inline Checkout
Static payment links	Bạn muốn một URL có thể chia sẻ mà không cần code.	Payment Links
Mobile checkout SDKs	Bạn đang xây dựng ứng dụng native Android, iOS, React Native hoặc Flutter.	Mobile Integration

Overlay checkout và inline checkout chỉ chạy trên trang web. Trong ứng dụng mobile native, hãy tạo checkout session trên server rồi mở checkout_url bằng mobile checkout SDK.

Để một coding agent xây dựng tích hợp này cho bạn, hãy cài đặt Agent Plugin.

​

Checkout Sessions

Tạo trải nghiệm checkout an toàn được lưu trữ. Bạn tạo session trên server, sau đó chuyển hướng khách hàng đến checkout_url được trả về.

Mỗi checkout_url chỉ hoạt động một lần và hết hạn sau 24 giờ, hoặc sau 15 phút khi bạn truyền confirm: true. Với confirm: true, bạn cũng phải cung cấp mọi field bắt buộc. Tạo session mới cho mỗi khách hàng và mỗi lần thử thanh toán.

​

Tạo 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"
  }'

​

Chuyển hướng đến Checkout

Sau khi tạo session, hãy chuyển hướng khách hàng đến checkout_url:

window.location.href = session.checkout_url;

Để tùy chỉnh nâng cao, hãy xem hướng dẫn đầy đủ về Checkout Sessions và API Reference.

​

Xử lý lỗi

Khi request không thành công, API trả về HTTP status code và JSON body với code và message. Hãy phân nhánh xử lý lỗi dựa trên code, không phải message. Để xem từng code, nguyên nhân và cách khắc phục, hãy xem Error Codes. Failed payment được báo cáo riêng: status của payment là failed, error_code cung cấp lý do và bạn nhận được một webhook payment.failed. Để quyết định có retry hay không, hãy xem Handle Payment Failures.

​

Payment Links

Payment link là một URL mở checkout cho một sản phẩm, giúp bạn thu payment mà không cần viết code. Query parameters điền sẵn thông tin khách hàng và điều khiển form checkout. Khi khách hàng mở link, checkout lưu các parameter vào một session và rút gọn URL thành parameter session, nhờ đó các parameter vẫn được giữ lại khi refresh trang.

​

Static Payment Links

Static payment link là URL bạn tạo một lần và chia sẻ nhiều lần. URL cơ sở là:

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

Thêm query parameters để tùy chỉnh checkout:

quantity · integer · mặc định: "1"

Số lượng sản phẩm cần mua.

redirect_url · string · bắt buộc

Payment links sử dụng redirect_url. Checkout Sessions API sử dụng return_url cho cùng mục đích.

URL để chuyển hướng sau khi thanh toán. Dodo Payments thêm thông tin payment dưới dạng query parameters, chẳng hạn https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded&email=customer%40example.com. Nếu sản phẩm cấp license keys, một parameter license_key cũng được thêm vào, với nhiều key được phân tách bằng dấu phẩy.

paymentCurrency · string

Chỉ định loại tiền thanh toán. Mặc định là loại tiền của quốc gia billing.

showCurrencySelector · boolean · mặc định: "true"

Hiển thị hoặc ẩn currency selector.

showDiscounts · boolean · mặc định: "true"

Hiển thị hoặc ẩn phần discounts. Đặt thành false để ngăn khách hàng nhập coupon codes.

paymentAmount · number

Cố định số tiền được charge, theo đơn vị tiền tệ chính; ví dụ 12.5 tương đương $12.50. Chỉ hoạt động với sản phẩm Pay What You Want và bị bỏ qua nếu thấp hơn giá tối thiểu của sản phẩm.

paymentAmount sử dụng đơn vị tiền tệ chính (12.5 là $12.50). Field product_cart[].amount của Checkout Sessions API sử dụng đơn vị tiền tệ nhỏ nhất (1250 là $12.50). Xem Dynamic Pricing.

metadata_* · string

Các field metadata tùy chỉnh, chẳng hạn metadata_orderId=123.

​

Điền trước thông tin khách hàng

Thêm các field của khách hàng dưới dạng query parameters để đơn giản hóa checkout:

fullName · string

Tên đầy đủ của khách hàng (bị bỏ qua nếu firstName hoặc lastName được cung cấp).

firstName · string

Tên của khách hàng.

lastName · string

Họ của khách hàng.

email · string

Địa chỉ email của khách hàng.

country · string

Quốc gia của khách hàng (mã ISO 3166-1 alpha-2).

addressLine · string

Địa chỉ đường phố.

city · string

Thành phố.

state · string

Bang hoặc tỉnh.

zipCode · string

Mã bưu chính hoặc ZIP code.

​

Vô hiệu hóa các field của form

Để ngăn khách hàng thay đổi thông tin đã điền trước, hãy vô hiệu hóa một field bằng cách cung cấp giá trị của field đó và đặt flag disable... tương ứng thành true:

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

Field	Disable Flag	Required Parameter
Full Name	disableFullName	fullName
First Name	disableFirstName	firstName
Last Name	disableLastName	lastName
Email	disableEmail	email
Country	disableCountry	country
Address Line	disableAddressLine	addressLine
City	disableCity	city
State	disableState	state
ZIP Code	disableZipCode	zipCode

​

Ví dụ Static Payment Link

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

Việc vô hiệu hóa các field giúp ngăn thay đổi ngoài ý muốn và đảm bảo tính nhất quán của dữ liệu.

​

Dynamic Payment Links (Đã ngừng sử dụng)

Các endpoint POST /payments và POST /subscriptions đã ngừng sử dụng. Thay vào đó, hãy sử dụng Checkout Sessions cho các tích hợp mới.

Đối với các tích hợp hiện có sử dụng dynamic payment links, hãy truyền payment_link: true đến Create One-Time Payment hoặc Create Subscription để tạo link. Các ví dụ bên dưới tạo one-time payment link. Đối với subscription, hãy xem 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 thông báo cho server của bạn khi payment thành công hoặc thất bại, để bạn có thể xử lý đơn hàng.

​

Tạo Webhook Endpoint

Truy cập Developer → Webhooks trong dashboard và thêm endpoint URL của bạn. Sao chép signing secret của endpoint vào biến môi trường DODO_PAYMENTS_WEBHOOK_KEY.

Dưới đây là ví dụ sử dụng 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 });
}

Triển khai webhook của chúng tôi tuân theo đặc tả Standard Webhooks.

​

Các event cần lắng nghe

Trong flow one-time payment, tối thiểu hãy lắng nghe các event sau:

Event	Thời điểm phát sinh	Việc cần làm
payment.succeeded	Payment được xử lý thành công.	Xử lý đơn hàng — cấp quyền truy cập, provision sản phẩm, gửi receipt.
payment.failed	Lần thử payment thất bại (thẻ bị từ chối, lỗi, v.v.).	Thông báo cho khách hàng và yêu cầu retry.
payment.processing	Payment được chấp nhận nhưng vẫn đang được xử lý (async methods).	Chờ payment.succeeded hoặc payment.failed trước khi xử lý đơn hàng.
payment.cancelled	Payment bị hủy trước khi hoàn tất.	Giải phóng mọi trạng thái đang giữ và đánh dấu đơn hàng là bị bỏ dở.

Luôn xử lý đơn hàng khi nhận payment.succeeded từ webhook, không phải từ browser redirect. Redirect có thể bị bỏ lỡ nếu khách hàng đóng tab, trong khi webhook sẽ được retry cho đến khi được xác nhận.

Nếu bạn bán sản phẩm có license keys, hãy xử lý thêm license_key.created. Để xem danh sách đầy đủ các event, bao gồm event về subscription, entitlement, credit, recovery và dunning, hãy xem Webhook Event Guide.

Để xem ví dụ đầy đủ về Next.js và TypeScript, hãy xem demo repository và live deployment của repository đó.

​

Loại tiền và địa chỉ billing

Để charge bằng một loại tiền cụ thể, hãy truyền billing_currency và billing_address.country khi tạo checkout session. Nếu bỏ qua các parameter này, Adaptive Currency sẽ chọn loại tiền và quốc gia dựa trên địa chỉ IP của khách hàng, có thể không phải loại tiền bạn dự định charge.

Số tiền Pay What You Want được tính theo loại tiền cơ sở của sản phẩm, phải là USD, GBP hoặc EUR. Để thu một số tiền cố định bằng loại tiền khác, hãy sử dụng Adaptive Currency, tính giá cơ sở theo tỷ giá hối đoái hiện tại, hoặc Localized Pricing, thiết lập giá cố định cho từng loại tiền. Localized Pricing không hoạt động với Pay What You Want.

​

Mua lại bằng một click

Để charge một khách hàng quay lại bằng payment method đã lưu, hãy truyền payment_method_id cùng với confirm: true. payment_method_id chỉ được chấp nhận khi confirm là true và bạn cũng phải truyền customer_id của khách hàng hiện tại. Vì confirm là true, bạn cũng phải truyền một billing_address đầy đủ, hoặc chỉ country và zipcode khi minimal_address là true. Session charge trực tiếp vào payment method đã lưu nên không trả về checkout_url. Sử dụng webhooks để biết payment có thành công hay không.

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,
});

​

Trang liên quan

Checkout Sessions

Hướng dẫn đầy đủ với các tùy chọn tùy chỉnh nâng cao.

Overlay Checkout

Nhúng checkout dưới dạng modal overlay trên trang của bạn.

Inline Checkout

Nhúng checkout trực tiếp vào bố cục trang của bạn.

Subscription Integration

Thiết lập billing định kỳ.

Webhook Event Guide

Danh sách đầy đủ tất cả webhook event.

API Reference

Tài liệu Checkout Sessions API.