Panduan Integrasi Langganan

​

Prasyarat

• Akun pedagang Dodo Payments
• Kredensial API (kunci API dan kunci rahasia webhook) dari dasbor

​

Integrasi API

​

Sesi Checkout

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: 'prod_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": "prod_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: 'prod_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 Acara Langganan

1. subscription.active - Langganan berhasil diaktifkan.
2. subscription.updated - Objek langganan diperbarui (dipicu pada setiap perubahan bidang).
3. subscription.on_hold - Langganan ditangguhkan karena pembaruan gagal.
4. subscription.failed - Pembuatan langganan gagal selama pembuatan mandat.
5. subscription.renewed - Langganan diperbarui untuk periode penagihan berikutnya.

​

Skenario Pembayaran

1. subscription.active: mandate diotorisasi dan subscription diaktifkan.
2. payment.succeeded: mengonfirmasi charge pertama. Ini biasanya terjadi dalam 2–10 menit setelah checkout.

1. Saat uji coba dimulai (checkout): subscription.active dipicu setelah payment method diotorisasi. Belum ada recurring charge yang diambil. Charge pertama yang sebenarnya ditunda hingga uji coba berakhir.
2. Saat uji coba berakhir: jumlah berulang ditagihkan, dan Anda menerima payment.succeeded bersama dengan subscription.renewed.

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

1. Kegagalan Subscription

• subscription.failed - Subscription gagal dibuat karena kegagalan membuat mandate.
• payment.failed - Menunjukkan pembayaran gagal.

2. Subscription Ditangguhkan

• subscription.on_hold - Subscription ditangguhkan karena pembayaran renewal atau charge perubahan plan gagal.
• Saat subscription ditangguhkan, subscription tidak akan diperbarui secara otomatis sampai payment method diperbarui.

​

subscription.failed vs. subscription.on_hold

​

Menangani Subscription yang Ditangguhkan

​

Kapan Subscription Ditangguhkan

• Pembayaran renewal gagal: Charge renewal otomatis gagal karena dana tidak mencukupi, kartu kedaluwarsa, atau penolakan bank
• Charge perubahan plan gagal: Charge langsung selama upgrade/downgrade plan gagal
• Otorisasi payment method gagal: Payment method tidak dapat diotorisasi untuk recurring charges

​

Mengaktifkan Kembali Subscription yang Ditangguhkan

1. Membuat charge untuk jumlah yang masih harus dibayar
2. Membuat invoice untuk charge tersebut
3. Memproses pembayaran menggunakan payment method 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, {
  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,
    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, {
  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 event Subscription

​

Mengubah Plan Subscription

​

Opsi Proration

​

1. prorated_immediately

• Menghitung jumlah prorata berdasarkan sisa waktu dalam billing cycle saat ini
• Menagih customer hanya untuk selisih antara plan lama dan baru
• Selama masa uji coba, opsi ini akan langsung memindahkan user ke plan baru dan langsung menagih customer

​

2. full_immediately

• Menagih customer seluruh jumlah subscription untuk plan baru
• Mengabaikan sisa waktu atau kredit dari plan sebelumnya
• Berguna jika Anda ingin mengatur ulang billing cycle atau menagih jumlah penuh tanpa memperhatikan proration

​

3. difference_immediately

• Saat melakukan upgrade, customer langsung ditagih sebesar selisih antara kedua jumlah plan.
• Misalnya, jika plan saat ini 30 Dolar dan customer melakukan upgrade ke plan 80 Dolar, mereka langsung ditagih $50.
• Saat melakukan downgrade, jumlah yang tidak terpakai dari plan saat ini ditambahkan sebagai kredit internal dan secara otomatis digunakan untuk renewal subscription berikutnya.
• Misalnya, jika plan saat ini 50 Dolar dan customer beralih ke plan 20 Dolar, sisa $30 dikreditkan dan digunakan untuk billing cycle berikutnya.

​

4. do_not_bill

• Menerapkan perubahan plan secara langsung tetapi tidak menagih apa pun saat perubahan dilakukan.
• Plan yang diperbarui (beserta quantity/add-ons) ditagihkan pada renewal terjadwal berikutnya, dan tanggal billing asli dipertahankan.

​

Perilaku

• Saat Anda memanggil API ini, Dodo Payments segera memulai charge berdasarkan opsi proration yang Anda pilih
• Jika perubahan plan merupakan downgrade dan Anda menggunakan prorated_immediately, kredit akan dihitung secara otomatis dan ditambahkan ke saldo kredit subscription. Kredit ini khusus untuk subscription tersebut dan hanya akan digunakan untuk mengimbangi recurring payments mendatang dari subscription yang sama
• Opsi full_immediately melewati penghitungan kredit dan menagih jumlah lengkap plan baru

​

Pemrosesan Charge

• Charge langsung yang dimulai setelah perubahan plan biasanya selesai diproses dalam waktu kurang dari 2 menit
• Jika charge langsung ini gagal karena alasan apa pun, subscription secara otomatis ditangguhkan sampai masalah teratasi

​

Subscription On-Demand

​

Hal Penting yang Perlu Diketahui tentang Penagihan Subscription

​

Referensi API Terkait