API обработчика платежей

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

Когда веб-сайт продавца инициирует платеж через API запроса платежа, API обработчика платежей обнаруживает применимые платежные приложения, представляет их пользователю в качестве вариантов, открывает окно обработчика платежей после выбора пользователем, чтобы пользователь мог ввести данные платежа, и обрабатывает платежную транзакцию с помощью платежного приложения.

Взаимодействие с платежными приложениями (авторизация, передача данных платежа) осуществляется через Service Workers.

На веб-сайте продавца запрос платежа инициируется созданием нового объекта PaymentRequest:

const request = new PaymentRequest(
  [
    {
      supportedMethods: "https://bobbucks.dev/pay",
    },
  ],
  {
    total: {
      label: "total",
      amount: { value: "10", currency: "USD" },
    },
  },
);

Свойство supportedMethods задает URL, представляющий способ оплаты, поддерживаемый продавцом. Чтобы использовать более одного способа оплаты, необходимо указать их в массиве объектов, например:

const request = new PaymentRequest(
  [
    {
      supportedMethods: "https://alicebucks.dev/pay",
    },
    {
      supportedMethods: "https://bobbucks.dev/pay",
    },
  ],
  {
    total: {
      label: "total",
      amount: { value: "10", currency: "USD" },
    },
  },
);

В поддерживающих браузерах процесс начинается с запроса файла манифеста способа оплаты с каждого URL. Файл манифеста способа оплаты обычно называется чем-то вроде payment-manifest.json (точное название может быть любым), и должен быть структурирован следующим образом:

{
  "default_applications": ["https://bobbucks.dev/manifest.json"],
  "supported_origins": ["https://alicepay.friendsofalice.example"]
}

Учитывая идентификатор способа оплаты, например, https://bobbucks.dev/pay, браузер:

1. Начинает загрузку https://bobbucks.dev/pay и проверяет его HTTP-заголовки.
   1. Если найден заголовок Link со значением rel="payment-method-manifest", то вместо этого загружает манифест способа оплаты по этому адресу (см. Дополнительные способы направить браузер к поиску манифеста способа оплаты в другом месте для получения подробностей).
   2. В противном случае, разбирает содержимое ответа https://bobbucks.dev/pay как манифест способа оплаты.
2. Разбирает загруженное содержимое как JSON с элементами default_applications и supported_origins.

Эти элементы служат для следующих целей:

• default_applications сообщает браузеру, где найти приложение для обработки платежей по умолчанию, которое может использовать способ оплаты «BobBucks», если оно еще не установлено.
• supported_origins сообщает браузеру, какие другие платежные приложения разрешено использовать для обработки платежей «BobBucks», если это необходимо. Если они уже установлены на устройстве, они будут представлены пользователю как альтернативные варианты оплаты вместе с приложением по умолчанию.

Из манифеста способа оплаты браузер получает URL-адреса файлов манифеста веб-приложений приложений по умолчанию, которые могут называться как угодно и выглядеть примерно так:

{
  "name": "Pay with BobBucks",
  "short_name": "BobBucks",
  "description": "This is an example of the Payment Handler API.",
  "icons": [
    {
      "src": "images/manifest/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "images/manifest/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ],
  "serviceworker": {
    "src": "service-worker.js",
    "scope": "/",
    "use_cache": false
  },
  "start_url": "/",
  "display": "standalone",
  "theme_color": "#3f51b5",
  "background_color": "#3f51b5",
  "related_applications": [
    {
      "platform": "play",
      "id": "com.example.android.samplepay",
      "min_version": "1",
      "fingerprints": [
        {
          "type": "sha256_cert",
          "value": "4C:FC:14:C6:97:DE:66:4E:66:97:50:C0:24:CE:5F:27:00:92:EE:F3:7F:18:B3:DA:77:66:84:CD:9D:E9:D2:CB"
        }
      ]
    }
  ]
}

Когда метод PaymentRequest.show() вызывается приложением продавца в ответ на действие пользователя, браузер использует информацию name и icons, найденную в каждом манифесте, чтобы представить платежные приложения пользователю в пользовательском интерфейсе Payment Request, предоставляемом браузером.

• Если доступно несколько вариантов платежных приложений, пользователю будет представлен список вариантов для выбора. Выбор платежного приложения запустит процесс платежа, что заставит браузер выполнить установку веб-приложения Just-In-Time (JIT), если это необходимо, зарегистрировав сервис-воркер, указанный в элементе serviceworker, чтобы он мог обработать платеж.
• Если доступен только один вариант платежного приложения, метод PaymentRequest.show() запустит процесс платежа с этим платежным приложением, выполнив JIT-установку, если это необходимо, как описано выше. Это оптимизация для того, чтобы избежать отображения пользователю списка, содержащего только один вариант платежного приложения.

См. Отображение манифеста веб-приложения для получения дополнительных сведений.

Метод PaymentRequest.canMakePayment() API запроса платежа возвращает true, если на устройстве клиента доступно платежное приложение, что означает, что обнаружено платежное приложение, поддерживающее способ оплаты, и что платформно-специфическое платежное приложение установлено или веб-приложение для обработки платежей готово к регистрации.

async function checkCanMakePayment() {
  // ...

  const canMakePayment = await request.canMakePayment();
  if (!canMakePayment) {
    // Fallback to other means of payment or hide the button.
  }
}

API обработчика платежей добавляет дополнительный механизм подготовки к обработке платежа. Событие canmakepayment генерируется в service worker платежного приложения для проверки готовности к обработке платежа. В частности, оно генерируется, когда веб-сайт продавца вызывает конструктор PaymentRequest(). Затем сервис-воркер может использовать метод CanMakePaymentEvent.respondWith() для соответствующей реакции:

self.addEventListener("canmakepayment", (e) => {
  e.respondWith(
    new Promise((resolve, reject) => {
      someAppSpecificLogic()
        .then((result) => {
          resolve(result);
        })
        .catch((error) => {
          reject(error);
        });
    }),
  );
});

Возвращаемое обещание respondWith() разрешается с булевым значением, сигнализирующим о готовности к обработке запроса на оплату (true), или о неготовности (false).

После вызова метода PaymentRequest.show() в сервис-воркере платежного приложения генерируется событие paymentrequest. Это событие отслеживается внутри сервис-воркера платежного приложения для начала следующего этапа процесса оплаты.

let payment_request_event;
let resolver;
let client;

// `self` is the global object in service worker
self.addEventListener("paymentrequest", async (e) => {
  if (payment_request_event) {
    // If there's an ongoing payment transaction, reject it.
    resolver.reject();
  }
  // Preserve the event for future use
  payment_request_event = e;

  // ...
});

При получении события paymentrequest, платежное приложение может открыть окно обработчика платежей, вызвав PaymentRequestEvent.openWindow(). Окно обработчика платежей предоставит клиентам интерфейс платежного приложения, где они могут пройти аутентификацию, выбрать адрес доставки и параметры и авторизовать платеж.

При обработке платежа используется PaymentRequestEvent.respondWith() для возврата результата платежа на веб-сайт продавца.

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

После регистрации сервис-воркера платежного приложения можно использовать экземпляр PaymentManager сервис-воркера (доступный через ServiceWorkerRegistration.paymentManager) для управления различными аспектами функциональности платежного приложения.

Например:

navigator.serviceWorker.register("serviceworker.js").then((registration) => {
  registration.paymentManager.userHint = "Card number should be 16 digits";

  registration.paymentManager
    .enableDelegations(["shippingAddress", "payerName"])
    .then(() => {
      // ...
    });

  // ...
});

• PaymentManager.userHint используется для предоставления подсказки для браузера, которая будет отображаться вместе с именем и иконкой платежного приложения в пользовательском интерфейсе Payment Handler.
• PaymentManager.enableDelegations() используется для делегирования ответственности за предоставление различных частей необходимой платежной информации платежному приложению вместо сбора ее браузером (например, через автозаполнение).

CanMakePaymentEvent

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

PaymentManager

Используется для управления различными аспектами функциональности приложения для оплаты. Доступно через свойство ServiceWorkerRegistration.paymentManager.

PaymentRequestEvent Experimental

Объект события для события paymentrequest, запускаемого в сервисном воркере приложения для оплаты, когда поток платежа был инициирован на сайте продавца с помощью метода PaymentRequest.show().

canmakepayment событие

Запускается в ServiceWorkerGlobalScope приложения для оплаты после успешной регистрации, чтобы сигнализировать о готовности к обработке платежей.

paymentrequest событие

Запускается в ServiceWorkerGlobalScope приложения для оплаты, когда поток платежа был инициирован на сайте продавца с помощью метода PaymentRequest.show().

ServiceWorkerRegistration.paymentManager

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

• Пример приложения для оплаты BobBucks
• Обзор веб-приложений для оплаты
• Настройка метода оплаты
• Жизненный цикл транзакции платежа
• Использование Payment Request API
• Концепции обработки платежей