این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

Google Pay API برای وب 101: اصول

۱. مقدمه

آنچه خواهید ساخت

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

آنچه یاد خواهید گرفت

نحوه بارگیری و پیکربندی API گوگل پی
نحوه نمایش دکمه Google Pay و مدیریت کلیک‌ها
نحوه درخواست توکن پرداخت از گوگل پی

آنچه نیاز دارید

یک ویرایشگر متن به دلخواه شما برای ویرایش فایل‌های HTML و جاوا اسکریپت.
مرورگر وب گوگل کروم یا روش دیگری برای آزمایش یک وب‌سایت محلی.
برای تولید، به یک شناسه تجاری گوگل پی (Google Pay merchantId ) نیاز دارید. ثبت نام در کنسول گوگل پی و کیف پول (Google Pay & Wallet Console) فقط یک دقیقه طول می‌کشد، پس بهتر است همین الان این کار را انجام دهید.

با استفاده از Firebase Studio همراه ما باشید

۲. صفحه HTML را ایجاد کنید

ایجاد فایل‌های پروژه

یک پوشه در رایانه خود با نام gpay-web-101 ایجاد کنید و درون آن پوشه دو فایل متنی خالی با نام‌های index.html و main.js ایجاد کنید. ساختار دایرکتوری شما باید به این شکل باشد:
```
gpay-web-101/
  index.html
  main.js
```

index.html در IDE مورد نظر خود باز کنید و کد زیر را به آن اضافه کنید:

<!doctype html>
<html lang="en">

<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Google Pay API for Web 101</title>
</head>

<body>
  <div id="gpay-container"></div>
  <p>Transaction info and errors will be logged to the console.</p>
  <script type="text/javascript" src="main.js"></script>
  <script
    async src="https://pay.google.com/gp/p/js/pay.js"
    onload="onGooglePayLoaded()">
  </script>
</body>

</html>

توضیح کد

یک DIV خالی با شناسه gpay-container به صفحه اضافه می‌شود. این عنصر DOM، عنصر والدی خواهد بود که دکمه Google Pay در آن اضافه می‌شود. می‌توانید این عنصر را در طرح‌بندی وب‌سایت خود، در صورت لزوم، قرار دهید.
تگ اسکریپت main.js در DOM و پس از عنصر gpay-container قرار می‌گیرد. این کار برای اطمینان از وجود DIV مربوط به container در DOM قبل از درخواست‌های main.js برای آن ضروری است. علاوه بر این، اسکریپت همگام‌سازی می‌شود تا از بارگذاری آن قبل از بارگذاری pay.js اطمینان حاصل شود، زیرا متد onGooglePayLoaded() باید قبل از تکمیل بارگذاری وجود داشته باشد. روش‌های دیگری نیز برای دستیابی به همین نتیجه وجود دارد، اما در اینجا مورد بحث قرار نمی‌گیرند.
در نهایت، pay.js به صورت ناهمگام بارگذاری می‌شود و onGooglePayLoaded() را به عنوان هندلر onload خود پیکربندی می‌کند. این متد در main.js تعریف خواهد شد.

۳. پیکربندی گوگل پی

یک درخواست پرداخت گوگل پی به یک شیء درخواست نیاز دارد. شیء تعریف شده در اینجا به عنوان baseGooglePayRequest شامل حداقل تنظیمات مشترک برای همه درخواست‌ها است. تنظیمات اضافی بسته به درخواست انجام شده اضافه خواهند شد که در این آزمایشگاه کد بررسی خواهیم کرد.

ثابت‌های پیکربندی Google Pay را به فایل خالی main.js اضافه کنید:

//=============================================================================
// Configuration
//=============================================================================

// The DOM element that the Google Pay button will be rendered into
const GPAY_BUTTON_CONTAINER_ID = 'gpay-container';

// Update the `merchantId` and `merchantName` properties with your own values.
// Your real info is required when the environment is `PRODUCTION`.
const merchantInfo = {
  merchantId: '12345678901234567890',
  merchantName: 'Example Merchant'
};

// This is the base configuration for all Google Pay payment data requests.
const baseGooglePayRequest = {
  apiVersion: 2,
  apiVersionMinor: 0,
  allowedPaymentMethods: [
    {
      type: 'CARD',
      parameters: {
        allowedAuthMethods: [
          "PAN_ONLY", "CRYPTOGRAM_3DS"
        ],
        allowedCardNetworks: [
          "AMEX", "DISCOVER", "INTERAC", "JCB", "MASTERCARD", "VISA"
        ]
      },
      tokenizationSpecification: {
        type: 'PAYMENT_GATEWAY',
        parameters: {
          gateway: 'example',
          gatewayMerchantId: 'exampleGatewayMerchantId'
        }
      }
    }
  ],
  merchantInfo
};

// Prevent accidental edits to the base configuration. Mutations will be
// handled by cloning the config using deepCopy() and modifying the copy.
Object.freeze(baseGooglePayRequest);

توضیح کد

متغیر ثابت GPAY_BUTTON_CONTAINER_ID روی شناسه عنصر DOM استفاده شده در صفحه HTML به عنوان کانتینر والد برای دکمه Google Pay تنظیم کنید.
شیء پیکربندی baseGooglePayRequest با تنظیمات مربوط به برنامه خود ایجاد کنید. هر یک از ویژگی‌ها و مقادیر را می‌توانید در مستندات مرجع پیدا کنید. مقادیر نشان داده شده در این مثال ممکن است کاملاً با نیازهای شما مطابقت داشته باشد یا نداشته باشد، بنابراین با دقت بررسی کنید.
ویژگی‌های merchantId و merchantName را با مقادیر دلخواه خود به‌روزرسانی کنید. این فیلدها در محیط TEST اختیاری هستند.

منابع

پست وبلاگ : آیا می‌خواهید پرداخت با گوگل پی روان‌تر باشد؟ گزینه‌های پرداخت خود را پیکربندی کنید!
مرجع API : مستندات اشیاء درخواست API گوگل پی
مرجع API : برای اطلاعات بیشتر در مورد روش‌های مجوزدهی مجاز، شبکه‌های کارتی مجاز و مشخصات توکن‌سازی از جمله مقدار مناسب درگاه، به PaymentMethod مراجعه کنید.

۴. افزودن کلاینت پرداخت

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

این کد کلاینت را به انتهای main.js اضافه کنید:

//=============================================================================
// Google Payments client singleton
//=============================================================================

let paymentsClient = null;

function getGooglePaymentsClient() {
  if (paymentsClient === null) {
    paymentsClient = new google.payments.api.PaymentsClient({
      environment: 'TEST',
      merchantInfo,
      // todo: paymentDataCallbacks (codelab pay-web-201)
    });
  }

  return paymentsClient;
}

توضیح کد

متغیر paymentsClient پس از ایجاد، نمونه را برای کلاینت نگه می‌دارد. این متغیر مستقیماً توسط کد ما قابل دسترسی نیست، بلکه همیشه توسط متد getGooglePaymentsClient() قابل دسترسی است.
متد getGooglePaymentsClient() بررسی می‌کند که آیا یک کلاینت قبلاً نمونه‌سازی شده است یا خیر و آن نمونه را برمی‌گرداند. اگر قبلاً نمونه‌ای از کلاینت ایجاد نشده باشد، یکی ایجاد، ذخیره و بازگردانده می‌شود. این متد تضمین می‌کند که فقط یک نمونه در طول عمر این اسکریپت ایجاد و استفاده شود.
برای نمونه‌سازی یک کلاینت، متد PaymentsClient() فراخوانی می‌شود. در این مثال، به کلاینت می‌گوییم که در یک محیط TEST هستیم. گزینه جایگزین، PRODUCTION است. با این حال، TEST پیش‌فرض است و می‌توان آن را حذف کرد.

۵. اضافه کردن کمک‌کننده‌ها

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

توابع کمکی را به انتهای main.js اضافه کنید:

//=============================================================================
// Helpers
//=============================================================================

const deepCopy = (obj) => JSON.parse(JSON.stringify(obj));

function renderGooglePayButton() {
  const button = getGooglePaymentsClient().createButton({
    onClick: onGooglePaymentButtonClicked
  });

  document.getElementById(GPAY_BUTTON_CONTAINER_ID).appendChild(button);
}

توضیح کد

deepCopy() ابزاری است که از سریال‌سازی و غیر سریال‌سازی JSON برای ایجاد یک کپی عمیق از شیء ارائه شده استفاده می‌کند. این یک روش مناسب برای کلون کردن اشیاء بدون نگرانی در مورد ارجاعات مشترک است.
renderGooglePayButton() ابزاری است که متد کتابخانه createButton() را برای نمایش دکمه Google Pay فراخوانی می‌کند. آرگومان ارسالی مجموعه‌ای از گزینه‌ها است که نحوه رفتار دکمه را تعریف می‌کند، مانند ثبت تابع onGooglePaymentButtonClicked() برای مدیریت کلیک‌های دکمه.

۶. اضافه کردن کنترل‌کننده‌های رویداد

در این اسکریپت ما دو رویداد را پیکربندی می‌کنیم. اولی زمانی فراخوانی می‌شود که بارگذاری کتابخانه pay.js به پایان برسد و دومی زمانی فراخوانی می‌شود که دکمه Google Pay کلیک شود.

کنترل‌کننده‌های رویداد را به انتهای فایل main.js اضافه کنید:

//=============================================================================
// Event Handlers
//=============================================================================

function onGooglePayLoaded() {
  const req = deepCopy(baseGooglePayRequest);

  getGooglePaymentsClient()
    .isReadyToPay(req)
    .then(function(res) {
      if (res.result) {
        renderGooglePayButton();
      } else {
        console.log("Google Pay is not ready for this user.");
      }
    })
    .catch(console.error);
}

function onGooglePaymentButtonClicked() {
  // Create a new request data object for this request
  const req = {
    ...deepCopy(baseGooglePayRequest),
    transactionInfo: {
      countryCode: 'US',
      currencyCode: 'USD',
      totalPriceStatus: 'FINAL',
      totalPrice: (Math.random() * 999 + 1).toFixed(2),
    },
    // todo: callbackIntents (codelab gpay-web-201)
  };

  // Write request object to console for debugging
  console.log(req);

  getGooglePaymentsClient()
    .loadPaymentData(req)
    .then(function (res) {
      // Write response object to console for debugging
      console.log(res);
      // @todo pass payment token to your gateway to process payment
      // @note DO NOT save the payment credentials for future transactions
      paymentToken = res.paymentMethodData.tokenizationData.token;
    })
    .catch(console.error);
}

توضیح کد

تابع onGooglePayLoaded() زمانی فراخوانی می‌شود که اسکریپت pay.js طبق تعریف فایل HTML، بارگذاری خود را به پایان رسانده باشد. تابع isReadyToPay() برای تعیین نمایش یا عدم نمایش دکمه Google Pay فراخوانی می‌شود. اگر مصرف‌کننده آماده پرداخت باشد (به این معنی که نوعی پرداخت را به کیف پول گوگل خود اضافه کرده باشد)، دکمه Google Pay نمایش داده می‌شود.
متد onGooglePaymentButtonClicked() زمانی فراخوانی می‌شود که دکمه Google Pay کلیک شود. این متد، متد کتابخانه‌ای loadPaymentData() را فراخوانی می‌کند که برای بازیابی توکن پرداخت استفاده می‌شود. پس از دریافت توکن پرداخت، آن را برای پردازش تراکنش به درگاه پرداخت خود ارسال می‌کنید. transactionInfo تراکنشی را که باید با کلیک این دکمه پردازش شود، توصیف می‌کند.

۷. نتیجه‌گیری

تبریک می‌گویم که این Codelab را به پایان رساندید! شما یاد گرفتید که چگونه API گوگل پی را در یک وب‌سایت ادغام کنید.

اجرای پروژه

با گوگل کروم تست کنید

با استفاده از مرورگر وب گوگل کروم ، index.html را با استفاده از مسیر File > Open File... از منوی اصلی کروم باز کنید. کروم وقتی پروژه به این روش باز شود، main.js اجرا خواهد کرد. سایر مرورگرهای وب ممکن است اجازه اجرای جاوا اسکریپت را ندهند.

– یا –

با یک وب سرور محلی تست کنید

اگر پایتون نصب شده است، دستور python3 -m http.server را از طریق ترمینال و در پوشه‌ی root یعنی pay-web-101 اجرا کنید.

$ cd /your/path/to/pay-web-101
$ python3 -m http.server
Serving HTTP on :: port 8000 (http://[::]:8000/) ...

سپس، از سایت خود در http://localhost:8000 بازدید کنید.

از اینجا به کجا برویم؟

منابع اضافی

به گفتگو در کانال #payments در دیسکورد بپیوندید
@GooglePayDevs را در X دنبال کنید
ویدیوهای مرتبط با گوگل پی را در یوتیوب تماشا کنید