Overview

Ada beberapa langkah sederhana untuk mulai menggunakan Xendit pembayaran berulang. Berdasarkan kebutuhan yang berbeda dari merchant kami, Xendit memungkinkan konfigurasi dibuat untuk disesuaikan dengan beberapa kebutuhan. Dalam panduan pembayaran berulang ini, pertama-tama kita akan menelusuri fitur dasar pembayaran berulang diikuti dengan bagaimana fitur lanjutan dapat dikonfigurasi.

Alur API untuk pembuatan pembayaran berulang

---

---

Alur API untuk pembuatan siklus pembayaran berulang (setiap instance penagihan)

---

---

Persiapan sebelum membuat Rencana Pembayaran Berulang

Sebelum membuat rencana pembayaran berulang pada kami Buat Rencana, ada 3 informasi yang perlu disiapkan - informasi pelanggan, informasi metode pembayaran, dan jadwal pengulangan. Xendit menggunakan objek pelanggan, objek metode pembayaran, dan objek jadwal untuk menyimpan informasi ini secara bersamaan.

Buat Objek Pelanggan

Langkah pertama untuk pembayaran berulang adalah membuat objek pelanggan melalui Buat Pelanggan API. Informasi dalam objek ini sangat penting karena akan digunakan dalam notifikasi kepada pelanggan. Disarankan untuk memberikan semua detail secara akurat sehingga notifikasi akan terkirim dengan lancar.

Contoh request buat pelanggan -

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"
        }
}

Perhatikan bahwa objek pelanggan yang dibuat dapat digunakan kembali di beberapa rencana, satu customer_id dapat digunakan untuk membuat beberapa rencana pembayaran berulang.

Untuk kompatibilitas terbaik, gunakan versi 2020-10-31 untuk API Buat Pelanggan.

Membuat objek metode pembayaran (Opsional)

Ini adalah langkah opsional karena Xendit menyediakan UI penautan akun/pengikatan kartu (melalui API Buat Rencana) untuk membuat objek metode pembayaran. Jika merchant memilih untuk menggunakan UI yang disediakan oleh Xendit, objek metode pembayaran akan diberitahukan kepada merchant kami melalui webhook recurring.plan.activated.

Menggunakan UI Xendit memiliki beberapa keunggulan dibandingkan membuat sendiri -

1. Saluran pembayaran akan dikelola oleh Xendit saat kami menambahkan lebih banyak saluran dengan fitur autodebit
2. Xendit menangani persyaratan keamanan yang kompleks dan kepatuhan audit terhadap penyedia/jaringan pembayaran.

Anda yang memilih untuk menyediakan alur penggunanya sendiri harus membuat objek metode pembayaran melalui API Buat Metode Pembayaran.

1. Siapkan URL webhook Anda melalui halaman pengaturan dasbor Xendit - di bawah metode pembayaran
2. Panggil API POST /v2/payment_methods untuk menginisialisasi proses penautan akun. Pastikan bahwa parameter berikut tersedia:

• type - Jenis metode pembayaran yang Anda coba tautkan
• reusability - Berikan nilai MULTIPLE_USE sehingga dapat digunakan untuk pembayaran di masa mendatang atau untuk pembayaran berulang
• customer_id - Menautkan biasanya mengharuskan Anda membuat Objek Pelanggan sehingga metode pembayaran dapat ditautkan padanya
• objek ewallet atau direct_debit atau card - untuk menempatkan properti khusus saluran untuk menginisialisasi penautan.

Contoh request buat metode pembayaran -

POST https://api.xendit.co/v2/payment_methods

{
  "type": "EWALLET",
  "reusability": "MULTIPLE_USE",
  "ewallet": {
    "channel_code": "OVO",
    "channel_properties": {
      "success_return_url": "https://your-redirect-website.com/success",
      "failure_return_url": "https://your-redirect-website.com/failure"
    }
  },
  "customer_id": "fc4c060b-3c41-4707-b7b2-df9c3376edde",
  "metadata": {
    "sku": "ABCDEFGH"
  }
}

3. Setelah API memberikan respons yang berhasil, proses penautan akun telah dimulai.
4. Jika status respons adalah "REQUIRES_ACTION", ini berarti diperlukan langkah tambahan agar penautan akun berhasil. Tindakan paling umum yang diperlukan:

• Mengarahkan pengguna akhir ke halaman web untuk konfirmasi
• Melalui kode satu kali untuk otorisasi yang divalidasi melalui API

5. Webhook yang Diaktifkan Metode Pembayaran akan dikirim setelah metode pembayaran berhasil diotorisasi untuk pembayaran.

Membuat objek jadwal (Opsional)

Pembuatan objek jadwal di endpoint Buat Jadwal bersifat opsional. Anda dapat meneruskan objek jadwal secara langsung pada setiap permintaan Buat Rencana Berulang atau membuat schedule_id sebelum meneruskannya ke API Buat Rencana Berulang.

Bergantung pada kasus penggunaan Anda, salah satu pendekatan bisa lebih cocok. Kami merekomendasikan Anda untuk membuat objek jadwal di endpoint Buat Jadwal hanya jika mereka perlu mengontrol atau mengelola logika interval berulang dari beberapa rencana berulang sekaligus.

Atau, Anda harus menyiapkan objek ini untuk kasus penggunaan pelanggan. Beberapa contoh diberikan di bawah ini -

Di bawah ini contoh konfigurasi jadwal dasar -

{
  "interval": "MONTH",
  "interval_count": 1,
  "total_recurrence": 12,
  "anchor_date": "2022-02-15T16:23:52Z"
}

Contoh (di bawah) langgan bulanan dengan percobaan ulang (misalnya Streaming Video) -

1. Penyedia biasanya mengenakan biaya sebulan sekali tanpa tanggal akhir yang pasti
2. Tidak ada tanggal tertentu di mana penyedia ingin membebankan biaya kepada pelanggan, yang berarti tagihan bulan berikutnya akan berada pada tanggal yang sama dengan saat rencana pertama kali dibuat
3. Penyedia ingin mencoba lagi pembayaran dua kali lagi jika upaya pertama gagal, setiap upaya harus berjarak 3 hari
4. Agar tidak mengganggu pelanggan, merchant hanya ingin memberi tahu pelanggan pada upaya kedua

{
"interval" : "MONTH",
"interval_count" : 1,
"retry_interval" : "DAY",
"retry_interval_count" : 3,
"total_retry" : 2,
"failed_attempt_notifications" : [2]
}

Contoh (di bawah) adalah langganan bulanan dengan jumlah siklus dan tanggal tetap (misalnya Uang Sekolah) -

1. Penyedia biasanya mengenakan biaya sebulan sekali untuk kursus pendidikan tetap 2 tahun
2. Penyedia ingin menagih pelanggan setiap tanggal 25 setiap bulan
3. Penyedia ingin mencoba lagi pembayaran dua kali lagi jika upaya pertama gagal, setiap upaya harus berjarak 3 hari
4. Karena edukasi penting bagi pelanggan, merchant ingin memberi tahu pengguna akhir pada setiap upaya yang gagal

{
"interval" : "MONTH",
"interval_count" : 1,
"total_recurrence" : 24,
"anchor_date" : "2020-11-25T16:23:52Z",
"retry_interval" : "DAY",
"retry_interval_count" : 3,
"total_retry" : 2,
"failed_attempt_notifications" : [1,2]
}

Membuat Rencana Pembayaran Berulang

Membuat Objek Rencana Pembayaran Berulang

Setelah menyelesaikan langkah-langkah persiapan, kini Anda siap menggunakan API Buat Rencana. Dengan informasi dari langkah-langkah persiapan, merchant kami akan memiliki sebagian besar informasi yang dibutuhkan untuk membuat rencana pembayaran berulang. Selama langkah ini, Anda dapat mengonfigurasi beberapa setelan lagi untuk pelanggan Anda. Ini termasuk -

1. Parameter immediate_action_type - apakah rencana berulang harus memulai tindakan segera. Saat parameter ini digunakan, siklus khusus dengan tipe "IMMEDIATE" akan dibuat. Xendit akan mencoba melakukan tindakan pembayaran selama Pembuatan Rencana. Jika pembayaran langsung gagal, paket akan dinonaktifkan secara otomatis. Parameter ini membantu merchant melanjutkan pembuatan paket hanya jika pengguna akhir berhasil menyelesaikan transaksi pembayaran langsung.

2. Parameter notification_config - menentukan jenis notifikasi yang harus diterima pelanggan.

3. Parameter failed_cycle_action - apakah rencana berulang dinonaktifkan saat mengalami siklus gagal. Parameter ini membantu Anda menangani paket berulang jika siklus telah menghabiskan semua percobaan ulang dan gagal. Merchant dapat menggunakan parameter ini untuk "STOP" paket berulang secara otomatis atau "RESUME" untuk mengabaikan kegagalan dan melanjutkan siklus pembayaran berikutnya.

Dengan semua informasi ini disiapkan, rencana pembayaran berulang sudah siap digunakan dan apa yang tersisa adalah menyiapkan URL untuk menerima webhook atas pembaruan pada rencana pembayaran berulang Anda.

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

Contoh membuat rencana pembayaran berulang dengan objek jadwal tanpa objek metode pembayaran -

{
  "reference_id": "test_reference_id",
  "customer_id": "cust-uhdquwy18237y213",
  "recurring_action": "PAYMENT",
  "currency": "IDR",
  "amount": 100000,
  "schedule": {
    "reference_id": "test_reference_id",
    "interval": "MONTH",
    "interval_count": 1,
    "total_recurrence": 12,
    "anchor_date": "2020-02-15T16:23:52Z",
    "retry_interval": "DAY",
    "retry_interval_count": 5,
    "total_retry": 5,
    "failed_attempt_notifications": [2,4]
  },
  "immediate_action_type": "FULL_AMOUNT",
  "notification_config": {
    "recurring_created": ["WHATSAPP","EMAIL"],
    "recurring_succeeded": ["WHATSAPP","EMAIL"],
    "recurring_failed": ["WHATSAPP","EMAIL"]},
  "failed_cycle_action": "STOP", 
  "metadata": null,
  "description": "Video Game Subscription",
  "items": [
      {
          "type": "DIGITAL_PRODUCT",
          "name": "Cine Mraft",
          "net_unit_amount": 100000,
          "quantity": 1,
          "url": "https://www.xendit.co/",
          "category": "Gaming",
          "subcategory": "Open World"
      }
  ],
  "success_return_url": "https://www.xendit.co/successisthesumoffailures",
  "failure_return_url": "https://www.xendit.co/failureisthemotherofsuccess"
}

Contoh mengirimkan schedule_id dan payment_method_id -

{
  "reference_id": "test_reference_id",
  "customer_id": "cust-uhdquwy18237y213",
  "recurring_action": "PAYMENT",
  "currency": "IDR",
  "amount": 100000,
  "payment_methods": [{
      "payment_method_id": "pm-asdaso213897821hdas",
      "rank": 1
    }],
  "schedule_id": "resc-uhdquwy18237y213",
  "immediate_action_type": "FULL_AMOUNT",
  "notification_config": {
    "recurring_created": ["WHATSAPP","SMS","EMAIL"],
    "recurring_succeeded": [],
    "recurring_failed": ["WHATSAPP","SMS"]},
  "failed_cycle_action": "STOP", 
  "metadata": null,
  "description": "Video Game Subscription",
  "items": [
      {
          "type": "DIGITAL_PRODUCT",
          "name": "Cine Mraft",
          "net_unit_amount": 100000,
          "quantity": 1,
          "url": "https://www.xendit.co/",
          "category": "Gaming",
          "subcategory": "Open World"
      }
  ],
}

Di subbagian dokumentasi ini, akan ada contoh khusus tentang bagaimana penjual dapat mengatur langganan berulang mereka berdasarkan kasus penggunaan mereka - [langganan dengan jumlah tetap](https://docs.xendit.co/recurring/fixed-amount- langganan) atau langganan berbasis penggunaan.

Menangani Webhook Pembayaran Berulang

Penting untuk mengetahui webhook apa yang tersedia dan kapan dipicu. Ini membantu merencanakan respons sistem Anda terhadap setiap peristiwa. Tabel di bawah mencantumkan dan menjelaskan jenis webhook yang tersedia.

Webhook event	Pemicu	Deskripsi
Aktivasi Rencana Pembayaran Berulang recurring.plan.activated	1. Saat rencana berulang telah berhasil dibuat 2. Atau, saat rencana pembayaran berulang dengan immediate_action_type telah dibuat DAN tindakan segera yang sesuai berhasil	Merchant dapat menggunakan ini sebagai indikasi bahwa rencana pembayaran berulang berhasil dibuat dan akan dilanjutkan sesuai jadwal yang ditentukan. Jika ini tidak diterima, rencananya tidak akan dilanjutkan
Penonaktifan Rencana Pembayaran Berulang recurring.plan.inactivated	1. Ketika rencana pembayaran berulang dengan nilai total_recurrence yang ditentukan telah mencapai jumlah total siklus 2. Ketika rencana berulang dengan failed_cycle_action = "STOP" bertemu dengan siklus berulang "FAILED" 3. Atau, ketika rencana berulang dengan immediate_action_type telah dibuat DAN tindakan segera yang sesuai gagal	Merchant dapat menggunakan notifikasi ini untuk menutup rencana pembayaran berulang mereka dengan pelanggan tertentu, sebagai indikator untuk menghentikan penyediaan barang/jasa
Pembuatan Siklus Pembayaran Berulang recurring.cycle.created	1. Saat rencana dibuat, siklus dengan status "SCHEDULED" akan dibuat terlepas dari apakah rencana telah menetapkan nilai immediate_action_type. 2. Atau, ketika siklus yang akan datang berubah status dari "SCHEDULED" menjadi "PENDING" (tindakan pembayaran pertama sedang dijalankan)	Anda akan mendapatkan pemberitahuan tentang siklus berulang yang akan datang yang sedang dibuat. Merchant akan dapat menyesuaikan nilai tertentu dari siklus berulang yang akan datang menggunakan titik akhir siklus berulang pembaruan
Aksi Sukses Siklus Pembayaran Berulang recurring.cycle.succeeded	Ketika salah satu upaya yang dikonfigurasi dan tindakannya berhasil	Anda dapat menggunakan notifikasi ini sebagai indikasi bahwa pelanggan telah berhasil membayar untuk interval yang ditentukan
Tindakan Mencoba Ulang Siklus Berulang recurring.cycle.retrying	Ketika upaya saat ini tidak berhasil mendapatkan tindakan yang berhasil DAN masih ada upaya coba ulang yang dikonfigurasi untuk siklus ini	Merchant dapat menggunakan notifikasi ini sebagai indikasi bahwa pelanggan gagal membayar untuk interval yang ditentukan tetapi Xendit akan terus mencoba lagi pembayaran
Tindakan Gagal Siklus Berulang recurring.cycle.failed	Ketika semua upaya yang dikonfigurasi (termasuk upaya coba lagi) tidak berhasil menghasilkan tindakan yang berhasil	Anda dapat menggunakan notifikasi ini sebagai indikasi bahwa pelanggan gagal membayar untuk interval yang ditentukan dan tidak ada tindakan lebih lanjut yang akan diambil

Alasan Kegagalan Umum untuk Pembayaran Berulang

Respons Kegagalan API

Lihat API Pembayaran Berulang untuk kegagalan umum API

Kegagalan Pembayaran

Skenario Kegagalan	Alasan Kegagalan
Akun pelanggan telah diblokir oleh penyedia eWallet	Kode kegagalan ACCOUNT_ACCESS_BLOCKED melalui webhook siklus gagal
Detail akun pelanggan tidak valid	Kode kegagalan INVALID_ACCOUNT_DETAILS melalui webhook siklus gagal
Akun Pelanggan telah mencapai batas maksimum transaksi	kode kegagalan MAXIMUM_LIMIT_REACHED melalui webhook siklus gagal
Saldo tidak cukup di ewallet pelanggan	Kode kegagalan INSUFFICIENT_BALANCE melalui webhook siklus gagal
Pelanggan membatalkan tautan metode pembayaran dari sistem kami	Kode kegagalan INVALID_PAYMENT_METHOD_ID melalui webhook siklus gagal