Spesifikasi pemroses pembayaran Google Pay

Nama Handler: com.google.pay
Versi: 2026-01-11

1. Pengantar

Handler com.google.pay memungkinkan bisnis menawarkan Google Pay sebagai opsi checkout yang dipercepat melalui platform yang kompatibel dengan UCP. Google Pay API memungkinkan checkout cepat dengan memberi pengguna akses ke metode pembayaran yang disimpan di Akun Google mereka.

Handler ini memungkinkan model integrasi tanpa UI di mana bisnis menyediakan konfigurasi Google Pay mereka (seperti jaringan kartu yang diizinkan dan parameter gateway), dan platform menangani interaksi sisi klien dengan Google Pay API untuk membuat token pembayaran yang aman.

1.1 Manfaat Utama

Konfigurasi Universal: Bisnis mengonfigurasi Google Pay satu kali menggunakan JSON standar, sehingga platform resmi mana pun dapat merender antarmuka pembayaran tanpa kode frontend kustom.
Frontend yang Tidak Terikat: Platform menangani kompleksitas integrasi Google Pay JavaScript API atau SDK, sementara bisnis menggunakan token yang dihasilkan.
Tokenisasi Aman: Memanfaatkan tokenisasi bawaan Google untuk meneruskan kredensial terenkripsi langsung ke Penyedia Layanan Pembayaran (PSP) bisnis.

2. Integrasi Bisnis

2.1 Persyaratan

Sebelum mengiklankan Google Pay melalui UCP, bisnis harus:

Dapatkan ID Penjual Google Pay: Diperlukan untuk pemrosesan di lingkungan PRODUCTION (daftar di Konsol Google Pay & Wallet).
Verifikasi Dukungan PSP: Pastikan Penyedia Layanan Pembayaran (PSP) Anda ada dalam daftar pemroses dan gateway yang didukung untuk tokenisasi Google Pay.

2.2 Konfigurasi Handler

Bisnis mengiklankan dukungan Google Pay dengan menyertakan handler dalam array handler pembayaran mereka. Konfigurasi ini secara ketat mengikuti struktur yang diperlukan untuk melakukan inisialisasi Google Pay API.

2.2.1 Skema Konfigurasi

Objek konfigurasi menentukan lingkungan, identitas bisnis, dan metode pembayaran yang diizinkan.

Metode Pembayaran Google Pay

Berdasarkan PaymentMethod Google Pay.

Spesifikasi Tokenisasi

Berdasarkan TokenizationSpecification Google Pay.

2.2.2 Contoh Deklarasi Handler

{
  "payment": {
    "handlers": [
      {
        "id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
        "name": "com.google.pay",
        "version": "2026-01-11",
        "spec": "https://pay.google.com/gp/p/ucp/2026-01-11/",
        "config_schema": "https://pay.google.com/gp/p/ucp/2026-01-11/schemas/config.json",
        "instrument_schemas": [
          "https://pay.google.com/gp/p/ucp/2026-01-11/schemas/card_payment_instrument.json"
        ],
        "config": {
          "api_version": 2,
          "api_version_minor": 0,
          "environment": "TEST",
          "merchant_info": {
            "merchant_name": "Example Merchant",
            "merchant_id": "01234567890123456789",
            "merchant_origin": "checkout.merchant.com"
          },
          "allowed_payment_methods": [
            {
              "type": "CARD",
              "parameters": {
                "allowed_auth_methods": ["PAN_ONLY"],
                "allowed_card_networks": ["VISA", "MASTERCARD"]
              },
              "tokenization_specification": {
                "type": "PAYMENT_GATEWAY",
                "parameters": {
                  "gateway": "example",
                  "gatewayMerchantId": "exampleGatewayMerchantId"
                }
              }
            }
          ]
        }
      }
    ]
  }
}

2.3 Entitas

2.3.1 Skema Instrumen

Instrumen Google Pay (card_payment_instrument) memperluas Instrumen Pembayaran Kartu dasar. Objek ini mewarisi kolom tampilan standar (seperti brand dan last_digits) untuk memastikan rendering tanda terima yang konsisten, sekaligus menyempurnakan kolom credential untuk membawa payload tokenisasi Google Pay tertentu.

Perilaku Platform: Platform bertanggung jawab untuk memetakan dari respons Google Pay PaymentMethodData ke dalam struktur ini sebelum mengirimkannya ke bisnis.

Nama	Jenis	Wajib diisi	Deskripsi
id	string	Ya	ID unik untuk alat pembayaran ini, yang ditetapkan oleh platform.
handler_id	string	Ya	ID untuk handler Google Pay.
jenis	string	Ya	Constant = `card`. Menunjukkan bahwa instrumen ini berperilaku seperti kartu (mewarisi kolom tampilan kartu).
brand	string	Ya	Jaringan kartu (misalnya, `visa`, `mastercard`). Dipetakan dari `info.cardNetwork` Google Pay.
last_digits	string	Ya	4 digit terakhir kartu. Dipetakan dari `info.cardDetails` Google Pay.
rich_text_description	string	Tidak	Deskripsi teks multimedia opsional untuk kartu (misalnya, Visa yang berakhiran 1234, berakhir pada 12/2025").
rich_card_art	string (uri)	Tidak	URI opsional ke gambar lengkap yang merepresentasikan kartu (misalnya, gambar kartu penerbit).
billing_address	Alamat Pos	Tidak	Alamat penagihan yang terkait dengan kartu.
kredensial	Payload Kredensial	Tidak	Data tokenisasi aman yang ditampilkan oleh Google Pay.

Payload Kredensial

Objek ini berfungsi sebagai credential untuk instrumen. Langsung dipetakan ke Data Tokenisasi Google Pay.

Alamat Pos

Objek ini berfungsi sebagai kolom address. Atribut ini dipetakan langsung ke PostalAddress.

3. Integrasi Platform

3.1 Persyaratan

Sebelum menangani pembayaran com.google.pay, platform harus:

Dapat memuat Google Pay API untuk Web (atau yang setara dengan Android).
Patuhi Pedoman Merek Google Pay saat merender tombol pembayaran.

3.2 Protokol Pembayaran

Platform HARUS mengikuti alur ini untuk memproses pengendali:

Langkah 1: Temukan & Konfigurasi

Platform menginisialisasi klien untuk mengelola siklus proses API.

Referensi: PaymentsClient

Langkah 2: Periksa Kesiapan untuk Membayar

Platform akan memeriksa apakah pengguna dapat melakukan pembayaran dengan metode pembayaran yang ditentukan sebelum menampilkan tombol.

Referensi: isReadyToPay

Langkah 3: Buat Permintaan Pembayaran

Platform menyusun objek permintaan data pembayaran, termasuk konfigurasi penjual, metode pembayaran, dan detail transaksi (harga dan mata uang).

Referensi: PaymentDataRequest

Langkah 4: Panggil Interaksi Pengguna

Platform memicu tampilan halaman pembayaran saat pengguna berinteraksi dengan tombol pembayaran.

Referensi: loadPaymentData

Langkah 5: Selesaikan Checkout

Setelah interaksi pengguna berhasil, Google Pay API akan menampilkan objek PaymentInstrument di bawah kunci payment_data. Platform memetakan respons ini ke skema card_payment_instrument dan mengirimkan permintaan penyelesaian checkout.

POST /checkout-sessions/{checkout_id}/complete

{
  "payment_data": {
    "id": "pm_1234567890abc",
    "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
    "type": "card",
    "brand": "visa",
    "last_digits": "4242",
    "billing_address": {
      "street_address": "123 Main Street",
      "extended_address": "Suite 400",
      "address_locality": "Charleston",
      "address_region": "SC",
      "postal_code": "29401",
      "address_country": "US",
      "first_name": "Jane",
      "last_name": "Smith"
    },
    "credential": {
      "type": "PAYMENT_GATEWAY",
      "token": "{\"signature\":\"...\",\"protocolVersion\":\"ECv2\"...}"
    }
  },
  "risk_signals": {
      ...
  }
}

4. Pemrosesan Bisnis

Setelah menerima alat pembayaran Google Pay, bisnis HARUS:

Validasi Handler: Konfirmasi bahwa handler_id sesuai dengan handler Google Pay.
Ekstrak Token: Ambil string token dari payment_data.credential.token.
Proses Pembayaran: Teruskan string token dan detail transaksi ke endpoint PSP.
- Catatan: Sebagian besar PSP memiliki kolom khusus untuk "Payload Google Pay" atau "Token Jaringan".
Respons Pengembalian: Merespons dengan status checkout akhir (Berhasil/Gagal).

5. Pertimbangan Keamanan

5.1 Keamanan Token

PAYMENT_GATEWAY: Saat menggunakan jenis tokenisasi ini, token dienkripsi khusus untuk pihak tokenisasi. Pihak perantara tidak dapat mendekripsi token ini dan harus meneruskannya ke pihak tokenisasi apa adanya.
LANGSUNG: Jika menggunakan tokenisasi DIRECT, bisnis menerima data kartu terenkripsi yang harus didekripsi. Hal ini akan meningkatkan cakupan kepatuhan PCI DSS secara signifikan dan umumnya tidak direkomendasikan kecuali jika bisnis tersebut adalah Penyedia Layanan yang Mematuhi PCI Level 1.

5.2 Isolasi Lingkungan

Mode TEST: Di lingkungan TEST, Google Pay menampilkan token dummy. Kartu ini tidak dapat ditagih.
Mode PRODUKSI: Kartu asli digunakan. Bisnis harus memastikan kredensial PSP di config.allowed_payment_methods cocok dengan lingkungan.

Spesifikasi pemroses pembayaran Google Pay Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.