digitalbazaar/payment-handler-polyfill

Name: payment-handler-polyfill

Owner: Digital Bazaar, Inc.

Description: A polyfill for the Payment Handler API

Created: 2017-07-31 17:28:52.0

Updated: 2017-12-08 03:44:27.0

Pushed: 2017-10-25 00:21:24.0

Homepage: null

Size: 35

Language: JavaScript

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

payment-handler-polyfill

A polyfill for the Payment Handler API

API Differences with Payment Handler API

TODO: introduction of PaymentHandlers global with API:

• register(url) - registers a payment handler identified by url that will be loaded when a related payment instrument is selected by the user… as opposed to registering a service worker. Result is a Promise that resolves to a PaymentHandlerRegistration instance with a paymentManager API (just like a service worker registration). This can be used to register payment instruments via paymentManager.paymentInstruments using the same API as the official spec.
• unregister(url) - unregisters a payment handler and removes any stored payment instruments.

TODO: PaymentRequest API is the same, but some important notes:

There are three scenarios that this polyfill considers (and changes its behavior accordingly):

1. A browser that has implemented both PaymentRequest and PaymentHandler.
2. A browser that has implemented PaymentRequest but not PaymentHandler.
3. A browser that has not implemented PaymentRequest or PaymentHandler.

Under scenario 1, this polyfill will not expose or override any existing native APIs.

Under scenario 2, this polyfill will expose the PaymentHandlers polyfill API but will only override PaymentRequest if one ore more PaymentInstruments have been registered via the polyfill. Otherwise the native PaymentRequest API will be used.

Under scenario 3, this polyfill will expose PaymentHandlers and its own version of PaymentRequest.

Loading the polyfill

Usage:

rt * as polyfill from 'payment-handler-polyfill';

EDIATOR_ORIGIN is expected to default to 'https://web-payments.io' in
he future
t polyfill.loadOnce(
DIATOR_ORIGIN + '/mediator?origin=' +
codeURIComponent(window.location.origin));

Registering a Payment Handler

Usage:

c function install() {
 request permission to install a payment handler
nst result = await PaymentManager.requestPermission();
(result !== 'granted') {
throw new Error('Permission denied.');
return;


 get payment handler registration
nst registration = await PaymentHandlers.register('/payment-handler');

ait addInstruments(registration);


c function addInstruments(registration) {
turn Promise.all([
registration.paymentManager.instruments.set(
  // this could be a UUID -- any 'key' understood by this payment handler
  'default',
  {
    name: 'Visa *1234',
    icons: [{
      src: '/images/new_visa.gif',
      sizes: '40x40',
      type: 'image/gif'
    }],
    enabledMethods: ['basic-card'],
    capabilities: {
      supportedNetworks: ['visa'],
      supportedTypes: ['credit', 'debit', 'prepaid']
    }
  })
]);

Requesting Payment

c function pay() {
y {
// request payment by credit card for $1 USD
const pr = new PaymentRequest([{
  supportedMethods: ['basic-card']
}], {
  total: {
    label: 'Total',
    amount: {currency: 'USD', value: '1.00'}
  }
});
const response = await pr.show();
console.log('payment response', response);
catch(e) {
console.error(e);

Handling a Payment Request in the Payment Handler

This code must run when the browser requests the URL registered as a payment handler (e.g. '/credential-handler'). It is similar to running a Service Worker but will work in browsers that have no implemented the Service Worker specification.

Usage:

t handler = new PaymentHandler(MEDIATOR_ORIGIN);

ler.addEventListener('paymentrequest', event => {
ent.respondWith(new Promise(async (resolve, reject) => {
let windowClient;

window.addEventListener('message', e => {
  // ignore messages we don't care about
  if(!(e.source === windowClient &&
    e.origin === window.location.origin)) {
    return;
  }

  // wait for 'request' message from the window we opened requesting the
  // payment request details
  if(e.data.type === 'request') {
    // send the window we opened the payment request details
    return windowClient.postMessage({
      topLevelOrigin: event.topLevelOrigin,
      methodData: event.methodData,
      total: event.total,
      instrumentKey: event.instrumentKey
    }, window.location.origin);
  }

  if(e.data.type === 'response') {
    // we've received the payment response from the window we opened,
    // send it back to the browser, we're done!
    resolve(e.data.response);
  }
});

// open a window to show a UI to handle the payment request; it will
// send us a message requesting the payment request details when it's ready
windowClient = await event.openWindow('/paymentrequest');
);