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

Kode pembayaran reusable

Prev Next

Bergantung pada kasus penggunaan pembayaran, Anda dapat memilih untuk menggunakan kode pembayaran yang dapat digunakan kembali untuk mengumpulkan beberapa instance pembayaran. Ini bisa menjadi kasus di mana nomor rekening bank virtual terikat ke akun satu pengguna untuk beberapa pembayaran atau kasus di mana satu kode QR ditampilkan di toko untuk beberapa pengguna untuk melakukan beberapa pembayaran individu.

Pada artikel ini, kita akan membahas integrasi dasar dengan API pembayaran kami untuk checkout tamu kami di jenis alur REUSABLE_PAYMENT_CODE pada /payment_requests. Sebelum memulai, pastikan Anda telah menyelesaikan pengaturan environment integrasi Anda.

Alur integrasi

Cara integrasi

  1. Buat halaman bagi pengguna untuk mengambil kode pembayaran

    Pada aplikasi Anda, siapkan halaman tempat pengguna akhir dapat memperoleh informasi tentang kode pembayaran yang dapat digunakan kembali. Sebaiknya sertakan instruksi pembayaran di samping kode pembayaran untuk mengurangi error pembayaran.

    Jika Anda berencana untuk menggunakan kode pembayaran di toko, Anda juga dapat mencetak nilai kode pembayaran untuk tampilan di toko.

  2. Buat permintaan pembayaran
    Saat pengguna memasuki halaman untuk mencoba pembayaran, buat API request body untuk REUSABLE_PAYMENT_CODE dengan informasi yang diperlukan oleh channel pembayaran Anda. Dalam skenario ini, permintaan type pembayaran Anda harus .REUSABLE_PAYMENT_CODE

    Request - POST /payment_requests

    {
      "reference_id": "90392f42-d98a-49ef-a7f3-abcezas123",
      "type": "REUSABLE_PAYMENT_CODE",
      "country": "ID",
      "currency": "IDR",
      "request_amount": 10000.01,
      "channel_code": "BRI_VIRTUAL_ACCOUNT",
      "channel_properties": {
        "expires_at": "2024-12-31T23:59:59Z"
      },
      "description": "Description examples",
      "metadata": {
        "metametadata": "metametametadata"
      }
    }

    Response - POST /payment_request

    {
      "business_id": "5f27a14a9bf05c73dd040bc8",
      "reference_id": "90392f42-d98a-49ef-a7f3-abcezas123",
      "payment_request_id": "pr-90392f42-d98a-49ef-a7f3-abcezas123",
      "type": "REUSABLE_PAYMENT_CODE",
      "country": "ID",
      "currency": "IDR",
      "request_amount": 10000.01,
      "capture_method": "AUTOMATIC",
      "channel_code": "BRI_VIRTUAL_ACCOUNT",
      "channel_properties": {
        "expires_at": "2024-12-31T23:59:59Z"
      },
      "actions": [
        {
          "type": "PRESENT_TO_CUSTOMER",
          "descriptor": "VIRTUAL_ACCOUNT_NUMBER",
          "value": "1251255"
        }
      ],
      "status": "ACCEPTING_PAYMENTS",
      "description": "Description examples",
      "metadata": {
        "metametadata": "metametametadata"
      },
      "created": "2021-12-31T23:59:59Z",
      "updated": "2021-12-31T23:59:59Z"
    }


    Fitur tambahan dapat dikonfigurasi jika channel pembayaran mengizinkannya. Misalnya, Anda akan dapat mengatur waktu kedaluwarsa permintaan pembayaran kustom jika kolom properti channel menerima parameter expires_at.

  3. Tangani tindakan yang diperlukan

    Setelah berhasil membuat permintaan pembayaran dengan Xendit, Anda akan menerima objek permintaan pembayaran kami. Jika status permintaan pembayaran adalah REQUIRES_ACTION, Anda harus melakukan beberapa tindakan pada aplikasi klien agar pengguna akhir dapat menyelesaikan pembayaran. Jika tidak ada tindakan yang diperlukan, status pembayaran akhir akan dikembalikan secara sinkron dan webhook dengan pembaruan status pembayaran akan dikirim.

    1. Presentasikan kepada pelanggan

      1. Tindakan "ketik": "PRESENT_TO_CUSTOMER"

      2. Di aplikasi klien, tampilkan nilai tindakan kepada pengguna. Jika itu adalah string QR, Anda mungkin perlu merendernya menjadi kode QR yang dapat dipindai. Untuk memaksimalkan tingkat keberhasilan pembayaran, Anda harus menyertakan beberapa instruksi pembayaran di samping nilai yang ditampilkan.

  4. Terima webhook event pembayaran untuk konfirmasi pembayaran
    Setelah pengguna akhir menyelesaikan langkah otentikasi pembayaran mereka dan penyedia metode pembayaran memberi tahu Xendit tentang pembaruan, Xendit akan melanjutkan untuk mengirim webhook ke url webhook yang Anda konfigurasikan di halaman pengaturan dasbor Xendit Anda.

    {
        "created": "2025-02-09T06:50:19.852Z",
        "business_id": "62440e322008e87fb29c1fd0",
        "event": "payment.capture",
        "data": {
            "type": "REUSABLE_PAYMENT_CODE",
            "status": "SUCCEEDED",
            "country": "ID",
            "created": "2025-02-09T06:50:18.000Z",
            "updated": "2025-02-09T06:50:18.000Z",
            "captures": [
                {
                    "capture_id": "cptr-fa2abf5c-b5e4-4cd5-95df-f2c949eba332",
                    "capture_amount": 10000,
                    "capture_timestamp": "2025-02-09T06:50:18.927Z"
                }
            ],
            "currency": "IDR",
            "payment_id": "py-4e0209e9-67a2-449a-9748-57df6a8bddad",
            "business_id": "62440e322008e87fb29c1fd0",
            "channel_code": "BNI_VIRTUAL_ACCOUNT",
            "reference_id": "test-1739083782",
            "capture_method": "AUTOMATIC",
            "request_amount": 10000,
            "payment_details": {},
            "payment_request_id": "pr-4f978be5-0e6a-4218-a281-155b362a9ffb"
        },
        "api_version": "v3"
    }
  5. Tampilkan status pembayaran kepada pengguna

    Untuk kode pembayaran yang dapat digunakan kembali, penting untuk memberikan informasi terbaru tentang pembayaran untuk pengguna Anda. Untuk melakukannya, sistem Anda harus dirancang untuk mengharapkan banyak kait web pembayaran masuk untuk satu kode pembayaran yang dapat digunakan kembali dan mengharapkan bahwa kait web ini dapat terjadi kapan saja. Seringkali, merchant akan menyiapkan halaman yang dapat menampilkan daftar lengkap pembayaran yang dikenali oleh kode pembayaran yang dapat digunakan kembali.

Lifecycle Pembayaran

Berikut adalah status lifecycle untuk permintaan pembayaran untuk alur kode pembayaran yang dapat digunakan kembali:

Status

Deskripsi

Event Webhook

ACCEPTING_PAYMENTS

Permintaan pembayaran memasuki status ini secara sinkron setelah respons API, yang menunjukkan bahwa permintaan tersebut siap menerima beberapa pembayaran menggunakan kode pembayaran yang dihasilkan. Setiap pembayaran yang berhasil dari pengguna akhir akan memicu webhook payment.capture yang dikirim ke URL yang dikonfigurasi.

  • payment.capture

DIBATALKAN

Anda dapat membatalkan permintaan pembayaran secara manual jika Anda tidak lagi ingin menerima pembayaran menggunakan kode pembayaran. Memicu titik akhir pembatalan akan mentransisikan permintaan pembayaran ke status CANCELED secara sinkron.

-

KEDALUWARSA

Permintaan pembayaran bertransisi ke status ini saat mencapai tanggal kedaluwarsa yang ditentukan dalam permintaan.

-