Langganan - Dodo Payments Documentation

Langganan memungkinkan Anda menjual akses berkelanjutan dengan pembaruan otomatis. Gunakan siklus penagihan yang fleksibel, percobaan gratis, perubahan rencana, dan add-on untuk menyesuaikan harga untuk setiap pelanggan.

Tingkatkan & Turunkan

Kontrol perubahan rencana dengan prorata dan pembaruan kuantitas.

Langganan Sesuai Permintaan

Otorisasi mandat sekarang dan tarik biaya nanti dengan jumlah yang disesuaikan.

Portal Pelanggan

Biarkan pelanggan mengelola rencana, penagihan, dan pembatalan.

Webhook Langganan

Reaksi terhadap peristiwa siklus hidup seperti dibuat, diperbarui, dan dibatalkan.

Apa Itu Langganan?

Langganan adalah produk berulang yang dibeli pelanggan sesuai jadwal. Mereka ideal untuk:

Lisensi SaaS: Aplikasi, API, atau akses platform
Keanggotaan: Komunitas, program, atau klub
Konten digital: Kursus, media, atau konten premium
Rencana dukungan: SLA, paket keberhasilan, atau pemeliharaan

Manfaat Utama

Pendapatan yang dapat diprediksi: Penagihan berulang dengan pembaruan otomatis
Siklus fleksibel: Bulanan, tahunan, interval kustom, dan percobaan
Agilitas rencana: Prorata untuk peningkatan dan penurunan
Add-on dan kursi: Lampirkan peningkatan opsional yang dapat dihitung
Checkout yang mulus: Checkout yang dihosting dan portal pelanggan
Developer-first: API yang jelas untuk pembuatan, perubahan, dan pelacakan penggunaan

Membuat Langganan

Buat produk langganan di dasbor Dodo Payments Anda, lalu jual melalui checkout atau API Anda. Memisahkan produk dari langganan aktif memungkinkan Anda untuk memversioning harga, melampirkan add-on, dan melacak kinerja secara independen.

Pembuatan produk langganan

Konfigurasikan bidang di dasbor untuk mendefinisikan bagaimana langganan Anda dijual, diperbarui, dan ditagih. Bagian di bawah ini langsung memetakan apa yang Anda lihat di formulir pembuatan.

Detail produk

Nama Produk (wajib): Nama tampilan yang ditampilkan di checkout, portal pelanggan, dan faktur.
Deskripsi Produk (wajib): Pernyataan nilai yang jelas yang muncul di checkout dan faktur.
Gambar Produk (wajib): PNG/JPG/WebP hingga 3 MB. Digunakan di checkout dan faktur.
Merek: Kaitkan produk dengan merek tertentu untuk tema dan email.
Kategori Pajak (wajib): Pilih kategori (misalnya, SaaS) untuk menentukan aturan pajak.

Pilih kategori pajak yang paling akurat untuk memastikan pengumpulan pajak yang benar per wilayah.

Penetapan Harga

Tipe Penetapan Harga: Pilih Langganan (panduan ini). Alternatifnya adalah Pembayaran Tunggal dan Penagihan Berdasarkan Penggunaan.
Harga (wajib): Harga berulang dasar dengan mata uang.
Diskon yang Berlaku (%): Diskon persentase opsional yang diterapkan pada harga dasar; tercermin di checkout dan faktur.
Pembayaran ulang setiap (wajib): Interval untuk pembaruan, misalnya, setiap 1 Bulan. Pilih ritme (bulan atau tahun) dan kuantitas.
Periode Langganan (wajib): Total masa di mana langganan tetap aktif (misalnya, 10 Tahun). Setelah periode ini berakhir, pembaruan berhenti kecuali diperpanjang.
Hari Periode Percobaan (wajib): Atur panjang percobaan dalam hari. Gunakan 0 untuk menonaktifkan percobaan. Biaya pertama terjadi secara otomatis ketika percobaan berakhir.
Pilih add-on: Lampirkan hingga 3 add-on yang dapat dibeli pelanggan bersamaan dengan rencana dasar.

Mengubah harga pada produk aktif mempengaruhi pembelian baru. Langganan yang ada mengikuti pengaturan perubahan rencana dan prorata Anda.

Add-on sangat ideal untuk ekstra yang dapat dihitung seperti kursi atau penyimpanan. Anda dapat mengontrol kuantitas yang diizinkan dan perilaku prorata saat pelanggan mengubahnya.

Pengaturan Lanjutan

Harga Termasuk Pajak: Tampilkan harga termasuk pajak yang berlaku. Perhitungan pajak akhir masih bervariasi berdasarkan lokasi pelanggan.
Hasilkan kunci lisensi: Terbitkan kunci unik untuk setiap pelanggan setelah pembelian. Lihat panduan Kunci Lisensi.
Pengiriman Produk Digital: Kirim file atau konten secara otomatis setelah pembelian. Pelajari lebih lanjut di Pengiriman Produk Digital.
Metadata: Lampirkan pasangan kunci-nilai kustom untuk penandaan internal atau integrasi klien. Lihat Metadata.

Gunakan metadata untuk menyimpan pengidentifikasi dari sistem Anda (misalnya, accountId) sehingga Anda dapat mencocokkan peristiwa dan faktur nanti.

Percobaan Langganan

Percobaan memungkinkan pelanggan mengakses langganan tanpa pembayaran segera. Biaya pertama terjadi secara otomatis ketika percobaan berakhir.

Mengonfigurasi Percobaan

Atur Hari Periode Percobaan di bagian penetapan harga produk (gunakan 0 untuk menonaktifkan). Anda dapat menimpa ini saat membuat langganan:

// Via subscription creation
const subscription = await client.subscriptions.create({
  customer_id: 'cus_123',
  product_id: 'prod_monthly',
  trial_period_days: 14  // Overrides product's trial period
});

// Via checkout session
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'prod_monthly', quantity: 1 }],
  subscription_data: { trial_period_days: 14 }
});

Nilai trial_period_days harus antara 0 dan 10.000 hari.

Mendeteksi Status Percobaan

Saat ini, tidak ada bidang langsung untuk mendeteksi status percobaan. Berikut adalah solusi sementara yang memerlukan kueri pembayaran, yang tidak efisien. Kami sedang mengerjakan solusi yang lebih efisien.

Untuk menentukan apakah langganan sedang dalam percobaan, ambil daftar pembayaran untuk langganan tersebut. Jika ada tepat satu pembayaran dengan jumlah 0, langganan sedang dalam periode percobaan:

const subscription = await client.subscriptions.retrieve('sub_123');
const payments = await client.payments.list({
  subscription_id: subscription.subscription_id
});

// Check if subscription is in trial
const isInTrial = payments.items.length === 1 && 
                  payments.items[0].total_amount === 0;

Memperbarui Periode Percobaan

Perpanjang percobaan dengan memperbarui next_billing_date:

await client.subscriptions.update('sub_123', {
  next_billing_date: '2025-02-15T00:00:00Z'  // New trial end date
});

Anda tidak dapat mengatur next_billing_date ke waktu yang telah berlalu. Tanggal harus di masa depan.

Perubahan Rencana Langganan

Perubahan rencana memungkinkan Anda untuk meningkatkan atau menurunkan langganan, menyesuaikan kuantitas, atau bermigrasi ke produk yang berbeda. Setiap perubahan memicu biaya segera berdasarkan mode prorata yang Anda pilih.

Mode Prorata

Pilih bagaimana pelanggan ditagih saat mengubah rencana:

`prorated_immediately`

Biaya prorata berdasarkan waktu yang tersisa dalam siklus penagihan saat ini. Terbaik untuk penagihan yang adil yang memperhitungkan waktu yang tidak terpakai.

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

`difference_immediately`

Biaya selisih harga segera (peningkatan) atau menambahkan kredit untuk pembaruan mendatang (penurunan). Terbaik untuk skenario peningkatan/penurunan yang sederhana.

// Upgrade: charges $50 (difference between $30 and $80)
// Downgrade: credits remaining value, auto-applied to renewals
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
});

Kredit dari penurunan menggunakan difference_immediately bersifat terikat langganan dan diterapkan secara otomatis untuk pembaruan mendatang. Mereka berbeda dari Kredit Pelanggan.

`full_immediately`

Biaya jumlah penuh rencana baru segera, mengabaikan waktu yang tersisa. Terbaik untuk mengatur ulang siklus penagihan.

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_monthly',
  quantity: 1,
  proration_billing_mode: 'full_immediately'
});

Mengubah Rencana dengan Add-on

Modifikasi add-on saat mengubah rencana. Add-on termasuk dalam perhitungan prorata:

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [{ addon_id: 'addon_extra_seats', quantity: 2 }]  // Add add-ons
  // addons: []  // Empty array removes all existing add-ons
});

Perubahan rencana memicu biaya segera. Biaya yang gagal dapat memindahkan langganan ke status on_hold. Lacak perubahan melalui peristiwa webhook subscription.plan_changed.

Prabaca Perubahan Rencana

Sebelum berkomitmen pada perubahan rencana, prabaca biaya yang tepat dan langganan yang dihasilkan:

const preview = await client.subscriptions.previewChangePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

// Show customer the charge before confirming
console.log('You will be charged:', preview.immediate_charge.summary);

Prabaca API Perubahan Rencana

Prabaca perubahan rencana sebelum berkomitmen pada mereka.

Status Langganan

Langganan dapat berada dalam berbagai status sepanjang siklus hidupnya:

active: Langganan aktif dan akan diperbarui secara otomatis
on_hold: Langganan ditangguhkan karena pembayaran gagal. Pembaruan metode pembayaran diperlukan untuk mengaktifkan kembali
cancelled: Langganan dibatalkan dan tidak akan diperbarui
expired: Langganan telah mencapai tanggal akhir
pending: Langganan sedang dibuat atau diproses

Status Ditangguhkan

Langganan memasuki status on_hold ketika:

Pembayaran pembaruan gagal (dana tidak mencukupi, kartu kadaluarsa, dll.)
Biaya perubahan rencana gagal
Otorisasi metode pembayaran gagal

Ketika langganan berada dalam status on_hold, itu tidak akan diperbarui secara otomatis. Anda harus memperbarui metode pembayaran untuk mengaktifkan kembali langganan.

Mengaktifkan Kembali dari Ditangguhkan

Untuk mengaktifkan kembali langganan dari status on_hold, perbarui metode pembayaran. Ini secara otomatis:

Membuat biaya untuk tunggakan yang tersisa
Menghasilkan faktur
Memproses pembayaran menggunakan metode pembayaran baru
Mengaktifkan kembali langganan ke status active setelah pembayaran berhasil

// Reactivate subscription from on_hold
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  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:', response.payment_id);
  // Redirect customer to response.payment_link to complete payment
  // Monitor webhooks for payment.succeeded and subscription.active
}

Setelah berhasil memperbarui metode pembayaran untuk langganan on_hold, Anda akan menerima payment.succeeded diikuti oleh peristiwa webhook subscription.active.

Manajemen API

Buat langganan

Gunakan POST /subscriptions untuk membuat langganan secara programatis dari produk, dengan percobaan dan add-on opsional.

Referensi API

Lihat API pembuatan langganan.

Perbarui langganan

Gunakan PATCH /subscriptions/{id} untuk memperbarui kuantitas, membatalkan di akhir periode, atau memodifikasi metadata.

Referensi API

Pelajari cara memperbarui detail langganan.

Ubah rencana (prorata)

Ubah produk aktif dan kuantitas dengan kontrol prorata.

Referensi API

Tinjau opsi perubahan rencana.

Biaya sesuai permintaan

Untuk langganan sesuai permintaan, tarik jumlah tertentu sesuai permintaan.

Referensi API

Tarik langganan sesuai permintaan.

Daftar dan ambil

Gunakan GET /subscriptions untuk mendaftar semua langganan dan GET /subscriptions/{id} untuk mengambil satu.

Referensi API

Jelajahi API daftar dan pengambilan.

Riwayat penggunaan

Ambil penggunaan yang tercatat untuk model harga terukur atau hibrida.

Referensi API

Lihat API riwayat penggunaan.

Perbarui metode pembayaran

Perbarui metode pembayaran untuk langganan. Untuk langganan aktif, ini memperbarui metode pembayaran untuk pembaruan mendatang. Untuk langganan dalam status on_hold, ini mengaktifkan kembali langganan dengan membuat biaya untuk tunggakan yang tersisa.

Referensi API

Pelajari cara memperbarui metode pembayaran dan mengaktifkan kembali langganan.

Kasus Penggunaan Umum

SaaS dan API: Akses bertingkat dengan add-on untuk kursi atau penggunaan
Konten dan media: Akses bulanan dengan percobaan pengantar
Rencana dukungan B2B: Kontrak tahunan dengan add-on dukungan premium
Alat dan plugin: Kunci lisensi dan rilis versi

Contoh Integrasi

Sesi Checkout (langganan)

Saat membuat sesi checkout, sertakan produk langganan Anda dan add-on opsional:

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_subscription',
      quantity: 1
    }
  ]
});

Perubahan rencana dengan prorata

Tingkatkan atau turunkan langganan dan kontrol perilaku prorata:

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
});

Batalkan di akhir periode

Jadwalkan pembatalan tanpa penghentian akses segera:

await client.subscriptions.update('sub_123', {
  cancel_at_period_end: true
});

Langganan sesuai permintaan

Buat langganan sesuai permintaan dan tarik biaya nanti sesuai kebutuhan:

const onDemand = await client.subscriptions.create({
  customer_id: 'cus_123',
  product_id: 'prod_on_demand',
  on_demand: true
});

await client.subscriptions.createCharge(onDemand.id, {
  amount: 4900,
  currency: 'USD',
  description: 'Extra usage for September'
});

Perbarui metode pembayaran untuk langganan aktif

Perbarui metode pembayaran untuk langganan aktif:

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

// Or use existing payment method
await client.subscriptions.updatePaymentMethod('sub_123', {
  type: 'existing',
  payment_method_id: 'pm_abc123'
});

Mengaktifkan kembali langganan dari ditangguhkan

Aktifkan kembali langganan yang ditangguhkan karena pembayaran gagal:

// Update payment method - automatically creates charge for remaining dues
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  type: 'new',
  return_url: 'https://example.com/return'
});

if (response.payment_id) {
  // Charge created for remaining dues
  // Redirect customer to response.payment_link
  // Monitor webhooks: payment.succeeded → subscription.active
}

Langganan dengan Mandat Sesuai RBI

Langganan UPI dan kartu India beroperasi di bawah regulasi RBI (Reserve Bank of India) dengan persyaratan mandat tertentu:

Batas Mandat

Tipe dan jumlah mandat tergantung pada biaya berulang langganan Anda:

Biaya di bawah ₹15.000: Kami membuat mandat sesuai permintaan untuk ₹15.000 INR. Jumlah langganan ditagih secara berkala sesuai dengan frekuensi langganan Anda, hingga batas mandat.
Biaya ₹15.000 atau lebih: Kami membuat mandat langganan (atau mandat sesuai permintaan) untuk jumlah langganan yang tepat.

Pertimbangan Peningkatan dan Penurunan

Penting: Saat meningkatkan atau menurunkan langganan, pertimbangkan batas mandat dengan hati-hati:

Jika peningkatan/penurunan menghasilkan jumlah biaya yang melebihi ₹15.000 dan melampaui batas pembayaran sesuai permintaan yang ada, biaya transaksi mungkin gagal.
Dalam kasus seperti itu, pelanggan mungkin perlu memperbarui metode pembayaran mereka atau mengubah langganan lagi untuk menetapkan mandat baru dengan batas yang benar.

Otorisasi untuk Biaya Nilai Tinggi

Untuk biaya langganan sebesar ₹15.000 atau lebih:

Pelanggan akan diminta oleh bank mereka untuk mengotorisasi transaksi.
Jika pelanggan gagal mengotorisasi transaksi, transaksi akan gagal dan langganan akan ditangguhkan.

Penundaan Pemrosesan 48 Jam

Jadwal Pemrosesan: Biaya berulang pada kartu India dan langganan UPI mengikuti pola pemrosesan yang unik:

Biaya dimulai pada tanggal yang dijadwalkan sesuai dengan frekuensi langganan Anda.
Pengurangan aktual dari akun pelanggan hanya terjadi setelah 48 jam dari inisiasi pembayaran.
Jendela 48 jam ini dapat diperpanjang hingga 2-3 jam tambahan tergantung pada respons API bank.

Jendela Pembatalan Mandat

Selama jendela pemrosesan 48 jam:

Pelanggan dapat membatalkan mandat melalui aplikasi perbankan mereka.
Jika pelanggan membatalkan mandat selama periode ini, langganan akan tetap aktif (ini adalah kasus tepi khusus untuk langganan AutoPay kartu India dan UPI).
Namun, pengurangan aktual mungkin gagal, dan dalam hal itu, kami akan menempatkan langganan ditangguhkan.

Penanganan Kasus Tepi: Jika Anda memberikan manfaat, kredit, atau penggunaan langganan kepada pelanggan segera setelah inisiasi biaya, Anda perlu menangani jendela 48 jam ini dengan tepat dalam aplikasi Anda. Pertimbangkan:

Menunda aktivasi manfaat hingga konfirmasi pembayaran
Menerapkan periode tenggang atau akses sementara
Memantau status langganan untuk pembatalan mandat
Menangani status ditangguhkan langganan dalam logika aplikasi Anda

Pantau webhook langganan untuk melacak perubahan status pembayaran dan menangani kasus tepi di mana mandat dibatalkan selama jendela 48 jam.

Praktik Terbaik

Mulailah dengan tingkatan yang jelas: 2–3 rencana dengan perbedaan yang jelas
Komunikasikan harga: Tampilkan total, prorata, dan pembaruan berikutnya
Gunakan percobaan dengan bijak: Konversi dengan onboarding, bukan hanya waktu
Manfaatkan add-on: Pertahankan rencana dasar yang sederhana dan tawarkan ekstra
Uji perubahan: Validasi perubahan rencana dan prorata dalam mode uji

Langganan adalah fondasi fleksibel untuk pendapatan berulang. Mulailah dengan sederhana, uji secara menyeluruh, dan iterasi berdasarkan adopsi, churn, dan metrik ekspansi.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Tingkatkan & Turunkan

Langganan Sesuai Permintaan

Portal Pelanggan

Webhook Langganan

​Apa Itu Langganan?

​Manfaat Utama

​Membuat Langganan

​Pembuatan produk langganan

​Detail produk

​Penetapan Harga

​Pengaturan Lanjutan

​Percobaan Langganan

​Mengonfigurasi Percobaan

​Mendeteksi Status Percobaan

​Memperbarui Periode Percobaan

​Perubahan Rencana Langganan

​Mode Prorata

​prorated_immediately

​difference_immediately

​full_immediately

​Mengubah Rencana dengan Add-on

​Prabaca Perubahan Rencana

Prabaca API Perubahan Rencana

​Status Langganan

​Status Ditangguhkan

​Mengaktifkan Kembali dari Ditangguhkan

​Manajemen API

Referensi API

Referensi API

Referensi API

Referensi API

Referensi API

Referensi API

Referensi API

​Kasus Penggunaan Umum

​Contoh Integrasi

​Sesi Checkout (langganan)

​Perubahan rencana dengan prorata

​Batalkan di akhir periode

​Langganan sesuai permintaan

​Perbarui metode pembayaran untuk langganan aktif

​Mengaktifkan kembali langganan dari ditangguhkan

​Langganan dengan Mandat Sesuai RBI

​Batas Mandat

​Pertimbangan Peningkatan dan Penurunan

​Otorisasi untuk Biaya Nilai Tinggi

​Penundaan Pemrosesan 48 Jam

​Jendela Pembatalan Mandat

​Praktik Terbaik

Apa Itu Langganan?

Manfaat Utama

Membuat Langganan

Pembuatan produk langganan

Detail produk

Penetapan Harga

Pengaturan Lanjutan

Percobaan Langganan

Mengonfigurasi Percobaan

Mendeteksi Status Percobaan

Memperbarui Periode Percobaan

Perubahan Rencana Langganan

Mode Prorata

`prorated_immediately`

`difference_immediately`

`full_immediately`

Mengubah Rencana dengan Add-on

Prabaca Perubahan Rencana

Status Langganan

Status Ditangguhkan

Mengaktifkan Kembali dari Ditangguhkan

Manajemen API

Kasus Penggunaan Umum

Contoh Integrasi

Sesi Checkout (langganan)

Perubahan rencana dengan prorata

Batalkan di akhir periode

Langganan sesuai permintaan

Perbarui metode pembayaran untuk langganan aktif

Mengaktifkan kembali langganan dari ditangguhkan

Langganan dengan Mandat Sesuai RBI

Batas Mandat

Pertimbangan Peningkatan dan Penurunan

Otorisasi untuk Biaya Nilai Tinggi

Penundaan Pemrosesan 48 Jam

Jendela Pembatalan Mandat

Praktik Terbaik