رسیدگی به اطلاعات پرداخت اختیاری با یک کارگر خدماتی

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

Eiji Kitamura

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

تغییر روش پرداخت را به تاجر اطلاع دهید

برنامه های پرداخت می توانند چندین ابزار پرداخت را با روش های پرداخت مختلف پشتیبانی کنند.

به عنوان مثال، در جدول بالا، کیف پول مبتنی بر وب مشتری الف دارای دو کارت اعتباری و یک حساب بانکی ثبت شده است. در این حالت، برنامه سه ابزار پرداخت ( ****1234 ، ****4242 ، ******123 ) و دو روش پرداخت (صادرکننده کارت اعتباری 1 و بانک X) را مدیریت می‌کند. در تراکنش پرداخت، برنامه پرداخت می‌تواند به مشتری اجازه دهد یکی از ابزارهای پرداخت را انتخاب کند و از آن برای پرداخت هزینه تاجر استفاده کند.

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

با استفاده از Payment Handler API، برنامه پرداخت می‌تواند رویداد «تغییر روش پرداخت» را از طریق یک سرویس‌دهنده برای تاجر ارسال کند تا به شناسه روش پرداخت جدید اطلاع دهد. کارگر سرویس باید PaymentRequestEvent.changePaymentMethod() با اطلاعات روش پرداخت جدید فراخوانی کند.

برنامه‌های پرداخت می‌توانند یک شی methodDetails به عنوان آرگومان دوم اختیاری برای PaymentRequestEvent.changePaymentMethod() ارسال کنند. این شی می‌تواند حاوی جزئیات روش پرداخت دلخواه باشد که برای تاجر برای پردازش رویداد تغییر لازم است.

[Payment handler] service-worker.js

…
// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      …
      case 'PAYMENT_METHOD_CHANGED':
        const newMethod = e.data.paymentMethod;
        const newDetails = e.data.methodDetails;
        // Redact or check that no sensitive information is passed in
        // `newDetails`.
        // Notify the merchant of the payment method change
        details =
          await payment_request_event.changePaymentMethod(newMethod, newDetails);
      …

هنگامی که تاجر یک رویداد paymentmethodchange از API درخواست پرداخت دریافت می‌کند، می‌تواند جزئیات پرداخت را به‌روزرسانی کند و با یک شی PaymentDetailsUpdate پاسخ دهد.

[تاجر]

request.addEventListener('paymentmethodchange', e => {
  if (e.methodName === 'another-pay') {
    // Apply $10 discount for example.
    const discount = {
      label: 'special discount',
      amount: {
        currency: 'USD',
        // The value being string complies the spec
        value: '-10.00'
      }
    };
    let total = 0;
    details.displayItems.push(discount);
    for (let item of details.displayItems) {
     total += parseFloat(item.amount.value);
    }
    // Convert the number back to string
    details.total.amount.value = total.toString();
  }
  // Pass a promise to `updateWith()` and send updated payment details
  e.updateWith(details);
});

هنگامی که تاجر پاسخ می دهد، قولی که PaymentRequestEvent.changePaymentMethod() برگردانده شده است با یک شی PaymentRequestDetailsUpdate حل می شود.

[Payment handler] service-worker.js

…
        // Notify the merchant of the payment method change
        details = await payment_request_event.changePaymentMethod(newMethod, newDetails);
        // Provided the new payment details,
        // send a message back to the frontend to update the UI
        postMessage('UPDATE_REQUEST', details);
        break;
…

از شی برای به روز رسانی رابط کاربری در قسمت جلویی استفاده کنید. به بازتاب جزئیات پرداخت به روز مراجعه کنید.

به تاجر از تغییر آدرس حمل و نقل اطلاع دهید

برنامه های پرداخت می توانند آدرس حمل و نقل مشتری را به عنوان بخشی از تراکنش پرداخت به تاجر ارائه دهند.

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

علاوه بر این، مشتریان می توانند اطلاعات آدرس خود را با برنامه پرداخت دلخواه خود ثبت کنند و از آن برای تجار مختلف استفاده مجدد کنند.

برنامه‌های پرداخت می‌توانند یک رابط کاربری برای ویرایش آدرس حمل و نقل یا انتخاب اطلاعات آدرس از پیش ثبت‌شده برای مشتری در تراکنش پرداخت ارائه کنند. وقتی یک آدرس حمل و نقل به طور موقت تعیین می شود، برنامه پرداخت می تواند به تاجر از اطلاعات آدرس ویرایش شده اطلاع دهد. این به تجار مزایای متعددی را ارائه می دهد:

• یک تاجر می تواند تعیین کند که آیا مشتری محدودیت منطقه ای برای ارسال کالا را رعایت می کند (مثلاً فقط داخلی).
• یک تاجر می تواند فهرست گزینه های حمل و نقل را بر اساس منطقه آدرس حمل و نقل (به عنوان مثال، بین المللی معمولی یا سریع) تغییر دهد.
• یک تاجر می تواند هزینه حمل و نقل جدید را بر اساس آدرس اعمال کند و قیمت کل را به روز کند.

با استفاده از Payment Handler API، برنامه پرداخت می‌تواند یک رویداد "تغییر آدرس حمل و نقل" را از طرف کارمند خدمات برای تاجر ارسال کند تا آدرس ارسال جدید را مطلع کند. کارگر سرویس باید PaymentRequestEvent.changeShippingAddress() با شی آدرس جدید فراخوانی کند.

[Payment handler] service-worker.js

...
// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      …
      case 'SHIPPING_ADDRESS_CHANGED':
        const newAddress = e.data.shippingAddress;
        details =
          await payment_request_event.changeShippingAddress(newAddress);
      …

تاجر یک رویداد shippingaddresschange از API درخواست پرداخت دریافت خواهد کرد تا بتواند با به روز رسانی PaymentDetailsUpdate پاسخ دهد.

[تاجر]

request.addEventListener('shippingaddresschange', e => {
  // Read the updated shipping address and update the request.
  const addr = request.shippingAddress;
  const details = getPaymentDetailsFromShippingAddress(addr);
  // `updateWith()` sends back updated payment details
  e.updateWith(details);
});

هنگامی که تاجر پاسخ می دهد، وعده PaymentRequestEvent.changeShippingAddress() بازگردانده شده با یک شی PaymentRequestDetailsUpdate حل می شود.

[Payment handler] service-worker.js

…
        // Notify the merchant of the shipping address change
        details = await payment_request_event.changeShippingAddress(newAddress);
        // Provided the new payment details,
        // send a message back to the frontend to update the UI
        postMessage('UPDATE_REQUEST', details);
        break;
…

از شی برای به روز رسانی رابط کاربری در قسمت جلویی استفاده کنید. به بازتاب جزئیات پرداخت به روز مراجعه کنید.

به تاجر از تغییر گزینه حمل و نقل اطلاع دهید

گزینه های حمل و نقل روش های تحویلی هستند که تجار برای ارسال اقلام خریداری شده به مشتری استفاده می کنند. گزینه های حمل و نقل معمولی عبارتند از:

• ارسال رایگان
• حمل و نقل سریع
• حمل و نقل بین المللی
• حمل و نقل بین المللی ممتاز

هر کدام هزینه های خاص خود را دارد. معمولا روش‌ها/گزینه‌های سریع‌تر گران‌تر هستند.

بازرگانانی که از API درخواست پرداخت استفاده می‌کنند، می‌توانند این انتخاب را به یک برنامه پرداخت واگذار کنند. برنامه پرداخت می‌تواند از اطلاعات برای ایجاد رابط کاربری استفاده کند و به مشتری اجازه دهد گزینه ارسال را انتخاب کند.

فهرست گزینه‌های ارسال مشخص‌شده در API درخواست پرداخت تاجر به‌عنوان ویژگی PaymentRequestEvent به کارمند خدمات برنامه پرداخت منتشر می‌شود.

[تاجر]

const request = new PaymentRequest([{
  supportedMethods: 'https://bobbucks.dev/pay',
  data: { transactionId: '****' }
}], {
  displayItems: [{
    label: 'Anvil L/S Crew Neck - Grey M x1',
    amount: { currency: 'USD', value: '22.15' }
  }],
  shippingOptions: [{
    id: 'standard',
    label: 'Standard',
    amount: { value: '0.00', currency: 'USD' },
    selected: true
  }, {
    id: 'express',
    label: 'Express',
    amount: { value: '5.00', currency: 'USD' }
  }],
  total: {
    label: 'Total due',
    amount: { currency: 'USD', value : '22.15' }
  }
}, {  requestShipping: true });

برنامه پرداخت می تواند به تاجر اطلاع دهد که مشتری کدام گزینه حمل و نقل را انتخاب کرده است. این امر هم برای تاجر و هم برای مشتری مهم است زیرا تغییر گزینه حمل و نقل قیمت کل را نیز تغییر می دهد. بعداً برای تأیید پرداخت باید تاجر از آخرین قیمت مطلع شود و مشتری نیز باید از تغییر مطلع باشد.

با استفاده از Payment Handler API، برنامه پرداخت می‌تواند رویداد «تغییر گزینه حمل و نقل» را از طرف کارمند خدمات برای تاجر ارسال کند. کارگر سرویس باید PaymentRequestEvent.changeShippingOption() با شناسه گزینه حمل و نقل جدید فراخوانی کند.

[Payment handler] service-worker.js

…
// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      …
      case 'SHIPPING_OPTION_CHANGED':
        const newOption = e.data.shippingOptionId;
        details =
          await payment_request_event.changeShippingOption(newOption);
      …

تاجر یک رویداد shippingoptionchange را از API درخواست پرداخت دریافت خواهد کرد. تاجر باید از اطلاعات برای به‌روزرسانی قیمت کل استفاده کند و سپس با PaymentDetailsUpdate به‌روزرسانی شده پاسخ دهد.

[تاجر]

request.addEventListener('shippingoptionchange', e => {
  // selected shipping option
  const shippingOption = request.shippingOption;
  const newTotal = {
    currency: 'USD',
    label: 'Total due',
    value: calculateNewTotal(shippingOption),
  };
  // `updateWith()` sends back updated payment details
  e.updateWith({ total: newTotal });
});

هنگامی که تاجر پاسخ می‌دهد، قولی که PaymentRequestEvent.changeShippingOption() برمی‌گرداند با یک شی PaymentRequestDetailsUpdate حل می‌شود.

[Payment handler] service-worker.js

…
        // Notify the merchant of the shipping option change
        details = await payment_request_event.changeShippingOption(newOption);
        // Provided the new payment details,
        // send a message back to the frontend to update the UI
        postMessage('UPDATE_REQUEST', details);
        break;
…

از شی برای به روز رسانی رابط کاربری در قسمت جلویی استفاده کنید. به بازتاب جزئیات پرداخت به روز مراجعه کنید.

جزئیات پرداخت به روز شده را منعکس کنید

هنگامی که تاجر به‌روزرسانی جزئیات پرداخت را تمام کرد، وعده‌های بازگردانده شده از .changePaymentMethod() ، .changeShippingAddress() و .changeShippingOption() با یک شی رایج PaymentRequestDetailsUpdate حل می‌شوند. کنترل کننده پرداخت می تواند از نتیجه برای منعکس کردن قیمت کل به روز شده و گزینه های ارسال به UI استفاده کند.

تاجران ممکن است به چند دلیل خطاها را برگردانند:

• روش پرداخت قابل قبول نیست.
• آدرس حمل و نقل خارج از مناطق پشتیبانی شده آنها است.
• آدرس حمل و نقل حاوی اطلاعات نامعتبر است.
• گزینه ارسال به دلیل آدرس ارسال ارائه شده یا دلایل دیگری قابل انتخاب نیست.

از ویژگی های زیر برای منعکس کردن وضعیت خطا استفاده کنید:

• error : رشته خطای قابل خواندن توسط انسان. این بهترین رشته برای نمایش به مشتریان است.
• shippingAddressErrors : شیء AddressErrors که شامل رشته خطای جزئی در هر ویژگی آدرس است. اگر می‌خواهید فرمی را باز کنید که به مشتری اجازه می‌دهد آدرس خود را ویرایش کند و باید او را مستقیماً به قسمت‌های نامعتبر هدایت کنید، مفید است.
• paymentMethodErrors : شیء خطای خاص روش پرداخت. می‌توانید از بازرگانان بخواهید یک خطای ساختاریافته را ارائه کنند، اما نویسندگان مشخصات Web Payments توصیه می‌کنند که آن را یک رشته ساده نگه دارید.

کد نمونه

اکثر کدهای نمونه ای که در این سند دیدید گزیده هایی از برنامه نمونه کار زیر بودند:

https://paymenthandler-demo.glitch.me

[پرداخت کننده] کارگر خدمات

[پرداخت کننده] فرانت اند

برای امتحان کردن:

1. به https://paymentrequest-demo.glitch.me/ بروید.
2. به پایین صفحه بروید.
3. دکمه افزودن یک پرداخت را فشار دهید.
4. https://paymenthandler-demo.glitch.me در قسمت شناسه روش پرداخت وارد کنید.
5. دکمه پرداخت را در کنار فیلد فشار دهید.