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

Simpan kartu dengan satu klik

Prev Next

Untuk menyederhanakan proses pembayaran bagi pelanggan yang kembali, tokenisasi kartu Xendit menawarkan solusi untuk menyimpan detail kartu pelanggan dengan aman dan efisien. Ini menghilangkan kebutuhan pembeli untuk memasukkan kembali informasi mereka pada setiap pembelian, sehingga menghasilkan proses checkout yang lebih lancar.. Anda dapat menyimpan beberapa kartu per pembeli dengan One-Click Payments with CVN atau Merchant-Initiated Transactions.

Alur penyimpanan kartu

Cara integrasi

  1. Buat payment session

    Untuk memulai proses tokenisasi, Anda perlu membuat sesi pembayaran dengan Xendit. session_type harus SAVE, dan amount harus 0.

Permintaan - POST /sesi

{
    "reference_id": "YOUR_PAYMENT_REFERENCE_ID",
    "session_type": "SAVE",
    "mode": "CARDS_SESSION_JS",
    "amount": 0,
    "currency": "IDR",
    "country": "ID",
    "customer": {
        "reference_id": "YOUR_CUSTOMER_REFERENCE",
        "type": "INDIVIDUAL",
        "email": "test@yourdomain.com",
        "mobile_number": "+6212345678",
        "individual_detail": {
            "given_names": "Jaap",
            "surname": "Stam"
        }
    },
    "cards_session_js": {
        "success_return_url": "https://yourcompany.com/success",
        "failure_return_url": "https://yourcompany.com/failure"
    }
}

Permintaan - POST /sesi

{
    "payment_session_id": "YOUR_PAYMENT_SESSION_ID",
    "created": "2024-11-28T07:03:19.571Z",
    "updated": "2024-11-28T07:03:19.571Z",
    "status": "ACTIVE",
    "reference_id": "YOUR_CUSTOMER_REFERENCE",
    "currency": "IDR",
    "amount": 0,
    "country": "ID",
    "customer_id": "cust-d7b12124-3dd1-471a-bf37-c956f44c2a2c",
    "expires_at": "2024-11-28T07:33:19.376Z",
    "session_type": "SAVE",
    "mode": "CARDS_SESSION_JS",
    "locale": "en",
    "business_id": "YOUR_BUSINESS_ID",
    "channel_properties": {
        "cards": {
            "skip_three_ds": false
        }
    },
    "cards_session_js": {
        "success_return_url": "https://yourcompany.com/success",
        "failure_return_url": "https://yourcompany.com/failure"
    }
}

  1. Kumpulkan informasi kartu

    Terapkan card_session.js untuk mengumpulkan informasi kartu.

Permintaan - card_session.js

{ 
    card_number: "4000000000001091"
    cardholder_email: "sample@email.com"
    cardholder_first_name: "firstName"
    cardholder_last_name: "lastName"
    cardholder_phone_number: "+6512341234"
    cvn: "123",
    expiry_month: "12"
    expiry_year: "2040"
    payment_session_id: "YOUR_PAYMENT_SESSION_ID"
}

response - card_session.js

{   "message": "Status updated. Wait for a callback or get the status using the Get API.", 
    "payment_token_id": "YOUR_PAYMENT_TOKEN_ID", 
    "action_url": "REDIRECT_URL" 
}

Penting: Anda harus menyimpan payment_token_id yang dikembalikan dalam respons ini dan mengirimkannya ke server Anda. payment_token_id ini sangat penting untuk melacak status tokenisasi kartu dan untuk transaksi di masa mendatang.

  1. Alihkan ke halaman autentikasi

    Setelah mengumpulkan informasi kartu, pelanggan Anda akan diarahkan ke halaman otentikasi 3D Secure (3DS) yang dihosting oleh bank penerbit. Setelah autentikasi berhasil, pelanggan akan diarahkan kembali ke halaman keberhasilan yang Anda tentukan (misalnya https://yourcompany.com/success).

  2. Terima webhook

    Xendit mengirimkan token pembayaran webhook ke endpoint webhook Anda yang memberikan update tentang aktivasi token pembayaran. Pastikan Anda mendengarkan webhook untuk mengonfirmasi status penyimpanan kartu.

Contoh webhook payment_token.activation:

{
    "created": "2024-12-18T03:57:21.601Z",
    "business_id": "62440e322008e87fb29c1fd0",
    "event": "payment_token.activation",
    "data": {
        "status": "ACTIVE",
        "country": "ID",
        "created": "2024-12-18T03:57:19.330Z",
        "updated": "2024-12-18T03:57:21.215Z",
        "currency": "IDR",
        "business_id": "62440e322008e87fb29c1fd0",
        "customer_id": "cust-9f02010d-1189-4f2c-95e9-fe7f52fdd29b",
        "channel_code": "CARDS",
        "reference_id": "efe51f0c-ea1f-45ec-96e4-5275db384d68_1b0d11cd-a",
        "token_details": {
            "authorization_data": {
                "reconciliation_id": "7344942402526026003955",
                "authorization_code": "831000",
                "acquirer_merchant_id": "xendit_ctv_agg",
                "network_response_code": "00",
                "network_transaction_id": "016153570198200",
                "cvn_verification_result": "M",
                "retrieval_reference_number": "435203752181",
                "address_verification_result": "M",
                "network_response_code_descriptor": "Approved and completed sucessfully"
            }
        },
        "payment_token_id": "pt-eda13864-5091-4bd2-b88d-ae640be90ee7",
        "channel_properties": {
            "card_details": {
                "type": "CREDIT",
                "issuer": "BRI",
                "country": "ID",
                "network": "VISA",
                "expiry_year": "2040",
                "fingerprint": "635a0be115cf90001ae83752",
                "expiry_month": "12",
                "cardholder_email": "test@yourdomain.com",
                "masked_card_number": "400000XXXXXX1091",
                "cardholder_last_name": "lastName",
                "cardholder_first_name": "firstName",
                "cardholder_phone_number": "+62812347290"
            },
            "skip_three_ds": true,
            "card_on_file_type": "CUSTOMER_UNSCHEDULED",
            "failure_return_url": "https://yourcompany.com/failure",
            "success_return_url": "https://yourcompany.com/success"
        }
    },
    "api_version": "v3"
}

  1. Mengambil detail kartu yang disimpan

    Setelah kartu berhasil ditokenisasi (dan Anda telah menerima webhook), payment_token.activation Anda dapat mengambil detail token dengan membuat permintaan GET ke payment_tokens/YOUR_PAYMENT_TOKEN_ID.

response - /v3/payment_tokens

{   
    "payment_token_id": "YOUR_PAYMENT_TOKEN_ID",
    "business_id": "YOUR_BUSINESS_ID",
    "customer_id": "YOUR_CUSTOMER_ID",
    "country": "ID",
    "reference_id": "YOUR_REFERENCE_ID",
    "currency": "IDR",
    "status": "ACTIVE",
    "actions": [],
    "created": "2024-12-05T02:05:56.176308Z",
    "updated": "2024-12-05T02:19:02.935905Z",
    "channel_properties": {
        "skip_three_ds": false,
        "success_return_url": "https://yourcompany.com/success",
        "failure_return_url": "https://yourcompany.com/failure",
        "card_details": {
            "masked_card_number": "400000XXXXXX1091",
            "cardholder_first_name": "Jaap",
            "cardholder_last_name": "Stam",
            "cardholder_email": "Jaap@stam.com",
            "cardholder_phone_number": "+6512341234",
            "expiry_month": "12",
            "expiry_year": "2040",
            "fingerprint": "635a0be115cf90001ae83752",
            "type": "CREDIT",
            "network": "VISA",
            "country": "ID",
            "issuer": "BRI"
        },
        "card_on_file_type": "CUSTOMER_UNSCHEDULED",
        "card_verification_results": {
            "three_ds_data": {
                "three_ds_flow": "CHALLENGE",
                "eci_code": "05",
                "three_ds_result": "AUTHENTICATED",
                "three_ds_result_reason": null,
                "three_ds_version": "2.1.0"
            },
            "cvn_result": null,
            "address_verification_result": "MATCH"
        }
    },
    "channel_code": "CARDS"
}

Gunakan token pembayaran untuk transaksi di masa mendatang

Setelah token pembayaran dihasilkan, token ini bertindak sebagai referensi aman ke detail kartu yang disimpan pengguna akhir. Anda dapat menggunakan token ini untuk transaksi di masa mendatang, berdasarkan perjanjian persetujuan Anda dengan pengguna akhir.

Use case untuk token pembayaran:

  1. Customer-Initiated Transactions (Returning Customers) - memungkinkan pengguna untuk menggunakan kartu yang disimpan dengan mulus untuk pembelian berikutnya. Untuk meningkatkan tingkat keberhasilan, sebaiknya minta pengguna untuk memasukkan kembali CVN mereka saat menyelesaikan transaksi. Lihat panduan integrasi

  2. Merchant-Initiated Transactions (Recurring Payments) - Anda dapat memulai transaksi tanpa interaksi pengguna akhir (misalnya, untuk langganan atau debit otomatis). Ideal untuk layanan berbasis langganan, keanggotaan, dan penagihan otomatis. Lihat panduan integrasi