xendit docs

Tokenisasi ( Tokenization )

Mengumpulkan detail kartu menggunakan Xendit.js

Tutorial ini menjelaskan cara menggunakan HTML dan Xendit.js, library Javascript mendasar kami, untuk mengumpulkan detail kartu dan melakukan tokenisasi. Ada tiga langkah untuk mengumpulkan detail kartu:

  1. Mengumpulkan informasi kartu kredit dengan xendit.js
  2. Mengubah detail pembayaran tersebut menjadi token tunggal guna
  3. Mengirimkan token beserta form ke server Anda

Langkah-langkah diatas dapat dilakukan jika Anda memiliki form pembayaran HTML yang tipikal, yang dapat menampilkan pesan error yang dikembalikan dari Xendit.js. Sebagai contoh, contoh form yang telah memiliki pemeriksaan eror untuk memastikan respon yang diterima user valid, dan dapat mengembalikan eror untuk kemudian diolah oleh user.

Langkah 1: Mengumpulkan Informasi Kartu Kredit

Untuk mengumpulkan informasi kartu kredit dengan aman, include Xendit.js pada halam Anda dengan menempatkan kode ini pada bagian <head> dari website Anda. Perhatikan bahwa xendit.js harus dimuat dari CDN dan bukan dari lokal:

  • HTML
<!-- Place this code in the <head> section of your page -->      
<script type="text/javascript" src="https://js.xendit.co/v1/xendit.min.js"></script>      
<script type="text/javascript">      
	 Xendit.setPublishableKey('YOUR_PUBLISHABLE_API_KEY');      
</script>

Publishable Key Anda akan mengidentifikasi website Anda kepada Xendit selama dilakukan komunikasi. Tukar nilai tersebut dengan publishable API key Anda yang sesungguhnya untuk menguji coba dengan akun Xendit Anda.

Ketika Anda akan menggunakan environment production , pastikan untuk mengganti publishable key development ke production

Langkah 2: Validasi informasi kartu kredit

Sebelum memanggil method createToken , pastikan detail kartu kredit telah divalidasi. Xendit.js menyediakan method yang dapat digunakan untuk melakukan validasi nomor kartu kredit, masa berlaku, dan cvn. Silakan lihat contoh penggunaan metode tersebut sebagai berikut:


Xendit.card.validateCardNumber('4000000000000002'); // true
Xendit.card.validateCardNumber('abc'); // false

Xendit.card.validateExpiry('09', '2017'); // true
Xendit.card.validateExpiry('13', '2017'); // false

Xendit.card.validateCvn('123'); // true
Xendit.card.validateCvn('aaa'); // false

Langkah 3: Membuat token tunggal guna (single use token)

Demi keamanan, informasi kartu kredit pelanggan tidak akan pernah dikirimkan melalui server Anda, melainkan informasi kartu kredit telah di-tokenisasi (‘tokenized’) pada browser, dan token tersebut yang digunakan untuk menagih pembayaran kartu kredit. Kemudian langkah berikutnya dilakukan pengubahan detail pembayaran menjadi token tunggal guna. Proses ini dilakukan ketika terdapat jeda saat melakukan submit form, pada saat ini detail pembayaran dikirimkan langsung ke Xendit (dari browser pengguna).

Setelah pemanggilan fungsi setPublishableKey di kode javascript, buatlah sebuah event handler yang menangani submit event pada form. Handler harus mengirimkan detail from ke Xendit untuk tokenisasi dan mencegah terjadinya submit form (form akan di-submit javascript kemudian). Berikut contoh kode yang menampilkan kode yang dapat digunakan. Meskipun pada contoh ini digunakan jQuerry, Xendit.js tidak memiliki dependency , Anda dapat saja menggunakan vanilla Javascript.

  • JS
$(function() {        
	var $form = $('#payment-form');        
	$form.submit(function(event) {        
		// Disable the submit button to prevent repeated clicks:        
		$form.find('.submit').prop('disabled', true);        
        
		// Request a token from Xendit:        
		Xendit.card.createToken({        
			amount: $form.find('#amount').val(),        
			card_number: $form.find('#card-number').val(),        
			card_exp_month: $form.find('#card-exp-month').val(),        
			card_exp_year: $form.find('#card-exp-year').val(),        
			card_cvn: $form.find('#card-cvn').val()        
			is_multiple_use: false        
		}, xenditResponseHandler);        
        
		// Prevent the form from being submitted:        
		return false;        
	});        
});

Yang paling penting adalah pemanggilan Xendit.card.createToken . Parameter input pertama adalah detail pembayaran. Detail ini harus harus disediakan dalam bentuk generic object .

Parameter input kedua, xenditResponseHandler , adalah callback yang dapat Anda gunakan untuk menangani respon dari form Xendit. Callback ini menerima dua parameter input:

  • err adalah objek error yang menyimpan informasi kegagalan
  • response berisi data yang kemudian digunakan untuk melakukan penagihan ( charge )

Response memiliki format sebagai berikut

  • JSON
{        
	"id": "583733d0320b64b636258a99", // Token identifier        
	"status": "IN_REVIEW", // Token identifier status        
	"failure_reason": "", // Token identifier failure reason        
	"payer_authentication_url": "https://api.xendit.co/credit_c...", // URL where your customer can perform 3DS verification        
}

Ketika script Anda menerima respon dari server Xendit, maka fungsi xendiResponseHandlert akan dipanggil:

  • Jika informasi kartu yang dimasukkan oleh pengguna mengembalikan error, error akan ditampilkan pada halaman
  • Jika tidak ada error, maka token tunggal guna ( single-use token ) telah berhasil dibuat, dan akan mengembalikan identifier token ke form yang kemudian akan di- submit ke server Anda.

Untuk memperoleh token pada server Anda, token tersimpan pada hidden input yang beru. Nilai token tersebut adalah token ID yang diterima sebelumnya.

Beberapa kartu kredit membutuhkan proses autentikasi tambahan yang dikenal dengan OTP (one-time password) atau 3D Secure (3DS). Agar kartu-kartu tersebut dapat digunakan pada website Anda, Anda harus memiliki tempat untuk dilakukan render halaman verifikasi 3DS yang akan digunakan pengguna untuk memasukkan kode OTP mereka. Pada umumnya hal ini dapat dilakukan dengan menempatkan iframe , namun Anda juga dapat menerapkannya dengan cara lain. Hal penting yang harus Anda perhatikan adalah:

  • Jika pengguna melakukan refresh pada halaman 3DS (atau menutup halaman pop-up 3DS), maka tampilan akan kembali ke halaman pengguna mengisi informasi kartu kredit.
  • Ketika proses 3DS selelai, iframe atau halaman akan tertutup dan pengguna akan diarahkan ke halaman berhasil atau error Anda, tergantung dengan hasilnya.

Untuk kartu-kartu kredit yang mengharuskan penggunaan 3DS, status dari respon akan bernilai IN_REVIEW dan akan ada field bernama payer_authentication_url . Anda harus mengirimkan URL autentikasi ini agar pemilik kartu dapat memasukkan informasi 3DS mereka. Selain itu, setelah proses 3DS selesai atau gagal, fungsi callback yang sama, xenditResponseHandler , akan dipanggil dan mengembalikan informasi token ID yang telah diperbarui.

Berikut contoh lengkap dari xenditResponseHandler , termasuk membuka iframe untuk verivikasi 3DS:

  • JS
function xenditResponseHandler (err, creditCardCharge) {        
	if (err) {        
		// Show the errors on the form        
		$('#error pre').text(err.message);        
		$('#error').show();        
		$form.find('.submit').prop('disabled', false); // Re-enable submission        
        
		return;        
	}        
        
	if (creditCardCharge.status === 'VERIFIED') {        
		// Get the token ID:        
		var token = creditCardCharge.id;        
        
		// Insert the token into the form so it gets submitted to the server:        
		$form.append($('<input type="hidden" name="xenditToken" />').val(token));        
        
		// Submit the form to your server:        
		$form.get(0).submit();        
	} else if (creditCardCharge.status === 'IN_REVIEW') {        
		window.open(creditCardCharge.payer_authentication_url, 'sample-inline-frame');        
		$('#three-ds-container').show();        
	} else if (creditCardCharge.status === 'FAILED') {        
		$('#error pre').text(creditCardCharge.failure_reason);        
		$('#error').show();        
		$form.find('.submit').prop('disabled', false); // Re-enable submission        
	}      
}

Mengumpulkan detail kartu dengan mobile SDK

Langkah-langkah untuk menggunakan mobile SDK dapat dilihat di:

  1. Android
  2. iOS

Referensi Tokenisasi

Untuk referensi API selengkapnya dapat dilihat di apireference Xendit .

Langkah Selanjutnya

Pertanyaan?

Masih memiliki pertanyaan? Dengan senang hati kami akan membantu Anda. Kirimkan email atau pesan melalui live chat .

Collecting cards detail using Xendit.js

This tutorial explains how to use HTML and Xendit.js, our foundational JavaScript library, to collect the card details and perform tokenization. There are three steps to collecting card details:

  1. Collecting credit card information with xendit.js
  2. Converting those payment details to a single-use token
  3. Submitting that token, with the rest of your form, to your server

The above steps assume you have a typical HTML payment form, with a span for displaying error messages returned by Xendit.js. For an example, here is a sample form that includes basic error checking to ensure valid responses from the user, and a span to display any errors back to the user for them to take action.

Step 1: Collect credit card information

To securely collect the credit card information, include Xendit.js in your page by putting this code into the <head> section of your website. Note that xendit.js should be loaded from the CDN and not locally:

  • HTML
<!-- Place this code in the <head> section of your page -->      
<script type="text/javascript" src="https://js.xendit.co/v1/xendit.min.js"></script>      
<script type="text/javascript">      
	 Xendit.setPublishableKey('YOUR_PUBLISHABLE_API_KEY');      
</script>

Your publishable API key identifies your website to Xendit during communications. Replace it with your actual publishable API key to test this code through your Xendit account.

When you're ready for production, be sure to change from the development publishable key to the production publishable key.

Step 2: Validate the credit card information

Before calling the createToken method, ensure that the credit card data is validated. Xendit.js provides methods that can be used to validate the card number, the expiry date, and the cvn. Please see example usage of those methods below:


Xendit.card.validateCardNumber('4000000000000002'); // true
Xendit.card.validateCardNumber('abc'); // false

Xendit.card.validateExpiry('09', '2017'); // true
Xendit.card.validateExpiry('13', '2017'); // false

Xendit.card.validateCvn('123'); // true
Xendit.card.validateCvn('aaa'); // false

Step 3: Create a single use token

For security, the customer’s credit card information never passes through your servers. Instead, the credit card information is ‘tokenized’ in the browser, and that token is what you need to charge the credit card. So, this second step is to convert the payment details into a single-use representative token. This is done by pausing the form's submission and passing the payment details directly to Xendit (from the user's browser).

After the javascript code where setPublishableKey was called, create an event handler that handles the submit event on the form. The handler should send the form data to Xendit for tokenization and prevent the form's submission (the form will be submitted by JavaScript later). Here is some sample code illustrating how this can be done. While this example uses jQuery, Xendit.js has no external dependencies. You can use vanilla JavaScript if you'd rather.

  • JS
$(function() {        
	var $form = $('#payment-form');        
	$form.submit(function(event) {        
		// Disable the submit button to prevent repeated clicks:        
		$form.find('.submit').prop('disabled', true);        
        
		// Request a token from Xendit:        
		Xendit.card.createToken({        
			amount: $form.find('#amount').val(),        
			card_number: $form.find('#card-number').val(),        
			card_exp_month: $form.find('#card-exp-month').val(),        
			card_exp_year: $form.find('#card-exp-year').val(),        
			card_cvn: $form.find('#card-cvn').val()        
			is_multiple_use: false        
		}, xenditResponseHandler);        
        
		// Prevent the form from being submitted:        
		return false;        
	});        
});

The most important line is the call to Xendit.card.createToken . The first argument is the payment details. This must be provided as individual members of a generic object.

The second argument, xenditResponseHandler , is a callback you will need to write that handles the response from Xendit. The handler accepts two arguments:

  • err is an error object which has information about failures
  • response contains the data that will be used to make a charge later

Response has the following format:

  • JSON
{        
	"id": "583733d0320b64b636258a99", // Token identifier        
	"status": "IN_REVIEW", // Token identifier status        
	"failure_reason": "", // Token identifier failure reason        
	"payer_authentication_url": "https://api.xendit.co/credit_c...", // URL where your customer can perform 3DS verification        
}

When your script receives the response from Xendit's servers, the xenditResponseHandler function is called:

  • If the card information entered by the user returned an error, the error gets displayed on the page
  • If no errors were returned—a single-use token was created successfully, add the returned token identifier to the form and submit the form to your server

To get the token to your server, it's stored in a new hidden input. Its value is the received token's ID.

Some credit cards require an additional level of authentication known as an OTP (one-time password) or 3D Secure (3DS). For your website to support these cards, you will need to have a place on the website to render the 3DS verification screen where the user can enter their OTP. This is often accomplished with an iframe, but you can implement it any way you prefer. It is important to ensure that:

  • If the user refreshes on the 3DS page (or closes a 3DS pop-up window), they are returned to the page where they enter credit card information.
  • When the 3DS process is completed, the iframe or window is closed and the user is directed to your success or error page, depending on the result.

If your customer's credit card requires 3DS, the status will be IN_REVIEW and there will be a field named payer_authentication_url . You will need to send your customer to this URL so they can enter their 3DS details. Additionally, when 3DS completes or fails, the same callback function, xenditResponseHandler , will be called with the updated token identifier information.

Below is a full example of xenditResponseHandler , including opening a new iframe for 3DS verification:

  • JS
function xenditResponseHandler (err, creditCardCharge) {        
	if (err) {        
		// Show the errors on the form        
		$('#error pre').text(err.message);        
		$('#error').show();        
		$form.find('.submit').prop('disabled', false); // Re-enable submission        
        
		return;        
	}        
        
	if (creditCardCharge.status === 'VERIFIED') {        
		// Get the token ID:        
		var token = creditCardCharge.id;        
        
		// Insert the token into the form so it gets submitted to the server:        
		$form.append($('<input type="hidden" name="xenditToken" />').val(token));        
        
		// Submit the form to your server:        
		$form.get(0).submit();        
	} else if (creditCardCharge.status === 'IN_REVIEW') {        
		window.open(creditCardCharge.payer_authentication_url, 'sample-inline-frame');        
		$('#three-ds-container').show();        
	} else if (creditCardCharge.status === 'FAILED') {        
		$('#error pre').text(creditCardCharge.failure_reason);        
		$('#error').show();        
		$form.find('.submit').prop('disabled', false); // Re-enable submission        
	}      
}

Collecting cards detail using mobile SDK

Steps to use our mobile SDK can be found in:

  1. Android
  2. iOS

Tokenization Reference

For full API reference you can check our apireference .

Next Steps

Questions?

Still have more questions? We're always happy to help however we can. Shoot us an email or chat to us in live chat.