Как адаптировать веб-версию платежного приложения к Web Payments и сделать его удобнее для пользователей.
После того как веб-версия платежного приложения получит запрос на оплату и инициирует платежную транзакцию, service worker будет выступать в качестве центра связи между продавцом и платежным приложением. В этой статье объясняется, как платежное приложение может передать продавцу информацию о способе оплаты, адресе доставки или контактную информацию с помощью service worker.
Сообщите продавцу
Важно сообщить продавцу о следующих изменениях.
Изменение способа оплаты
Платежные приложения могут поддерживать несколько платежных инструментов с разными способами оплаты.
| Клиент | Способ оплаты | Способ оплаты |
|---|---|---|
| A | Эмитент кредитных карт 1 | ****1234 |
| Эмитент кредитных карт 1 | ****4242 |
|
| Банк X | ******123 |
|
| B | Эмитент кредитной карты 2 | ****5678 |
| Банк X | ******456 |
Например, в таблице выше у клиента А в веб-версии кошелька зарегистрированы две кредитные карты и один банковский счет. В этом случае приложение обрабатывает три способа оплаты (****1234, ****4242, ******123) и два способа оплаты (эмитент кредитной карты 1 и банк X). При совершении платежной транзакции платежное приложение может позволить клиенту выбрать один из способов оплаты и использовать его для оплаты продавцу.
Платежное приложение может сообщить продавцу, какой способ оплаты выбрал клиент, прежде чем отправлять полный ответ на платеж. Это может быть полезно, например, если продавец хочет провести кампанию со скидками для определенного бренда способов оплаты.
С помощью веб-версии API Payment Handler платежное приложение может отправить продавцу событие "изменение способа оплаты" через service worker, чтобы сообщить новый идентификатор способа оплаты. Сервис-воркер должен вызвать 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);
});
Когда продавец ответит, объект Promise, возвращенный методом 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);
…
Ключевое понятие: отредактированный адрес. В этом случае сообщать продавцу полный адрес доставки не нужно, и это может нарушить конфиденциальность клиентов. Продавец получает только те части адреса, которые нужны для расчета стоимости доставки. В частности, браузер очистит поля 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;
…
Используйте объект, чтобы обновить интерфейс. Подробнее о том, как обновить платежные данные…
Сообщите продавцу об изменении способа доставки
Варианты доставки – это способы, которыми продавцы отправляют купленные товары клиентам. Типичные варианты доставки:
- Бесплатная доставка
- Экспресс-доставка
- условия международной доставки;
- Премиум-доставка за границу
У каждого из них своя цена. Обычно более быстрые способы и варианты стоят дороже.
Продавцы, использующие 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 });
});
Когда продавец ответит, объект Promise, возвращенный методом 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 рекомендуют использовать простую строку.