پرداخت بومی

ادغام بومی شما را ملزم به ساخت یک API RESTful می‌کند که گوگل بتواند برای ایجاد و مدیریت جلسات پرداخت، آن را فراخوانی کند.

جریان کلی به شرح زیر است:

1. ساخت جلسه پرداخت: کاربر و در صورت تمایل، یک نماینده (Agent) در یک حلقه، اقلام را به جلسه اضافه می‌کنند.
2. انتقال به رابط کاربری گوگل: به محض اینکه کاربر تصمیم به پرداخت می‌گیرد، نماینده (در صورت فعال بودن) کنترل را به رابط کاربری گوگل منتقل می‌کند (داده‌های جلسه پرداخت را ارسال می‌کند)
3. پرداخت دستی: کاربر اکنون فقط با رابط کاربری گوگل تعامل دارد تا جزئیات حساس تکمیل سفارش و پرداخت را پر کند و سفارش را ارسال کند. نماینده در این بخش دخالتی ندارد و قطعیت را تضمین می‌کند.
4. تکمیل و بازگشت: رابط کاربری گوگل یک صفحه "تشکر" برای تأیید سفارش نشان می‌دهد. در صورت تمایل، کاربر می‌تواند به نماینده هدایت شود، که ممکن است قبلاً از تکمیل خرید مطلع شده باشد.

مراحل زیر، نقاط پایانی API مورد نیاز برای پیاده‌سازی و رفتارهای آنها را شرح می‌دهد.

۱. ایجاد جلسه پرداخت

این نقطه پایانی امکان ایجاد یک جلسه پرداخت شامل محصولاتی را که کاربر به خرید آنها علاقه‌مند است، فراهم می‌کند.

• نقطه پایانی: POST /checkout-sessions
• محرک: کاربر روی «خرید» روی یک محصول کلیک می‌کند.

درخواست: گوگل اقلام خط و ارز را ارسال می‌کند.

{
  "line_items": [
    {
      "item": {
        "id": "product_12345", // Must match Product Feed ID
        "title": "Running Shoes"
      },
      "quantity": 1
    }
  ],
  "currency": "USD"
}

پاسخ: شما جلسه اولیه را با جمع کل، مالیات (تخمین اولیه) و قابلیت‌های پرداخت برمی‌گردانید. شما باید پیوندهایی به شرایط خدمات و سیاست حفظ حریم خصوصی خود داشته باشید که در زیر دکمه پرداخت پیوند داده می‌شوند.

{
  "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" }
  ]
}

۲. جلسه تسویه حساب را دریافت کنید

این نقطه پایانی امکان بازیابی یک جلسه پرداخت را فراهم می‌کند.

• نقطه پایانی: GET /checkout-sessions/{id}

درخواست: گوگل شناسه‌ی جلسه‌ی پرداخت را ارسال می‌کند. اگر از شناسه‌های سراسری (Global IDs) استفاده می‌کنید (مثلاً gid://merchant.example.com/Checkout/session_abc123 )، توجه داشته باشید که شناسه‌ی موجود در مسیر درخواست، تنها آخرین جزء این شناسه خواهد بود (مثلاً session_abc123 ).

پاسخ: شما شیء پرداخت کامل را برمی‌گردانید.

۳. به‌روزرسانی جلسه پرداخت

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

• نقطه پایانی: PUT /checkout-sessions/{id}
• فعال‌ساز: کاربر آدرس ارسال خود را انتخاب یا تغییر می‌دهد، انتخاب ارسال خود را به‌روزرسانی می‌کند یا اطلاعات پرداخت خود را به‌روزرسانی می‌کند.

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

{
  "id": "gid://merchant.example.com/Checkout/session_abc123",
  "buyer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "[e-mail]"
  },
  "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.)
}

پاسخ: شما در صورت لزوم مالیات‌ها و گزینه‌های ارسال را دوباره محاسبه می‌کنید و کل مبلغ پرداختی را برمی‌گردانید.

{
  "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
                  }
                ]
              }
            ]
          }
      ]
  }
}

۴. تکمیل فرآیند پرداخت

این نقطه پایانی امکان تکمیل جلسه پرداخت و ثبت سفارش را فراهم می‌کند. این نقطه باید جلسه پرداخت تکمیل‌شده را برگرداند و شامل اطلاعات سفارش باشد. پردازش پرداخت باید پس از دریافت این تماس آغاز شود.

• نقطه پایانی: POST /checkout-sessions/{id}/complete
• فعال‌کننده: کاربر روی «ثبت سفارش» کلیک می‌کند.

درخواست: گوگل توکن پرداخت (حباب رمزگذاری‌شده) را از ارائه‌دهنده (مثلاً Google Pay) ارسال می‌کند و سیگنال‌های ریسک مربوط به خریدار را برای شما ارسال می‌کند تا بتوانید تشخیص کلاهبرداری خود را انجام دهید.

{
  "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\"...}"
    }
  }
}

پاسخ: شما شیء پرداخت کامل را که نشان می‌دهد سفارش کامل شده است، شامل شناسه سفارش و یک URL پیوند دائمی به سفارش، برمی‌گردانید.

{
  "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"
}

۵. لغو جلسه پرداخت

این نقطه پایانی، جلسه پرداخت را لغو می‌کند.

• نقطه پایانی: POST /checkout-sessions/{id}/cancel

درخواست: گوگل شناسه جلسه پرداخت را ارسال می‌کند.

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