Wbudowana funkcja płatności

Integracja wbudowanej funkcji płatności umożliwia umieszczenie procesu płatności w internecie na platformach Google. Użyj tej ścieżki, jeśli Twój produkt wymaga złożonej logiki (np. dostosowań), której nie obsługuje natywny interfejs API. Wdrożysz interfejs płatności, który zostanie osadzony w procesie płatności za pomocą elementu iframe.

Czym jest wbudowana funkcja płatności?

Osadzona płatność (EC) umożliwia hostowi (np. wyszukiwarce Google lub agentowi AI) wyświetlanie istniejącej płatności internetowej w jego aplikacji (za pomocą elementu iframe lub widoku internetowego). W przeciwieństwie do standardowego przekierowania w internecie umożliwia to dwukierunkową komunikację. Host może „delegować” określone zadania, takie jak wybieranie zapisanego adresu lub płacenie za pomocą zapisanych danych logowania, aby zapewnić szybsze działanie i lepsze wrażenia użytkownika, a Ty pozostajesz sprzedawcą i odpowiadasz za utworzenie zamówienia.

Lista kontrolna wdrożenia dla sprzedawcy

Aby obsługiwać płatność wbudowaną, musisz spełnić te wymagania w interfejsie UCP API i w aplikacji do płatności na stronie.

1. Włączanie wykrywania (interfejs UCP API)

W odpowiedziach interfejsu UCP API musisz zadeklarować, że Twoja strona płatności obsługuje rozszerzenie zagnieżdżone.

  • Działanie: dodaj obiekt możliwości dev.ucp.shopping.embedded_checkout do tablicy możliwości odpowiedzi UCP.
  • Wymaganie: podaj adresy URL specyfikacji i schematu.
  • Opcjonalnie: jeśli do wczytania strony płatności wymagane jest uwierzytelnianie (np. token JWT), ustaw wartość auth.required na true.
"capabilities": [
  {
    "name": "dev.ucp.shopping.embedded_checkout",
    "version": "2026-01-11",
    "spec": "https://ucp.dev/specs/shopping/embedded_checkout",
    "config": {
        "auth": { "required": true }
    }
  }
]

2. Obsługa inicjowania adresu URL (frontend)

Gdy host wczyta Twój continue_url, dołączy do niego określone parametry zapytania. Interfejs musi je przeanalizować natychmiast po wczytaniu.

  • Działanie: przeanalizuj te parametry zapytania w adresie URL:
    • ec_version: wersja protokołu (np. 2026-01-11).
    • ec_auth: (Jeśli ma zastosowanie) Sprawdź token uwierzytelniający podany przez hosta, jeśli ustawisz auth.required: true.
    • ec_delegate: lista działań, które host chce obsługiwać natywnie, rozdzielona przecinkami (np. payment.credential, fulfillment.address_change, payment.instruments_change).

3. Nawiązywanie komunikacji (frontend)

Komunikacja odbywa się za pomocą postMessage w formacie JSON-RPC 2.0.

  • Działanie: zaimplementuj detektor zdarzeń message.
  • Wymaganie: musisz weryfikować pochodzenie każdej wiadomości, aby upewnić się, że jest zgodne z hostem.
  • Obsługa natywna: w przypadku hostów aplikacji natywnych sprawdzaj i wykorzystuj wstrzyknięte zmienne globalne (np. window.EmbeddedCheckoutProtocolConsumer), jeśli postMessage jest niedostępny.

4. Przeprowadzanie uzgadniania (frontend)

Gdy tylko pojawi się strona płatności, musisz poinformować hosta, że jesteś gotowy, i potwierdzić, które delegacje akceptujesz.

  • Działanie: wyślij żądanie ec.ready natychmiast po wczytaniu.
  • Payload: dołącz tablicę delegate z listą funkcji, które host może obsługiwać.
  • Przykład: jeśli żądany adres URL to ec_delegate=payment.credential i akceptujesz to żądanie, w ładunku ec.ready umieść "payment.credential".
// Example: Sending the ec.ready message
const hostWindow = window.parent;
hostWindow.postMessage(JSON.stringify({
  "jsonrpc": "2.0",
  "id": "ready_1",
  "method": "ec.ready",
  "params": {
    "delegate": ["payment.credential"] // List capabilities you accept to delegate
  }
}), "*");

5. Implementowanie logiki przekazywania dostępu (frontend)

Jeśli w ramach uzgadniania połączenia zaakceptujesz delegowanie, musisz zmodyfikować działanie interfejsu, aby uniknąć konfliktów.

  • Działanie: ukryj odpowiednie elementy interfejsu w przypadku zadań przekazanych.
  • Przykład: jeśli fulfillment.address_change jest delegowany, ukryj formularz adresu i zamiast niego wyświetl przycisk „Zmień adres”.
  • Działanie: gdy użytkownik kliknie ten przycisk, wyślij wiadomość _request (np. ec.fulfillment.address_change_request) do gospodarza.
  • Działanie: poczekaj na odpowiedź gospodarza. Odpowiedź będzie zawierać nowe dane (np. wybrany adres).
  • Wymaganie: zaktualizuj stan płatności za pomocą zamiany w stylu PUT (zastąp całą sekcję obiektu) na podstawie danych zwróconych przez hosta.
// Example: requesting payment credential
hostWindow.postMessage(JSON.stringify({
  "jsonrpc": "2.0",
  "id": "req_1",
  "method": "ec.payment.credential_request",
  "params": {
      "checkout": currentCheckoutState // Pass the full current checkout object
  }
}), "*");

6. Wysyłanie aktualizacji cyklu życia i stanu (frontend)

Musisz informować hosta o stanie płatności, aby mógł on aktualizować interfejs lub obsługiwać błędy.

  • Działanie: wysyłanie powiadomień (wiadomości bez identyfikatora) po zmianie stanu:
    • ec.start: gdy strona płatności jest w pełni widoczna.
    • ec.line_items.change: jeśli zawartość koszyka lub sumy ulegną zmianie.
    • ec.buyer.change: jeśli dane kupującego ulegną zmianie.
    • ec.complete: po złożeniu zamówienia.
    • ec.error: jeśli wystąpi błąd krytyczny.

7. Wymuszanie zabezpieczeń (serwer/nagłówki)

Musisz zadbać o to, aby nieuczciwe podmioty nie mogły osadzać Twojego procesu płatności.

  • Działanie: wdróż nagłówki Content Security Policy (CSP).
  • Wymaganie: ustaw frame-ancestors <host_origin>;, aby zezwolić na umieszczanie tylko przez zaufanych hostów.
  • Nawigacja: logika blokowania, która odciąga użytkownika od procesu płatności (np. usuwanie linków „Kontynuuj zakupy” prowadzących do strony głównej). Wyjątki są dozwolone w przypadku weryfikacji 3DS lub przekierowań płatności innych firm.