Spec-Zone.ru › Web APIs

Использование API Payment Request

Безопасный контекст: Эта функция доступна только в безопасных контекстах (HTTPS) в некоторых или во всех поддерживающих браузерах.

API Payment Request предоставляет основанный на браузере метод подключения пользователей и их предпочитаемых платформ для платежей к продавцам, которым они хотят оплатить товары и услуги. Эта статья — руководство по использованию API Payment Request с примерами и рекомендациями по лучшим практикам.

Основы совершения платежа

Этот раздел описывает основы использования API Payment Request для совершения платежа.

Примечание: Примеры кода из этого раздела взяты из нашей демо-версии проверки поддержки функции.

Создание нового объекта запроса платежа

Запрос платежа всегда начинается с создания нового объекта PaymentRequest — с использованием конструктора PaymentRequest(). Он принимает два обязательных параметра и один необязательный параметр:

  • methodData — объект, содержащий информацию о поставщике платежей, например, какие методы платежей поддерживаются и т. д.
  • details — объект, содержащий информацию о конкретном платеже, например, общую сумму платежа, налог, стоимость доставки и т. д.
  • options (необязательно) — объект, содержащий дополнительные параметры, связанные с платежом.

Например, вы можете создать новый экземпляр PaymentRequest следующим образом:

const request = new PaymentRequest(
  buildSupportedPaymentMethodData(),
  buildShoppingCartDetails(),
);

Функции, вызываемые внутри конструктора, возвращают необходимые параметры объекта:

function buildSupportedPaymentMethodData() {
  // Example supported payment methods:
  return [{ supportedMethods: "https://example.com/pay" }];
}

function buildShoppingCartDetails() {
  // Hardcoded for demo purposes:
  return {
    id: "order-123",
    displayItems: [
      {
        label: "Example item",
        amount: { currency: "USD", value: "1.00" },
      },
    ],
    total: {
      label: "Total",
      amount: { currency: "USD", value: "1.00" },
    },
  };
}

Запуск процесса платежа

После создания объекта PaymentRequest, вы вызываете метод PaymentRequest.show() для него, чтобы инициировать запрос платежа. Это возвращает промис, который выполняется с объектом PaymentResponse, если платеж успешен:

request.show().then((paymentResponse) => {
  // Here we would process the payment. For this demo, simulate immediate success:
  paymentResponse.complete("success").then(() => {
    // For demo purposes:
    introPanel.style.display = "none";
    successPanel.style.display = "block";
  });
});

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

Другие полезные методы запроса платежа

Есть и другие полезные методы запроса платежа, о которых стоит знать.

PaymentRequest.canMakePayment() можно использовать для проверки возможности объекта PaymentRequest совершить платеж перед началом процесса платежа. Он возвращает промис, который выполняется со значением boolean, указывающим, возможно ли это или нет, например:

// Dummy payment request to check whether payment can be made
new PaymentRequest(buildSupportedPaymentMethodData(), {
  total: { label: "Stub", amount: { currency: "USD", value: "0.01" } },
})
  .canMakePayment()
  .then((result) => {
    if (result) {
      // Real payment request
      const request = new PaymentRequest(
        buildSupportedPaymentMethodData(),
        checkoutObject,
      );
      request.show().then((paymentResponse) => {
        // Here we would process the payment.
        paymentResponse.complete("success").then(() => {
          // Finish handling payment
        });
      });
    }
  });

PaymentRequest.abort() можно использовать для прерывания запроса платежа, если это необходимо.

Обнаружение доступности API Payment Request

Вы можете эффективно обнаружить поддержку API Payment Request, проверив, поддерживает ли браузер пользователя PaymentRequest, т. е. if (window.PaymentRequest).

В следующем фрагменте код страницы магазина выполняет эту проверку и, если она возвращает true, обновляет кнопку оформления заказа, чтобы использовать PaymentRequest вместо устаревших веб-форм.

const checkoutButton = document.getElementById("checkout-button");
if (window.PaymentRequest) {
  let request = new PaymentRequest(
    buildSupportedPaymentMethodNames(),
    buildShoppingCartDetails(),
  );
  checkoutButton.addEventListener("click", () => {
    request
      .show()
      .then((paymentResponse) => {
        // Handle successful payment
      })
      .catch((error) => {
        // Handle cancelled or failed payment. For example, redirect to
        // the legacy web form checkout:
        window.location.href = "/legacy-web-form-checkout";
      });

    // Every click on the checkout button should use a new instance of
    // PaymentRequest object, because PaymentRequest.show() can be
    // called only once per instance.
    request = new PaymentRequest(
      buildSupportedPaymentMethodNames(),
      buildShoppingCartDetails(),
    );
  });
}

Примечание: Смотрите нашу демо-версию проверки поддержки функции для полного кода.

Проверка возможности пользователей совершать платежи

Проверка возможности пользователей совершать платежи всегда полезна. Вот несколько связанных техник.

Настройка кнопки платежа

Полезной техникой является настройка кнопки запроса платежа в зависимости от того, могут ли пользователи совершать платежи.

В следующем примере мы делаем именно это — в зависимости от того, может ли пользователь совершить быстрый платеж или ему необходимо добавить данные платежной информации, заголовок кнопки оформления заказа изменяется с «Быстрое оформление заказа с W3C» на «Настройка оформления заказа с W3C». В обоих случаях кнопка оформления заказа вызывает PaymentRequest.show().

const checkoutButton = document.getElementById("checkout-button");
checkoutButton.innerText = "Loading…";
if (window.PaymentRequest) {
  const request = new PaymentRequest(
    buildSupportedPaymentMethodNames(),
    buildShoppingCartDetails(),
  );
  request
    .canMakePayment()
    .then((canMakeAFastPayment) => {
      checkoutButton.textContent = canMakeAFastPayment
        ? "Fast Checkout with W3C"
        : "Setup W3C Checkout";
    })
    .catch((error) => {
      // The user may have turned off the querying functionality in their
      // privacy settings. The website does not know whether they can make
      // a fast payment, so pick a generic title.
      checkoutButton.textContent = "Checkout with W3C";
    });
}

Примечание: Смотрите нашу демо-версию настройки кнопки платежа для полного кода.

Проверка до получения всех цен

Если рабочий процесс оформления заказа должен знать, вернёт ли PaymentRequest.canMakePayment() значение true даже до того, как будут известны все позиции и их цены, вы можете инициализировать PaymentRequest с тестовыми данными и предварительно запросить .canMakePayment(). Если вы вызываете .canMakePayment() несколько раз, помните, что первый параметр конструктора PaymentRequest должен содержать те же имена методов и данные.

// The page has loaded. Should the page use PaymentRequest?
// If PaymentRequest fails, should the page fallback to manual
// web form checkout?
const supportedPaymentMethods = [
  /* supported methods */
];

let shouldCallPaymentRequest = true;
let fallbackToLegacyOnPaymentRequestFailure = false;
new PaymentRequest(supportedPaymentMethods, {
  total: { label: "Stub", amount: { currency: "USD", value: "0.01" } },
})
  .canMakePayment()
  .then((result) => {
    shouldCallPaymentRequest = result;
  })
  .catch((error) => {
    console.error(error);

    // The user may have turned off query ability in their privacy settings.
    // Let's use PaymentRequest by default and fallback to legacy
    // web form based checkout.
    shouldCallPaymentRequest = true;
    fallbackToLegacyOnPaymentRequestFailure = true;
  });

// User has clicked on the checkout button. We know
// what's in the cart, but we don't have a `Checkout` object.
function onCheckoutButtonClicked(lineItems) {
  callServerToRetrieveCheckoutDetails(lineItems);
}

// The server has constructed the `Checkout` object. Now we know
// all of the prices and shipping options.
function onServerCheckoutDetailsRetrieved(checkoutObject) {
  if (shouldCallPaymentRequest) {
    const request = new PaymentRequest(supportedPaymentMethods, checkoutObject);
    request
      .show()
      .then((paymentResponse) => {
        // Post the results to the server and call `paymentResponse.complete()`.
      })
      .catch((error) => {
        console.error(error);
        if (fallbackToLegacyOnPaymentRequestFailure) {
          window.location.href = "/legacy-web-form-checkout";
        } else {
          showCheckoutErrorToUser();
        }
      });
  } else {
    window.location.href = "/legacy-web-form-checkout";
  }
}

Примечание: Смотрите нашу демо-версию проверки возможности пользователя совершать платежи до получения цен для полного кода.

Рекомендация платежного приложения, если у пользователя нет приложений

Если вы выбираете оплатить с демо-платежным провайдером BobPay на этой странице продавца, он пытается вызвать PaymentRequest.show(), перехватывая NotSupportedError DOMException. Если этот способ оплаты не поддерживается, он перенаправляет пользователя на страницу регистрации BobPay.

Код выглядит примерно так:

checkoutButton.addEventListener("click", () => {
  const request = new PaymentRequest(
    buildSupportedPaymentMethodData(),
    buildShoppingCartDetails(),
  );
  request
    .show()
    .then((paymentResponse) => {
      // Here we would process the payment. For this demo, simulate immediate success:
      paymentResponse.complete("success").then(() => {
        // For demo purposes:
        introPanel.style.display = "none";
        successPanel.style.display = "block";
      });
    })
    .catch((error) => {
      if (error.name === "NotSupportedError") {
        window.location.href = "https://bobpay.xyz/#download";
      } else {
        // Other kinds of errors; cancelled or failed payment. For demo purposes:
        introPanel.style.display = "none";
        legacyPanel.style.display = "block";
      }
    });
});

Примечание: Смотрите нашу демо-версию рекомендации платежного приложения, если у пользователя нет приложений для полного кода.

Отображение дополнительного пользовательского интерфейса после успешных платежей

Если продавец хочет собрать дополнительную информацию, не являющуюся частью API (например, дополнительные инструкции по доставке), он может отобразить страницу с дополнительными <input type="text"> полями после оформления заказа.

request
  .show()
  .then((paymentResponse) => {
    // Process payment here.
    // Close the UI:
    paymentResponse.complete('success').then(() => {
      // Request additional shipping address details.
      const additionalDetailsContainer = document.getElementById('additional-details-container');
      additionalDetailsContainer.style.display = 'block';
      window.scrollTo(additionalDetailsContainer.getBoundingClientRect().x, 0);
  })
  .catch((error) => {
    // Handle error.
  });

Примечание: Смотрите нашу демо-версию отображения дополнительного пользовательского интерфейса после успешного платежа для полного кода.

Предварительное авторизация транзакций

Некоторые сценарии использования (например, оплата топлива на заправочной станции) предполагают предварительную авторизацию платежа. Один из способов сделать это — с помощью обработчика платежей (см. API обработчика платежей). На момент написания этой спецификации в обработчике платежей присутствует событие canmakepayment , которое обработчик платежей может использовать для возврата состояния авторизации.

Код продавца будет выглядеть так:

const paymentRequest = new PaymentRequest(
  [{ supportedMethods: "https://example.com/preauth" }],
  details,
);

// Send `CanMakePayment` event to the payment handler.
paymentRequest
  .canMakePayment()
  .then((res) => {
    if (res) {
      // The payment handler has pre-authorized a transaction
      // with some static amount, e.g., USD $1.00.
    } else {
      // Pre-authorization failed or payment handler not installed.
    }
  })
  .catch((err) => {
    // Unexpected error occurred.
  });

Обработчик платежей будет включать следующий код:

self.addEventListener("canmakepayment", (evt) => {
  // Pre-authorize here.
  const preAuthSuccess = true;
  evt.respondWith(preAuthSuccess);
});

Этот обработчик платежей должен находиться в рабочем потоке https://example.com/preauth scope.

Примечание: Смотрите нашу демо-версию предварительной авторизации транзакций для полного кода.

См. также

  • Примеры Google PaymentRequest

© 2005–2024 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/Payment_Request_API/Using_the_Payment_Request_API

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API