Chuyển đến nội dung chính

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

Để tích hợp API Dodo Payments, bạn cần:
  • Một tài khoản thương nhân Dodo Payments
  • Thông tin xác thực API (khóa API và khóa bí mật webhook) từ bảng điều khiển

Thiết lập bảng điều khiển

  1. Điều hướng đến Bảng điều khiển Dodo Payments
  2. Tạo một sản phẩm (thanh toán một lần hoặc đăng ký)
  3. Tạo khóa API của bạn:
    • Đi tới Developer > API
    • Hướng dẫn chi tiết
    • Sao chép khóa API trong biến môi trường có tên DODO_PAYMENTS_API_KEY
  4. Cấu hình webhooks:
    • Đi tới Developer > Webhooks
    • Tạo một URL webhook cho thông báo thanh toán
    • Sao chép khóa bí mật webhook trong biến môi trường

Tích hợp

Liên kết thanh toán

Chọn con đường tích hợp phù hợp với trường hợp sử dụng của bạn:
  • Phiên thanh toán (được khuyến nghị): Tốt nhất cho hầu hết các tích hợp. Tạo một phiên trên máy chủ của bạn và chuyển hướng khách hàng đến một trang thanh toán an toàn, được lưu trữ.
  • Thanh toán chồng (nhúng): Sử dụng khi bạn cần trải nghiệm trong trang nhúng thanh toán được lưu trữ trên trang web của bạn.
  • Liên kết thanh toán tĩnh: URL có thể chia sẻ ngay lập tức không cần mã cho việc thu thập thanh toán nhanh chóng.
  • Liên kết thanh toán động: Liên kết được tạo lập trình. Tuy nhiên, các phiên thanh toán được khuyến nghị và cung cấp nhiều tính linh hoạt hơn.

1. Phiên thanh toán

Sử dụng các phiên thanh toán để tạo trải nghiệm thanh toán an toàn, được lưu trữ cho các khoản thanh toán một lần hoặc đăng ký. Bạn tạo một phiên trên máy chủ của mình, sau đó chuyển hướng khách hàng đến checkout_url.
Các phiên thanh toán có hiệu lực trong 24 giờ theo mặc định. Nếu bạn truyền confirm=true, các phiên có hiệu lực trong 15 phút và tất cả các trường cần thiết phải được cung cấp.
1

Tạo một phiên thanh toán

Chọn SDK ưa thích của bạn hoặc gọi API REST.
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: 'prod_123', quantity: 1 }],
  customer: { email: '[email protected]', name: 'John Doe' },
  return_url: 'https://yourapp.com/checkout/success',
});
2

Chuyển hướng khách hàng đến thanh toán

Sau khi tạo phiên, chuyển hướng đến checkout_url để bắt đầu quy trình lưu trữ.
// Example in a browser context
window.location.href = session.checkout_url;
Ưu tiên các phiên thanh toán cho cách nhanh nhất và đáng tin cậy nhất để bắt đầu nhận thanh toán. Để tùy chỉnh nâng cao, xem hướng dẫn đầy đủ về Các phiên thanh toánTài liệu API.

2. Thanh toán chồng

Để có trải nghiệm thanh toán trong trang liền mạch, hãy khám phá tích hợp Thanh toán chồng của chúng tôi cho phép khách hàng hoàn tất thanh toán mà không rời khỏi trang web của bạn.

3. Liên kết thanh toán tĩnh

Liên kết thanh toán tĩnh cho phép bạn nhanh chóng chấp nhận thanh toán bằng cách chia sẻ một URL đơn giản. Bạn có thể tùy chỉnh trải nghiệm thanh toán bằng cách truyền các tham số truy vấn để tự động điền thông tin khách hàng, kiểm soát các trường biểu mẫu và thêm siêu dữ liệu tùy chỉnh.
1

Xây dựng liên kết thanh toán của bạn

Bắt đầu với URL cơ bản và thêm ID sản phẩm của bạn:
https://checkout.dodopayments.com/buy/{productid}
2

Thêm các tham số chính

Bao gồm các tham số truy vấn thiết yếu:
  • quantity
    integer
    default:"1"
    Số lượng hàng hóa để mua.
  • redirect_url
    string
    required
    URL để chuyển hướng sau khi hoàn tất thanh toán.
URL chuyển hướng sẽ bao gồm chi tiết thanh toán dưới dạng tham số truy vấn, ví dụ:
https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded
3

Tự động điền thông tin khách hàng (tùy chọn)

Thêm các trường khách hàng hoặc thanh toán dưới dạng tham số truy vấn để đơn giản hóa quy trình thanh toán.
  • fullName
    string
    Họ và tên của khách hàng (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.
  • addressLine
    string
    Địa chỉ đường phố.
  • city
    string
    Thành phố.
  • state
    string
    Tiểu bang hoặc tỉnh.
  • zipCode
    string
    Mã bưu điện/ZIP.
  • showDiscounts
    boolean
    true hoặc false
4

Kiểm soát các trường biểu mẫu (tùy chọn)

Bạn có thể vô hiệu hóa các trường cụ thể để làm cho chúng chỉ đọc cho khách hàng. Điều này hữu ích khi bạn đã có thông tin của khách hàng (ví dụ: người dùng đã đăng nhập).
Để vô hiệu hóa một trường, cung cấp giá trị của nó và đặt cờ disable… tương ứng thành true:
&[email protected]&disableEmail=true
TrườngCờ vô hiệu hóaTham số bắt buộc
Họ và têndisableFullNamefullName
TêndisableFirstNamefirstName
HọdisableLastNamelastName
EmaildisableEmailemail
Quốc giadisableCountrycountry
Địa chỉ đườngdisableAddressLineaddressLine
Thành phốdisableCitycity
Tiểu bangdisableStatestate
Mã bưu điệndisableZipCodezipCode
Việc vô hiệu hóa các trường giúp ngăn chặn những thay đổi không mong muốn và đảm bảo tính nhất quán của dữ liệu.
Đặt showDiscounts=false sẽ vô hiệu hóa và ẩn phần giảm giá trong biểu mẫu thanh toán. Sử dụng điều này nếu bạn muốn ngăn khách hàng nhập mã giảm giá hoặc mã khuyến mãi trong quá trình thanh toán.
5

Thêm các điều khiển nâng cao (tùy chọn)

  • paymentCurrency
    string
    Chỉ định loại tiền tệ thanh toán. Mặc định là loại tiền tệ của quốc gia thanh toán.
  • showCurrencySelector
    boolean
    default:"true"
    Hiện hoặc ẩn trình chọn tiền tệ.
  • paymentAmount
    integer
    Số tiền tính bằng xu (chỉ cho giá Pay What You Want).
  • metadata_*
    string
    Các trường siêu dữ liệu tùy chỉnh (ví dụ: metadata_orderId=123).
6

Chia sẻ liên kết

Gửi liên kết thanh toán đã hoàn thành đến khách hàng của bạn. Khi họ truy cập, tất cả các tham số truy vấn sẽ được thu thập và lưu trữ với một ID phiên. URL sau đó sẽ được đơn giản hóa để chỉ bao gồm tham số phiên (ví dụ: ?session=sess_1a2b3c4d). Thông tin đã lưu trữ sẽ tồn tại qua các lần làm mới trang và có thể truy cập trong suốt quá trình thanh toán.
Trải nghiệm thanh toán của khách hàng giờ đây đã được đơn giản hóa và cá nhân hóa dựa trên các tham số của bạn.

4. Liên kết thanh toán động

Ưu tiên các phiên thanh toán cho hầu hết các trường hợp sử dụng, chúng cung cấp nhiều tính linh hoạt và kiểm soát hơn.
Được tạo thông qua cuộc gọi API hoặc SDK của chúng tôi với thông tin khách hàng. Đây là một ví dụ: Có hai API để tạo liên kết thanh toán động: Hướng dẫn dưới đây là cho việc tạo liên kết thanh toán một lần. Để biết hướng dẫn chi tiết về việc tích hợp đăng ký, hãy tham khảo Hướng dẫn tích hợp đăng ký.
Đảm bảo bạn đang truyền payment_link = true để nhận liên kết thanh toán
import DodoPayments from 'dodopayments';

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

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 protected]', name: 'name' },
product_cart: [{ product_id: 'product_id', quantity: 0 }],
});

console.log(payment.payment_id);
}

main();
Sau khi tạo liên kết thanh toán, hãy chuyển hướng khách hàng của bạn để hoàn tất thanh toán.

Triển khai Webhooks

Thiết lập một điểm cuối API để nhận thông báo thanh toán. Đây là một ví dụ sử dụng 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
}
Triển khai webhook của chúng tôi tuân theo tiêu chuẩn Standard Webhooks. Để biết định nghĩa loại webhook, hãy tham khảo Hướng dẫn sự kiện Webhook. Bạn có thể tham khảo dự án này với triển khai demo trên GitHub sử dụng Next.js và TypeScript. Bạn có thể xem triển khai trực tiếp tại đây.