Integracja natywna wymaga utworzenia interfejsu API REST, który Google może wywoływać w celu tworzenia sesji płatności i zarządzania nimi.
Ogólny przepływ wygląda tak:
- Budowanie sesji płatności: użytkownik i opcjonalnie agent są w pętli dodawania elementów do sesji.
- Przekazanie do interfejsu Google: gdy użytkownik zdecyduje się na płatność, agent (jeśli jest zaangażowany) przekazuje kontrolę do interfejsu Google (przekazując dane sesji płatności).
- Ręczne płatności: użytkownik wchodzi w interakcję tylko z interfejsem Google, aby podać poufne dane dotyczące realizacji zamówienia i płatności oraz przesłać zamówienie. Agent nie jest zaangażowany w tę część, co zapewnia determinizm.
- Zakończenie i zwrot: w interfejsie Google wyświetla się strona „Dziękujemy” z potwierdzeniem zamówienia. Opcjonalnie użytkownik może zostać przekierowany z powrotem do agenta, który mógł już otrzymać powiadomienie o zakończonym zakupie.
Poniżej znajdziesz opis punktów końcowych interfejsu API, które musisz wdrożyć, oraz ich działania.
1. Tworzenie sesji płatności
Ten punkt końcowy umożliwia utworzenie sesji płatności zawierającej produkty, które użytkownik chce kupić.
- Punkt końcowy:
POST /checkout-sessions - Reguła: użytkownik klika „Kup” przy produkcie.
Żądanie: Google wysyła elementy zamówienia i walutę.
{
"line_items": [
{
"item": {
"id": "product_12345", // Must match Product Feed ID
"title": "Running Shoes"
},
"quantity": 1
}
],
"currency": "USD"
}
Odpowiedź: zwracasz zainicjowaną sesję z sumami, podatkami (początkowo szacowanymi) i możliwościami płatności. Musisz dodać linki do warunków korzystania z usługi i polityki prywatności, które będą umieszczone pod przyciskiem płatności.
{
"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. Pobieranie sesji płatności
Ten punkt końcowy umożliwia pobranie sesji płatności.
- Punkt końcowy:
GET /checkout-sessions/{id}
Żądanie: Google wysyła identyfikator sesji płatności. Jeśli używasz identyfikatorów globalnych (np. gid://merchant.example.com/Checkout/session_abc123), pamiętaj, że identyfikator w ścieżce żądania będzie tylko ostatnim komponentem tego identyfikatora (np.
session_abc123).
Odpowiedź: zwracasz pełny obiekt płatności.
3. Aktualizowanie sesji płatności
Ten punkt końcowy umożliwia aktualizowanie sesji płatności. Po zaktualizowaniu adresu dostawy musi ponownie obliczyć i zwrócić podatki oraz opcje dostawy.
- Punkt końcowy:
PUT /checkout-sessions/{id} - Reguła: użytkownik wybiera lub zmienia adres dostawy, aktualizuje wybór dostawy lub aktualizuje informacje o płatności.
Żądanie: Google wysyła pełny obiekt płatności ze zaktualizowanymi informacjami.
{
"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.)
}
Odpowiedź: w razie potrzeby ponownie obliczasz podatki i opcje dostawy oraz zwracasz pełny obiekt płatności.
{
"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. Zakończ sesję płatności
Ten punkt końcowy umożliwia dokończenie sesji płatności i złożenie zamówienia. Powinna zwrócić ukończoną sesję płatności i zawierać informacje o zamówieniu. Przetwarzanie płatności powinno rozpocząć się po otrzymaniu tego wywołania.
- Punkt końcowy:
POST /checkout-sessions/{id}/complete - Aktywator: użytkownik klika „Złóż zamówienie”.
Żądanie: Google wysyła token płatności (zaszyfrowany obiekt binarny) od dostawcy (np. Google Pay) oraz sygnały ryzyka dotyczące kupującego, aby umożliwić Ci wykrywanie oszustw.
{
"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\"...}"
}
}
}
Odpowiedź: zwracasz pełny obiekt płatności, który wskazuje, że zamówienie zostało zrealizowane, w tym identyfikator zamówienia i adres URL permalinka do zamówienia.
{
"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. Anulowanie sesji płatności
Ten punkt końcowy anuluje sesję płatności.
- Punkt końcowy:
POST /checkout-sessions/{id}/cancel
Żądanie: Google wysyła identyfikator sesji płatności.
Odpowiedź: zwracasz pełny obiekt płatności ze stanem zaktualizowanym do
canceled.