תשלום מוטמע

הטמעת התכונה 'תשלום מוטמע' מאפשרת להטמיע את תהליך התשלום באתר שלכם בפלטפורמות השונות של Google. כדאי להשתמש בנתיב הזה אם המוצר שלכם דורש לוגיקה מורכבת (למשל, התאמות אישיות) שממשק ה-API המקורי לא יכול לתמוך בה. תטמיעו ממשק משתמש לתשלום שיוטמע בתהליך התשלום באמצעות iframe.

מהו תשלום מוטמע?

הטמעה של תהליך התשלום (EC) מאפשרת למארח (כמו חיפוש Google או סוכן AI) להציג את תהליך התשלום הקיים שלכם באינטרנט בתוך האפליקציה שלו (באמצעות iframe או WebView). בניגוד להפניה רגילה באתר, ההפניה הזו מאפשרת תקשורת דו-כיוונית. המארח יכול "להקצות" משימות ספציפיות כמו בחירת כתובת שמורה או תשלום באמצעות פרטי כניסה שמורים, כדי לספק חוויה מהירה יותר שמרגישה טבעית, בזמן שאתם נשארים המוכר הרשום ומטפלים ביצירת ההזמנה בפועל.

רשימת משימות להטמעה של מוכרים

כדי לתמוך בתכונה 'הטמעה של דף תשלום', אתם צריכים להטמיע את הדרישות הבאות ב-UCP API ובאפליקציית דף התשלום שלכם.

1. הפעלת גילוי (UCP API)

אתם צריכים להצהיר שתהליך התשלום שלכם תומך בתוסף המוטמע בתשובות של UCP API.

• פעולה: מוסיפים את אובייקט היכולת dev.ucp.shopping.embedded_checkout למערך היכולות של תגובת ה-UCP.
• דרישה: צריך לכלול את כתובות ה-URL של המפרט והסכימה.
• אופציונלי: אם נדרש אימות (למשל, טוקן JWT) כדי לטעון את דף התשלום, מגדירים את auth.required כ-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. טיפול באתחול של כתובת URL (חלק הקצה)

כשהמארח טוען את continue_url, הוא מוסיף פרמטרים ספציפיים של שאילתה. המערכת הקדמית צריכה לנתח את הנתונים האלה מיד אחרי הטעינה.

• פעולה: ניתוח הפרמטרים הבאים של שאילתות בכתובות URL:
  • ‫ec_version: גרסת הפרוטוקול (למשל, 2026-01-11).
  • ‫ec_auth: (אם רלוונטי) מאמתים את אסימון ההרשאה שסופק על ידי המארח, אם הגדרתם את auth.required: true.
  • ‫ec_delegate: רשימה מופרדת בפסיקים של פעולות שהמארח רוצה לטפל בהן באופן מקורי (למשל, payment.credential, fulfillment.address_change, payment.instruments_change).

3. יצירת תקשורת (קצה קדמי)

התקשורת מתבצעת באמצעות postMessage בפורמט JSON-RPC 2.0.

• פעולה: מטמיעים listener לאירועי message.
• דרישה: צריך לאמת את המקור של כל הודעה כדי לוודא שהוא תואם למארח.
• תמיכה מובנית: במארחים של אפליקציות מקוריות, צריך לבדוק אם יש משתנים גלובליים מוזרקים (למשל, ‫window.EmbeddedCheckoutProtocolConsumer) אם postMessage לא זמין.

4. ביצוע לחיצת היד (קצה קדמי)

ברגע שדף התשלום מוצג, צריך להודיע למארח שאתם מוכנים ולאשר את ההרשאות שאתם מקבלים.

• פעולה: שליחת הבקשה ec.ready מיד אחרי הטעינה.
• המטען הייעודי (Payload): צריך לכלול מערך delegate עם רשימה של היכולות שאתם מסכימים שהמארח יטפל בהן.
• דוגמה: אם כתובת ה-URL שמתבקשת היא ec_delegate=payment.credential ואתם מאשרים, צריך לכלול את "payment.credential" במטען הייעודי (payload) של ec.ready.

// 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. הטמעה של לוגיקת הענקת גישה (חלק הקצה)

אם אישרתם העברה של הרשאות בשיטת ה-handshake, אתם צריכים לשנות את אופן הפעולה של ממשק המשתמש כדי למנוע התנגשויות.

• פעולה: הסתרת רכיבי ממשק המשתמש הרלוונטיים למשימות שהוקצו.
• דוגמה: אם fulfillment.address_change מוקצה, צריך להסתיר את טופס הכתובת ולהציג במקומו את הלחצן 'שינוי כתובת'.
• פעולה: כשמשתמש לוחץ על הכפתור הזה, נשלחת הודעה מסוג _request (לדוגמה, ec.fulfillment.address_change_request) למארח.
• פעולה: ממתינים לתגובה מהמארח/ת. התשובה תכיל את הנתונים החדשים (למשל, הכתובת שנבחרה).
• דרישה: צריך לעדכן את מצב התשלום באמצעות החלפה בסגנון PUT (החלפה של כל קטע האובייקט) על סמך הנתונים שמוחזרים על ידי המארח.

// 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. שליחת עדכונים לגבי מחזור החיים והמצב (חלק הקצה)

אתם צריכים לעדכן את המארח לגבי סטטוס התשלום כדי שהוא יוכל לעדכן את ממשק המשתמש שלו או לטפל בשגיאות.

• פעולה: שליחת התראות (הודעות ללא מזהה) כשמצב משתנה:
  • ‫ec.start: כשהדף של תהליך התשלום מוצג במלואו.
  • ‫ec.line_items.change: אם יש עדכון בפריטים בעגלת הקניות או בסכומים הכוללים.
  • ‫ec.buyer.change: אם פרטי הקונה משתנים.
  • ‫ec.complete: כשההזמנה מתבצעת בהצלחה.
  • ‫ec.error: אם מתרחשת שגיאה קריטית.

7. אכיפת אבטחה (שרת/כותרות)

עליכם לוודא שגורמים זדוניים לא יכולים להטמיע את תהליך התשלום שלכם.

• פעולה: הטמעת כותרות של Content Security Policy‏ (CSP).
• דרישה: צריך להגדיר את frame-ancestors <host_origin>; כך שרק מארחים מהימנים יוכלו להטמיע את התוסף.
• ניווט: חסימת לוגיקה שמפנה את המשתמש מחוץ לתהליך התשלום (למשל, הסרת קישורים של 'המשך קניות' שמובילים לדף הבית). יש חריגים שמותרים לאימות 3DS או להפניות אוטומטיות לתשלום של צד שלישי.