برای اینکه کاربران بتوانند تسویه حساب کنند، باید یکپارچهسازی تسویه حساب بومی را پیادهسازی کنید. این شامل ایجاد یک API استاندارد REST است که به گوگل اجازه میدهد جریان تسویه حساب را با سرورهای شما به صورت برنامهنویسی مدیریت کند. این روش، یکپارچهترین تجربه را برای کاربران فراهم میکند. در ابتدا، گوگل رابط کاربری را برای خریدار رندر میکند و در آینده برنامههایی برای پشتیبانی از تجربیات عاملیت بیشتر دارد.
جریان پرداخت
ادغام بومی شما را ملزم به ساخت یک API RESTful میکند که گوگل بتواند برای ایجاد و مدیریت جلسات پرداخت، آن را فراخوانی کند.
جریان کلی به شرح زیر است:
- ساخت جلسه پرداخت: کاربر و در صورت تمایل، یک نماینده (Agent) در یک حلقه، اقلام را به جلسه اضافه میکنند.
- انتقال به رابط کاربری گوگل: زمانی که کاربر تصمیم به پرداخت میگیرد، نماینده (در صورت فعال بودن)، کنترل را به رابط کاربری گوگل منتقل میکند (دادههای جلسه پرداخت را ارسال میکند)
- پرداخت دستی: کاربر اکنون فقط با رابط کاربری گوگل تعامل دارد تا جزئیات حساس تکمیل سفارش و پرداخت را پر کند و سفارش را ارسال کند. نماینده در این بخش دخالتی ندارد و قطعیت را تضمین میکند.
- تکمیل و بازگشت: رابط کاربری گوگل یک صفحه "تشکر" برای تأیید سفارش نشان میدهد. در صورت تمایل، کاربر میتواند به نماینده هدایت شود، که ممکن است قبلاً از تکمیل خرید مطلع شده باشد.
چرخه حیات وضعیت جلسه پرداخت
همزمان با پیشرفت کاربر در جریان پرداخت، شما باید status جلسه پرداخت را بهروزرسانی کنید تا وضعیت فعلی آن را منعکس کند. جلسه از چرخه حیات زیر عبور میکند:
-
incomplete: وضعیت اولیه هنگام ایجاد یک جلسه. این نشان میدهد که اطلاعات اجباری (مانند روشهای ارسال، مالیات یا جزئیات کاربر) وجود ندارد یا محاسبه نشده است. -
ready_for_payment: وضعیتی که پس از بهروزرسانی آدرس ارسال توسط کاربر و محاسبهی گزینههای ارسال و جمع کل توسط شما، اما قبل از نهایی شدن ابزار پرداخت، استفاده میشود. -
ready_for_complete: وضعیتی که هنگام تکمیل کامل فرآیند پرداخت، پس از انتخاب روش پرداخت و تأیید اعتبار تمام جزئیات سفارش، استفاده میشود. -
completed: وضعیت نهایی که پس از پردازش موفقیتآمیز پرداخت و ثبت سفارش توسط شما بازگردانده میشود. -
canceled: وضعیتی که در صورت لغو شدن جلسه پرداخت، بازگردانده میشود. -
error: وضعیتی که در صورت بروز یک خطای منطقی غیرقابل بازیابی، مانع از پرداخت میشود، بازگردانده میشود. این وضعیت در UCP نسخه2026-04-08و بالاتر موجود است.
جریان پرداخت چند کالایی:
گوگل اکنون از چندین ردیف مجزا در یک جلسه پرداخت پشتیبانی میکند. روند کلی به شرح زیر است:
- کاربر پرداخت را از یک رابط کاربری دارای UCP آغاز میکند (مثلاً با کلیک روی «همین حالا بخرید» روی یک محصول).
- فراخوانی
POST /checkout-sessionsانجام میشود و تمام اقلام متمایز در آرایهline_itemsرا شامل میشود. آرایهline_itemsبرای هر مورد منحصر به فرد که بررسی میشود، یک شیء جداگانه خواهد داشت. - کاربر میتواند با استفاده از فراخوانیهای
PUT /checkout-sessions/{id}، ابزار پرداخت و جزئیات تکمیل سفارش خود را بهروزرسانی کند یا تخفیف اعمال کند. - وقتی کاربر روی دکمهی «پرداخت با GPay» کلیک میکند، فراخوانی
POST /checkout-sessions/{id}/completeانجام میشود.
احراز هویت
اگرچه نیازی به احراز هویت نیست، گوگل از گزینههای زیر برای استفاده هنگام فراخوانی نقطه پایانی API پرداخت کسبوکار پشتیبانی میکند.
کلیدهای API
هدر HTTP: X-API-Key
یک مقدار مخفی مشترک که در هدر HTTP درخواست کلاینت UCP API گوگل برای احراز هویت با نقطه پایانی checkout استفاده خواهد شد.
OAuth 2.0 (توصیه میشود)
هدر HTTP: Authorization: Bearer <Access Token>
طبق RFC 6749 ، عامل پلتفرم UCP گوگل از ویژگیهای زیر برای درخواست توکنهای دسترسی مورد نیاز برای تعامل نقطه پایانی checkout استفاده میکند.
| ملک | توضیحات |
|---|---|
| شناسه مشتری | یک رشته منحصر به فرد که نشان دهنده کلاینت است (برای مثال، کلاینت UCP API گوگل) |
| راز مشتری | رشتهای از نوع رمز عبور که برای احراز هویت با سرور مجوز استفاده میشود |
| URL نقطه پایانی مجوز | آدرس اینترنتی (URL) مربوط به نقطه پایانی API مربوط به OAuth2 |
| قالب | احراز هویت اولیه هدر HTTP یا بدنه HTTP |
| رمزگذاری | دادههای فرم یا JSON |
ابزارهای توسعهدهندگان
برای کمک به پیادهسازی API پرداخت بومی خود، میتوانید منابع زیر را در مخزن گیتهاب پروتکل تجارت جهانی پیدا کنید:
- مخزن گیتهاب UCP: مخزن اصلی را برای مستندات جامع، مشخصات و منابع انجمن کاوش کنید.
- SDKها: از کیتهای توسعه نرمافزار برای تسریع ادغام خود استفاده کنید. SDKهای مختص زبانهای مختلف در دسترس هستند، از جمله:
تستهای انطباق: نقاط پایانی API خود را با استفاده از مجموعه تستهای انطباق، در برابر مشخصات UCP اعتبارسنجی کنید.
این به شما کمک میکند تا اطمینان حاصل کنید که پیادهسازی شما مطابق با استانداردها و رفتارهای مورد نیاز است.
ما اکیداً توصیه میکنیم از این ابزارها برای سادهسازی فرآیند توسعه و آزمایش خود استفاده کنید.
اهداف سطح خدمات
اهداف سطح خدمات (SLO) زیر برای نقاط پایانی API Native Checkout REST اعمال میشوند. انتظار میرود کسبوکارهایی که با گوگل ادغام میشوند، این اهداف را برای عملکرد و در دسترس بودن API برآورده کنند.
| نقطه پایانی | در دسترس بودن | تأخیر (صدک پنجاهم) | تأخیر (صدک ۹۵) |
|---|---|---|---|
POST /checkout-sessions (ایجاد) | >= ۹۵٪ | <= 1 ثانیه | <= 4 ثانیه |
PUT /checkout-sessions/{id} (بهروزرسانی) | >= ۹۵٪ | <= 1 ثانیه | <= 5 ثانیه |
POST /checkout-sessions/{id}/complete (کامل شده) | >= ۹۵٪ | <= 6 ثانیه | <= 10 ثانیه |
تأخیر صدک ۵۰ نشان میدهد که انتظار میرود حداقل ۵۰٪ درخواستها در این مدت زمان تکمیل شوند. تأخیر صدک ۹۵ نشان میدهد که انتظار میرود حداقل ۹۵٪ درخواستها در این مدت زمان تکمیل شوند.
مراحل بعدی
جزئیات مربوط به API پرداخت و پیادهسازی فنی نسخه UCP خود را مشاهده کنید: