Langganan Sesuai Permintaan

​

Ikhtisar

• Membuat langganan sesuai permintaan (mengotorisasi mandat dengan harga awal opsional)
• Memicu biaya berikutnya dengan jumlah kustom
• Melacak hasil menggunakan webhook

​

Prasyarat

• Akun pedagang Dodo Payments dan kunci API
• Rahasia webhook yang dikonfigurasi dan endpoint untuk menerima peristiwa
• Produk langganan dalam katalog Anda

​

Cara kerja sesuai permintaan

1. Anda membuat langganan dengan objek on_demand untuk mengotorisasi metode pembayaran dan secara opsional mengumpulkan biaya awal.
2. Kemudian, Anda membuat biaya terhadap langganan tersebut dengan jumlah kustom menggunakan endpoint biaya khusus.
3. Anda mendengarkan webhook (misalnya, payment.succeeded, payment.failed) untuk memperbarui sistem Anda.

​

Buat langganan sesuai permintaan

​

Buat langganan sesuai permintaan

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": []
}

​

Kenakan biaya langganan sesuai permintaan

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" }

​

Pengulangan pembayaran

​

Prinsip untuk kebijakan pengulangan yang aman

• Mekanisme penundaan: Gunakan penundaan eksponensial antara pengulangan.
• Batas pengulangan: Batasi total pengulangan (maksimal 3–4 percobaan).
• Penyaringan cerdas: Hanya ulangi pada kegagalan yang dapat diulang (misalnya, kesalahan jaringan/penerbit, dana tidak mencukupi); jangan pernah ulangi penolakan keras.
• Pencegahan pengujian kartu: Jangan ulangi kegagalan seperti DO_NOT_HONOR, STOLEN_CARD, LOST_CARD, PICKUP_CARD, FRAUDULENT, AUTHENTICATION_FAILURE.
• Variasi metadata (opsional): Jika Anda mempertahankan sistem pengulangan Anda sendiri, bedakan pengulangan melalui metadata (misalnya, retry_attempt).

​

Jadwal pengulangan yang disarankan (langganan)

• Percobaan pertama: Segera setelah Anda membuat biaya
• Percobaan kedua: Setelah 3 hari
• Percobaan ketiga: Setelah 7 hari lagi (total 10 hari)
• Percobaan keempat (akhir): Setelah 7 hari lagi (total 17 hari)

​

Hindari pengulangan mendadak; sesuaikan dengan waktu otorisasi

• Jangkar pengulangan pada cap waktu otorisasi asli untuk menghindari perilaku “ledakan” di seluruh portofolio Anda.
• Contoh: Jika pelanggan memulai percobaan atau mandat pada pukul 1:10 siang hari ini, jadwalkan pengulangan berikutnya pada pukul 1:10 siang pada hari-hari berikutnya sesuai dengan penundaan Anda (misalnya, +3 hari → 1:10 siang, +7 hari → 1:10 siang).
• Sebagai alternatif, jika Anda menyimpan waktu pembayaran terakhir yang berhasil T, jadwalkan percobaan berikutnya pada T + X days untuk mempertahankan penyelarasan waktu-hari.

​

Kode penolakan yang sebaiknya tidak Anda ulangi

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

​

Pedoman implementasi (tanpa kode)

• Gunakan penjadwal/antrian yang mempertahankan cap waktu yang tepat; hitung percobaan berikutnya pada offset waktu-hari yang tepat (misalnya, T + 3 days pada HH:MM yang sama).
• Pertahankan dan rujuk cap waktu pembayaran terakhir yang berhasil T untuk menghitung percobaan berikutnya; jangan mengelompokkan beberapa langganan pada saat yang sama.
• Selalu evaluasi alasan penolakan terakhir; hentikan pengulangan untuk penolakan keras dalam daftar lewati di atas.
• Batasi pengulangan bersamaan per pelanggan dan per akun untuk mencegah lonjakan yang tidak disengaja.
• Komunikasikan secara proaktif: email/SMS pelanggan untuk memperbarui metode pembayaran mereka sebelum percobaan berikutnya yang dijadwalkan.
• Gunakan metadata hanya untuk observabilitas (misalnya, retry_attempt); jangan pernah mencoba untuk “menghindari” sistem penipuan/risiko dengan memutar bidang yang tidak penting.

​

Lacak hasil dengan webhook

• subscription.active: Mandat diotorisasi dan langganan diaktifkan
• subscription.failed: Pembuatan gagal (misalnya, kegagalan mandat)
• subscription.on_hold: Langganan ditangguhkan (misalnya, status tidak dibayar)
• payment.succeeded: Biaya berhasil
• payment.failed: Biaya gagal

​

Pengujian dan langkah selanjutnya

​

Pemecahan Masalah

• 422 Permintaan Tidak Valid: Pastikan on_demand.mandate_only disediakan saat pembuatan dan product_price disediakan untuk biaya.
• Kesalahan mata uang: Jika Anda mengganti product_currency, pastikan itu didukung untuk akun dan pelanggan Anda.
• Tidak ada webhook yang diterima: Verifikasi URL webhook dan konfigurasi rahasia tanda tangan.