پرداخت جاسازی‌شده

ادغام پرداخت جاسازی‌شده، پرداخت مبتنی بر وب شما را قادر می‌سازد تا در سطوح گوگل جاسازی شود. اگر محصول شما به منطق پیچیده‌ای (مثلاً سفارشی‌سازی‌ها) نیاز دارد که API بومی نمی‌تواند از آن پشتیبانی کند، از این مسیر استفاده کنید. شما یک رابط کاربری پرداخت پیاده‌سازی خواهید کرد که از طریق یک iframe در جریان پرداخت جاسازی می‌شود.

پرداخت درون برنامه‌ای چیست؟

پرداخت جاسازی‌شده (EC) به یک میزبان (مانند جستجوی گوگل یا یک عامل هوش مصنوعی) اجازه می‌دهد تا پرداخت مبتنی بر وب موجود شما را در برنامه خود (با استفاده از iframe یا webview) نمایش دهد. برخلاف یک تغییر مسیر وب استاندارد، این امکان ارتباط دو طرفه را فراهم می‌کند. میزبان می‌تواند وظایف خاصی مانند انتخاب یک آدرس ذخیره شده یا پرداخت با اعتبار ذخیره شده را "تفویض" کند تا تجربه‌ای سریع‌تر و با حس بومی ارائه دهد، در حالی که شما همچنان فروشنده اصلی هستید و ایجاد سفارش واقعی را مدیریت می‌کنید.

چک لیست پیاده سازی فروشنده

برای پشتیبانی از پرداخت درون‌برنامه‌ای، باید الزامات زیر را در UCP API و برنامه پرداخت فرانت‌اند خود پیاده‌سازی کنید.

۱. فعال کردن قابلیت کشف (UCP API)

شما باید در پاسخ‌های UCP API خود اعلام کنید که پرداخت شما از افزونه‌ی تعبیه‌شده پشتیبانی می‌کند.

• اقدام : شیء قابلیت dev.ucp.shopping.embedded_checkout را به آرایه قابلیت‌های پاسخ UCP خود اضافه کنید.
• الزامات : مشخصات و آدرس‌های اینترنتی طرحواره را وارد کنید.
• اختیاری : اگر برای بارگیری پرداخت به احراز هویت (مثلاً یک توکن 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 }
    }
  }
]

۲. مدیریت مقداردهی اولیه URL (فرانت‌اند)

وقتی میزبان continue_url شما را بارگذاری می‌کند، پارامترهای پرس‌وجوی خاصی را اضافه می‌کند. فرانت‌اند شما باید بلافاصله پس از بارگذاری، این پارامترها را تجزیه و تحلیل کند.

• اقدام : پارامترهای کوئری URL زیر را تجزیه کنید:
  • ec_version : نسخه پروتکل (مثلاً 2026-01-11 ).
  • ec_auth : (در صورت وجود) اگر auth.required: true تنظیم کرده باشید، توکن احراز هویت ارائه شده توسط میزبان را اعتبارسنجی می‌کند.
  • ec_delegate : فهرستی از اقداماتی که میزبان می‌خواهد به صورت بومی انجام دهد (مثلاً payment.credential ، fulfillment.address_change ، payment.instruments_change ) که با کاما از هم جدا شده‌اند.

۳. ایجاد ارتباط (فرانت‌اند)

ارتباط با استفاده از postMessage و با استفاده از فرمت JSON-RPC 2.0 برقرار می‌شود.

• اقدام : پیاده‌سازی یک شنونده برای رویدادهای message .
• الزام : شما باید مبدا هر پیام را اعتبارسنجی کنید تا از مطابقت آن با میزبان اطمینان حاصل شود.
• پشتیبانی بومی : برای میزبان‌های برنامه‌های بومی، بررسی کنید و در صورت عدم وجود postMessage از متغیرهای سراسری تزریق‌شده (مثلاً window.EmbeddedCheckoutProtocolConsumer ) استفاده کنید.

۴. انجام دست دادن (در ابتدا)

به محض اینکه پرداخت شما انجام شد، باید به میزبان اطلاع دهید که آماده هستید و تأیید کنید که کدام نمایندگی‌ها را می‌پذیرید.

• اقدام : درخواست ec.ready را بلافاصله پس از بارگیری ارسال کنید.
• بار مفید : یک آرایه delegate array) را اضافه کنید که قابلیت‌هایی را که موافقت می‌کنید میزبان بتواند مدیریت کند، فهرست می‌کند.
• مثال : اگر 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
  }
}), "*");

۵. پیاده‌سازی منطق واگذاری (فرانت‌اند)

اگر در فرآیند handshake، یک delegate را پذیرفته‌اید، باید رفتار رابط کاربری خود را برای جلوگیری از تداخل تغییر دهید.

• اقدام : عناصر رابط کاربری مرتبط را برای وظایف محول شده پنهان کنید.
• مثال : اگر 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
  }
}), "*");

۶. ارسال به‌روزرسانی‌های چرخه حیات و وضعیت (فرانت‌اند)

شما باید میزبان را از وضعیت پرداخت مطلع نگه دارید تا بتواند رابط کاربری خود را به‌روزرسانی کند یا خطاها را مدیریت کند.

• اقدام : ارسال اعلان‌ها (پیام‌های بدون شناسه) هنگام تغییر وضعیت:
  • ec.start : زمانی که صفحه پرداخت کاملاً قابل مشاهده است.
  • ec.line_items.change : اگر محتویات سبد خرید یا مجموع اقلام به‌روزرسانی شود.
  • ec.buyer.change : اگر جزئیات خریدار به‌روزرسانی شود.
  • ec.complete : زمانی که سفارش با موفقیت ثبت شده باشد.
  • ec.error : اگر یک خطای بحرانی رخ دهد.

۷. امنیت (سرور/هدرها) را تقویت کنید

شما باید مطمئن شوید که صفحه پرداخت شما توسط افراد مخرب قابل جاسازی نیست.

• اقدام : هدرهای سیاست امنیت محتوا (CSP) را پیاده‌سازی کنید.
• الزام : frame-ancestors <host_origin>; تنظیم کنید تا فقط میزبان‌های مورد اعتماد بتوانند آن را جاسازی کنند.
• ناوبری : منطقی را که کاربر را از جریان پرداخت خارج می‌کند، مسدود کنید (مثلاً پیوندهای «ادامه خرید» را که به صفحه اصلی شما منتهی می‌شوند، حذف کنید). استثنائات برای تأیید 3DS یا تغییر مسیرهای پرداخت شخص ثالث مجاز است.