إعداد طريقة دفع

تبدأ معاملة دفع باستخدام Web Payments باكتشاف تطبيق الدفع الخاص بك. تعرَّف على كيفية إعداد طريقة دفع وتجهيز تطبيق الدفع ليتمكن التجّار والعملاء من إجراء عمليات الدفع.

Eiji Kitamura

لاستخدام واجهة برمجة التطبيقات Payment Request API، يجب ربط تطبيق الدفع بمعرّف طريقة الدفع. سيستخدم التجّار الذين يريدون دمج تطبيق الدفع معرّف طريقة الدفع للإشارة إلى ذلك في المتصفح. تناقش هذه المقالة طريقة عمل اكتشاف تطبيقات الدفع وكيفية إعداد تطبيق الدفع الخاص بك لاكتشافه واستدعاءه بشكل صحيح من خلال المتصفّح.

إذا كنت مبتدئًا في التعامل مع مفهوم "الدفعات عبر الويب" أو طريقة إجراء معاملة دفع من خلال تطبيقات الدفع، يُرجى قراءة المقالات التالية أولاً:

المتصفحات المتوافقة

تتكوّن دفعات الويب من بعض التقنيات المختلفة وتعتمد حالة الدعم على المتصفّح.

Chromium برنامج المتصفح Safari Firefox
أجهزة الكمبيوتر المكتبي Android أجهزة الكمبيوتر المكتبي الأجهزة الجوّالة أجهزة الكمبيوتر المكتبية/الأجهزة الجوّالة
واجهة برمجة تطبيقات طلب الدفع ✔ ✔ ✔ ✔
واجهة برمجة تطبيقات معالج الدفع ✔ ✔
تطبيق الدفع لأجهزة iOS/Android ✔ ✔ ✔* ✔*

كيفية عثور المتصفِّح على تطبيق دفع

يحتاج كل تطبيق للدفع إلى تقديم ما يلي:

  • معرّف طريقة الدفع المستنِدة إلى عنوان URL
  • بيان طريقة الدفع (إلا عندما يتم توفير معرّف طريقة الدفع من قِبل طرف ثالث)
  • بيان تطبيق الويب
رسم بياني: كيفية عثور المتصفّح على تطبيق الدفع من معرّف طريقة دفع مستنِدة إلى عنوان URL

تبدأ عملية الاكتشاف عندما يبدأ التاجر معاملة:

  1. يرسل المتصفّح طلبًا إلى عنوان URL لمعرّف طريقة الدفع ويجلب بيان طريقة الدفع.
  2. يحدّد المتصفّح عنوان URL لبيان تطبيق الويب من بيان طريقة الدفع ويجلب بيان تطبيق الويب.
  3. يحدِّد المتصفّح ما إذا كان يريد تشغيل تطبيق الدفع على نظام التشغيل أو تطبيق الدفع المستنِد إلى الويب من بيان تطبيق الويب.

تشرح الأقسام التالية بالتفصيل كيفية إعداد طريقة الدفع الخاصة بك كي تتمكّن المتصفّحات من اكتشافها.

الخطوة 1: تقديم معرّف طريقة الدفع

معرِّف طريقة الدفع هو سلسلة مستنِدة إلى عنوان URL. على سبيل المثال، معرّف Google Pay هو https://google.com/pay. يمكن لمطوّري تطبيقات الدفع اختيار أي عنوان URL كمعرِّف طريقة دفع طالما أنّهم يتحكمون فيه ويمكنه عرض محتوى عشوائي. في هذه المقالة، سنستخدم https://bobbucks.dev/pay كمعرّف طريقة الدفع.

كيفية استخدام التجّار لمعرّف طريقة الدفع

يتم إنشاء عنصر PaymentRequest باستخدام قائمة من معرّفات طرق الدفع تحدّد تطبيقات الدفع التي يقرّر التاجر قبولها. يتمّ ضبط معرّفات طريقة الدفع كقيمة للسمة supportedMethods. مثال:

يطلب [التاجر] الدفع:

const request = new PaymentRequest([{
  supportedMethods: 'https://bobbucks.dev/pay'
}], {
  total: {
    label: 'total',
    amount: { value: '10', currency: 'USD' }
  }
});

الخطوة 2: عرض بيان طريقة الدفع

بيان طريقة الدفع هو ملف JSON يحدد تطبيق الدفع الذي يمكنه استخدام طريقة الدفع هذه.

تقديم بيان طريقة الدفع

عندما يبدأ التاجر معاملة دفع، يرسل المتصفّح طلب HTTP GET إلى عنوان URL لمعرّف طريقة الدفع. يستجيب الخادم بنص بيان طريقة الدفع.

يحتوي بيان طريقة الدفع على حقلَين، default_applications وsupported_origins.

اسم الموقع الوصف
default_applications (مطلوب) مصفوفة من عناوين URL التي تشير إلى بيانات تطبيق الويب حيث تتم استضافة تطبيقات الدفع. (يمكن أن يكون عنوان URL نسبيًا). من المتوقّع أن تشير هذه الصفيفة إلى بيان التطوير وبيان الإنتاج وما إلى ذلك.
supported_origins مصفوفة من عناوين URL التي تشير إلى مصادر قد تستضيف تطبيقات دفع تابعة لجهات خارجية تطبّق طريقة الدفع نفسها. تجدر الإشارة إلى أنّه من الممكن استخدام طريقة دفع من خلال تطبيقات دفع متعددة.
الحقول في بيان طريقة الدفع

يجب أن يظهر ملف بيان طريقة الدفع على النحو التالي:

[معالج الدفعات] /payment-manifest.json:

{
  "default_applications": ["https://bobbucks.dev/manifest.json"],
  "supported_origins": [
    "https://alicepay.friendsofalice.example"
  ]
}

عندما يقرأ المتصفّح الحقل default_applications، يعثر على قائمة بالروابط إلى بيانات تطبيقات الويب لتطبيقات الدفع المتوافقة.

يمكنك توجيه المتصفّح للعثور على بيان طريقة الدفع في موقع آخر.

يمكن لعنوان URL لمعرّف طريقة الدفع أن يستجيب بشكل اختياري باستخدام عنوان Link يشير إلى عنوان URL آخر حيث يمكن للمتصفح جلب بيان طريقة الدفع. ويكون ذلك مفيدًا عندما تتم استضافة بيان طريقة الدفع على خادم مختلف أو عندما تكون جهة خارجية تعرض تطبيق الدفع.

كيفية عثور المتصفّح على تطبيق الدفع من معرّف طريقة دفع مستنِدة إلى عنوان URL باستخدام عمليات إعادة التوجيه

يمكنك ضبط خادم طريقة الدفع للاستجابة باستخدام عنوان HTTP Link مع السمة rel="payment-method-manifest" وعنوان URL لبيان طريقة الدفع.

على سبيل المثال، إذا كان البيان على https://bobbucks.dev/payment-manifest.json، سيتضمن عنوان الاستجابة ما يلي:

Link: <https://bobbucks.dev/payment-manifest.json>; rel="payment-method-manifest"

قد يكون عنوان URL اسم مجال مؤهّلاً بالكامل أو مسارًا نسبيًا. افحص https://bobbucks.dev/pay/ بحثًا عن حركة بيانات الشبكة للاطّلاع على مثال. يمكنك أيضًا استخدام أمر curl:

curl --include https://bobbucks.dev/pay

الخطوة 3: عرض بيان تطبيق الويب

يُستخدم بيان تطبيق الويب لتعريف تطبيق ويب كما يوحي الاسم. هو ملف بيان مستخدَم على نطاق واسع لتحديد تطبيق ويب تقدّمي (PWA).

سيظهر البيان النموذجي لتطبيق الويب على النحو التالي:

[معالج الدفعات] /manifest.json:

{
  "name": "Pay with Bobpay",
  "short_name": "Bobpay",
  "description": "This is an example of the Payment Handler API.",
  "icons": [
    {
      "src": "images/manifest/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "images/manifest/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ],
  "serviceworker": {
    "src": "service-worker.js",
    "scope": "/",
    "use_cache": false
  },
  "start_url": "/",
  "display": "standalone",
  "theme_color": "#3f51b5",
  "background_color": "#3f51b5",
  "related_applications": [
    {
      "platform": "play",
      "id": "com.example.android.samplepay",
      "min_version": "1",
      "fingerprints": [
        {
          "type": "sha256_cert",
          "value": "4C:FC:14:C6:97:DE:66:4E:66:97:50:C0:24:CE:5F:27:00:92:EE:F3:7F:18:B3:DA:77:66:84:CD:9D:E9:D2:CB"
        }
      ]
    }
  ]
}

تُستخدَم المعلومات الموضَّحة في بيان تطبيق الويب أيضًا لتحديد كيفية ظهور تطبيق الدفع في واجهة مستخدم طلب الدفع.

اسم الموقع الوصف
name (مطلوب) يُستخدَم كاسم لتطبيق الدفع.
icons (مطلوب) يُستخدم كرمز لتطبيق الدفع. يستخدم متصفّح Chrome هذه الرموز فقط، وقد تستخدمها المتصفّحات الأخرى كرموز احتياطية في حال عدم تحديدها كجزء من وسيلة الدفع.
serviceworker يتم استخدامه لاكتشاف مشغّل الخدمات الذي يعمل كتطبيق دفع مستند إلى الويب.
serviceworker.src عنوان URL المطلوب تنزيل النص البرمجي لمشغّل الخدمات منه.
serviceworker.scope سلسلة تمثّل عنوان URL يحدّد نطاق تسجيل مشغّل الخدمات.
serviceworker.use_cache عنوان URL المطلوب تنزيل النص البرمجي لمشغّل الخدمات منه.
related_applications يتم استخدامه لاكتشاف التطبيق الذي يعمل كتطبيق الدفع الذي توفّره خدمة "نظام التشغيل". يمكنك الاطّلاع على مزيد من التفاصيل على دليل مطوّر تطبيقات الدفع لتطبيقات Android.
prefer_related_applications يُستخدَم لتحديد تطبيق الدفع الذي سيتم إطلاقه عند توفُّر تطبيق دفع مستند إلى نظام التشغيل وتطبيق دفع مستنِد إلى الويب.
حقول مهمة في بيان تطبيق الويب
تطبيق دفع برمز
تصنيف ورمز تطبيق الدفع

يتم استخدام السمة name في بيان تطبيق الويب كاسم تطبيق الدفع، أمّا الموقع icons، فيستخدم كرمز لتطبيق الدفع.

كيفية تحديد Chrome لتطبيق الدفع المطلوب تشغيله

إطلاق تطبيق الدفع الخاص بالنظام الأساسي

لتشغيل تطبيق الدفع الخاص بالنظام الأساسي، يجب استيفاء الشروط التالية:

  • يتم تحديد الحقل related_applications في بيان تطبيق الويب، بالإضافة إلى:
    • يتطابق كل من معرّف حزمة التطبيق المثبَّت وتوقيعه، في حين أنّ الحد الأدنى للإصدار (min_version) في بيان تطبيق الويب أقل من إصدار التطبيق المثبّت أو يساويه.
  • الحقل prefer_related_applications هو true.
  • تم تثبيت تطبيق الدفع الخاص بالنظام الأساسي ويتضمّن ما يلي:
    • فلتر أهداف للسمة org.chromium.action.PAY.
    • تمثّل هذه السمة معرّف طريقة الدفع المحدّد كقيمة للسمة org.chromium.default_payment_method_name.

راجع دليل تطبيقات الدفع Android: للحصول على المزيد من التفاصيل حول كيفية إعداد هذه التطبيقات.

[معالج الدفعات] /manifest.json

"prefer_related_applications": true,
"related_applications": [{
  "platform": "play",
  "id": "xyz.bobpay.app",
  "min_version": "1",
  "fingerprints": [{
    "type": "sha256_cert",
    "value": "92:5A:39:05:C5:B9:EA:BC:71:48:5F:F2:05:0A:1E:57:5F:23:40:E9:E3:87:14:EC:6D:A2:04:21:E0:FD:3B:D1"
  }]
}]

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

إطلاق تطبيق الدفع المستند إلى الويب

يجب تحديد تطبيق الدفع المستنِد إلى الويب في حقل serviceworker في بيان تطبيق الويب.

[معالج الدفعات] /manifest.json:

"serviceworker": {
  "src": "payment-handler.js"
}

يشغِّل المتصفّح تطبيق الدفع المستنِد إلى الويب عن طريق إرسال حدث paymentrequest إلى مشغّل الخدمات. لا يتعين على عامل الخدمة أن يكون مسجلاً مسبقًا. يمكن تسجيله في الوقت المناسب.

فهم التحسينات الخاصة

كيف يمكن للمتصفّحات تخطي واجهة مستخدم طلب الدفع وتشغيل تطبيق دفع مباشرةً

عند استدعاء طريقة show() في PaymentRequest في Chrome، تعرض واجهة برمجة التطبيقات Payment Request API واجهة مستخدم يوفّرها المتصفّح باسم "واجهة مستخدم طلب الدفع". تتيح واجهة المستخدم هذه للمستخدمين اختيار تطبيق للدفع. بعد الضغط على الزر متابعة في واجهة مستخدم طلب الدفع، يتم تشغيل تطبيق الدفع المحدد.

تتدخل واجهة المستخدم لطلبات الدفع قبل إطلاق تطبيق الدفع.

يؤدي عرض واجهة المستخدم لطلب الدفع قبل تشغيل أي تطبيق للدفع إلى زيادة عدد الخطوات التي يحتاجها المستخدم لإتمام عملية الدفع. لتحسين هذه العملية، يمكن للمتصفّح تفويض تطبيقات الدفع لتنفيذ هذه المعلومات وتشغيل تطبيق دفع مباشرةً بدون عرض واجهة المستخدم لطلب الدفع عند استدعاء show().

يمكنك تخطّي واجهة مستخدم طلب الدفع وتشغيل تطبيق الدفع مباشرةً.

لتشغيل تطبيق دفع مباشرةً، يجب استيفاء الشروط التالية:

  • يتم تفعيل "show()" باستخدام إيماءة المستخدم (بالنقر على الماوس مثلاً).
  • يتوفّر تطبيق دفع واحد فقط:
    • يتيح استخدام معرّف طريقة الدفع المطلوب.

متى يتم تسجيل تطبيق دفع مستند إلى الويب في الوقت المناسب (JIT)؟

يمكن إطلاق تطبيقات الدفع المستندة إلى الويب بدون زيارة المستخدِم الصريحة إلى الموقع الإلكتروني لتطبيق الدفع وتسجيل عامل الخدمة. يمكن تسجيل مشغّل الخدمات في الوقت المناسب عندما يختار المستخدم الدفع باستخدام تطبيق الدفع المستند إلى الويب. وهناك نوعان مختلفان من توقيت التسجيل:

  • إذا ظهرت واجهة المستخدم لطلب الدفع، يعني ذلك أنّ التطبيق يتم تسجيله في الوقت المناسب ويتم تشغيله عندما ينقر المستخدم على متابعة.
  • إذا تم تخطي واجهة مستخدم طلب الدفع، يتم تسجيل تطبيق الدفع في الوقت المناسب ويتم تشغيله مباشرةً. يتطلّب تخطّي واجهة مستخدم طلب الدفع لتشغيل تطبيق مسجَّل في الوقت المناسب إيماءة مستخدم، ما يمنع التسجيل غير المتوقع للعاملين في الخدمات من مصادر متعددة.

الخطوات التالية

الآن بعد أن أصبح تطبيق الدفع قابلاً للاكتشاف، تعرَّف على كيفية تطوير تطبيق دفع خاص بالنظام الأساسي وتطبيق دفع مستند إلى الويب.