Bayar dan Simpan

  • Dipublikasikan pada Jun 26, 2025
Prev Next

Mengintegrasikan pembayaran dan menyimpan detail kartu dengan aman di halaman checkout Anda sangat mudah dengan alur "Bayar dan Simpan" kami. Hal ini memungkinkan pelanggan Anda untuk menyimpan informasi kartu mereka untuk transaksi di masa mendatang selama satu perjalanan pengguna akhir.

Alur pembayaran dan simpan (dengan autentikasi)

  1. Buat sesi pembayaran

Request - POST /sesi

{
    "reference_id": "YOUR_PAYMENT_REFERENCE_ID",
    "session_type": "PAY",
    "mode": "CARDS_SESSION_JS",
    "amount": 100000,
    "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"
    }
}

Response - POST /sesi

{
    "payment_session_id": "ps-6746c1006b7752b4d91725af",
    "created": "2024-11-27T06:49:36.535Z",
    "updated": "2024-11-27T06:49:36.535Z",
    "status": "ACTIVE",
    "reference_id": "YOUR_PAYMENT_REFERENCE_ID",
    "currency": "IDR",
    "amount": 10000,
    "country": "ID",
    "customer_id": "XENDIT_GENERATED_CUSTOMER_ID",
    "expires_at": "2024-11-27T07:19:36.434Z",
    "session_type": "PAY",
    "mode": "CARDS_SESSION_JS",
    "locale": "en",
    "business_id": "YOUR_BUSINESS_ID", 
    "cards_session_js": {
        "success_return_url": "https://yourcompany.com/success",
        "failure_return_url": "https://yourcompany.com/failure"
    }
}

  1. Kumpulkan informasi kartu

    Buat card_session.js pada halaman Anda. Kumpulkan informasi kartu menggunakan Xendit.payment.collectCardData(reqData, xenditResponseHandler). Ini akan mengumpulkan informasi kartu dan mengirimkannya ke Xendit menggunakan card_session.js.

Permintaan - untuk card_session_js

{
    "card_number": "4000000000001091",
    "expiry_month": "12",
    "expiry_year": "2040",
    "cvn": "123",
    "cardholder_first_name": "Firstname",
    "cardholder_last_name": "Last",
    "cardholder_email": "shopper@emailaddress.com",
    "cardholder_phone_number": "+61111111111",
    "save_card_payment_token": true,
    "payment_session_id": "YOUR_PAYMENT_SESSION_ID"
}

response - dari card_session_js

{ 
    "message": "Status updated. Wait for a callback or get the status using the Get API.", 
    "payment_request_id": "PAYMENT_REQUEST_ID", 
    "action_url": "AUTHENTICATION_PAGE_URL" 
}

Penting: Simpan payment_request_id karena Anda akan memerlukannya untuk mengambil status transaksi dan akan disertakan dalam webhook untuk pembaruan status.

  1. Alihkan ke halaman autentikasi

    Arahkan pelanggan ke halaman autentikasi menggunakan action_url objek from the response.

  2. Pelanggan menyelesaikan otentikasi

    Setelah autentikasi berhasil , pelanggan Anda diarahkan ke success_return_url Jika autentikasi gagal, autentikasi tersebut dapat dialihkan ke failure_return_url.

  3. Terima webhook

    Xendit mengirimkan webhook pembayaran ke endpoint webhook Anda yang menunjukkan status akhir transaksi. Anda dapat mencocokkan webhook pembayaran dengan payment_request_id.

Contoh webhook payment.capture:

{
    "created": "2024-12-18T05:46:35.109Z",
    "business_id": "62440e322008e87fb29c1fd0",
    "event": "payment.capture",
    "data": {
        "type": "PAY",
        "status": "SUCCEEDED",
        "country": "ID",
        "created": "2024-12-18T05:46:08.192Z",
        "updated": "2024-12-18T05:46:30.627Z",
        "captures": [
            {
                "capture_id": "cptr-08f17fa3-e80c-4d8e-8c34-17aa3400bc1c",
                "capture_amount": 10000,
                "capture_timestamp": "2024-12-18T05:46:34.234Z"
            }
        ],
        "currency": "IDR",
        "payment_id": "py-3f57d678-2448-4c9f-a433-8468d366fb5c",
        "business_id": "62440e322008e87fb29c1fd0",
        "customer_id": "cust-7de9a9b4-37e8-40ad-b665-d97f42e538c5",
        "channel_code": "CARDS",
        "reference_id": "97ba0a32-b996-4abf-8a7b-6184a6644676_b8d18f2f-3",
        "capture_method": "AUTOMATIC",
        "request_amount": 10000,
        "payment_details": {
            "authorization_data": {
                "reconciliation_id": "7345007929096981703954",
                "authorization_code": "831000",
                "acquirer_merchant_id": "xendit_ctv_agg",
                "network_response_code": "00",
                "network_transaction_id": "016153570198200",
                "cvn_verification_result": "M",
                "retrieval_reference_number": "435205253972",
                "address_verification_result": "M",
                "network_response_code_descriptor": "Approved and completed sucessfully"
            },
            "authentication_data": {
                "flow": "CHALLENGE",
                "a_res": {
                    "eci": "05",
                    "message_version": "2.1.0",
                    "authentication_value": "AAIBBYNoEwAAACcKhAJkdQAAAAA=","directory_server_trans_id": "e537f539-d59f-4ebe-8d56-7fdc31a8e9b4"
                }
            }
        },
        "payment_request_id": "pr-5593127f-8c7b-4d2f-b487-c785ffc21e2f",
        "payment_token_id": "pt-8983127f-98er-76dr-67er-d985gff21z2f"
    },
    "api_version": "v3"
}

Kami menyarankan untuk menyimpan payment_id dan payment_details dari webhook, yang berkorelasi dengan payment_request_id, sebagai bukti pembayaran.

Bayar dan Simpan tanpa autentikasi

Kami sangat menyarankan Anda untuk melakukan autentikasi saat memproses transaksi kartu. Autentikasi tidak hanya memberikan liability shift (melindungi Anda dari sengketa penipuan tertentu), tetapi juga untuk memverifikasi identitas pengguna.

Namun, berdasarkan permintaan dan setelah penilaian berbasis resiko, Xendit dapat mengaktifkan guest checkout tanpa mewajibkan autentikasi. Kami akan melakukan penilaian berbasis risiko sebelum mengizinkan Anda menerima transaksi tanpa autentikasi.

Alur Bayar dan Simpan tanpa autentikasi

  1. Buat payment session

Request - POST /sesi

{
    "reference_id": "YOUR_PAYMENT_REFERENCE_ID",
    "session_type": "PAY",
    "mode": "CARDS_SESSION_JS",
    "amount": 10000,
    "currency": "IDR",
    "channel_properties": {
        "cards": {
            "skip_three_ds": true
        }
    },
    "country": "ID",
    "customer": {
        "reference_id": "YOUR_CUSTOMER_REFERENCE",
        "type": "INDIVIDUAL",
        "email": "test@yourdomain.com",
        "mobile_number": "+6212345678",
        "individual_detail": {
            "given_names": "Lorem",
            "surname": "Ipsum"
        }
    },
    "cards_session_js": {
        "success_return_url": "https://yourcompany.com/success",
        "failure_return_url": "https://yourcompany.com/failure"
    }
}

Response - POST /sesi

{
    "payment_session_id": "UNIQUE_PAYMENT_SESSION_ID",
    "created": "2024-11-28T05:07:14.585Z",
    "updated": "2024-11-28T05:07:14.585Z",
    "status": "ACTIVE",
    "reference_id": "new-uuid8",
    "currency": "IDR",
    "amount": 10000,
    "country": "ID",
    "customer_id": "cust-f945d691-2101-4582-890a-12afd211ea12",
    "expires_at": "2024-11-28T05:37:14.390Z",
    "session_type": "PAY",
    "mode": "CARDS_SESSION_JS",
    "locale": "en",
    "business_id": "62440e322008e87fb29c1fd0",
    "channel_properties": {
        "cards": {
            "skip_three_ds": true
        }
    },
    "cards_session_js": {
        "success_return_url": "https://yourcompany.com/success",
        "failure_return_url": "https://yourcompany.com/failure"
    }
}

  1. Kumpulkan informasi kartu

    Buat card_session.js pada halaman Anda. Collect the card information menggunakan Xendit.payment.collectCardData(reqData, xenditResponseHandler). Ini akan mengumpulkan informasi kartu dan mengirimkannya ke Xendit menggunakan card_session.js.

Request - untuk card_session_js

{
    "card_number": "4000000000001091",
    "expiry_month": "12",
    "expiry_year": "2040",
    "cvn": "123",
    "cardholder_first_name": "firstName",
    "cardholder_last_name": "lastName",
    "cardholder_email": "shopper@emailaddress.com",
    "cardholder_phone_number": "+61111111111",
    "save_card_payment_token": true,
    "payment_session_id": "YOUR_PAYMENT_SESSION_ID"
}

Response - dari card_session_js

{ 
    "message": "Status updated. Wait for a callback or get the status using the Get API.", 
    "payment_request_id": "PAYMENT_REQUEST_ID" 
}

Penting: Simpan payment_request_id untuk mengambil status transaksi nanti.

  1. Terima webhook

    Xendit mengirimkan webhook pembayaran ke endpoint webhook Anda yang menunjukkan status akhir transaksi. Anda dapat mencocokkan webhook pembayaran dengan payment_request_id.

Contoh webhook payment.capture:

{
    "created": "2024-12-18T05:46:35.109Z",
    "business_id": "62440e322008e87fb29c1fd0",
    "event": "payment.capture",
    "data": {
        "type": "PAY",
        "status": "SUCCEEDED",
        "country": "ID",
        "created": "2024-12-18T05:46:08.192Z",
        "updated": "2024-12-18T05:46:30.627Z",
        "captures": [
            {
                "capture_id": "cptr-08f17fa3-e80c-4d8e-8c34-17aa3400bc1c",
                "capture_amount": 10000,
                "capture_timestamp": "2024-12-18T05:46:34.234Z"
            }
        ],
        "currency": "IDR",
        "payment_id": "py-3f57d678-2448-4c9f-a433-8468d366fb5c",
        "business_id": "62440e322008e87fb29c1fd0",
        "customer_id": "cust-7de9a9b4-37e8-40ad-b665-d97f42e538c5",
        "channel_code": "CARDS",
        "reference_id": "97ba0a32-b996-4abf-8a7b-6184a6644676_b8d18f2f-3",
        "capture_method": "AUTOMATIC",
        "request_amount": 10000,
        "payment_details": {
            "authorization_data": {
                "reconciliation_id": "7345007929096981703954",
                "authorization_code": "831000",
                "acquirer_merchant_id": "xendit_ctv_agg",
                "network_response_code": "00",
                "network_transaction_id": "016153570198200",
                "cvn_verification_result": "M",
                "retrieval_reference_number": "435205253972",
                "address_verification_result": "M",
                "network_response_code_descriptor": "Approved and completed sucessfully"
            },
            "authentication_data": {
                "flow": "CHALLENGE",
                "a_res": {
                    "eci": "05",
                    "message_version": "2.1.0",
                    "authentication_value": "AAIBBYNoEwAAACcKhAJkdQAAAAA=","directory_server_trans_id": "e537f539-d59f-4ebe-8d56-7fdc31a8e9b4"
                }
            }
        },
        "payment_request_id": "pr-5593127f-8c7b-4d2f-b487-c785ffc21e2f",
        "payment_token_id": "pt-8983127f-98er-76dr-67er-d985gff21z2f"
    },
    "api_version": "v3"
}

Kami sarankan untuk menyimpan payment_id dan payment_details dari webhook, yang berkorelasi dengan payment_request_id, sebagai bukti pembayaran.

Dapatkan detail token pembayaran

Untuk mengambil detail token pembayaran yang disimpan, seperti masked_card_number, gunakan endpoint berikut:

https://api.xendit.co/v3/payment_token/YOUR_PAYMENT_TOKEN_ID

Ini akan mengembalikan detail token pembayaran.

Response - dari payment_token

{
    "payment_token_id": "pt-f5f570a2-f204-49ae-b2f0-10b786de5047",
    "business_id": "62440e322008e87fb29c1fd0",
    "customer_id": "cust-c1a6b0a0-a501-4479-8b57-d038601f139e",
    "country": "ID",
    "reference_id": "ref-id-1_Z6a2sG4sfp",
    "currency": "IDR",
    "status": "ACTIVE",
    "actions": [],
    "created": "2025-01-10T08:45:24.687Z",
    "updated": "2025-01-10T08:45:41.246Z",
    "channel_properties": {
        "success_return_url": "https://checkout-staging.xendit.co/session/ps-6780de086602873447b03b01?token_request_id=82232fe7-32bc-4004-ae15-0cb99dc56b5f",
        "failure_return_url": "https://checkout-staging.xendit.co/session/ps-6780de086602873447b03b01?token_request_id=82232fe7-32bc-4004-ae15-0cb99dc56b5f",
        "skip_three_ds": false,
        "card_on_file_type": "RECURRING",
        "recurring_configuration": {
            "recurring_expiry": "2025-12-12",
            "recurring_frequency": 30
        },
        "card_details": {
            "masked_card_number": "400000XXXXXX1091",
            "expiry_month": "01",
            "expiry_year": "2028",
            "fingerprint": "62c571cc9f1788001b255135",
            "type": "CREDIT",
            "network": "VISA",
            "country": "ID",
            "issuer": "BRI",
            "cardholder_first_name": "John",
            "cardholder_last_name": "Doe",
            "cardholder_email": "test@yourdomain.com",
            "cardholder_phone_number": "+628121233333"
        }
    },
    "channel_code": "CARDS",
    "token_details": {
        "authentication_data": {
            "flow": "CHALLENGE",
            "a_res": {
                "eci": "05",
                "message_version": "2.1.0",
                "authentication_value": "AAIBBYNoEwAAACcKhAJkdQAAAAA=","directory_server_trans_id": "df613bfd-2619-4f1c-989c-f7b32029d4a7"
            }
        },
        "authorization_data": {
            "cvn_verification_result": "M",
            "address_verification_result": "M",
            "network_response_code": "00",
            "network_response_code_descriptor": "Approved and completed sucessfully",
            "authorization_code": "831000",
            "retrieval_reference_number": "501008635675",
            "acquirer_merchant_id": "xendit_ctv_agg",
            "reconciliation_id": "7364987404086454403955",
            "network_transaction_id": "016153570198200"
        }
    }
}

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