SDK

Untuk penggunaan web, pendekatan yang direkomendasikan adalah menggunakan Unico SDK dengan alasan berikut:

• Keamanan yang lebih tinggi;
• Pengalaman yang terintegrasi dengan alur Anda;
• Tingkat konversi yang lebih tinggi saat menggunakan SDK;
• Implementasi yang lebih mudah.

peringatan

Penggunaan integrasi yang tidak sesuai dengan standar yang ditetapkan dalam dokumentasi ini dapat mengakibatkan gangguan fungsionalitas sistem yang tidak terduga, yang tidak akan dicakup atau didukung oleh Verifikasi Kartu Tidak Hadir.

Contoh: Mengimplementasikan Unico melalui iFrame di dalam webview, mengimplementasikan iFrame melalui tag HTML, dll.

Panduan umum

Untuk mengoptimalkan performa operasi Anda, meningkatkan tingkat konversi, dan memberikan pengalaman pengguna yang lebih lancar, wajib untuk mengimplementasikan Unico SDK dalam mode full-screen di aplikasi Anda.

Cara memulai

Untuk menggunakan Verifikasi Kartu Tidak Hadir melalui SDK Verifikasi Kartu Tidak Hadir, langkah pertama adalah mendaftarkan domain yang akan digunakan sebagai host untuk menampilkan pengalaman perjalanan pengguna.

bahaya

Beri tahu penanggung jawab proyek integrasi Anda atau tim dukungan Unico untuk melakukan konfigurasi ini.

Untuk mulai menggunakan SDK, kita harus memulai dengan instalasi Unico web SDK:

npm install idpay-b2b-sdk

tips

Saat menginstal package Unico SDK, deploy tanpa menentukan versi yang Anda gunakan agar dependency manager Anda selalu memperbarui minor dan patch ke versi terbaru.

Untuk memeriksa versi sebelumnya, kunjungi npmjs.com/package/idpay-b2b-sdk.

Metode yang Tersedia

init(options)

Metode ini memungkinkan SDK diinisialisasi, terlepas dari ID transaksi, sehingga membuat pengalaman pengguna akhir menjadi lebih lancar. Hal ini karena ketika ID transaksi dan token tersedia, aplikasi akan sudah dimuat sebelumnya (pre-loaded) melalui metode ini. Jika metode ini tidak dipanggil langsung oleh aplikasi, pengguna akhir akan mengalami waktu muat yang lama saat SDK dibuka untuk pertama kalinya.

Parameters:

• options — menerima sebuah objek dengan properti konfigurasi:
  • type — jenis alur yang akan diinisialisasi. Saat ini, kami menawarkan jenis IFRAME. Untuk aplikasi baru, kami merekomendasikan menggunakan jenis IFRAME, yang membuat pengalaman pengguna akhir menjadi jauh lebih lancar dan dengan lebih sedikit friksi, karena menghindari kebutuhan untuk meninggalkan layar checkout, dan pengalaman tersebut dapat dimuat sebelumnya (preloaded).

import { IDPaySDK } from "idpay-b2b-sdk";

IDPaySDK.init({
  type: 'IFRAME',
  env: 'uat' // Only needed for the test environment.
});

open({ transactionId, token, onFinish? })

Metode ini membuka pengalaman Verifikasi Kartu Tidak Hadir sesuai dengan jenis alur yang dipilih sebelumnya pada function inisialisasi. Untuk alur REDIRECT, function ini melakukan redirect sederhana ke rute alur pengambilan Verifikasi Kartu Tidak Hadir. Untuk alur IFRAME, function ini menampilkan iframe yang telah dimuat sebelumnya (pre-loaded) dan memulai alur pengiriman pesan antara halaman pelanggan dan pengalaman Verifikasi Kartu Tidak Hadir.

Parameters:

• options — menerima sebuah objek dengan properti konfigurasi:
  • transactionId — menerima ID dari transaksi yang dibuat. ID ini penting untuk mendapatkan detail transaksi dan menyelesaikan alur dengan benar (ID ini dapat diperoleh saat pembuatan transaksi melalui API).
  • token — menerima token untuk transaksi yang dibuat. Token ini penting untuk mengautentikasi transaksi dan memastikan bahwa hanya domain yang berwenang yang menggunakannya (token ini dapat diperoleh saat pembuatan transaksi melalui API).
  • onFinish(transaction, type) (opsional) — menerima sebuah callback function yang akan dijalankan pada akhir alur pengambilan Verifikasi Kartu Tidak Hadir, dengan memberikan dua argumen: objek transaksi ({ captureConcluded, concluded, id }), dan jenis respons — FINISH untuk kasus di mana alur berhasil diselesaikan, atau ERROR untuk kasus di mana alur terputus karena kesalahan. Dalam kasus terjadi kesalahan pada alur, status transaksi tidak akan berubah, dan callback melalui webhook, jika dikonfigurasi, tidak akan dipicu.

const transactionId = '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf';
const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';

const transaction = {
  id: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
  concluded: true,
  captureConcluded: true
};

const onFinish = (transaction, type) => {
  console.log('response', transaction, type);
}

IDPaySDK.open({
  transactionId,
  token,
  onFinish
});

// You can also close the SDK explicitly using the method below
IDPaySDK.close();

Keamanan

Setelah analisis yang cermat terhadap kebutuhan dan tantangan yang kami hadapi, kami memutuskan untuk mengadopsi solusi berbasis iFrame dengan authentication token, bukan mengimplementasikan Content Security Policy (CSP). Keputusan ini didorong oleh berbagai pertimbangan terkait keamanan dan fleksibilitas yang diperlukan untuk memenuhi kebutuhan klien kami.

Konteks dan Tantangan dengan CSP

Content Security Policy (CSP) adalah alat yang kuat untuk melindungi aplikasi web dari berbagai jenis serangan, seperti Cross-Site Scripting (XSS) dan code injection. Namun, saat mengonfigurasi kebijakan CSP, perlu ditentukan daftar domain tepercaya yang ketat. Pendekatan ini bekerja dengan baik ketika domain bersifat tetap dan dapat diprediksi. Namun, bagi klien kami yang sering menggunakan domain yang dinamis dan bervariasi, konfigurasi yang kaku ini menghadirkan tantangan yang signifikan.

Kerentanan dengan Domain Dinamis

Domain dinamis menimbulkan risiko keamanan yang substansial saat menggunakan CSP. Ketika klien memiliki domain yang sering berubah atau dibuat secara dinamis, kebijakan CSP perlu terus-menerus diperbarui untuk menyertakan domain baru ini. Hal ini tidak hanya meningkatkan upaya pemeliharaan tetapi juga mengekspos domain yang menjadi cakupan kebijakan CSP tersebut. Setiap domain yang ditambahkan ke kebijakan CSP berpotensi menjadi titik kerentanan jika tidak dikelola dengan benar.

Solusi dengan iFrame dan Auth Token

Untuk mengurangi risiko ini dan memenuhi fleksibilitas yang dibutuhkan oleh klien kami, kami memilih untuk menggunakan iFrame yang dikombinasikan dengan authentication token. Solusi ini memberikan lapisan keamanan tambahan dan menghilangkan kebutuhan untuk mengekspos atau mengelola daftar domain yang luas dan dinamis.

Cara Kerjanya

• Autentikasi Aman: Setiap iframe dimuat dengan authentication token unik untuk setiap transaksi, memastikan bahwa hanya pengguna yang berwenang yang dapat mengakses konten tersebut. Token ini diverifikasi secara real-time, memberikan lapisan keamanan dan kontrol tambahan.
• Isolasi Konten: Penggunaan iFrame memungkinkan konten diisolasi dalam konteks yang terpisah, mengurangi risiko interferensi antar origin yang berbeda dan mengurangi potensi serangan.
• Fleksibilitas untuk Domain Dinamis: Dengan tidak bergantung pada kebijakan CSP yang statis, solusi kami dapat dengan mudah beradaptasi dengan domain dinamis klien tanpa perlu terus-menerus memperbarui kebijakan keamanan.