Panduan Langganan Berbasis Penggunaan

Contoh Layanan Utilitas

Untuk contoh ini, kami akan berpura-pura menjadi layanan utilitas yang ingin mengumpulkan berbagai pembayaran berulang dari pelanggan mereka setiap bulan.

• Pertama, kami perlu menentukan metode pembayaran yang cocok untuk pelanggan kami berdasarkan harga rata-rata. Karena harga untuk layanan dasar dan premium kami adalah sekitar IDR 100,000 hingga IDR 300,000, eWallet, Direct Debit, dan Kartu Kredit akan sesuai. Kami akan melanjutkan untuk mendaftarkan saluran-saluran ini dengan Xendit dan menentukan bahwa transaksi dapat untuk autodebit/ diinisais merchant.
• Sambil menunggu aktivasi saluran pembayaran, kami dapat melanjutkan pengujian. Untuk memulai pengujian, pertama-tama kami akan membuka Dasbor Xendit untuk membuat kunci API (Pengaturan > Pengembang > kunci API) dan menyediakan URL yang dihosting di server layanan streaming kami untuk menerima webhook pembayaran berulang dari Xendit (Pengaturan > Developer > Callbacks > RECURRING).
• Sekarang setelah persiapan selesai, kami dapat melihat use case kami dan mencocokkannya dengan fitur di API Xendit
  • Pembayaran dilakukan di tanggal yang tetap setiap bulan
  • Jumlah akan berubah setiap bulan berdasarkan penggunaan pelanggan
  • Untuk memaksimalkan tingkat keberhasilan pembayaran, kami ingin melakukan pembayaran ulang saat pelanggan memiliki saldo lagi
  • Utilitas penting bagi pelanggan, kami akan memberi tahu mereka setiap kali proses pembayaran gagal
  • Untuk memaksimalkan tingkat keberhasilan pembayaran, kami ingin memberi tahu pelanggan melalui Whatsapp dan email ketika pembayaran gagal
  • Jika pelanggan gagal melakukan pembayaran selama sebulan, kami akan menghentikan layanan mereka
  • Ada jumlah dasar yang dibayar pelanggan terlepas dari penggunaan utilitas mereka
• Kami dapat memulai integrasi dengan menautkan metode pembayaran ke API Xendit. API pertama adalah Buat Pelanggan tempat kami akan meneruskan informasi kontak pelanggan ke dalam permintaan. Ini membantu untuk menyimpan informasi kontak dengan Xendit sehingga notifikasi Whatsapp dapat terkirim. Kami dapat memberikan informasi berdasarkan input pelangga selama pendaftaran atau membuat formulir bagi pelanggan untuk memasukkan data.

POST https://api.xendit.co/customers 

{
    "reference_id": "test_reference_id",
    "mobile_number": "+6218181818181",
    "email": "honeybadgey@xendit.co",
    "type" : "INDIVIDUAL",
    "individual_detail": {
        "given_names": "Honey Badgey"
        }
}

• Untuk menyederhanakan integrasi kami, kami akan menggunakan UI Xendit untuk pembuatan metode pembayaran. API berikutnya yang perlu kita tekan adalah Buat Rencana.

POST https://api.xendit.co/recurring 

{
  "reference_id": "test_reference_id",
  "customer_id": "cust-239c16f4-866d-43e8-9341-7badafbc019f",
  "recurring_action": "PAYMENT",
  "currency": "IDR",
  "amount": 100000,
  "schedule": {
    "reference_id": "test_reference_id",
    "interval": "MONTH",
    "interval_count": 1,
    "anchor_date": "2022-02-15T16:23:52Z",
    "retry_interval": "DAY",
    "retry_interval_count": 3,
    "total_retry": 3,
    "failed_attempt_notifications": [1,2,3]
  },
  "notification_config": {
    "recurring_created": ["WHATSAPP"],
    "recurring_succeeded": ["WHATSAPP"],
    "recurring_failed": ["WHATSAPP"]
  },
  "failed_cycle_action": "STOP", 
  "metadata": null,
  "success_return_url": "https://www.xendit.co/successisthesumoffailures",
  "failure_return_url": "https://www.xendit.co/failureisthemotherofsuccess"
}

Parameter untuk kebutuhan use case ini:

• Setelah permintaan dikirim, kami akan menerima respons HTTPS dengan objek rencana pembayaran berulang yang berstatus "REQUIRES_ACTION"

{
  "id": "repl-239c16f4-866d-43e8-9341-7badafbc019f",
  "reference_id": "test_reference_id",
  "customer_id": "cust-239c16f4-866d-43e8-9341-7badafbc019f",
  "recurring_action": "PAYMENT",
  "recurring_cycle_count": 0,
  "currency": "IDR",
  "amount": 100000,
  "status": "REQUIRES_ACTION",
  "created": "2020-11-20T16:23:52Z",
  "updated": "2020-11-20T16:23:52Z",
  "schedule_id": "resc-239c16f4-866d-43e8-9341-7badafbc019f",
  "schedule": {
    "reference_id": "test_reference_id",
    "interval": "MONTH",
    "interval_count": 1,
    "created": "2022-02-15T16:23:52Z",
    "updated": "2022-02-15T16:23:52Z",
    "anchor_date": "2022-02-15T16:23:52Z",
    "retry_interval": "DAY",
    "retry_interval_count": 3,
    "total_retry": 3,
    "failed_attempt_notifications": [1,3]
  },
  "immediate_action_type": "FULL_AMOUNT",
  "notification_config": {
    "recurring_created": ["WHATSAPP"],
    "recurring_succeeded": ["WHATSAPP"],
    "recurring_failed": ["WHATSAPP",],
    "locale": "en"
  },
  "failed_cycle_action": "STOP",
  "metadata": null,
  "description": null,
  "items": null,
  "actions": [{
      "action": "AUTH",
      "url": "https://linking-dev.xendit.co/pali_e53e1ca6-3c09-4026-be2e-95ed3d4bb25b",
      "url_type": "WEB",
      "method": "GET"
    }],
  "success_return_url": "https://www.xendit.co/successisthesumoffailures",
  "failure_return_url": "https://www.xendit.co/failureisthemotherofsuccess"
}

Status "REQUIRES_ACTION" menunjukkan bahwa kami perlu mengalihkan pelanggan ke actions.url agar mereka dapat menyelesaikan penautan akun metode pembayaran. Setelah pelanngan kita dialihkan, kita perlu mendengarkan webhook dari Xendit untuk melanjutkan ke langkah berikutnya.

• Jika event webhook untuk recurring.plan.activated diterima, kami akan mencocokkannya dengan reference_id atau id yang disimpan di database kami untuk memvalidasi bahwa itu adalah event webhook yang terkait dengan rencana yang baru saja kami buat. Setelah dikonfirmasi, kami dapat mulai memberikan layanan kepada pelanggan. Jika recurring.plan.inactivated diterima, kami dapat meminta pelanggan untuk mencoba kembali alur langganan.
• Pada saat yang sama, event webhook recurring.cycle.created juga akan diterima untuk siklus penagihan pengguna yang akan datang. Untuk langganan berbasis penggunaan, penting untuk menangani dan menyimpan informasi siklus berulang ini. Contoh webhook ada di bawah ini.

{
  "created": "2022-10-01T12:37:08.251Z",
  "business_id": "62440e322008e87fb29c1fd0",
  "event": "recurring.cycle.created",
  "data": {
    "id": "recy-239c16f4-866d-43e8-9341-7badafbc019f",
    "reference_id": "test_reference_id",
    "customer_id": "cust-239c16f4-866d-43e8-9341-7badafbc019f",
    "recurring_action": "PAYMENT",
    "type": "SCHEDULED",
    "cycle_number": 1,
    "attempt_count": 0,
    "attempt_details": [],
    "status": "SCHEDULED",
    "scheduled_timestamp": "2020-12-20T16:23:52Z",
    "created": "2020-11-20T16:23:52Z",
    "updated": "2020-11-20T16:23:52Z",
    "currency": "IDR",
    "amount": 13579,
    "metadata": null
  },
  "api_version": "v1"
}

• Ketika tiba waktunya untuk melakukan pengurangan tagihan pelanggan yang akan datang, kami akan memanggil endpoint Siklus Pembaruan untuk menyertakan biaya penggunaan layanan kami ke dalam jumlah yang akan dipotong. Karena pembaruan tidak dapat dilakukan setelah komponen tanggal dalam scheduled_timestamp ("20-12-2020", waktu diabaikan) tercapai, kami harus memastikan bahwa pembaruan dilakukan setidaknya 1 hari sebelum schduled_timestamp. Proses ini kemudian diulang untuk bulan-bulan berikutnya.
• Untuk setiap bulan penagihan, jika pembayaran berhasil, event webhook recurring.cycle.succeeded akan diterima. Jika event webhook recurring.cycle.retrying diterima, berarti pembayaran gagal tetapi Xendit akan tetap melanjutkan percobaan. Jika event webhook recurring.cycle.failed diterima, kami akan menghentikan layanan pengguna karena semua upaya pembayaran termasuk percobaan ulang telah gagal.

Last Updated on 2023-05-24