PaymentRequest: метод show()

Метод show() интерфейса PaymentRequest инструктирует пользовательский агент начать процесс отображения и обработки пользовательского интерфейса для запроса платежа пользователем.

Только один запрос платежа может обрабатываться одновременно во всех документах. После вызова метода show() для одного PaymentRequest, любой другой вызов show() будет отклонен с AbortError, пока возвращённое промис не завершит свою работу, либо успешно, с PaymentResponse, показывающим результаты запроса платежа, или же неуспешно, с ошибкой.

Если ваша архитектура не имеет всех данных в момент создания интерфейса платежа вызовом show(), укажите параметр detailsPromise, предоставив Promise, который выполнится, когда данные будут готовы. Если это предоставлено, show() не позволит пользователю взаимодействовать с интерфейсом платежа до выполнения промиса, так что данные могут быть обновлены перед взаимодействием пользователя с процессом платежа.

Обработка результата и, при необходимости, вызов PaymentResponse.retry() для повторной попытки неудачного платежа могут быть выполнены асинхронно или синхронно, в зависимости от ваших потребностей. Для наилучшего пользовательского опыта, асинхронные решения обычно являются лучшим вариантом. Большинство примеров на MDN и других ресурсах используют async/await для асинхронного ожидания, пока результаты не будут проверены и т. д.

details Необязательно

Либо объект, либо Promise, который разрешается в объект. Предоставьте это, если ваша архитектура требует, чтобы детали запроса платежа были обновлены между созданием интерфейса платежа и началом взаимодействия пользователя с ним. Объект должен содержать обновлённую информацию:

displayItems Необязательно

Массив объектов, каждый из которых описывает один элемент строки для запроса платежа. Эти элементы представляют строки на чеке или счете, каждый с такими свойствами:

amount

Объект, описывающий денежную стоимость элемента. Этот объект включает следующие поля:

currency

Строка, содержащая допустимый 3-буквенный идентификатор валюты ISO 4217 (ISO 4217), указывающий валюту, используемую для платежа value.

value

Строка, содержащая допустимое десятичное значение, представляющее сумму валюты, составляющую сумму платежа. Эта строка должна содержать необязательный ведущий символ "-" для указания отрицательного значения, затем одну или несколько цифр от 0 до 9 и необязательную десятичную точку (".", независимо от языка) и ещё хотя бы одну цифру. Пробелы не допускаются.

label

Строка, определяющая удобочитаемое имя или описание элемента или услуги, за которые взимается плата. Пользовательский агент может отобразить эту информацию в зависимости от дизайна интерфейса.

pending

Булево значение, которое является true, если указанная amount ещё не завершена. Это можно использовать для отображения таких элементов, как стоимость доставки или налогов, которые зависят от выбора адреса доставки, варианта доставки и так далее. Пользовательский агент может отобразить эту информацию, но не обязан это делать.

error Необязательно Устарело Нестандартный

Строка, определяющая сообщение об ошибке, которое следует отобразить пользователю. При вызове updateWith(), включение error в обновлённые данные заставляет пользовательский агент отобразить текст как общее сообщение об ошибке. Для ошибок, связанных с полями адреса, используйте поле shippingAddressErrors.

modifiers Необязательно

Массив объектов, каждый из которых описывает модификатор для определённых идентификаторов методов платежа, каждый с такими свойствами:

supportedMethods

Строка, представляющая идентификатор метода платежа. Идентификатор метода платежа применим только если пользователь выбирает этот метод платежа.

total Необязательно

Объект, который перезаписывает свойство total параметра detailsPromise, если пользователь выбирает этот метод платежа. Свойство принимает те же данные, что и свойство total параметра detailsPromise.

additionalDisplayItems Необязательно

Массив объектов, которые добавляют дополнительные элементы отображения, добавляемые к свойству displayItems параметра detailsPromise, если пользователь выбирает этот метод платежа. Это свойство обычно используется для добавления строки скидки или надбавки, указывающей причину изменения общей суммы для выбранного пользователем метода платежа, которое может отобразить пользовательский агент. Свойство принимает те же данные, что и свойство displayItems параметра detailsPromise.

data Необязательно

Сериализуемый объект, который предоставляет дополнительную информацию, которая может потребоваться поддерживаемым методам платежа.

Например, вы можете использовать его для корректировки общей суммы платежа в зависимости от выбранного метода платежа ("скидка 5% за наличный расчёт!").

shippingAddressErrors Необязательно Устарело Нестандартный

Объект, который включает сообщение об ошибке для каждого свойства адреса доставки, который не удалось проверить.

shippingOptions Необязательно Устарело Нестандартный

Массив объектов, каждый из которых описывает один доступный вариант доставки, из которого пользователь может выбрать.

total Необязательно

Объект с теми же свойствами, что и объекты в displayItems, предоставляющий обновлённую общую сумму платежа. Убедитесь, что это равно сумме всех элементов в displayItems. Это не вычисляется автоматически. Вы должны обновить это значение всякий раз, когда общая сумма к оплате изменяется. Это даёт вам гибкость в том, как обрабатывать такие вещи, как налоги, скидки и другие корректировки к общей стоимости.

A Promise, который в конечном итоге разрешается с PaymentResponse. Промис разрешается, когда пользователь принимает запрос на оплату (например, нажав кнопку «Оплатить» в платежном окне браузера).

Исключения не генерируются, а возвращаются, когда Promise отклоняется.

AbortError DOMException

Возвращается, если пользовательский агент уже отображает панель оплаты. Одновременно может быть видна только одна панель оплаты во всех документах, загруженных пользовательским агентом.

Обещание также отклоняется с AbortError если пользователь отменяет запрос на оплату.

InvalidStateError DOMException

Возвращается, если та же оплата уже была отображена для этого запроса (ее состояние interactive потому что она уже отображается).

NotSupportedError DOMException

Возвращается, если пользовательский агент не поддерживает методы оплаты, указанные при вызове конструктора PaymentRequest.

SecurityError DOMException

Возвращается, если вызов show() не был вызван в ответ на действие пользователя, например, событие click или keyup. Другие причины, по которым может быть сгенерировано SecurityError , зависят от пользовательского агента и могут включать такие ситуации, как слишком много вызовов show() в короткий промежуток времени или вызов show() , когда запросы на оплату заблокированы родительским контролем.

Временная активация пользователя требуется. Пользователь должен взаимодействовать со страницей или элементом пользовательского интерфейса, для того чтобы эта функция работала.

Наиболее распространенные схемы использования show() включают синтаксис async/await или использование show().then().catch() для обработки ответа и возможного отклонения. Они выглядят так:

Использование await для ожидания разрешения обещания позволяет написать код для обработки платежей особенно чисто:

async function processPayment() {
  try {
    const payRequest = new PaymentRequest(methodData, details, options);

    payRequest.onshippingaddresschange = (ev) =>
      ev.updateWith(checkAddress(payRequest));
    payRequest.onshippingoptionchange = (ev) =>
      ev.updateWith(checkShipping(payRequest));

    const response = await payRequest.show();
    await validateResponse(response);
  } catch (err) {
    /* handle the error; AbortError usually means a user cancellation */
  }
}

В этом коде методы checkAddress() и checkShipping(), соответственно, проверяют адрес доставки и изменения вариантов доставки и в ответ предоставляют либо объект, либо обещание вернуть объект; этот объект содержит поля в PaymentResponse, которые были изменены или должны быть изменены.

Метод validateResponse() ниже вызывается после того, как show() возвращает результат, для того чтобы просмотреть возвращенное значение response и либо подтвердить платеж, либо отклонить его как проваленный:

async function validateResponse(response) {
  try {
    if (await checkAllValues(response)) {
      await response.complete("success");
    } else {
      await response.complete("fail");
    }
  } catch (err) {
    await response.complete("fail");
  }
}

Здесь пользовательская функция checkAllValues() проверяет каждое значение в response и гарантирует, что они являются допустимыми, возвращая true если все поля допустимы или false если некоторые из них не являются таковыми. Если и только если все поля допустимы, вызывается метод complete() ответа со строкой "success", которая указывает, что все правильно и платеж может быть завершен соответственно.

Если какие-либо поля имеют недопустимые значения или если в предыдущем коде было сгенерировано исключение, вызывается complete() со строкой "fail", которая указывает, что процесс оплаты завершен и потерпел неудачу.

Вместо немедленного отказа можно вызвать retry() в объекте ответа, чтобы попросить пользовательский агент повторно обработать платеж; это следует делать только после того, как пользователь внес необходимые исправления в заказ.

В конечном итоге запустить процесс оплаты так же просто, как вызвать метод processPayment().

Вы также можете использовать более старый подход на основе обещаний, используя функции then() и catch() для обещания, возвращенного show():

function processPayment() {
  const payRequest = new PaymentRequest(methodData, details, options);

  payRequest.onshippingaddresschange = (ev) =>
    ev.updateWith(checkAddress(payRequest));
  payRequest.onshippingoptionchange = (ev) =>
    ev.updateWith(checkShipping(payRequest));

  payRequest
    .show()
    .then((response) => validateResponse(response))
    .catch((err) => handleError(err));
}

Это функционально эквивалентно методу processPayment() с использованием синтаксиса await.

function validateResponse(response) {
  checkAllValues(response)
    .then((response) => response.complete("success"))
    .catch((response) => response.complete("fail"));
}

Вы даже можете иметь checkAllValues() как синхронную функцию, хотя это может иметь негативное влияние на производительность:

function validateResponse(response) {
  if (checkAllValues(response)) {
    response.complete("success");
  } else {
    response.complete("fail");
  }
}

Смотрите статью Использование обещаний для получения дополнительной информации, если вам это нужно.

В приведенном ниже примере объект PaymentRequest создается до вызова метода show(). Этот метод запускает встроенный процесс пользовательского агента для получения информации об оплате от пользователя. Метод show() возвращает Promise, который разрешается в объект PaymentResponse, когда взаимодействие пользователя завершено. Затем разработчик использует информацию в объекте PaymentResponse для форматирования и отправки данных о платеже на сервер. Вы должны отправлять информацию о платеже на сервер асинхронно, чтобы заключительный вызов paymentResponse.complete() мог указать успех или неудачу платежа.

button.onclick = async function handlePurchase() {
  // Initialization of PaymentRequest arguments are excerpted for the sake of
  // brevity.
  const payment = new PaymentRequest(methods, details, options);
  try {
    const response = await payment.show();
    // Process response here, including sending payment instrument
    // (e.g., credit card) information to the server.
    // paymentResponse.methodName contains the selected payment method
    // paymentResponse.details contains a payment method specific response
    await response.complete("success");
  } catch (err) {
    console.error("Uh oh, something bad happened", err.message);
  }
};

В следующем примере показано, как обновлять лист оплаты по мере его отображения конечному пользователю.

async function requestPayment() {
  // We start with AU$0 as the total.
  const initialDetails = {
    total: {
      label: "Total",
      amount: { value: "0", currency: "AUD" },
    },
  };
  const request = new PaymentRequest(methods, initialDetails, options);
  // Check if the user supports the `methods`
  if (!(await request.canMakePayment())) {
    return; // no, so use a web form instead.
  }
  // Let's update the total as the sheet is shown
  const updatedDetails = {
    total: {
      label: "Total",
      amount: { value: "20", currency: "AUD" },
    },
  };
  const response = await request.show(updatedDetails);
  // Check response, etc.
}

document.getElementById("buyButton").onclick = requestPayment;

• API запроса на оплату
• Использование API запроса на оплату
• PaymentRequest.abort()
• PaymentResponse
• PaymentResponse.retry()
• PaymentResponse.complete()