Panduan Integrasi Langganan

​

Prasyarat

• Akun merchant Dodo Payments
• API key dari Developer → API Keys di dashboard, disimpan di DODO_PAYMENTS_API_KEY
• Secret webhook dari Developer → Webhooks, disimpan di DODO_PAYMENTS_WEBHOOK_KEY
• Setidaknya satu produk subscription yang dibuat di Products

​

Integrasi API

​

Checkout Sessions

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 session = await client.checkoutSessions.create({
    product_cart: [
      { product_id: 'pdt_subscription_monthly', quantity: 1 }
    ],
    // Optional: configure trials for subscription products
    subscription_data: { trial_period_days: 14 },
    customer: {
      email: 'subscriber@example.com',
      name: 'Jane Doe',
    },
    return_url: 'https://example.com/success',
  });

  console.log(session.checkout_url);
}

main();

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_subscription_monthly", "quantity": 1}
    ],
    subscription_data={"trial_period_days": 14},  # optional
    customer={
        "email": "subscriber@example.com",
        "name": "Jane Doe",
    },
    return_url="https://example.com/success",
)

print(session.checkout_url)

const response = await fetch('https://test.dodopayments.com/checkouts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`
  },
  body: JSON.stringify({
    product_cart: [
      { product_id: 'pdt_subscription_monthly', quantity: 1 }
    ],
    subscription_data: { trial_period_days: 14 }, // optional
    customer: {
      email: 'subscriber@example.com',
      name: 'Jane Doe'
    },
    return_url: 'https://example.com/success'
  })
});

if (!response.ok) {
  throw new Error(`HTTP error! status: ${response.status}`);
}

const session = await response.json();
console.log(session.checkout_url);

​

Respons API

{
  "session_id": "cks_Gi6KGJ2zFJo9rq9Ukifwa",
  "checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"
}

​

Webhook

​

Jenis Peristiwa Subscription

1. subscription.active — Subscription diaktifkan
2. subscription.updated — Sebuah field pada subscription berubah
3. subscription.on_hold — Tagihan renewal atau perubahan plan gagal
4. subscription.failed — Pembuatan subscription gagal (terminal; pelanggan harus berlangganan kembali)
5. subscription.renewed — Tagihan berkala berhasil
6. subscription.past_due — Renewal gagal dan masa tenggang dimulai; pelanggan tetap memiliki akses hingga past_due_ends_at
7. subscription.plan_changed — Plan ditingkatkan, diturunkan, atau diubah
8. subscription.cancelled — Subscription dibatalkan
9. subscription.expired — Subscription mencapai akhir masa berlakunya

​

Skenario Pembayaran

1. subscription.active: mandat diotorisasi dan subscription diaktifkan.
2. payment.succeeded: mengonfirmasi tagihan pertama. Peristiwa ini biasanya diterima dalam 2–10 menit setelah checkout.

1. Saat trial dimulai (checkout): subscription.active dipicu setelah metode pembayaran diotorisasi. Belum ada tagihan berkala yang diambil. Tagihan pertama ditunda hingga trial berakhir.
2. Saat trial berakhir: jumlah berkala ditagihkan, dan Anda menerima payment.succeeded bersama dengan subscription.renewed.

• subscription.renewed: dipicu pada setiap siklus penagihan saat pembayaran renewal dipotong, selalu bersama payment.succeeded. Peristiwa ini juga membawa next_billing_date yang telah diperbarui.

1. Kegagalan Subscription

• subscription.failed - Pembuatan subscription gagal karena mandat tidak berhasil dibuat.
• payment.failed - Menunjukkan pembayaran gagal.

2. Subscription Ditangguhkan

• subscription.on_hold - Subscription ditangguhkan karena pembayaran renewal atau tagihan perubahan plan gagal. Jika bisnis Anda memiliki masa tenggang, renewal yang gagal terlebih dahulu memindahkan subscription ke past_due (subscription.past_due), lalu memindahkannya ke on_hold (atau cancelled, bergantung pada pengaturan masa tenggang) hanya setelah masa tenggang berakhir. Lihat Status Subscription.
• Saat subscription ditangguhkan, subscription tidak akan diperbarui secara otomatis hingga metode pembayaran diperbarui.

​

subscription.failed vs. subscription.on_hold

​

Menangani Subscription yang Ditangguhkan

​

Kapan Subscription Ditangguhkan

• Pembayaran renewal gagal: Tagihan renewal otomatis gagal karena dana tidak mencukupi, kartu kedaluwarsa, atau penolakan bank
• Tagihan perubahan plan gagal: Tagihan langsung saat upgrade/downgrade plan gagal
• Otorisasi metode pembayaran gagal: Metode pembayaran tidak dapat diotorisasi untuk tagihan berkala

​

Mengaktifkan Kembali Subscription yang Ditangguhkan

1. Membuat tagihan untuk kewajiban yang tersisa
2. Membuat invoice untuk tagihan tersebut
3. Memproses pembayaran menggunakan metode pembayaran baru
4. Mengaktifkan kembali subscription ke status active setelah pembayaran berhasil

// Webhook handler
app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;
  
  if (event.type === 'subscription.on_hold') {
    const subscription = event.data;
    
    // Update subscription status in your database
    await updateSubscriptionStatus(subscription.subscription_id, 'on_hold');
    
    // Notify customer to update payment method
    await sendEmailToCustomer(subscription.customer_id, {
      subject: 'Payment Required - Subscription On Hold',
      message: 'Your subscription is on hold. Please update your payment method to continue service.'
    });
  }
  
  res.json({ received: true });
});

// Update with new payment method
const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
  payment_method: { type: 'new', return_url: 'https://example.com/return' }
});

// For on_hold subscriptions, a charge is automatically created
if (response.payment_id) {
  console.log('Charge created for remaining dues:', response.payment_id);
  // Redirect customer to response.payment_link to complete payment
}

# Update with new payment method
response = client.subscriptions.update_payment_method(
    subscription_id=subscription_id,
    payment_method={"type": "new", "return_url": "https://example.com/return"},
)

# For on_hold subscriptions, a charge is automatically created
if response.payment_id:
    print("Charge created for remaining dues:", response.payment_id)
    # Redirect customer to response.payment_link to complete payment

await client.subscriptions.updatePaymentMethod(subscriptionId, {
  payment_method: { type: 'existing', payment_method_id: 'pm_abc123' }
});

if (event.type === 'payment.succeeded') {
  const payment = event.data;
  
  // Check if this payment is for an on_hold subscription
  if (payment.subscription_id) {
    // Wait for subscription.active webhook to confirm reactivation
  }
}

if (event.type === 'subscription.active') {
  const subscription = event.data;
  
  // Update subscription status in your database
  await updateSubscriptionStatus(subscription.subscription_id, 'active');
  
  // Restore customer access
  await restoreCustomerAccess(subscription.customer_id);
  
  // Notify customer of successful reactivation
  await sendEmailToCustomer(subscription.customer_id, {
    subject: 'Subscription Reactivated',
    message: 'Your subscription has been reactivated successfully.'
  });
}

​

Contoh Payload Peristiwa Subscription

​

Mengubah Plan Subscription

​

Opsi Proration

​

1. prorated_immediately

• Mengkredit bagian siklus penagihan saat ini yang tidak terpakai, dengan prorata berdasarkan sisa waktu. Kredit mencakup base plan, kuantitas, dan add-on
• Kemudian menagih satu siklus penuh dengan plan, kuantitas, dan add-on baru. Tagihan itu sendiri tidak pernah diprorata
• Tagihan langsung bersih = (siklus baru penuh) dikurangi (fraksi tersisa x siklus lama penuh). Jika kredit lebih besar, selisihnya ditahan sebagai kredit dalam cakupan subscription untuk renewal mendatang
• Selama periode trial, opsi ini segera memindahkan pengguna ke plan baru dan langsung menagih pelanggan

​

2. full_immediately

• Menagih pelanggan sejumlah penuh subscription untuk plan baru tanpa kredit untuk siklus sebelumnya
• Baik saat upgrade maupun downgrade, pelanggan membayar seluruh harga plan baru dari awal
• Berguna jika Anda ingin menagih jumlah penuh terlepas dari sisa waktu pada plan lama

​

3. difference_immediately

• Pelanggan hanya membayar selisih antara harga plan lama dan plan baru
• Jumlahnya tidak bergantung pada kapan perubahan dilakukan dalam siklus. Upgrade yang sama memiliki biaya yang sama pada hari ke-1 maupun hari ke-29
• Saat upgrade, pelanggan langsung ditagih selisihnya. Contoh, $30/bulan → $80/bulan = $50 langsung ditagihkan
• Saat downgrade, selisih harga disimpan sebagai kredit dalam cakupan subscription dan diterapkan secara otomatis pada renewal mendatang. Contoh, $50/bulan → $20/bulan = $30 disimpan sebagai kredit

​

4. do_not_bill

• Menerapkan perubahan plan segera tetapi tidak menagih apa pun saat perubahan dilakukan. Plan, kuantitas, dan add-on baru langsung dapat digunakan
• Karena tidak ada tagihan sekarang, upgrade memberikan plan yang lebih tinggi secara gratis kepada pelanggan selama sisa siklus saat ini. Downgrade berlaku segera tanpa kredit untuk bagian siklus yang belum digunakan dan telah dibayar
• Add-on yang diberikan melalui do_not_bill tidak dikreditkan pada perubahan plan berikutnya karena add-on tersebut belum pernah ditagihkan. Perubahan berikutnya menagih jumlah add-on baru secara penuh
• Plan yang diperbarui (beserta kuantitas/add-on) ditagihkan pada renewal terjadwal berikutnya, dan tanggal penagihan asli dipertahankan

​

Perilaku

• Saat Anda memanggil API ini, Dodo Payments segera memulai tagihan berdasarkan opsi proration yang dipilih
• Dengan prorated_immediately, kredit untuk bagian siklus saat ini yang tidak terpakai dihitung pada setiap perubahan, baik upgrade maupun downgrade. Jika kredit tersebut melebihi tagihan siklus baru, sisanya ditambahkan ke saldo kredit subscription. Kredit ini khusus untuk subscription tersebut dan hanya digunakan untuk mengimbangi pembayaran berkala mendatang dari subscription yang sama
• Dengan difference_immediately, nilai bersih selalu sama persis dengan selisih harga. Untuk downgrade, kelebihannya disimpan sebagai kredit dalam cakupan subscription, sama seperti prorated_immediately
• Opsi full_immediately melewati perhitungan kredit dan menagih jumlah plan baru secara lengkap
• Opsi do_not_bill menerapkan perubahan segera tetapi menunda penagihan hingga tanggal renewal berikutnya, yang tetap dipertahankan

​

Pemrosesan Tagihan

• Tagihan langsung yang dimulai setelah perubahan plan biasanya selesai diproses dalam waktu kurang dari 2 menit
• Jika tagihan langsung ini gagal karena alasan apa pun, subscription secara otomatis ditangguhkan hingga masalah terselesaikan

​

Subscription On-Demand

​

Hal Penting yang Perlu Diketahui tentang Penagihan Subscription

​

Referensi API Terkait