چگونه برنامه پرداخت مبتنی بر وب خود را با «پرداخت‌های وب» سازگار کنید و تجربه کاربری بهتری برای مشتریان فراهم کنید.
Once a web-based payment app receives a payment request and initiates a payment transaction, the service worker will act as the hub for communication between the merchant and the payment app. This post explains how a payment app can pass information about the payment method, shipping address, or contact information to the merchant using a service worker.
به فروشنده اطلاع دهید
مهم است که تغییرات زیر را به اطلاع فروشنده برسانید.
تغییر روش پرداخت
برنامه‌های پرداخت می‌توانند از چندین ابزار پرداخت با روش‌های پرداخت مختلف پشتیبانی کنند.
| مشتری | روش پرداخت | ابزار پرداخت |
|---|---|---|
| آمپر | صادرکننده کارت اعتباری ۱ | ****1234 |
| صادرکننده کارت اعتباری ۱ | ****4242 |
|
| Bank X | ******123 |
|
| B | صادرکننده کارت اعتباری ۲ | ****5678 |
| Bank X | ******456 |
برای مثال، در جدول بالا، کیف پول مبتنی بر وب «مشتری الف» دو کارت اعتباری و یک حساب بانکی ثبت‌شده دارد. در این مورد، برنامه سه ابزار پرداخت (****1234، ****4242، ******123) و دو روش پرداخت (صادرکننده کارت اعتباری ۱ و بانک X) را مدیریت می‌کند. در تراکنش پرداخت، برنامه پرداخت می‌تواند به مشتری اجازه دهد یکی از ابزارهای پرداخت را انتخاب کند و از آن برای پرداخت به فروشنده استفاده کند.
برنامه پرداخت می‌تواند قبل‌از ارسال پاسخ کامل پرداخت، به فروشنده اطلاع دهد که مشتری کدام روش پرداخت را انتخاب کرده است. این ویژگی زمانی مفید است که فروشنده بخواهد پویش تخفیفی برای نمانام روش پرداخت خاصی اجرا کند.
با میانای برنامه‌سازی کاربردی «مدیریت پرداخت مبتنی بر وب»، برنامه پرداخت می‌تواند رویداد «تغییر روش پرداخت» را ازطریق یک سرویس‌کار به فروشنده ارسال کند تا شناسه روش پرداخت جدید را اطلاع دهد. کارگر سرویس باید
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 را از Payment
Request API دریافت می‌کند، می‌تواند جزئیات پرداخت را به‌روز کند و با شیء
PaymentDetailsUpdate
پاسخ دهد.
[merchant]
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;
…
از این شیء برای به‌روزرسانی میانای کاربری در بخش کاربری استفاده کنید. نمایش جزئیات پرداخت به‌روزشده را ببینید.
تغییر نشانی ارسال کالا
برنامه‌های پرداخت می‌توانند نشانی ارسال کالا را به‌عنوان بخشی از تراکنش پرداخت به فروشنده ارائه دهند.
این کار برای فروشندگان مفید است زیرا می‌توانند جمع‌آوری نشانی را به برنامه‌های پرداخت واگذار کنند. و چون داده‌های نشانی در قالب استاندارد داده ارائه می‌شود، فروشنده می‌تواند انتظار داشته باشد که نشانی‌های ارسال کالا را در ساختاری یکسان دریافت کند.
علاوه‌براین، مشتریان می‌توانند اطلاعات نشانی‌شان را در برنامه پرداخت ترجیحی‌شان ثبت کنند و از آن برای فروشندگان مختلف استفاده کنند.
برنامه‌های پرداخت می‌توانند واسط کاربری‌ای برای ویرایش نشانی ارسال کالا یا انتخاب اطلاعات نشانی ازپیش ثبت‌شده برای مشتری در تراکنش پرداخت ارائه دهند. وقتی نشانی ارسال کالا به‌طور موقت تعیین می‌شود، برنامه پرداخت می‌تواند اطلاعات نشانی ویرایش‌شده را به فروشنده اطلاع دهد. این کار مزایای متعددی برای فروشندگان دارد:
- فروشنده می‌تواند تعیین کند که آیا مشتری محدودیت منطقه‌ای را برای ارسال کالا رعایت می‌کند یا نه (برای مثال، فقط داخلی).
- فروشنده می‌تواند فهرست گزینه‌های ارسال را براساس منطقه نشانی ارسال کالا تغییر دهد (برای مثال، ارسال بین‌المللی عادی یا سریع).
- فروشنده می‌تواند هزینه ارسال جدید را براساس نشانی اعمال کند و قیمت کل را به‌روز کند.
با Web-based 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);
…
Key-term: Redacted address. در این مورد، اطلاع دادن نشانی کامل ارسال کالا به فروشنده ضروری نیست و حریم خصوصی مشتریان را به‌خطر می‌اندازد. فروشنده فقط بخش‌هایی از نشانی را دریافت می‌کند که برای تعیین هزینه ارسال لازم است. به‌طور مشخص، مرورگر فیلدهای organization، phone، recipient، addressLine را از نشانی ارائه‌شده توسط برنامه پرداخت پاک می‌کند و سپس رویداد shippingaddresschange را در DOM فروشنده ایجاد می‌کند.
فروشنده رویداد shippingaddresschange را از Payment Request API دریافت می‌کند تا بتواند با PaymentDetailsUpdate به‌روزشده پاسخ دهد.
[merchant]
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);
});
وقتی فروشنده پاسخ می‌دهد، promise
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;
…
از این شیء برای به‌روزرسانی میانای کاربری در بخش کاربری استفاده کنید. نمایش جزئیات پرداخت به‌روزشده را ببینید.
اطلاع دادن به فروشنده درباره تغییر گزینه ارسال کالا
گزینه‌های ارسال روش‌های تحویلی هستند که فروشندگان برای ارسال اقلام خریداری‌شده به مشتری استفاده می‌کنند. گزینه‌های ارسال کالا معمولاً شامل موارد زیر است:
- ارسال رایگان
- ارسال سریع
- ارسال بین‌المللی
- ارسال بین‌المللی Premium
هرکدام هزینه خودش را دارد. معمولاً روش‌ها و گزینه‌های سریع‌تر گران‌تر هستند.
فروشندگانی که از Payment Request API استفاده می‌کنند می‌توانند این انتخاب را به برنامه پرداخت واگذار کنند. برنامه پرداخت می‌تواند از این اطلاعات برای ساختن واسط کاربر استفاده کند و به مشتری اجازه دهد گزینه ارسال را انتخاب کند.
فهرست گزینه‌های ارسال مشخص‌شده در Payment Request API فروشنده به‌عنوان ویژگی PaymentRequestEvent به سرویس‌کار برنامه پرداخت منتشر می‌شود.
[merchant]
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 را از Payment
Request API دریافت خواهد کرد. فروشنده باید از این اطلاعات برای به‌روزرسانی قیمت کل استفاده کند
و سپس با
PaymentDetailsUpdate به‌روزشده پاسخ دهد.
[merchant]
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 مشترک حل‌وفصل می‌شود. گرداننده پرداخت می‌تواند از نتیجه برای منعکس کردن قیمت کل به‌روزشده
و گزینه‌های ارسال در واسط کاربر استفاده کند.
فروشندگان ممکن است به چند دلیل خطا برگردانند:
- روش پرداخت قابل‌قبول نیست.
- نشانی ارسال کالا خارج از مناطق پشتیبانی‌شده آن‌ها است.
- نشانی ارسال کالا حاوی اطلاعات نامعتبر است.
- گزینه ارسال برای نشانی ارسال ارائه‌شده یا به دلیل دیگری قابل‌انتخاب نیست.
از ویژگی‌های زیر برای نشان دادن وضعیت خطا استفاده کنید:
error: رشته خطای قابل‌خواندن برای انسان. این بهترین رشته برای نمایش به مشتریان است.-
shippingAddressErrors:AddressErrorsشیئی که حاوی رشته خطای دقیق برای هر ویژگی نشانی است. این کار زمانی مفید است که می‌خواهید فرمی را باز کنید که به مشتری اجازه می‌دهد نشانی‌اش را ویرایش کند و لازم است او را مستقیماً به فیلدهای نامعتبر هدایت کنید. paymentMethodErrors: شیء خطای مختص روش پرداخت. می‌توانید از فروشندگان بخواهید خطای ساختاریافته ارائه دهند، اما نویسندگان مشخصات Web Payments توصیه می‌کنند که آن را به‌صورت رشته‌ای ساده نگه دارید.