Yerel entegrasyon, Google'ın ödeme oturumları oluşturmak ve yönetmek için çağırabileceği bir RESTful API oluşturmanızı gerektirir.
Genel akış şu şekildedir:
- Ödeme oturumu oluşturma: Kullanıcı ve isteğe bağlı olarak bir temsilci, oturuma öğe ekleme döngüsündedir.
- Google kullanıcı arayüzüne aktarma: Kullanıcı ödeme yapmaya karar verdiğinde (etkileşim varsa) kontrol, bir Google kullanıcı arayüzüne aktarılır (ödeme oturumu verileri aktarılır).
- Manuel ödeme: Kullanıcı artık hassas sipariş karşılama ve ödeme ayrıntılarını doldurup siparişi göndermek için yalnızca Google kullanıcı arayüzüyle etkileşim kurar. Temsilci bu kısma dahil değildir ve determinizm sağlanır.
- Tamamlama ve geri dönüş: Google kullanıcı arayüzünde, siparişi onaylamak için "Teşekkür ederiz" sayfası gösterilir. İsteğe bağlı olarak, kullanıcı satın alma işleminin tamamlandığı konusunda önceden bilgilendirilmiş olabilecek Acente'ye geri yönlendirilebilir.
Aşağıdaki adımlarda, uygulamanız gereken API uç noktaları ve bunların davranışları açıklanmaktadır.
1. Ödeme oturumu oluşturma
Bu uç nokta, kullanıcının satın almak istediği ürünleri içeren bir ödeme oturumu oluşturulmasına olanak tanır.
- Uç nokta:
POST /checkout-sessions - Tetikleyici: Kullanıcı, bir üründe "Satın al"ı tıklar.
İstek: Google, satır öğelerini ve para birimini gönderir.
{
"line_items": [
{
"item": {
"id": "product_12345", // Must match Product Feed ID
"title": "Running Shoes"
},
"quantity": 1
}
],
"currency": "USD"
}
Yanıt: Toplamlar, vergiler (başlangıçta tahmin edilen) ve ödeme özellikleri ile başlatılan oturumu döndürürsünüz. Hizmet şartlarınıza ve gizlilik politikanıza bağlantılar eklemeniz gerekir. Bu bağlantılar, ödeme düğmesinin altında yer alır.
{
"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. Ödeme oturumunu alma
Bu uç nokta, ödeme oturumunun alınmasına olanak tanır.
- Uç nokta:
GET /checkout-sessions/{id}
İstek: Google, ödeme oturumunun kimliğini gönderir. Global kimlikler kullanıyorsanız (ör. gid://merchant.example.com/Checkout/session_abc123) kullanıyorsanız istek yolundaki kimliğin yalnızca bu kimliğin son bileşeni olacağını (ör.
session_abc123).
Yanıt: Ödeme nesnesinin tamamını döndürürsünüz.
3. Ödeme oturumunu güncelleme
Bu uç nokta, ödeme oturumunun güncellenmesine olanak tanır. Kargo adresi güncellendiğinde vergileri ve kargo seçeneklerini yeniden hesaplayıp döndürmesi gerekir.
- Uç nokta:
PUT /checkout-sessions/{id} - Tetikleyici: Kullanıcı, kargo adresini seçer veya değiştirir, kargo seçimini günceller ya da ödeme bilgilerini günceller.
İstek: Google, güncellenmiş bilgilerle birlikte tam ödeme nesnesini gönderir.
{
"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.)
}
Yanıt: Vergileri ve kargo seçeneklerini gerektiği gibi yeniden hesaplar ve ödeme nesnesinin tamamını döndürürsünüz.
{
"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. Ödeme oturumunu tamamlayın
Bu uç nokta, ödeme oturumunun tamamlanmasına ve sipariş verilmesine olanak tanır. Tamamlanan ödeme oturumunu döndürmeli ve sipariş bilgilerini içermelidir. Ödeme işleme, bu görüşme alındıktan sonra başlamalıdır.
- Uç nokta:
POST /checkout-sessions/{id}/complete - Tetikleyici: Kullanıcı "Sipariş Ver"i tıklar.
İstek: Google, sağlayıcıdan ödeme jetonunu (şifrelenmiş blob) gönderir (ör. Google Pay) ve kendi sahtekarlık tespitinizi yapabilmeniz için alıcıyla ilgili risk sinyalleri.
{
"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\"...}"
}
}
}
Yanıt: Siparişin tamamlandığını belirten tam ödeme nesnesini (sipariş kimliği ve siparişin permalink URL'si dahil) döndürürsünüz.
{
"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. Ödeme oturumunu iptal etme
Bu uç nokta, ödeme oturumunu iptal eder.
- Uç nokta:
POST /checkout-sessions/{id}/cancel
İstek: Google, ödeme oturumunun kimliğini gönderir.
Yanıt: Ödeme nesnesinin tamamını canceled olarak güncellenen durumla birlikte döndürürsünüz.