Autentikasi dengan Konfirmasi Pembayaran Aman

Eiji Kitamura

Penjual dapat menggunakan Konfirmasi Pembayaran Aman (SPC) sebagai bagian dari proses autentikasi pelanggan (SCA) yang ketat untuk kartu kredit atau rekening bank tertentu. WebAuthn melakukan autentikasi (sering melalui biometrik). WebAuthn harus didaftarkan terlebih dahulu, yang dapat Anda pelajari di Mendaftarkan Konfirmasi Pembayaran Aman.

Cara kerja implementasi umum

Penggunaan SPC yang paling umum adalah saat pelanggan melakukan pembelian situs Anda, dan penerbit kartu kredit atau bank memerlukan autentikasi pembayar.

Mari kita pelajari alur autentikasi:

1. Pelanggan memberikan kredensial pembayarannya (seperti kartu kredit ) kepada penjual.
2. Penjual meminta penerbit atau bank terkait kredensial pembayaran (pihak tepercaya atau RP) jika pembayar memerlukan autentikasi terpisah. Ini pertukaran data mungkin terjadi, misalnya, EMV® 3-D Secure.
   • Jika RP ingin penjual menggunakan SPC, dan jika pengguna terdaftar, RP merespons dengan daftar ID kredensial yang didaftarkan oleh pembayar dan suatu tantangan.
   • Jika autentikasi tidak diperlukan, penjual dapat melanjutkan menyelesaikan transaksi.
3. Jika diperlukan autentikasi, penjual menentukan apakah browser mendukung SPC.
   • Jika browser tidak mendukung SPC, lanjutkan dengan alur otentikasi.
4. Penjual memanggil SPC. Browser menampilkan dialog konfirmasi.
   • Jika tidak ada ID kredensial yang diteruskan dari RP, kembali ke alur otentikasi yang ada. Setelah autentikasi berhasil, pertimbangkan untuk menggunakan pendaftaranSPC untuk menyederhanakan autentikasi pada masa mendatang.
5. Pengguna mengonfirmasi dan mengautentikasi jumlah dan tujuan item pembayaran dengan membuka kunci perangkat.
6. Penjual menerima kredensial dari autentikasi.
7. RP menerima kredensial dari penjual dan memverifikasi keaslian.
8. RP mengirimkan hasil verifikasi kepada penjual.
9. Penjual menampilkan pesan kepada pengguna untuk menunjukkan apakah pembayaran telah berhasil atau gagal.

Poin penting: Untuk mendukung eksperimen SPC awal dengan cepat, API ini dirancang di atas implementasi yang ada untuk Payment Request dan Payment Handler API. Sekarang sudah ada kesepakatan umum untuk mengeksplorasi desain SPC yang terlepas dari Permintaan Pembayaran. Kami memperkirakan (tanpa linimasa konkret) bahwa SPC akan bergerak asal permintaan pembayaran. Bagi developer, hal ini akan meningkatkan deteksi fitur, pemanggilan, dan aspek terkait API.

Deteksi fitur

Untuk mendeteksi apakah SPC didukung pada browser, Anda dapat mengirim panggilan palsu ke canMakePayment()

Salin dan tempel kode berikut untuk menampilkan fitur deteksi SPC di situs penjual.

const isSecurePaymentConfirmationSupported = async () => {
  if (!'PaymentRequest' in window) {
    return [false, 'Payment Request API is not supported'];
  }

  try {
    // The data below is the minimum required to create the request and
    // check if a payment can be made.
    const supportedInstruments = [
      {
        supportedMethods: "secure-payment-confirmation",
        data: {
          // RP's hostname as its ID
          rpId: 'rp.example',
          // A dummy credential ID
          credentialIds: [new Uint8Array(1)],
          // A dummy challenge
          challenge: new Uint8Array(1),
          instrument: {
            // Non-empty display name string
            displayName: ' ',
            // Transparent-black pixel.
            icon: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhAJ/wlseKgAAAABJRU5ErkJggg==',
          },
          // A dummy merchant origin
          payeeOrigin: 'https://non-existent.example',
        }
      }
    ];

    const details = {
      // Dummy shopping details
      total: {label: 'Total', amount: {currency: 'USD', value: '0'}},
    };

    const request = new PaymentRequest(supportedInstruments, details);
    const canMakePayment = await request.canMakePayment();
    return [canMakePayment, canMakePayment ? '' : 'SPC is not available'];
  } catch (error) {
    console.error(error);
    return [false, error.message];
  }
};

isSecurePaymentConfirmationSupported().then(result => {
  const [isSecurePaymentConfirmationSupported, reason] = result;
  if (isSecurePaymentConfirmationSupported) {
    // Display the payment button that invokes SPC.
  } else {
    // Fallback to the legacy authentication method.
  }
});

Mengautentikasi pengguna

Untuk mengautentikasi pengguna, panggil metode PaymentRequest.show() dengan Parameter secure-payment-confirmation dan WebAuthn:

• PublicKeyCredentialRequestOptions
• Parameter khusus pembayaran lainnya di platform penjual.

Berikut adalah parameter yang harus Anda berikan ke properti data metode pembayaran, SecurePaymentConfirmationRequest.

Parameter	Deskripsi
rpId	Nama host asal RP sebagai ID RP.
challenge	Tantangan acak yang mencegah serangan replay.
credentialIds	Array ID kredensial. Dalam autentikasi WebAuthn, properti allowCredentials menerima array objek PublicKeyCredentialDescriptor, tetapi di SPC, Anda hanya meneruskan daftar ID kredensial.
payeeName (opsional)	Nama penerima pembayaran.
payeeOrigin	Asal penerima pembayaran. Dalam skenario yang disebutkan di atas, kode tersebut adalah asal penjual.
instrument	String untuk displayName dan URL untuk icon yang mengarah ke resource gambar. Boolean opsional (default-nya adalah true) untuk iconMustBeShown yang menentukan ikon harus berhasil diambil dan ditampilkan agar permintaan berhasil.
timeout	Waktu tunggu untuk menandatangani transaksi dalam milidetik
extensions	Ekstensi ditambahkan ke panggilan WebAuthn. Anda tidak perlu menentukan "pembayaran" ekstensi diri Anda.

Lihat kode contoh ini:

// After confirming SPC is available on this browser via a feature detection,
// fetch the request options cross-origin from the RP server.
const options = fetchFromServer('https://rp.example/spc-auth-request');
const { credentialIds, challenge } = options;

const request = new PaymentRequest([{
  // Specify `secure-payment-confirmation` as payment method.
  supportedMethods: "secure-payment-confirmation",
  data: {
    // The RP ID
    rpId: 'rp.example',

    // List of credential IDs obtained from the RP server.
    credentialIds,

    // The challenge is also obtained from the RP server.
    challenge,

    // A display name and an icon that represent the payment instrument.
    instrument: {
      displayName: "Fancy Card ****1234",
      icon: "https://rp.example/card-art.png",
      iconMustBeShown: false
    },

    // The origin of the payee (merchant)
    payeeOrigin: "https://merchant.example",

    // The number of milliseconds to timeout.
    timeout: 360000,  // 6 minutes
  }
}], {
  // Payment details.
  total: {
    label: "Total",
    amount: {
      currency: "USD",
      value: "5.00",
    },
  },
});

try {
  const response = await request.show();

  // response.details is a PublicKeyCredential, with a clientDataJSON that
  // contains the transaction data for verification by the issuing bank.
  // Make sure to serialize the binary part of the credential before
  // transferring to the server.
  const result = fetchFromServer('https://rp.example/spc-auth-response', response.details);
  if (result.success) {
    await response.complete('success');
  } else {
    await response.complete('fail');
  }
} catch (err) {
  // SPC cannot be used; merchant should fallback to traditional flows
  console.error(err);
}

Fungsi .show() menghasilkan PaymentResponse kecuali details berisi kredensial kunci publik dengan clientDataJSON yang berisi data transaksi (payment) untuk diverifikasi oleh RP.

Kredensial yang dihasilkan harus ditransfer lintas origin ke RP dan diverifikasi.

Cara RP memverifikasi transaksi

Memverifikasi data transaksi di server RP adalah langkah terpenting dalam proses pembayaran.

Untuk memverifikasi data transaksi, RP dapat mengikuti proses verifikasi pernyataan autentikasi WebAuthn. Selain itu, mereka perlu verifikasi payment.

Contoh payload clientDataJSON:

{
  "type":"payment.get",
  "challenge":"SAxYy64IvwWpoqpr8JV1CVLHDNLKXlxbtPv4Xg3cnoc",
  "origin":"https://spc-merchant.glitch.me",
  "crossOrigin":false,
  "payment":{
    "rp":"spc-rp.glitch.me",
    "topOrigin":"https://spc-merchant.glitch.me",
    "payeeOrigin":"https://spc-merchant.glitch.me",
    "total":{
      "value":"15.00",
      "currency":"USD"
    },
    "instrument":{
      "icon":"https://cdn.glitch.me/94838ffe-241b-4a67-a9e0-290bfe34c351%2Fbank.png?v=1639111444422",
      "displayName":"Fancy Card 825809751248"
    }
  }
}

Perhatian: Properti type menggunakan payment.get, bukan public-key. Ini mungkin memerlukan beberapa penyesuaian pada WebAuthn yang ada library, jika Anda memilih untuk menggunakan salah satunya.

• rp cocok dengan asal RP.
• topOrigin cocok dengan origin tingkat atas yang diharapkan RP ( asal penjual dalam contoh di atas).
• payeeOrigin cocok dengan asal penerima pembayaran yang seharusnya yang ditampilkan kepada pengguna.
• total cocok dengan jumlah transaksi yang seharusnya ditampilkan kepada pengguna.
• instrument cocok dengan detail instrumen pembayaran yang seharusnya memiliki ditampilkan kepada pengguna.

const clientData = base64url.decode(response.clientDataJSON);
const clientDataJSON = JSON.parse(clientData);

if (!clientDataJSON.payment) {
  throw 'The credential does not contain payment payload.';
}

const payment = clientDataJSON.payment;
if (payment.rp !== expectedRPID ||
    payment.topOrigin !== expectedOrigin ||
    payment.payeeOrigin !== expectedOrigin ||
    payment.total.value !== '15.00' ||
    payment.total.currency !== 'USD') {
  throw 'Malformed payment information.';
}

Setelah semua kriteria verifikasi dilewati, RP dapat memberi tahu penjual bahwa transaksi berhasil.

Langkah berikutnya

• Baca ringkasan Konfirmasi Pembayaran Aman
• Pelajari pendaftaran Konfirmasi Pembayaran Aman