سازماندهی تراکنش های پرداخت با یک کارگر خدماتی

چگونه اپلیکیشن پرداخت مبتنی بر وب خود را با پرداخت‌های وب تطبیق دهید و تجربه کاربری بهتری برای مشتریان فراهم کنید.

Eiji Kitamura

پس از ثبت برنامه پرداخت ، شما آماده پذیرش درخواست‌های پرداخت از سوی فروشندگان هستید. این پست نحوه هماهنگ‌سازی یک تراکنش پرداخت از یک سرویس ورکر را در زمان اجرا (یعنی زمانی که یک پنجره نمایش داده می‌شود و کاربر با آن تعامل دارد) توضیح می‌دهد.

هماهنگ‌سازی تراکنش‌های پرداخت با یک سرویس ورکر

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

دریافت رویداد درخواست پرداخت از فروشنده

وقتی مشتری تصمیم می‌گیرد با برنامه پرداخت مبتنی بر وب شما پرداخت کند و فروشنده PaymentRequest.show() را فراخوانی می‌کند ، سرویس ورکر شما یک رویداد paymentrequest دریافت می‌کند. یک شنونده رویداد به سرویس ورکر اضافه کنید تا رویداد را ثبت کرده و برای اقدام بعدی آماده شود.

[پردازنده پرداخت] service-worker.js:

…
let payment_request_event;
let resolver;
let client;

// `self` is the global object in service worker
self.addEventListener('paymentrequest', async e => {
  if (payment_request_event) {
    // If there's an ongoing payment transaction, reject it.
    resolver.reject();
  }
  // Preserve the event for future use
  payment_request_event = e;
…

احتیاط: به یاد داشته باشید که یک سرویس ورکر یک نمونه واحد در تب‌ها و پنجره‌های مختلف در یک مرورگر است. متغیرهای سراسری در تمام تب‌ها و پنجره‌ها به اشتراک گذاشته می‌شوند.

رویداد PaymentRequestEvent ذخیره شده حاوی اطلاعات مهمی در مورد این تراکنش است:

نام ملک	توضیحات
topOrigin	رشته‌ای که مبدأ صفحه وب سطح بالا (معمولاً فروشگاه پذیرنده وجه) را نشان می‌دهد. از این برای شناسایی مبدأ فروشگاه استفاده کنید.
paymentRequestOrigin	رشته‌ای که مبداء فراخوانی‌کننده را نشان می‌دهد. این می‌تواند مشابه topOrigin باشد وقتی که فروشنده مستقیماً API درخواست پرداخت را فراخوانی می‌کند، اما اگر API از درون یک iframe توسط شخص ثالثی مانند درگاه پرداخت فراخوانی شود، ممکن است متفاوت باشد.
paymentRequestId	ویژگی id از PaymentDetailsInit که به API درخواست پرداخت ارائه می‌شود. اگر فروشنده آن را حذف کند، مرورگر یک شناسه خودکار تولید می‌کند.
methodData	داده‌های مربوط به روش پرداخت که توسط فروشنده به عنوان بخشی از PaymentMethodData ارائه شده است. از این برای تعیین جزئیات تراکنش پرداخت استفاده کنید.
total	کل مبلغ ارائه شده توسط فروشنده به عنوان بخشی از PaymentDetailsInit . از این برای ساخت یک رابط کاربری استفاده کنید تا مشتری از کل مبلغ قابل پرداخت مطلع شود.
instrumentKey	کلید ابزار انتخاب شده توسط کاربر. این کلید instrumentKey که از قبل ارائه کرده‌اید، نشان می‌دهد. یک رشته خالی نشان می‌دهد که کاربر هیچ ابزاری را مشخص نکرده است.

پنجره مدیریت پرداخت را باز کنید تا رابط کاربری برنامه پرداخت مبتنی بر وب نمایش داده شود.

وقتی یک رویداد paymentrequest دریافت می‌شود، برنامه پرداخت می‌تواند با فراخوانی PaymentRequestEvent.openWindow() یک پنجره مدیریت پرداخت باز کند. پنجره مدیریت پرداخت، رابط برنامه پرداخت شما را به مشتریان ارائه می‌دهد که در آن می‌توانند احراز هویت کنند، آدرس و گزینه‌های ارسال را انتخاب کنند و پرداخت را تأیید کنند. ما نحوه نوشتن کد frontend را در بخش مدیریت پرداخت‌ها در frontend پرداخت (به زودی) پوشش خواهیم داد.

جریان پرداخت با یک برنامه پرداخت مبتنی بر وب.

یک promise حفظ‌شده را به PaymentRequestEvent.respondWith() ارسال کنید تا بتوانید در آینده آن را با یک نتیجه پرداخت حل کنید.

[پردازنده پرداخت] service-worker.js:

…
self.addEventListener('paymentrequest', async e => {
…
  // Retain a promise for future resolution
  // Polyfill for PromiseResolver is provided below.
  resolver = new PromiseResolver();

  // Pass a promise that resolves when payment is done.
  e.respondWith(resolver.promise);
  // Open the checkout page.
  try {
    // Open the window and preserve the client
    client = await e.openWindow(checkoutURL);
    if (!client) {
      // Reject if the window fails to open
      throw 'Failed to open window';
    }
  } catch (err) {
    // Reject the promise on failure
    resolver.reject(err);
  };
});
…

شما می‌توانید از یک چند-پر کردنیِ مناسبِ PromiseResolver برای حل یک promise در زمان دلخواه استفاده کنید.

class PromiseResolver {
  constructor() {
    this.promise_ = new Promise((resolve, reject) => {
      this.resolve_ = resolve;
      this.reject_ = reject;
    })
  }
  get promise() { return this.promise_ }
  get resolve() { return this.resolve_ }
  get reject() { return this.reject_ }
}

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

تبادل اطلاعات با رابط کاربری

سرویس ورکر برنامه پرداخت می‌تواند از طریق ServiceWorkerController.postMessage() با رابط کاربری برنامه پرداخت تبادل پیام کند. برای دریافت پیام‌ها از رابط کاربری، به رویدادهای message گوش دهید.

[پردازنده پرداخت] service-worker.js:

// Define a convenient `postMessage()` method
const postMessage = (type, contents = {}) => {
  if (client) client.postMessage({ type, ...contents });
}

سیگنال آماده بودن را از frontend دریافت کنید

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

رابط کاربری [پردازنده پرداخت]:

navigator.serviceWorker.controller.postMessage({
  type: 'WINDOW_IS_READY'
});

[پردازنده پرداخت] service-worker.js:

…
// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      // `WINDOW_IS_READY` is a frontend's ready state signal
      case 'WINDOW_IS_READY':
        const { total } = payment_request_event;
…

جزئیات تراکنش را به frontend ارسال کنید

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

[پردازنده پرداخت] service-worker.js:

…
        // Pass the payment details to the frontend
        postMessage('PAYMENT_IS_READY', { total });
        break;
…

رابط کاربری [پردازنده پرداخت]:

let total;

navigator.serviceWorker.addEventListener('message', async e => {
  switch (e.data.type) {
      case 'PAYMENT_IS_READY':
        ({ total } = e.data);
        // Update the UI
        renderHTML(total);
        break;
…

اطلاعات پرداخت مشتری را برگردانید

وقتی مشتری پرداخت را تأیید می‌کند، frontend می‌تواند یک پیام post برای ادامه کار به service worker ارسال کند. شما می‌توانید promise ارسال شده به PaymentRequestEvent.respondWith() را حل کنید تا نتیجه به فروشنده ارسال شود. یک شیء PaymentHandlerResponse ارسال کنید.

نام ملک	توضیحات
methodName	شناسه روش پرداختی که برای انجام پرداخت استفاده می‌شود.
details	داده‌های خاص روش پرداخت که اطلاعات لازم را برای پردازش پرداخت در اختیار فروشنده قرار می‌دهد.

رابط کاربری [پردازنده پرداخت]:

  const paymentMethod = …

  postMessage('PAYMENT_AUTHORIZED', {
    paymentMethod,              // Payment method identifier
  });

[پردازنده پرداخت] service-worker.js:

…
// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      …
      case 'PAYMENT_AUTHORIZED':
        // Resolve the payment request event promise
        // with a payment response object
        const response = {
          methodName: e.data.paymentMethod,
          details: { id: 'put payment credential here' },
        }
        resolver.resolve(response);
        // Don't forget to initialize.
        payment_request_event = null;
        break;
      …

تراکنش پرداخت را لغو کنید

برای اینکه مشتری بتواند تراکنش را لغو کند، frontend می‌تواند یک پیام post به service worker ارسال کند تا این کار را انجام دهد. سپس service worker می‌تواند promise ارسال شده به PaymentRequestEvent.respondWith() را با null حل کند تا به فروشنده نشان دهد که تراکنش لغو شده است.

رابط کاربری [پردازنده پرداخت]:

  postMessage('CANCEL_PAYMENT');

[پردازنده پرداخت] service-worker.js:

…
// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      …
      case 'CANCEL_PAYMENT':
        // Resolve the payment request event promise
        // with null
        resolver.resolve(null);
        // Don't forget to initialize.
        payment_request_event = null;
        break;
      …

کد نمونه

تمام کدهای نمونه‌ای که در این سند مشاهده کردید، گزیده‌هایی از موارد زیر بودند: نسخه آزمایشی کنترل‌کننده پرداخت مبتنی بر وب

مراحل بعدی

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

• مدیریت اطلاعات پرداخت اختیاری با یک سرویس ورکر