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 - Menunjukkan aktivasi langganan
2. payment.succeeded - Mengonfirmasi pembayaran awal:
   • Untuk penagihan langsung (0 hari percobaan): Harapkan dalam 2-10 menit
   • Untuk masa percobaan: kapan pun itu berakhir
3. subscription.renewed - Menunjukkan pemotongan pembayaran dan pembaruan untuk siklus berikutnya. (Pada dasarnya, kapan pun pembayaran ditagihkan untuk produk langganan, Anda akan menerima webhook subscription.renewed bersamaan dengan payment.succeeded)

1. Kegagalan Langganan

• subscription.failed - Pembuatan langganan gagal karena kegagalan membuat mandat.
• payment.failed - Menunjukkan pembayaran gagal.

2. Langganan Ditangguhkan

• subscription.on_hold - Langganan ditangguhkan karena pembayaran pembaruan gagal atau biaya perubahan paket gagal.
• Saat langganan ditangguhkan, langganan tidak akan diperbarui otomatis sampai metode pembayaran diperbarui.

​

Menangani Langganan Ditangguhkan

​

Ketika Langganan Ditangguhkan

• Pembayaran pembaruan gagal: Biaya pembaruan otomatis gagal karena dana tidak mencukupi, kartu kadaluarsa, atau penolakan bank
• Biaya perubahan rencana gagal: Biaya segera selama peningkatan/penurunan rencana gagal
• Otorisasi metode pembayaran gagal: Metode pembayaran tidak dapat diotorisasi untuk biaya berulang

​

Mengaktifkan Kembali Langganan dari Ditangguhkan

1. Membuat biaya untuk tunggakan yang tersisa
2. Menghasilkan faktur untuk biaya tersebut
3. Memproses pembayaran menggunakan metode pembayaran baru
4. Mengaktifkan kembali langganan 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
}

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 Acara Langganan

​

Mengubah Rencana Langganan

​

Opsi Prorata

​

1. prorated_immediately

• Menghitung jumlah prorata berdasarkan waktu yang tersisa dalam siklus penagihan saat ini
• Menagih pelanggan hanya untuk selisih antara paket lama dan baru
• Selama masa percobaan, ini akan langsung memindahkan pengguna ke paket baru dan menagih pelanggan segera

​

2. full_immediately

• Menagih pelanggan jumlah langganan penuh untuk paket baru
• Mengabaikan waktu tersisa atau kredit dari paket sebelumnya
• Berguna ketika Anda ingin mereset siklus penagihan atau menagih jumlah penuh tanpa memperhatikan prorata

​

3. difference_immediately

• Saat upgrade, pelanggan langsung dikenakan selisih antara dua jumlah paket yang berbeda.
• Misalnya, jika paket saat ini 30 Dollars dan pelanggan upgrade ke 80 Dollars, mereka langsung dikenakan $50.
• Saat downgrade, jumlah yang tidak terpakai dari paket saat ini ditambahkan sebagai kredit internal dan otomatis diterapkan ke pembaruan langganan berikutnya.
• Misalnya, jika paket saat ini 50 Dollars dan pelanggan beralih ke paket 20 Dollars, sisa $30 dikreditkan dan digunakan untuk siklus penagihan berikutnya.

​

Perilaku

• Saat Anda memanggil API ini, Dodo Payments segera memulai biaya berdasarkan opsi prorata yang Anda pilih
• Jika perubahan paket adalah downgrade dan Anda menggunakan prorated_immediately, kredit akan otomatis dihitung dan ditambahkan ke saldo kredit langganan. Kredit ini khusus untuk langganan tersebut dan hanya akan digunakan untuk mengimbangi pembayaran berulang di masa depan dari langganan yang sama
• Opsi full_immediately melewati perhitungan kredit dan menagih jumlah paket baru secara penuh

​

Pemrosesan Biaya

• Biaya segera yang dimulai saat perubahan rencana biasanya selesai diproses dalam waktu kurang dari 2 menit
• Jika biaya segera ini gagal karena alasan apa pun, langganan secara otomatis ditangguhkan sampai masalah teratasi

​

Langganan Sesuai Permintaan