Đăng ký theo yêu cầu

​

Tổng quan

• Tạo một đăng ký theo yêu cầu (ủy quyền một mệnh lệnh với giá ban đầu tùy chọn)
• Kích hoạt các khoản phí tiếp theo với số tiền tùy chỉnh
• Theo dõi kết quả bằng cách sử dụng webhook

​

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

• Tài khoản thương nhân Dodo Payments và khóa API
• Bí mật webhook được cấu hình và một điểm cuối để nhận sự kiện
• Một sản phẩm đăng ký trong danh mục của bạn

​

Cách thức hoạt động của đăng ký theo yêu cầu

1. Bạn tạo một đăng ký với đối tượng on_demand để ủy quyền một phương thức thanh toán và tùy chọn thu phí ban đầu.
2. Sau đó, bạn tạo các khoản phí chống lại đăng ký đó với số tiền tùy chỉnh bằng cách sử dụng điểm cuối phí chuyên dụng.
3. Bạn lắng nghe các webhook (ví dụ: payment.succeeded, payment.failed) để cập nhật hệ thống của bạn.

​

Tạo một đăng ký theo yêu cầu

​

Tạo một đăng ký theo yêu cầu

import DodoPayments from 'dodopayments';

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

async function main() {
  const subscription = await client.subscriptions.create({
    billing: { city: 'SF', country: 'US', state: 'CA', street: '1 Market St', zipcode: '94105' },
    customer: { customer_id: 'customer_123' },
    product_id: 'prod_sub_123',
    quantity: 1,
    payment_link: true,
    return_url: 'https://example.com/billing/success',
    on_demand: {
      mandate_only: true, // set false to collect an initial charge
      // product_price: 1000, // optional: charge $10.00 now if mandate_only is false
      // product_currency: 'USD',
      // product_description: 'Custom initial charge',
      // adaptive_currency_fees_inclusive: false,
    },
  });

  // If payment_link was true, redirect the customer to authorize the mandate
  console.log(subscription.payment_link);
}

main().catch(console.error);

import os
from dodopayments import DodoPayments

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

subscription = client.subscriptions.create(
    billing={
        "city": "SF",
        "country": "US",
        "state": "CA",
        "street": "1 Market St",
        "zipcode": "94105",
    },
    customer={"customer_id": "customer_123"},
    product_id="prod_sub_123",
    quantity=1,
    payment_link=True,
    return_url="https://example.com/billing/success",
    on_demand={
        "mandate_only": True,
        # "product_price": 1000,
        # "product_currency": "USD",
        # "product_description": "Custom initial charge",
        # "adaptive_currency_fees_inclusive": False,
    },
)

print(subscription.payment_link)

package main

import (
  "context"
  "fmt"
  "github.com/dodopayments/dodopayments-go"
  "github.com/dodopayments/dodopayments-go/option"
)

func main() {
  client := dodopayments.NewClient(
    option.WithBearerToken("YOUR_API_KEY"),
  )
  subscription, err := client.Subscriptions.New(context.TODO(), dodopayments.SubscriptionNewParams{
    Billing: dodopayments.F(dodopayments.BillingAddressParam{
      City:    dodopayments.F("SF"),
      Country: dodopayments.F(dodopayments.CountryCodeUs),
      State:   dodopayments.F("CA"),
      Street:  dodopayments.F("1 Market St"),
      Zipcode: dodopayments.F("94105"),
    }),
    Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](dodopayments.AttachExistingCustomerParam{
      CustomerID: dodopayments.F("customer_123"),
    }),
    ProductID:  dodopayments.F("prod_sub_123"),
    Quantity:   dodopayments.F(int64(1)),
    PaymentLink: dodopayments.F(true),
    ReturnURL:   dodopayments.F("https://example.com/billing/success"),
    OnDemand: dodopayments.F(dodopayments.OnDemandSubscriptionReqParam{
      MandateOnly: dodopayments.F(true),
      // ProductPrice: dodopayments.F(int64(1000)),
      // ProductCurrency: dodopayments.F(dodopayments.CurrencyUsd),
      // ProductDescription: dodopayments.F("Custom initial charge"),
      // AdaptiveCurrencyFeesInclusive: dodopayments.F(false),
    }),
  })
  if err != nil { panic(err) }
  fmt.Println(subscription.PaymentLink)
}

curl -X POST "$DODO_API/subscriptions" \
  -H "Authorization: Bearer $DODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "billing": {"city": "SF", "country": "US", "state": "CA", "street": "1 Market St", "zipcode": "94105"},
    "customer": {"customer_id": "customer_123"},
    "product_id": "prod_sub_123",
    "quantity": 1,
    "payment_link": true,
    "return_url": "https://example.com/billing/success",
    "on_demand": {
      "mandate_only": true
    }
  }'

{
  "subscription_id": "sub_123",
  "payment_link": "https://pay.dodopayments.com/checkout/...",
  "customer": { "customer_id": "customer_123", "email": "[email protected]", "name": "Alex Doe" },
  "metadata": {},
  "recurring_pre_tax_amount": 0,
  "addons": []
}

​

Tính phí cho một đăng ký theo yêu cầu

import DodoPayments from 'dodopayments';

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

async function chargeNow(subscriptionId) {
  const res = await client.subscriptions.charge(subscriptionId, { product_price: 2500 });
  console.log(res.payment_id);
}

chargeNow('sub_123').catch(console.error);

import os
from dodopayments import DodoPayments

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

response = client.subscriptions.charge(
    subscription_id="sub_123",
    product_price=2500,
)

print(response.payment_id)

package main

import (
  "context"
  "fmt"
  "github.com/dodopayments/dodopayments-go"
  "github.com/dodopayments/dodopayments-go/option"
)

func main() {
  client := dodopayments.NewClient(option.WithBearerToken("YOUR_API_KEY"))
  res, err := client.Subscriptions.Charge(context.TODO(), "sub_123", dodopayments.SubscriptionChargeParams{
    ProductPrice: dodopayments.F(int64(2500)),
  })
  if err != nil { panic(err) }
  fmt.Println(res.PaymentID)
}

curl -X POST "$DODO_API/subscriptions/sub_123/charge" \
  -H "Authorization: Bearer $DODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_price": 2500,
    "product_description": "Extra usage for March"
  }'

{ "payment_id": "pay_abc123" }

​

Thử lại thanh toán

​

Nguyên tắc cho các chính sách thử lại an toàn

• Cơ chế lùi: Sử dụng lùi theo cấp số nhân giữa các lần thử lại.
• Giới hạn thử lại: Giới hạn tổng số lần thử lại (tối đa 3–4 lần).
• Lọc thông minh: Chỉ thử lại khi gặp lỗi có thể thử lại (ví dụ: lỗi mạng/nhà phát hành, không đủ tiền); không bao giờ thử lại các từ chối cứng.
• Ngăn chặn thử nghiệm thẻ: Không thử lại các lỗi như DO_NOT_HONOR, STOLEN_CARD, LOST_CARD, PICKUP_CARD, FRAUDULENT, AUTHENTICATION_FAILURE.
• Thay đổi metadata (tùy chọn): Nếu bạn duy trì hệ thống thử lại của riêng mình, phân biệt các lần thử lại qua metadata (ví dụ: retry_attempt).

​

Lịch trình thử lại đề xuất (đăng ký)

• Lần thử lại đầu tiên: Ngay lập tức khi bạn tạo khoản phí
• Lần thử lại thứ hai: Sau 3 ngày
• Lần thử lại thứ ba: Sau 7 ngày nữa (tổng cộng 10 ngày)
• Lần thử lại thứ tư (cuối cùng): Sau 7 ngày nữa (tổng cộng 17 ngày)

​

Tránh các thử lại bùng nổ; căn chỉnh theo thời gian ủy quyền

• Gắn các lần thử lại vào dấu thời gian ủy quyền ban đầu để tránh hành vi “bùng nổ” trên toàn bộ danh mục của bạn.
• Ví dụ: Nếu khách hàng bắt đầu một thử nghiệm hoặc mệnh lệnh vào lúc 1:10 chiều hôm nay, hãy lên lịch các lần thử lại tiếp theo vào lúc 1:10 chiều trong các ngày tiếp theo theo lịch lùi của bạn (ví dụ: +3 ngày → 1:10 chiều, +7 ngày → 1:10 chiều).
• Ngoài ra, nếu bạn lưu thời gian thanh toán thành công cuối cùng T, hãy lên lịch lần thử tiếp theo vào T + X days để duy trì sự căn chỉnh theo thời gian trong ngày.

​

Mã từ chối bạn không nên thử lại

• STOLEN_CARD
• DO_NOT_HONOR
• FRAUDULENT
• PICKUP_CARD
• AUTHENTICATION_FAILURE
• LOST_CARD

​

Hướng dẫn triển khai (không có mã)

• Sử dụng một bộ lập lịch/ hàng đợi mà duy trì các dấu thời gian chính xác; tính toán lần thử tiếp theo tại thời điểm chính xác (ví dụ: T + 3 days vào cùng một HH:MM).
• Duy trì và tham chiếu dấu thời gian thanh toán thành công cuối cùng T để tính toán lần thử tiếp theo; không gom nhiều đăng ký vào cùng một thời điểm.
• Luôn đánh giá lý do từ chối cuối cùng; dừng thử lại cho các từ chối cứng trong danh sách bỏ qua ở trên.
• Giới hạn số lần thử lại đồng thời theo khách hàng và theo tài khoản để ngăn chặn các đợt tăng đột biến không mong muốn.
• Giao tiếp chủ động: gửi email/SMS cho khách hàng để cập nhật phương thức thanh toán của họ trước lần thử tiếp theo đã lên lịch.
• Sử dụng metadata chỉ để quan sát (ví dụ: retry_attempt); không bao giờ cố gắng “tránh” các hệ thống gian lận/rủi ro bằng cách xoay vòng các trường không quan trọng.

​

Theo dõi kết quả với webhook

• subscription.active: Mệnh lệnh đã được ủy quyền và đăng ký đã được kích hoạt
• subscription.failed: Tạo không thành công (ví dụ: thất bại mệnh lệnh)
• subscription.on_hold: Đăng ký bị tạm hoãn (ví dụ: trạng thái chưa thanh toán)
• payment.succeeded: Tính phí thành công
• payment.failed: Tính phí thất bại

​

Kiểm tra và các bước tiếp theo

​

Khắc phục sự cố

• 422 Yêu cầu không hợp lệ: Đảm bảo on_demand.mandate_only được cung cấp khi tạo và product_price được cung cấp cho các khoản phí.
• Lỗi tiền tệ: Nếu bạn ghi đè product_currency, xác nhận rằng nó được hỗ trợ cho tài khoản và khách hàng của bạn.
• Không nhận được webhook: Xác minh URL webhook và cấu hình bí mật chữ ký.