Welcome to Xendit’s latest documentation. For legacy content, access the previous documentation here or the previous API reference here.

Usage-based Subscriptions

Prev Next

Usage-based Subscriptions adalah jenis model pembayaran berulang di mana jumlah pembayaran bervariasi dan ditentukan berdasarkan konsumsi atau penggunaan pengguna pada waktu batas tertentu sebelum siklus penagihan berikutnya. Model ini menawarkan fleksibilitas bagi bisnis yang membebankan biaya kepada pelanggan berdasarkan penggunaan aktual daripada biaya tetap.

Kasus penggunaan umum termasuk layanan utilitas, paket pascabayar untuk telekomunikasi, ride hailing, Subscription SaaS atau penyimpanan cloud, dan banyak lagi.

Cara integrasi

Dalam Usage-based Subscriptions, jumlah yang akan ditagih harus ditentukan untuk setiap siklus penagihan sebelum siklus dimulai. Ini memastikan bahwa saldo pengguna akhir dapat dikurangi secara akurat berdasarkan penggunaan mereka selama periode tersebut.

  1. Untuk memulai, Anda perlu membuat objek pelanggan di Xendit dengan mendaftarkan detail pengguna akhir.

    Request - POST /pelanggan

    {
         "reference_id": "demo_1475801962688",
         "type": "INDIVIDUAL",
         "individual_detail": {
           "given_names": "John",
           "surname": "Doe"
         },
         "email": "customer@website.com",
         "mobile_number": "+628121234567890"
    }
     

    Response - POST /pelanggan

    {
        "type": "INDIVIDUAL",
        "date_of_registration": null,
        "email": "customer@website.com",
        "mobile_number": "+628121234567890",
        "phone_number": null,
        "created": "2024-12-06T02:42:36.343Z",
        "updated": "2024-12-06T02:42:36.343Z",
        "description": null,
        "hashed_phone_number": null,
        "domicile_of_registration": null,
        "kyc_documents": [],
        "id": "cust-ab93b98b-3e79-4961-b243-66a0e66daadc",
        "reference_id": "demo_1475801962688",
        "metadata": null,
        "individual_detail": {
            "given_names": "John",
            "given_names_non_roman": null,
            "surname": "Doe",
            "surname_non_roman": null,
            "nationality": null,
            "date_of_birth": null,
            "place_of_birth": null,
            "gender": null,
            "employment": null
        },
        "business_detail": null,
        "addresses": [],
        "identity_accounts": []
    }
  2. Setelah pengguna akhir terdaftar, buat paket Subscription yang disesuaikan dengan preferensi dan kebutuhan mereka

    Permintaan - POST /berulang/rencana

    {
        "reference_id": "ref-{{$timestamp}}",
        "customer_id": "cust-7e34f507-808d-44f8-a4a6-aea89a14a89c",
        "recurring_action": "PAYMENT",
        "currency": "IDR",
        "amount": 13579,
        "schedule": {
            "reference_id": "test-{{$timestamp}}",
            "interval": "MONTH",
            "interval_count": 1,
            "total_recurrence": 6,
            "anchor_date": "2025-02-15T09:44:19.546Z",
            "retry_interval": "DAY",
            "retry_interval_count": 1,
            "total_retry": 3,
            "failed_attempt_notifications": [
                1,3
            ]
        },
        "notification_config": {
            "locale": "en",
            "recurring_created": [
                "WHATSAPP",
                "EMAIL"
            ],
            "recurring_succeeded": [
                "WHATSAPP",
                "EMAIL"
            ],
            "recurring_failed": [
                "WHATSAPP",
                "EMAIL"
            ]
        },
        "failed_cycle_action": "STOP",
        "immediate_action_type": "FULL_AMOUNT",
        "payment_link_for_failed_attempt": true,
        "metadata": null,
        "description": "Xendit Recurring Test",
        "success_return_url": "https://www.xendit.co/",
        "failure_return_url": "https://www.xendit.co/"
    }

    response - POST /berulang/rencana

    {
        "id": "repl_c87f3312-a9c1-4eee-932c-38479f911830",
        "reference_id": "ref-1733299168",
        "customer_id": "cust-7e34f507-808d-44f8-a4a6-aea89a14a89c",
        "recurring_action": "PAYMENT",
        "failed_cycle_action": "STOP",
        "recurring_cycle_count": 0,
        "currency": "IDR",
        "amount": 13579,
        "status": "REQUIRES_ACTION",
        "created": "2024-12-04T07:59:28.553Z",
        "updated": "2024-12-04T07:59:28.553Z",
        "schedule_id": "resc_07d3197d-f860-47dc-bc6e-b87deaf34735",
        "payment_methods": [],
        "schedule": {
            "id": "resc_07d3197d-f860-47dc-bc6e-b87deaf34735",
            "reference_id": "test-1733299168",
            "business_id": "62440e322008e87fb29c1fd0",
            "interval": "MONTH",
            "interval_count": 1,
            "total_recurrence": 6,
            "anchor_date": "2025-02-15T09:44:19.546Z",
            "retry_interval": "DAY",
            "retry_interval_count": 1,
            "total_retry": 3,
            "failed_attempt_notifications": [
                1,
                3
            ],
            "created": "2024-12-04T07:59:28.545Z",
            "updated": "2024-12-04T07:59:28.545Z"
        },
        "immediate_action_type": "FULL_AMOUNT",
        "notification_config": {
            "locale": "en",
            "recurring_created": [
                "WHATSAPP",
                "EMAIL"
            ],
            "recurring_succeeded": [
                "WHATSAPP",
                "EMAIL"
            ],
            "recurring_failed": [
                "WHATSAPP",
                "EMAIL"
            ]
        },
        "metadata": null,
        "description": "Xendit Recurring Test",
        "actions": [
            {
                "url": "https://linking-dev.xendit.co/pali_a757f019-19b9-4522-91fe-03b6dc00368a",
                "action": "AUTH",
                "method": "GET",
                "url_type": "WEB"
            }
        ],
        "success_return_url": "https://www.xendit.co/",
        "failure_return_url": "https://www.xendit.co/",
        "items": null,
        "payment_link_for_failed_attempt": true,
        "failure_code": null
    }
  3. Setelah membuat Subscription, arahkan pengguna akhir ke halaman yang dihosting Xendit menggunakan objek dari actions respons API. Langkah ini memungkinkan pengguna akhir untuk menautkan metode pembayaran mereka ke paket Subscription.

  4. Setelah pengguna akhir berhasil menautkan metode pembayaran mereka, Xendit akan mengirimkan recurring.plan.activation webhook untuk mengonfirmasi aktivasi paket Subscription.

  5. Xendit akan mengirimkan recurring.cycle.created webhook untuk setiap siklus penagihan yang akan datang, memberi tahu Anda bahwa siklus berikutnya akan segera dimulai. Anda dapat menyimpan cycle.id di pihak Anda untuk digunakan untuk memperbarui tagihan siklus berikutnya.

  6. Untuk mengurangi saldo pengguna secara akurat untuk siklus penagihan mendatang, Anda harus menggunakan Update Cycle API untuk menentukan jumlah total berbasis penggunaan yang akan ditagih. Pembaruan ini harus diselesaikan sebelum tanggal ( scheduled_timestamp misalnya, jika scheduled_timestamp "20-12-2020", pembaruan harus dilakukan selambat-lambatnya "19-12-2020"). Setelah komponen scheduled_timestamp tanggal tercapai, tidak ada pembaruan lebih lanjut yang dapat dilakukan untuk siklus tersebut.

  7. Proses ini perlu diulang untuk setiap siklus penagihan berikutnya untuk mencerminkan biaya berbasis penggunaan yang benar.

Pelajari selengkapnya tentang lifecycle pembayaran di sini.