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

Bayar dan simpan

Prev Next

Melakukan pembayaran dan menyimpan informasi pembayaran pengguna akhir secara bersamaan adalah alur bundel yang disederhanakan yang kami sebut sebagai "Bayar dan Simpan". Alur ini menampilkan pengumpulan pembayaran dan penyimpanan informasi pembayaran dalam satu panggilan API. Alur ini sering digunakan oleh merchant dengan jumlah pengguna berulang yang tinggi dan dengan kepercayaan merek yang kuat bagi pengguna untuk menyetujui menyimpan informasi pembayaran mereka.

Pada artikel ini, kita akan membahas integrasi dasar dengan API pembayaran kami untuk membayar dan menyimpan informasi pembayaran di bawah jenis alur PAY_AND_SAVE pada /payment_requests. Sebelum memulai, pastikan Anda telah menyelesaikan pengaturan environment integrasi Anda.

Alur Integrasi

Cara integrasi

  1. Buat halaman checkout

    Di aplikasi Anda, siapkan alur checkout untuk memfasilitasi langkah-langkah pembayaran yang akan dilalui pengguna akhir. Untuk langkah pertama, buat halaman checkout tempat channel pembayaran ditampilkan. Pengguna akhir akan memilih channel pembayaran yang mereka inginkan di sini. Dalam alur bayar dan tabung, kami juga menyarankan untuk mengumpulkan perjanjian pengguna akhir untuk bisnis Anda untuk menyimpan informasi pembayaran mereka.

  2. Kumpulkan data yang diperlukan untuk channel pembayaran yang dipilih
    Setelah pengguna akhir memilih channel, kumpulkan data yang diperlukan untuk memulai pembayaran dengan penyedia metode pembayaran. Lihat Routing channel pembayaran untuk daftar lengkap informasi yang diperlukan.

  3. Buat permintaan pembayaran
    Buat API request body untuk PAY_AND_SAVE dengan informasi yang diperlukan oleh channel pembayaran Anda. Dalam alur pembayaran ini, Anda juga harus meneruskan objek pelanggan customer_id atau pelanggan sebagai pengidentifikasi untuk pengguna akhir.

    Request - POST /payment_requests

    {
      "reference_id": "90392f42-d98a-49ef-a7f3-abcezas123",
      "customer": {
        "reference_id": "demo_1475801962607",
        "type": "INDIVIDUAL",
        "individual_detail": {
          "given_names": "John",
          "surname": "Doe"
        },
        "email": "example@xendit.co",
        "mobile_number": "+628000000000008"
      },
      "type": "PAY_AND_SAVE",
      "country": "PH",
      "currency": "PHP",
      "request_amount": 10000.01,
      "capture_method": "AUTOMATIC",
      "channel_code": "MAYA",
      "channel_properties": {
        "failure_return_url": "https://xendit.co/failure",
        "success_return_url": "https://xendit.co/success"
      },
      "description": "Description examples",
      "metadata": {
        "metametadata": "metametametadata"
      }
    }
    Response - POST /payment_requests

    {
      "business_id": "5f27a14a9bf05c73dd040bc8",
      "reference_id": "90392f42-d98a-49ef-a7f3-abcezas123",
      "payment_request_id": "pr-90392f42-d98a-49ef-a7f3-abcezas123",
      "customer_id": "cust-90392f42-d98a-49ef-a7f3-abcezas123",
      "type": "PAY_AND_SAVE",
      "country": "PH",
      "currency": "PHP",
      "request_amount": 10000.01,
      "capture_method": "AUTOMATIC",
      "channel_code": "MAYA",
      "channel_properties": {
        "failure_return_url": "https://xendit.co/failure",
        "success_return_url": "https://xendit.co/success"
      },
      "actions": [
        {
          "type": "REDIRECT_CUSTOMER",
          "value": "xendit.co/example",
          "descriptor": "WEB_URL"
        }
      ],
      "status": "REQUIRES_ACTION",
      "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 deskripsi pernyataan jika bidang properti channel menerima parameter statement_descriptor.

  4. 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. Pengalihan

      1. Tindakan "type": "REDIRECT_CUSTOMER"

      2. Di aplikasi klien, arahkan pengguna ke nilai url dalam tindakan. Untuk memaksimalkan tingkat keberhasilan pembayaran, Anda harus menangani pengalihan berdasarkan jenis perangkat pengguna. Perhatikan bahwa untuk channel pembayaran tertentu, ada aturan pengalihan untuk tertunda atau pembatalan. Aplikasi Anda harus dirancang untuk menangani skenario tersebut.

  5. 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.

    Dalam PAY_AND_SAVE alur, a payment_token_id akan disertakan dalam pembayaran webhook jika pembayaran berhasil ditagih.

    {
      "event": "payment.capture",
      "business_id": "5f27a14a9bf05c73dd040bc8",
      "created": "2021-12-02T14:52:21.566Z",
      "data": {
        "payment_id": "py-1402feb0-bb79-47ae-9d1e-e69394d3949c",
        "business_id": "5f27a14a9bf05c73dd040bc8",
        "reference_id": "90392f42-d98a-49ef-a7f3-abcezas123",
        "payment_request_id": "pr-1102feb0-bb79-47ae-9d1e-e69394d3949c",
        "payment_token_id": "pt-cc3938dc-c2a5-43c4-89d7-7570793348c2",
        "customer_id": "cust-b98d6f63-d240-44ec-9bd5-aa42954c4f48",
        "type": "PAY_AND_SAVE",
        "country": "PH",
        "currency": "PHP",
        "request_amount": 10000.01,
        "capture_method": "AUTOMATIC",
        "channel_code": "PAYMAYA",
        "channel_properties": {
          "success_return_url": "https://xendit.co/success",
          "failure_return_url": "https://xendit.co/failure"
        },
        "captures": [
          {
            "capture_timestamp": "2029-12-31T23:59:59Z",
            "capture_id": "cap-1502feb0-bb79-47ae-9d1e-e69394d3949c",
            "capture_amount": 10000.01
          }
        ],
        "status": "SUCCEEDED",
        "payment_details": {
          "remark": "example remark"
        },
        "metadata": {
          "metametadata": "metametametadata"
        },
        "created": "2029-12-31T23:59:59Z",
        "updated": "2029-12-31T23:59:59Z"
      }
    }


  6. Simpan token pembayaran untuk digunakan di masa mendatang

    Di sistem Anda, simpan ke payment_token_id pengguna terkait. Untuk pembayaran di masa mendatang, Anda dapat meneruskan  payment_token_id permintaan pembayaran ke dalam pembayaran yang lebih mudah.

  7. Tampilkan status pembayaran kepada pengguna

    Dengan status webhook, Anda seharusnya dapat menyelesaikan perjalanan pembayaran untuk pengguna akhir dengan berhasil menyelesaikan transaksi atau mengarahkan mereka kembali untuk dicoba lagi jika gagal.

    Di semua sistem pesan waktu nyata, ada kemungkinan webhook tidak mencapai sistem Anda. Aplikasi Anda juga harus melayani skenario di mana webhook tidak diterima saat pengguna akhir masih menunggu di layar mereka. Dalam kasus seperti itu, kami sarankan pemberitahuan pembayaran yang tertunda diberikan kepada pengguna akhir saat Anda menunggu webhook dari Xendit.

Status Lifecycle

Perlu tindakan pengguna

Berikut adalah status lifecycle untuk permintaan pembayaran yang memerlukan tindakan pengguna:

Status

Deskripsi

Event Webhook

REQUIRES_ACTION

Permintaan pembayaran memasuki status ini secara sinkron setelah respons API jika tindakan pengguna diperlukan untuk menyelesaikan otorisasi. Tangani actions objek pada tahap ini.

-

BERHASIL

Permintaan pembayaran beralih ke status ini saat pembayaran berhasil diselesaikan. Xendit akan mengirimkan webhook payment.capture sebagai pengidentifikasi pembayaran dan webhook payment_token.activation untuk token pembayaran yang dibuat. Anda harus menyimpan untuk payment_token_id digunakan dalam transaksi di masa mendatang.

  • payment.capture

  • payment_token.activation

GAGAL

Permintaan pembayaran beralih ke status ini saat pembayaran gagal. Xendit akan mengirimkan webhook payment.failure yang berisi untuk payment_request_id mengidentifikasi permintaan. Centang untuk failure_code menentukan tindakan berikutnya.

Catatan: Tidak semua channel pembayaran memberikan notifikasi untuk pembayaran yang gagal.

  • payment.failure

DIBATALKAN

Anda dapat membatalkan permintaan pembayaran yang berstatus REQUIRES_ACTION . Pembatalan akan segera mentransisikan permintaan pembayaran ke CANCELED, dan pengguna akhir tidak akan dapat lagi menyelesaikan file actions.

-

KEDALUWARSA

Permintaan pembayaran beralih ke status ini saat kedaluwarsa karena kedaluwarsa partner pembayaran.

-


Tidak perlu tindakan

Berikut adalah siklus proses status untuk permintaan pembayaran yang tidak memerlukan tindakan:

Status

Deskripsi

Event Webhook

BERHASIL

Permintaan pembayaran bertransisi ke status ini secara sinkron saat pembayaran segera berhasil. Anda masih akan menerima webhook payment.capture yang berisi detail pembayaran dan webhook payment_token.activation untuk token pembayaran yang dibuat.

  • payment.capture

  • payment_token.aktivasi

GAGAL

Permintaan pembayaran bertransisi ke status ini secara sinkron saat pembayaran segera gagal. Anda masih akan menerima webhook payment.failure.

Catatan: Tidak semua channel pembayaran memberikan notifikasi untuk proses penautan yang gagal.

  • payment.failure

TERTUNDA

Permintaan pembayaran memasuki status ini secara sinkron setelah respons API jika mitra pembayaran belum merespons dengan hasil pembayaran. Tunggu hingga webhook pembayaran tiba di URL webhook yang dikonfigurasi.

-