Integrasi Native mengharuskan Anda membuat RESTful API yang dapat dipanggil Google untuk membuat dan mengelola sesi checkout.
Alur keseluruhannya adalah sebagai berikut:
- Bangun sesi checkout: Pengguna dan Agen secara opsional berada dalam loop menambahkan item ke sesi.
- Penyerahan ke UI Google: Setelah pengguna memutuskan untuk melakukan checkout, Agen (jika berinteraksi) akan meneruskan kontrol ke UI Google (meneruskan data sesi checkout)
- Checkout manual: Pengguna kini hanya berinteraksi dengan UI Google untuk mengisi detail pembayaran dan pemenuhan pesanan yang sensitif serta mengirimkan pesanan. Agen tidak terlibat dalam bagian ini, sehingga memastikan determinisme.
- Penyelesaian & pengembalian: UI Google menampilkan halaman "Terima Kasih" untuk mengonfirmasi pesanan. Secara opsional, pengguna dapat dialihkan kembali ke Agen, yang mungkin telah diberi tahu tentang pembelian yang telah selesai.
Langkah-langkah berikut menjelaskan endpoint API yang perlu Anda terapkan dan perilakunya.
1. Buat sesi checkout
Endpoint ini memungkinkan pembuatan sesi checkout yang berisi produk yang ingin dibeli pengguna.
- Endpoint:
POST /checkout-sessions - Pemicu: Pengguna mengklik "Beli" pada produk.
Permintaan: Google mengirimkan item baris dan mata uang.
{
"line_items": [
{
"item": {
"id": "product_12345", // Must match Product Feed ID
"title": "Running Shoes"
},
"quantity": 1
}
],
"currency": "USD"
}
Respons: Anda menampilkan sesi yang diinisialisasi dengan total, pajak (awalnya diperkirakan), dan kemampuan pembayaran. Anda harus menyertakan link ke persyaratan layanan dan kebijakan privasi, yang akan ditautkan di bawah tombol pembayaran.
{
"ucp": {
"version": "2026-01-11",
"capabilities": [
{
"name": "dev.ucp.shopping.checkout",
"version": "2026-01-11"
},
{
"name": "dev.ucp.shopping.fulfillment",
"version": "2026-01-11"
}
]
},
"id": "gid://merchant.example.com/Checkout/session_abc123",
"status": "incomplete",
"line_items": [
{
"id": "line_1",
"item": {
"id": "product_12345",
"title": "Running Shoes",
"price": 10000
},
"quantity": 1,
"base_amount": 10000,
"subtotal": 10000,
"total": 10000
}
],
"totals": [
{ "type": "subtotal", "amount": 10000 }, // in cents
{ "type": "tax", "amount": 0 },
{ "type": "total", "amount": 10000 }
],
"payment": {
"handlers": [
{
"id": "gpay",
"name": "com.google.pay",
"config": {
"api_version": 2,
"api_version_minor": 0,
"merchant_info": {
"merchant_id": "12345678901234567890",
"merchant_name": "Example Merchant"
},
"allowed_payment_methods": [
{
"type": "CARD",
"parameters": {
"allowed_auth_methods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
"allowed_card_networks": ["VISA", "MASTERCARD"]
},
"tokenization_specification": {
"type": "PAYMENT_GATEWAY",
"parameters": {
"gateway": "stripe",
"gateway_merchant_id": "exampleGatewayMerchantId"
}
}
}
]
}
}
]
},
"links": [
{ "type": "privacy_policy", "url": "https://m.com/privacy" },
{ "type": "terms_of_service", "url": "https://m.com/terms" }
]
}
2. Mendapatkan sesi checkout
Endpoint ini memungkinkan pengambilan sesi checkout.
- Endpoint:
GET /checkout-sessions/{id}
Permintaan: Google mengirimkan ID sesi checkout. Jika Anda menggunakan ID Global
(misalnya, gid://merchant.example.com/Checkout/session_abc123), perhatikan bahwa ID
di jalur permintaan hanya akan menjadi komponen terakhir dari ID ini (misalnya,
session_abc123).
Respons: Anda menampilkan objek checkout lengkap.
3. Memperbarui sesi checkout
Endpoint ini memungkinkan pembaruan sesi checkout. Saat alamat pengiriman diperbarui, alamat tersebut harus menghitung ulang dan menampilkan pajak serta opsi pengiriman.
- Endpoint:
PUT /checkout-sessions/{id} - Pemicu: Pengguna memilih atau mengubah alamat pengiriman, memperbarui pilihan pengiriman, atau memperbarui informasi pembayaran.
Permintaan: Google mengirimkan objek checkout lengkap dengan informasi yang diperbarui.
{
"id": "gid://merchant.example.com/Checkout/session_abc123",
"buyer": {
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com"
},
"fulfillment": {
"methods": [
{
"type": "shipping",
"destinations": [
{
"id": "dest_1",
"postal_code": "94043",
"country": "US",
"address_locality": "Mountain View",
"address_region": "CA"
}
],
"selected_destination_id": "dest_1"
}
]
},
"payment": {
"selected_instrument_id": "pi_gpay_5678",
"instruments": [
{
"id": "pi_gpay_5678",
"handler_id": "gpay",
"type": "card",
"brand": "mastercard",
"last_digits": "5678",
"rich_text_description": "Google Pay •••• 5678"
}
]
}
// ... other fields (line_items, currency, etc.)
}
Respons: Anda menghitung ulang pajak dan opsi pengiriman sesuai kebutuhan dan mengembalikan objek checkout lengkap.
{
"id": "gid://merchant.example.com/Checkout/session_abc123",
"totals": [
{ "type": "subtotal", "amount": 10000 },
{ "type": "shipping", "display_text": "Ground Shipping", "amount": 500 },
{ "type": "tax", "amount": 850 },
{ "type": "total", "amount": 11350 }
],
// ... other fields (line_items, currency, etc.)
"fulfillment": {
"methods": [
{
"id": "method_shipping",
"type": "shipping",
"line_item_ids": ["line_1"],
"selected_destination_id": "dest_1",
"destinations": [
{
"id": "dest_1",
"postal_code": "94043",
"country": "US",
"address_locality": "Mountain View",
"address_region": "CA"
}
],
"groups": [
{
"id": "group_1",
"line_item_ids": ["line_1"],
"selected_option_id": "ship_ground",
"options": [
{
"id": "ship_ground",
"title": "Ground (3-5 days)",
"total": 500
},
{
"id": "ship_express",
"title": "Express (1-2 days)",
"total": 1500
}
]
}
]
}
]
}
}
4. Menyelesaikan sesi checkout
Endpoint ini memungkinkan penyelesaian sesi checkout dan melakukan pemesanan. Respons harus menampilkan sesi checkout yang telah selesai dan menyertakan informasi pesanan. Pemrosesan pembayaran harus dimulai setelah panggilan ini diterima.
- Endpoint:
POST /checkout-sessions/{id}/complete - Pemicu: Pengguna mengklik "Buat Pesanan".
Permintaan: Google mengirimkan token pembayaran (blob terenkripsi) dari penyedia (misalnya, Google Pay), dan sinyal risiko tentang pembeli agar Anda dapat melakukan deteksi penipuan sendiri.
{
"payment_data": {
"id": "pi_gpay_5678",
"handler_id": "gpay",
"type": "card",
"brand": "mastercard",
"last_digits": "5678",
"billing_address": {
"postal_code": "94043",
"address_country": "US"
},
"credential": {
"type": "PAYMENT_GATEWAY",
"token": "{\"signature\":\"...\",\"protocolVersion\":\"ECv2\"...}"
}
}
}
Respons: Anda menampilkan objek checkout lengkap yang menunjukkan bahwa pesanan telah selesai, termasuk ID pesanan dan URL permalink ke pesanan.
{
"ucp": {
"version": "2026-01-11",
"capabilities": [...]
},
"id": "gid://merchant.example.com/Checkout/session_abc123",
"status": "completed",
// ... other fields (line_items, currency, etc.)
"order_id": "gid://merchant.example.com/Order/789",
"order_permalink_url": "https://merchant.example.com/orders/789"
}
5. Membatalkan sesi checkout
Endpoint ini membatalkan sesi checkout.
- Endpoint:
POST /checkout-sessions/{id}/cancel
Permintaan: Google mengirimkan ID sesi checkout.
Respons: Anda menampilkan objek checkout lengkap dengan status yang diperbarui menjadi
canceled.