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

Xử lý Thanh toán

Tích hợp thanh toán Dodo Payments vào ứng dụng Express của bạn.

Cổng Thông Tin Khách Hàng

Cho phép khách hàng quản lý đăng ký và thông tin.

Webhook

Nhận và xử lý các sự kiện webhook của Dodo Payments.

​
Cài đặt

1

Cài đặt gói

Chạy lệnh sau trong thư mục gốc của dự án bạn:
npm install @dodopayments/express
2

Thiết lập biến môi trường

Tạo một tệp .env trong thư mục gốc của dự án bạn:
DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
DODO_PAYMENTS_RETURN_URL=your-return-url
Không bao giờ cam kết tệp .env hoặc bí mật của bạn vào hệ thống kiểm soát phiên bản.

​
Ví dụ về Xử lý Đường dẫn

Sử dụng bộ xử lý này để tích hợp thanh toán Dodo Payments vào ứng dụng Express của bạn. Hỗ trợ các luồng thanh toán tĩnh (GET), động (POST) và phiên (POST).
import { checkoutHandler } from '@dodopayments/express';

app.get('/api/checkout', checkoutHandler({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    type: "static"
}))

app.post('/api/checkout', checkoutHandler({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    type: "dynamic"
}))

app.post('/api/checkout', checkoutHandler({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    type: "session"
}))

curl --request GET \
--url 'https://example.com/api/checkout?productId=pdt_fqJhl7pxKWiLhwQR042rh' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test

curl --request POST \
--url https://example.com/api/checkout \
--header 'Content-Type: application/json' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test \
--data '{
"billing": {
  "city": "Texas",
  "country": "US",
  "state": "Texas",
  "street": "56, hhh",
  "zipcode": "560000"
},
"customer": {
  "email": "[email protected]",
  	"name": "test"
},
"metadata": {},
"payment_link": true,
  "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
  "quantity": 1,
  "billing_currency": "USD",
  "discount_code": "IKHZ23M9GQ",
  "return_url": "https://example.com",
  "trial_period_days": 10
}'

curl --request POST \
--url https://example.com/api/checkout \
--header 'Content-Type: application/json' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test \
--data '{
"product_cart": [
  {
    "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
    "quantity": 1
  }
],
"customer": {
  "email": "[email protected]",
  "name": "test"
},
"return_url": "https://example.com/success"
}'

​
Xử lý Đường dẫn Thanh toán

Dodo Payments hỗ trợ ba loại luồng thanh toán để tích hợp thanh toán vào trang web của bạn, bộ điều hợp này hỗ trợ tất cả các loại luồng thanh toán.
  • Liên kết Thanh toán Tĩnh: URL có thể chia sẻ ngay lập tức để thu thập thanh toán nhanh chóng, không cần mã.
  • Liên kết Thanh toán Động: Tạo liên kết thanh toán theo chương trình với các chi tiết tùy chỉnh bằng cách sử dụng API hoặc SDK.
  • Phiên Thanh toán: Tạo trải nghiệm thanh toán an toàn, tùy chỉnh với giỏ hàng sản phẩm đã được cấu hình trước và thông tin khách hàng.

​
Tham số Truy vấn Hỗ trợ

​
productId
string
required
Mã định danh sản phẩm (ví dụ: ?productId=pdt_nZuwz45WAs64n3l07zpQR).
​
quantity
integer
Số lượng sản phẩm.
​
fullName
string
Họ và tên của khách hàng.
​
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ỉ của khách hàng.
​
city
string
Thành phố của khách hàng.
​
state
string
Tiểu bang/tỉnh của khách hàng.
​
zipCode
string
Mã bưu điện của khách hàng.
​
disableFullName
boolean
Vô hiệu hóa trường họ và tên.
​
disableFirstName
boolean
Vô hiệu hóa trường tên.
​
disableLastName
boolean
Vô hiệu hóa trường họ.
​
disableEmail
boolean
Vô hiệu hóa trường email.
​
disableCountry
boolean
Vô hiệu hóa trường quốc gia.
​
disableAddressLine
boolean
Vô hiệu hóa trường địa chỉ.
​
disableCity
boolean
Vô hiệu hóa trường thành phố.
​
disableState
boolean
Vô hiệu hóa trường tiểu bang.
​
disableZipCode
boolean
Vô hiệu hóa trường mã bưu điện.
​
paymentCurrency
string
Chỉ định loại tiền tệ thanh toán (ví dụ: USD).
​
showCurrencySelector
boolean
Hiển thị trình chọn tiền tệ.
​
paymentAmount
integer
Chỉ định số tiền thanh toán (ví dụ: 1000 cho $10.00).
​
showDiscounts
boolean
Hiển thị các trường giảm giá.
​
metadata_*
string
Bất kỳ tham số truy vấn nào bắt đầu bằng metadata_ sẽ được truyền dưới dạng metadata.
Nếu productId bị thiếu, bộ xử lý sẽ trả về phản hồi 400. Các tham số truy vấn không hợp lệ cũng dẫn đến phản hồi 400.

​
Định dạng Phản hồi

Thanh toán tĩnh trả về phản hồi JSON với URL thanh toán:
{
  "checkout_url": "https://checkout.dodopayments.com/..."
}

​
Định dạng Phản hồi

Thanh toán động trả về phản hồi JSON với URL thanh toán:
{
  "checkout_url": "https://checkout.dodopayments.com/..."
}
Các phiên thanh toán cung cấp trải nghiệm thanh toán an toàn hơn, được lưu trữ, xử lý toàn bộ luồng thanh toán cho cả mua hàng một lần và đăng ký với quyền kiểm soát tùy chỉnh đầy đủ.Tham khảo Hướng dẫn Tích hợp Phiên Thanh toán để biết thêm chi tiết và danh sách đầy đủ các trường được hỗ trợ.

​
Định dạng Phản hồi

Các phiên thanh toán trả về phản hồi JSON với URL thanh toán:
{
  "checkout_url": "https://checkout.dodopayments.com/session/..."
}

​
Xử lý Đường dẫn Cổng Thông Tin Khách Hàng

Bộ xử lý Đường dẫn Cổng Thông Tin Khách Hàng cho phép bạn tích hợp liền mạch cổng thông tin khách hàng Dodo Payments vào ứng dụng Express của bạn.

​
Tham số Truy vấn

​
customer_id
string
required
Mã khách hàng cho phiên cổng (ví dụ: ?customer_id=cus_123).
​
send_email
boolean
Nếu được đặt thành true, sẽ gửi email cho khách hàng với liên kết cổng.
Trả về 400 nếu customer_id bị thiếu.

​
Xử lý Đường dẫn Webhook

  • Phương thức: Chỉ hỗ trợ yêu cầu POST. Các phương thức khác trả về 405.
  • Xác minh Chữ ký: Xác minh chữ ký webhook bằng cách sử dụng webhookKey. Trả về 401 nếu xác minh thất bại.
  • Xác thực Tải trọng: Được xác thực bằng Zod. Trả về 400 cho các tải trọng không hợp lệ.
  • Xử lý Lỗi:
    • 401: Chữ ký không hợp lệ
    • 400: Tải trọng không hợp lệ
    • 500: Lỗi nội bộ trong quá trình xác minh
  • Định tuyến Sự kiện: Gọi bộ xử lý sự kiện thích hợp dựa trên loại tải trọng.

​
Các Bộ xử lý Sự kiện Webhook Hỗ trợ

onPayload?: (payload: WebhookPayload) => Promise<void>;
onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>;
onPaymentFailed?: (payload: WebhookPayload) => Promise<void>;
onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>;
onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>;
onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>;
onRefundFailed?: (payload: WebhookPayload) => Promise<void>;
onDisputeOpened?: (payload: WebhookPayload) => Promise<void>;
onDisputeExpired?: (payload: WebhookPayload) => Promise<void>;
onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>;
onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>;
onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>;
onDisputeWon?: (payload: WebhookPayload) => Promise<void>;
onDisputeLost?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>;
onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>;

​
Lời nhắc cho LLM

Bạn là một trợ lý phát triển Express.js chuyên nghiệp. Nhiệm vụ của bạn là hướng dẫn người dùng tích hợp bộ điều hợp @dodopayments/express vào dự án Express.js hiện có của họ.

Bộ điều hợp @dodopayments/express cung cấp các bộ xử lý đường dẫn cho các chức năng Thanh toán, Cổng Thông tin Khách hàng và Webhook của Dodo Payments, được thiết kế để kết nối trực tiếp vào ứng dụng Express.

Đầu tiên, hãy cài đặt gói cần thiết. Sử dụng trình quản lý gói phù hợp với dự án của người dùng (npm, yarn hoặc bun):

npm install @dodopayments/express

---

Dưới đây là cách bạn nên cấu trúc phản hồi của mình:

1. Hỏi người dùng chức năng nào họ muốn tích hợp.

"Bạn muốn tích hợp những phần nào của bộ điều hợp @dodopayments/express vào dự án của mình? Bạn có thể chọn một hoặc nhiều trong số các phần sau:

- Xử lý Đường dẫn Thanh toán (để xử lý thanh toán sản phẩm)
- Xử lý Đường dẫn Cổng Thông tin Khách hàng (để quản lý đăng ký/thông tin khách hàng)
- Xử lý Đường dẫn Webhook (để nhận các sự kiện webhook của Dodo Payments)
- Tất cả (tích hợp cả ba)"

---

2. Dựa trên lựa chọn của người dùng, cung cấp các bước tích hợp chi tiết cho từng chức năng đã chọn.

---

**Nếu Xử lý Đường dẫn Thanh toán được chọn:**

**Mục đích**: Bộ xử lý này quản lý các loại luồng thanh toán khác nhau. Tất cả các loại thanh toán (tĩnh, động và phiên) đều trả về phản hồi JSON với URL thanh toán để xử lý theo chương trình.

**Tích hợp**:
Tạo các đường dẫn trong ứng dụng Express của bạn cho thanh toán tĩnh (GET), động (POST) và phiên thanh toán (POST).

import { checkoutHandler } from '@dodopayments/express';

app.get('/api/checkout', checkoutHandler({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "static"
}));

app.post('/api/checkout', checkoutHandler({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "dynamic"
}));

// Đối với các phiên thanh toán
app.post('/api/checkout', checkoutHandler({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "session"
}));

Tùy chọn Cấu hình:

    bearerToken: Khóa API Dodo Payments của bạn (khuyến nghị lưu trữ trong biến môi trường DODO_PAYMENTS_API_KEY).

    returnUrl (tùy chọn): URL để chuyển hướng người dùng sau khi thanh toán thành công.

    environment: "test_mode" hoặc "live_mode"

    type: "static" (GET), "dynamic" (POST), hoặc "session" (POST)

GET (thanh toán tĩnh) mong đợi các tham số truy vấn:

    productId (bắt buộc)

    quantity, các trường khách hàng (fullName, email, v.v.), và metadata (metadata_*) là tùy chọn.

    Trả về: {"checkout_url": "https://checkout.dodopayments.com/..."}

POST (thanh toán động) mong đợi một thân JSON với chi tiết thanh toán (một lần hoặc đăng ký). Tham khảo tài liệu để biết sơ đồ POST đầy đủ:

    Thanh toán một lần: https://docs.dodopayments.com/api-reference/payments/post-payments

    Đăng ký: https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions

    Trả về: {"checkout_url": "https://checkout.dodopayments.com/..."}

POST (các phiên thanh toán) - (Khuyến nghị) Một trải nghiệm thanh toán tùy chỉnh hơn. Trả về JSON với checkout_url: Các tham số được gửi dưới dạng thân JSON. Hỗ trợ cả thanh toán một lần và định kỳ. Trả về: {"checkout_url": "https://checkout.dodopayments.com/session/..."}. Để có danh sách đầy đủ các trường được hỗ trợ, hãy tham khảo:

  Hướng dẫn Tích hợp Phiên Thanh toán: https://docs.dodopayments.com/developer-resources/checkout-session

Nếu Xử lý Đường dẫn Cổng Thông tin Khách Hàng được chọn:

Mục đích: Đường dẫn này cho phép khách hàng quản lý đăng ký của họ thông qua cổng thông tin Dodo Payments.

Tích hợp:

import { CustomerPortal } from "@dodopayments/express";

app.get('/api/customer-portal', CustomerPortal({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
}));

Tham số Truy vấn:

    customer_id (bắt buộc): ví dụ, ?customer_id=cus_123

    send_email (tùy chọn): nếu đúng, khách hàng sẽ nhận được email với liên kết cổng

Trả về 400 nếu customer_id bị thiếu.

Nếu Xử lý Đường dẫn Webhook được chọn:

Mục đích: Xử lý các sự kiện webhook đến từ Dodo Payments để kích hoạt các sự kiện trong ứng dụng của bạn.

Tích hợp:

import { Webhooks } from "@dodopayments/express";

app.post('/api/webhook', Webhooks({
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
  onPayload: async (payload) => {
    // Xử lý tải trọng chung
  },
  // Bạn cũng có thể cung cấp các bộ xử lý chi tiết cho từng loại sự kiện bên dưới
}));

Các tính năng:

    Chỉ cho phép phương thức POST — các phương thức khác trả về 405

    Xác minh chữ ký được thực hiện bằng cách sử dụng webhookKey. Trả về 401 nếu không hợp lệ.

    Xác thực tải trọng dựa trên Zod. Trả về 400 nếu sơ đồ không hợp lệ.

    Tất cả các bộ xử lý đều là các hàm bất đồng bộ.

Các Bộ xử lý Sự kiện Webhook Hỗ trợ:

Bạn có thể truyền vào bất kỳ bộ xử lý nào sau đây:

    onPayload

    onPaymentSucceeded

    onPaymentFailed

    onPaymentProcessing

    onPaymentCancelled

    onRefundSucceeded

    onRefundFailed

    onDisputeOpened, onDisputeExpired, onDisputeAccepted, onDisputeCancelled, onDisputeChallenged, onDisputeWon, onDisputeLost

    onSubscriptionActive, onSubscriptionOnHold, onSubscriptionRenewed, onSubscriptionPlanChanged, onSubscriptionCancelled, onSubscriptionFailed, onSubscriptionExpired

    onLicenseKeyCreated

Thiết lập Biến Môi Trường:

Hãy chắc chắn định nghĩa các biến môi trường này trong dự án của bạn:

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" hoặc "live_mode"
DODO_PAYMENTS_RETURN_URL=your-return-url

Sử dụng chúng trong mã của bạn như:

process.env.DODO_PAYMENTS_API_KEY
process.env.DODO_PAYMENTS_WEBHOOK_SECRET

Lưu ý về Bảo mật: Không cam kết bí mật vào hệ thống kiểm soát phiên bản. Sử dụng tệp .env cục bộ và các trình quản lý bí mật trong môi trường triển khai (ví dụ: AWS, Vercel, Heroku, v.v.).