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: '[email protected]',
      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": "[email protected]",
        "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: '[email protected]',
      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 (terjadi pada setiap perubahan field).
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 segera (0 hari percobaan): Harapkan dalam 2-10 menit
   • Untuk hari percobaan: kapan pun itu berakhir
3. subscription.renewed - Menunjukkan pemotongan pembayaran dan pembaruan untuk siklus berikutnya. (Pada dasarnya, kapan pun pembayaran dipotong untuk produk langganan, Anda akan mendapatkan webhook subscription.renewed bersama dengan payment.succeeded)

1. Kegagalan Langganan

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

2. Langganan Ditangguhkan

• subscription.on_hold - Langganan ditangguhkan karena pembayaran pembaruan gagal atau biaya perubahan rencana gagal.
• Ketika langganan ditangguhkan, itu tidak akan diperbarui secara 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
• Mengenakan biaya kepada pelanggan hanya untuk selisih antara rencana lama dan baru
• Selama periode percobaan, ini akan segera mengalihkan pengguna ke rencana baru, mengenakan biaya kepada pelanggan segera

​

2. full_immediately

• Mengenakan biaya kepada pelanggan jumlah penuh untuk rencana baru
• Mengabaikan waktu atau kredit yang tersisa dari rencana sebelumnya
• Berguna ketika Anda ingin mereset siklus penagihan atau mengenakan biaya jumlah penuh terlepas dari proration

​

3. difference_immediately

• Saat meningkatkan, pelanggan segera dikenakan biaya selisih antara dua jumlah rencana.
• Misalnya, jika rencana saat ini adalah 30 Dolar dan pelanggan meningkatkan ke 80 Dolar, mereka dikenakan biaya $50 secara instan.
• Saat menurunkan, jumlah yang tidak terpakai dari rencana saat ini ditambahkan sebagai kredit internal dan secara otomatis diterapkan pada pembaruan langganan di masa mendatang.
• Misalnya, jika rencana saat ini adalah 50 Dolar dan pelanggan beralih ke rencana 20 Dolar, sisa $30 dikreditkan dan digunakan untuk siklus penagihan berikutnya.

​

Perilaku

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

​

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