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

تبدأ معاملة دفع باستخدام 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. مثلاً:

يطلب [merchant] الدفع:

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 إلى مشغّل الخدمات. لا ينبغي أن يكون عامل الخدمة مسجَّلاً مسبقًا. يمكن تسجيله في الوقت المناسب.

التعرّف على التحسينات الخاصة

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

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

تظهر واجهة المستخدم الخاصة بطلب الدفع قبل تشغيل تطبيق الدفع.

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

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

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

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

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

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

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

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

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