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

Simpan informasi pembayaran

Prev Next

Menyimpan informasi pembayaran pengguna untuk digunakan di masa mendatang adalah alur yang digunakan untuk meningkatkan tingkat keberhasilan pembayaran. Alur ini sering digunakan oleh merchant yang ingin mengelola dompet atau serangkaian channel pembayaran untuk pengguna akhir terlepas dari penagihan pembayaran.

Pada artikel ini, kami akan membahas integrasi dasar dengan API pembayaran kami untuk menyimpan informasi pembayaran dengan endpoint /payment_tokens. Sebelum memulai, pastikan Anda telah menyelesaikan pengaturan environment integrasi Anda.

Alur integrasi

Cara integrasi

  1. Buat halaman untuk menampilkan kemungkinan channel pembayaran untuk disimpan.

    Di aplikasi Anda, siapkan halaman untuk dipilih oleh pengguna akhir dan menyetujui penyimpanan informasi pembayaran untuk channel yang mereka inginkan. Pengguna akhir akan memilih channel pembayaran yang mereka inginkan di sini.

    Kami menyarankan untuk mengurutkan daftar channel pembayaran berdasarkan yang disukai oleh grup pengguna yang Anda targetkan. Anda juga dapat mempertimbangkan saldo rata-rata/kredit yang tersedia dalam channel pembayaran yang dipilih atau batas jumlah pembayaran.

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

  3. Buat permintaan token pembayaran
    Buat API request body dengan informasi yang diperlukan oleh channel pembayaran Anda.

    Request - POST /payment_tokens

    {
      "reference_id": "90392f42-d98a-49ef-a7f3-abcezas123",
      "customer_id": "cust-90392f42-d98a-49ef-a7f3-abcezas123",
      "country": "ID",
      "currency": "IDR",
      "channel_code": "OVO",
      "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_tokens

    {
      "business_id": "5f27a14a9bf05c73dd040bc8",
      "reference_id": "90392f42-d98a-49ef-a7f3-abcezas123",
      "payment_token_id": "pt-90392f42-d98a-49ef-a7f3-abcezas123",
      "customer_id": "cust-90392f42-d98a-49ef-a7f3-abcezas123",
      "country": "ID",
      "currency": "IDR",
      "channel_code": "OVO",
      "channel_properties": {
        "failure_return_url": "https://xendit.co/failure",
        "success_return_url": "https://xendit.co/success"
      },
      "actions": [
        {
          "type": "REDIRECT_CUSTOMER",
          "descriptor": "WEB_URL",
          "value": "https://ewallet-mock-connector.xendit.co/v1/ewallet_connector/checkouts?token=ciqv4nkabidq0em86ofg"
        }
      ],
      "status": "REQUIRES_ACTION",
      "description": "Description examples",
      "metadata": {
        "metametadata": "metametametadata"
      },
      "created": "2021-12-31T23:59:59Z",
      "updated": "2021-12-31T23:59:59Z"
    }



  4. Tangani tindakan yang diperlukan

    Setelah berhasil membuat permintaan token pembayaran dengan Xendit, Anda akan menerima objek token pembayaran kami. Jika status token 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, Anda harus menangani pengalihan berdasarkan jenis perangkat pengguna. Perhatikan bahwa untuk channelpembayaran tertentu, ada aturan pengalihan untuk tertunda atau pembatalan. Aplikasi Anda harus dirancang untuk menangani skenario tersebut.

  5. Terima webhook event token pembayaran untuk aktivasi token pembayaran
    Setelah pengguna akhir menyelesaikan langkah otentikasi 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.

    {
      "event": "payment_token.activation",
      "business_id": "5f27a14a9bf05c73dd040bc8",
      "created": "2021-12-02T14:52:21.566Z",
      "data": {
        "payment_token_id": "pt-1402feb0-bb79-47ae-9d1e-e69394d3949c",
        "business_id": "5f27a14a9bf05c73dd040bc8",
        "reference_id": "90392f42-d98a-49ef-a7f3-abcezas123",
        "customer_id": "cust-b98d6f63-d240-44ec-9bd5-aa42954c4f48",
        "country": "ID",
        "currency": "IDR",
        "channel_code": "OVO",
        "channel_properties": {
          "failure_return_url": "https://xendit.co/failure",
          "success_return_url": "https://xendit.co/success"
        },
        "actions": [
          {
            "type": "REDIRECT_CUSTOMER",
            "descriptor": "WEB_URL",
            "value": "https://xendit.co/"
          }
        ],
        "status": "ACTIVE",
        "token_details": {
          "account_name": "John Doe",
          "account_balance": "1000001",
          "account_point_balance": "50000"
        },
        "metadata": {
          "metametadata": "metametametadata"
        },
        "created": "2029-12-31T23:59:59Z",
        "updated": "2029-12-31T23:59:59Z"
      }
    }

  6. Tampilkan status token pembayaran kepada pengguna

    Dengan status webhook, Anda seharusnya dapat menyelesaikan perjalanan penyimpanan 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, disarankan untuk pemberitahuan pembayaran yang tertunda diberikan kepada pengguna akhir saat Anda menunggu webhook dari Xendit.

Status Lifecycle

Berikut adalah status lifecycle untuk token pembayaran

Status

Deskripsi

Event Webhook

REQUIRES_ACTION

Token pembayaran memasuki status ini secara sinkron setelah respons API agar pengguna akhir menyelesaikan proses penautan. Tangani actions objek pada tahap ini.

-

AKTIF

Token pembayaran bertransisi ke status ini saat linking berhasil diselesaikan. Xendit akan mengirimkan webhook payment_token.activation sebagai pengidentifikasi bahwa token pembayaran aktif. Anda harus menyimpan untuk payment_token_id digunakan dalam transaksi di masa mendatang.

  • payment_token.activation

GAGAL

Token pembayaran bertransisi ke status ini saat proses linking gagal. Xendit akan mengirimkan webhook payment_token.failure yang berisi sebagai payment_token_id pengidentifikasi. Tinjau untuk failure_code menentukan langkah berikutnya yang sesuai.

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

  • payment_token.failure

DIBATALKAN

Anda dapat mengakhiri kedaluwarsa token pembayaran yang ada dalam status secara ACTIVE manual. Kedaluwarsa segera mentransisikan permintaan pembayaran ke CANCELED, dan Anda tidak dapat menggunakan token pembayaran untuk transaksi lagi.

-

KEDALUWARSA

Token pembayaran bertransisi ke status ini saat kedaluwarsa karena kedaluwarsa partner pembayaran.

Catatan: Tidak semua channel pembayaran memberikan notifikasi untuk token pembayaran kedaluwarsa.

  • payment_token.expiry