مشخصات کنترل‌کننده پرداخت گوگل پی

• نام مدیر: com.google.pay
• نسخه: 2026-01-11

۱. مقدمه

رابط برنامه‌نویسی کاربردی com.google.pay API) گوگل پی (Google Pay) با ارائه دسترسی کاربران به روش‌های پرداخت ذخیره شده در حساب گوگلشان، امکان پرداخت سریع را برای کسب‌وکارها فراهم می‌کند.

این هندلر یک مدل یکپارچه‌سازی بدون سر (headless) را فعال می‌کند که در آن کسب‌وکارها پیکربندی Google Pay خود (مانند شبکه‌های کارت مجاز و پارامترهای دروازه) را ارائه می‌دهند و پلتفرم‌ها تعامل سمت کلاینت با API Google Pay را برای تولید یک توکن پرداخت امن مدیریت می‌کنند.

۱.۱ مزایای کلیدی

• پیکربندی جهانی: کسب‌وکارها یک بار Google Pay را با استفاده از JSON استاندارد پیکربندی می‌کنند و به هر پلتفرم مجاز اجازه می‌دهند رابط پرداخت را بدون کد سفارشی frontend رندر کند.
• رابط کاربری جدا: پلتفرم‌ها پیچیدگی ادغام API جاوا اسکریپت یا SDK گوگل پی را مدیریت می‌کنند، در حالی که کسب‌وکارها توکن حاصل را مصرف می‌کنند.
• توکن‌سازی امن: از توکن‌سازی داخلی گوگل برای انتقال مستقیم اعتبارنامه‌های رمزگذاری شده به ارائه‌دهنده خدمات پرداخت (PSP) کسب‌وکار استفاده می‌کند.

۲. ادغام کسب و کار

۲.۱ الزامات

قبل از تبلیغ Google Pay از طریق UCP، کسب‌وکارها باید:

1. دریافت شناسه فروشنده گوگل پی: برای پردازش در محیط PRODUCTION مورد نیاز است (در کنسول گوگل پی و کیف پول ثبت نام کنید).
2. تأیید پشتیبانی PSP: مطمئن شوید که ارائه‌دهنده خدمات پرداخت (PSP) شما در فهرست پردازنده‌ها و درگاه‌های پشتیبانی‌شده برای توکن‌سازی Google Pay قرار دارد.

۲.۲ پیکربندی هندلر

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

۲.۲.۱ طرحواره پیکربندی

شیء پیکربندی، محیط، هویت کسب‌وکار و روش‌های پرداخت مجاز را تعریف می‌کند.

روش پرداخت گوگل پی

بر اساس روش پرداخت گوگل پی .

مشخصات توکن‌سازی

بر اساس مشخصات توکن‌سازی گوگل پی .

۲.۲.۲ مثال تعریف هندلر

{
  "payment": {
    "handlers": [
      {
        "id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
        "name": "com.google.pay",
        "version": "2026-01-11",
        "spec": "https://pay.google.com/gp/p/ucp/2026-01-11/",
        "config_schema": "https://pay.google.com/gp/p/ucp/2026-01-11/schemas/config.json",
        "instrument_schemas": [
          "https://pay.google.com/gp/p/ucp/2026-01-11/schemas/card_payment_instrument.json"
        ],
        "config": {
          "api_version": 2,
          "api_version_minor": 0,
          "environment": "TEST",
          "merchant_info": {
            "merchant_name": "Example Merchant",
            "merchant_id": "01234567890123456789",
            "merchant_origin": "checkout.merchant.com"
          },
          "allowed_payment_methods": [
            {
              "type": "CARD",
              "parameters": {
                "allowed_auth_methods": ["PAN_ONLY"],
                "allowed_card_networks": ["VISA", "MASTERCARD"]
              },
              "tokenization_specification": {
                "type": "PAYMENT_GATEWAY",
                "parameters": {
                  "gateway": "example",
                  "gatewayMerchantId": "exampleGatewayMerchantId"
                }
              }
            }
          ]
        }
      }
    ]
  }
}

۲.۳ نهادها

۲.۳.۱ طرحواره ابزار دقیق

ابزار Google Pay ( card_payment_instrument ) ابزار پرداخت کارت پایه را توسعه می‌دهد. این ابزار فیلدهای نمایش استاندارد (مانند brand و last_digits ) را به ارث می‌برد تا از نمایش یکپارچه رسید اطمینان حاصل کند، در حالی که فیلد credential را برای حمل بار داده توکن‌سازی خاص Google Pay اصلاح می‌کند.

رفتار پلتفرم: پلتفرم مسئول نگاشت پاسخ Google Pay PaymentMethodData به این ساختار قبل از ارسال آن به کسب‌وکار است.

نام	نوع	مورد نیاز	توضیحات
شناسه	رشته	بله	یک شناسه منحصر به فرد برای این ابزار پرداخت، که توسط پلتفرم اختصاص داده شده است.
شناسه_هدایتگر	رشته	بله	شناسه‌ی مربوط به کنترل‌کننده‌ی گوگل پی.
نوع	رشته	بله	ثابت = card . نشان می‌دهد که این ابزار مانند یک کارت رفتار می‌کند (فیلدهای نمایش کارت را به ارث می‌برد).
برند	رشته	بله	شبکه کارت (مثلاً visa ، mastercard ). از info.cardNetwork گوگل پی نگاشت شده است.
آخرین_رقم‌ها	رشته	بله	چهار رقم آخر کارت. برگرفته از info.cardDetails گوگل پی.
متن_توضیح_غنی	رشته	خیر	یک توضیح متنی غنی اختیاری از کارت (مثلاً «ویزایی که به ۱۲۳۴ ختم می‌شود، در ۱۲/۲۰۲۵ منقضی می‌شود»).
rich_card_art	رشته (uri)	خیر	یک URI اختیاری برای یک تصویر غنی که نمایانگر کارت است (مثلاً تصویر کارت صادرکننده).
آدرس_صورتحساب	آدرس پستی	خیر	آدرس صورتحساب مرتبط با کارت.
اعتبارنامه	بار داده‌ی اعتبارنامه	خیر	داده‌های توکن‌سازی امن که توسط گوگل پی برگردانده می‌شوند.

بار داده‌ی اعتبارنامه

این شیء به عنوان credential برای ابزار عمل می‌کند و مستقیماً به داده‌های توکن‌سازی گوگل پی (Google Pay Tokenization Data) نگاشت می‌شود.

آدرس پستی

این شیء به عنوان فیلد address عمل می‌کند و مستقیماً به PostalAddress نگاشت می‌شود.

۳. ادغام پلتفرم

۳.۱ الزامات

قبل از مدیریت پرداخت‌های com.google.pay ، پلتفرم‌ها باید:

1. قابلیت بارگذاری API گوگل پی برای وب (یا معادل اندروید) را داشته باشد.
2. هنگام نمایش دکمه پرداخت، دستورالعمل‌های برند Google Pay را رعایت کنید.

۳.۲ پروتکل پرداخت

پلتفرم‌ها باید برای پردازش هندلر از این جریان پیروی کنند:

مرحله ۱: کشف و پیکربندی

این پلتفرم، کلاینت را برای مدیریت چرخه حیات API مقداردهی اولیه می‌کند.

• مرجع: PaymentsClient

مرحله ۲: بررسی آمادگی برای پرداخت

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

• مرجع: isReadyToPay

مرحله ۳: ایجاد درخواست پرداخت

این پلتفرم، شیء درخواست داده‌های پرداخت، شامل پیکربندی فروشنده، روش‌های پرداخت و جزئیات تراکنش (قیمت و ارز) را جمع‌آوری می‌کند.

• مرجع: PaymentDataRequest

مرحله ۴: تعامل کاربر را فراخوانی کنید

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

• مرجع: loadPaymentData

مرحله ۵: تکمیل فرآیند پرداخت

پس از تعامل موفقیت‌آمیز کاربر، API گوگل پی یک شیء PaymentInstrument را تحت کلید payment_data برمی‌گرداند. پلتفرم این پاسخ را به طرحواره card_payment_instrument نگاشت کرده و درخواست تکمیل پرداخت را ارسال می‌کند.

POST /checkout-sessions/{checkout_id}/complete

{
  "payment_data": {
    "id": "pm_1234567890abc",
    "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
    "type": "card",
    "brand": "visa",
    "last_digits": "4242",
    "billing_address": {
      "street_address": "123 Main Street",
      "extended_address": "Suite 400",
      "address_locality": "Charleston",
      "address_region": "SC",
      "postal_code": "29401",
      "address_country": "US",
      "first_name": "Jane",
      "last_name": "Smith"
    },
    "credential": {
      "type": "PAYMENT_GATEWAY",
      "token": "{\"signature\":\"...\",\"protocolVersion\":\"ECv2\"...}"
    }
  },
  "risk_signals": {
      ...
  }
}

۴. پردازش کسب و کار

پس از دریافت ابزار پرداخت گوگل پی، کسب‌وکارها باید:

1. اعتبارسنجی هندلر: تأیید کنید که handler_id مربوط به هندلر گوگل پی است.
2. استخراج توکن: رشته توکن را از payment_data.credential.token بازیابی کنید.
3. پردازش پرداخت: رشته توکن و جزئیات تراکنش را به نقطه پایانی PSP ارسال کنید.
   • توجه: اکثر PSPها فیلد خاصی برای «Google Pay Payload» یا «Network Token» دارند.
4. پاسخ بازگشت: با وضعیت پرداخت نهایی (موفق/ناموفق) پاسخ دهید.

۵. ملاحظات امنیتی

۵.۱ امنیت توکن

• PAYMENT_GATEWAY: هنگام استفاده از این نوع توکن‌سازی، توکن به طور خاص برای طرف توکن‌سازی رمزگذاری می‌شود. طرف عبور نمی‌تواند این توکن را رمزگشایی کند و باید آن را به همان شکل به طرف توکن‌سازی منتقل کند.
• DIRECT: در صورت استفاده از توکن‌سازی DIRECT ، کسب‌وکار داده‌های رمزگذاری‌شده کارت را دریافت می‌کند که باید رمزگشایی شوند. این امر دامنه انطباق با PCI DSS را به میزان قابل توجهی افزایش می‌دهد و عموماً توصیه نمی‌شود، مگر اینکه کسب‌وکار ارائه‌دهنده خدمات سازگار با PCI سطح 1 باشد.

۵.۲ ایزوله‌سازی محیطی

• حالت آزمایشی: در محیط TEST ، گوگل پی توکن‌های ساختگی برمی‌گرداند. این توکن‌ها قابل برداشت نیستند.
• حالت تولید: از کارت‌های واقعی استفاده می‌شود. کسب‌وکارها باید اطمینان حاصل کنند که اعتبارنامه‌های PSP آنها در config.allowed_payment_methods با محیط مطابقت دارد.