تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

أساسيات Google Pay API للويب

1. مقدمة

ما ستُنشئه

عند الانتهاء من هذا الدليل التعليمي حول رموز البرامج، سيكون لديك موقع إلكتروني صالح بحد أدنى من الوظائف مع تكامل Google Pay. يسترجع هذا المشروع رمز دفعة يمكن إرساله إلى مقدّم خدمة دفع لمعالجته.

المُعطيات

كيفية تحميل Google Pay API وضبط إعداداتها
كيفية عرض زر Google Pay ومعالجة النقرات
كيفية طلب رمز دفع من Google Pay

المتطلبات

محرِّر نصوص من اختيارك لتعديل ملفات HTML وJavaScript
متصفّح الويب Google Chrome أو طريقة أخرى لاختبار موقع إلكتروني على الجهاز
لاستخدام التطبيق في قناة الإصدار العلني، ستحتاج إلى merchantId في Google Pay. يستغرق التسجيل في Google Pay & Wallet Console دقيقة واحدة فقط، لذا ننصحك بإجراء ذلك الآن.

المتابعة باستخدام Project IDX

2. إنشاء صفحة 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 للحاويات في نموذج كائن المستند قبل أن تبحث عنه main.js. بالإضافة إلى ذلك، يكون النص البرمجي متزامنًا لضمان تحميله قبل تحميل pay.js، لأنّ طريقة onGooglePayLoaded() يجب أن تكون متوفّرة قبل اكتمال عملية التحميل. هناك طرق أخرى لتحقيق التأثير نفسه، ولكن لن تتم مناقشتها هنا.
أخيرًا، يتم تحميل pay.js بشكل غير متزامن وضبط onGooglePayLoaded() على أنّه معالِج onload. سيتم تحديد هذه الطريقة في main.js.

3- ضبط إعدادات Google Pay

يتطلّب طلب الدفع في Google Pay عنصر طلب. يحتوي العنصر المحدّد هنا باسم 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.

الموارد

مشاركة المدوّنة: هل تريد إتمام الدفع بسلاسة باستخدام Google Pay؟ ضبط خيارات الدفع
مرجع واجهة برمجة التطبيقات: مستندات عناصر الطلبات في Google Pay API
مرجع واجهة برمجة التطبيقات: يُرجى الرجوع إلى PaymentMethod للحصول على مزيد من المعلومات عن طرق التفويض المسموح بها وشبكات البطاقات المسموح بها ومواصفات إنشاء الرموز المميّزة، بما في ذلك قيمة البوابة المناسبة.

4. إضافة عميل دفعات

يتم استخدام واجهة برمجة تطبيقات دفع لتقديم طلبات الدفع وتسجيل عمليات معاودة الاتصال. في هذا الدليل التعليمي، سنُجري طلبات دفع فقط. بالإضافة إلى ذلك، يمكنك ضبط 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 تلقائيًا ويمكن حذفه.

5- إضافة مساعدين

يتم استخدام الدوالّ المساعِدة التالية لاحقًا في النص البرمجي، وقد تمت إضافتها بغرض تحسين سهولة قراءة الرمز البرمجي وقابلية صيانته فقط.

إلحاق الدوال المساعِدة بأسفل 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() لمعالجة النقرات على الزر.

6- إضافة معالِجات الأحداث

في هذا النص البرمجي، سنضبط معالِجَي حدثَين. يتمّ استدعاء الأول عند انتهاء تحميل مكتبة 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")، يتم عرض زر Google Pay.
يتمّ استدعاء onGooglePaymentButtonClicked() عند النقر على زر Google Pay. تستدعي هذه الطريقة طريقة مكتبة loadPaymentData() التي تُستخدَم لاسترداد رمز مميّز للدفع. بعد الحصول على رمز الدفع، عليك إرساله إلى بوابة الدفع لمعالجة المعاملة. يصف transactionInfo المعاملة التي يجب معالجتها من خلال النقر على هذا الزر.

7- الخاتمة

تهانينا على إكمال هذا الدرس التطبيقي حول الترميز. لقد تعرّفت على كيفية دمج Google Pay APi في موقع إلكتروني.

تنفيذ المشروع

الاختبار باستخدام Google Chrome

باستخدام متصفّح الويب Google Chrome، افتح index.html باستخدام ملف > فتح ملف... من القائمة الرئيسية في Chrome. سينفِّذ Chrome main.js عند فتح المشروع بهذه الطريقة. قد لا تسمح متصفّحات الويب الأخرى بتنفيذ JavaScript.

– أو –

الاختبار باستخدام خادم ويب محلي

إذا كان لديك Python مثبَّتًا، يمكنك تشغيل python3 -m http.server من طلب سطر الأوامر في المجلد الجذر 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 على Discord
متابعة ‎@GooglePayDevs على X
مشاهدة فيديوهات ذات صلة بخدمة Google Pay على YouTube