@signd/checkout-button NPM

Install

npm install @signd/checkout-button

Docs

Documentation is generated in ./docs directory

You should follow

  mkdir signd-checkout-button
  git clone git@bitbucket.org:amsdard/signd-checkout-button.git ./signd-checkout-button
  cd ./signd-checkout-button
  npm install
  npm run build
  # install any http server
  npm i -g http-server-spa
  http-server-spa docs index.html 3333

then you can visit http://localhost:3333

Demo

  mkdir signd-checkout-button
  git clone git@bitbucket.org:amsdard/signd-checkout-button.git ./signd-checkout-button
  cd ./signd-checkout-button
  npm install
  npm run build
  cd ./demo
  npm install
  npm run install:self
  # Populate signd-checkout-button/demo/.env
  npm start

Usage

Import signd-checkout-button element

import '@signd/checkout-button';

// if you need typings then
import {CheckoutButtonElement} from '@signd/checkout-button';

Add HTML markup

Attributes <signd-checkout-buttion />

sid (signd-id): must be uniq and valid HTML selector, used to find element on page is also included in signd-* events detail
web-sdk-url - URL to SignD WEB SDK
close-modal-button-name (optional) - button name to close modal with SIGND WEB SDK

<signd-checkout-button
  sid="YOR_UNIQ_TRANSACTION_ID"
  web-sdk-url={process.env.REACT_APP_SIGND_WEB_SDK_URL as string}
  close-modal-button-name="Abort process"
>
</signd-checkout-button>

Add button HTML markup. You are responsible for creating HTML markup that will be rendered as the checkout button. It can be one or more buttons or even other UI control.

<signd-checkout-button
  sid="YOR_UNIQ_TRANSACTION_ID"
  web-sdk-url={process.env.REACT_APP_SIGND_WEB_SDK_URL as string}
>
  <Button variant="outlined" onClick={onCustomButtonCheckoutHandler}>Checkout</Button>
</signd-checkout-button>

More advance HTML markup

<signd-checkout-button
  sid="YOR_UNIQ_TRANSACTION_ID"
  web-sdk-url={process.env.REACT_APP_SIGND_WEB_SDK_URL as string}
>
  <Button onClick="handleAddToCart">+</Button>
  <Button onClick="handleRemoveFromCart">-</Button>
  <Button variant="outlined" onClick={onCustomButtonCheckoutHandler}>Buy $1</Button>
</signd-checkout-button>

Add Checkout button handler

You are also responsible for adding handler to checkout button. Handler should do 2 things:

generate session token
assign obtained token to checkout button

import {onCheckoutHandlerBySid} from '@signd/checkout-button';

const createSession = async (payload: HandshakeAttributesPayload): Promise<string> => {
  // call your backend to crate session token
  const {token, uuid} = await fetch('YOUR_BACKEND_API_URL_TO_CREATE_SESSION');

  return token;
};

// type GenerateToken = (sid: string) => Promise<string>;
const generateToken: GenerateToken = (sid: string): Promsie<string> => {
  // prepare payload
  return createSesson(payload);
};

const onCustomButtonCheckoutHandler = () => onCheckoutHandlerBySid('YOR_UNIQ_TRANSACTION_ID', generateToken);

Above snippet is using utility function onCheckoutHandlerBySid witch just take 2 parameters:

sid - used to find target checkout button where generated token has to be assigned
callback function (sid: string) => Promise<string> that do request to crate token and return it.

Then function just search for <signd-checkout-button /> by sid and assign token to it.

const signdCheckoutButton: CheckoutButtonElement = findButtonBySid(sid);
signdCheckoutButton.token = token;

Once token is provided then modal with SIGND WEB SDK loaded via iframe will pop up.

Event handlers

You should add listeners on each <signd-checkout-button>

signd-auth-success - provided token is authenticated
signd-auth-failed - provided token couldn't be authenticated
signd-verification-done - payment process has been done successfully - you can wait for web_hook event
signd-verification-failed - verification process has failed, user terminate process
signd-verification-aborted - verification process has been aborted, user close modal

Each event is type of CustomEvent<SigndEventData>

where

export type SigndEventData = {
  sid: string;
};

To register event for single button you can use registerListenersBySid utility function.

import {registerListenersBySid, registerListeners} from '@signd/checkout-button';

registerListenersBySid('YOR_UNIQ_TRANSACTION_ID', {
  onDone: (e: CustomEvent<SigndEventData>) => console.log(`Process done for sid ${e.detail.sid}`),
  onFailed: (e: CustomEvent<SigndEventData>) => console.log(`Process failed for sid ${e.detail.sid}`),
  onAborted: (e: CustomEvent<SigndEventData>) => console.log(`Process aborted for sid ${e.detail.sid}`),
  onAuthSuccess: (e: CustomEvent<SigndEventData>) => console.log(`Auth success sid ${e.detail.sid}`),
  onAuthFailed: (e: CustomEvent<SigndEventData>) => console.log(`Auth failed sid ${e.detail.sid}`),
});

Note! If You have more than one checkout button then you have to register events on ech button by this function registerListenersBySid

or register listeners once on global object window

You can obtain handle from event e.detail.sid which is uniq id previously defined on each <signd-checkout-button> elements

registerListeners(window, {
  onDone: (e: CustomEvent<SigndEventData>) => console.log(`Process done for sid ${e.detail.sid}`),
  onFailed: (e: CustomEvent<SigndEventData>) => console.log(`Process failed for sid ${e.detail.sid}`),
  onAborted: (e: CustomEvent<SigndEventData>) => console.log(`Process aborted for sid ${e.detail.sid}`),
  onAuthSuccess: (e: CustomEvent<SigndEventData>) => console.log(`Auth success sid ${e.detail.sid}`),
  onAuthFailed: (e: CustomEvent<SigndEventData>) => console.log(`Auth failed sid ${e.detail.sid}`),
});

API

You will use 1 endpoint and 1 web_hook complete payment process. There is also one additional endpoint that allow you to fetch result output manually.

API SETUP

Provide WEB_HOOK URL
Provide default recipientIBAN and recipientHolderName

API Endpoints / WEB_HOOK

POST /SIGND_API_URL/internal/handshake
GET /results/result-output
POST WEB_HOOK_URL to push result-output

Generate session token

POST /SIGND_API_URL/internal/handshake

When user click checkout button then you should have collected all dynamic data for payment process and this is time to create session with required session attributes

Attributes

export type HandshakeAttributesPayload = {
  currency: 'EUR';
  orderID: string; // your handle
  purpose: string;
  amount: number; // must be in cents multiply by 100, 2.34 EUR should be 234
  recipientIBAN?: string; // is optional and override default one
  recipientHolderName?: string; // is optional and override default one
};

Request

You should use provided by SignD credentials login, token and prepared attributes

export type HandshakePayload = {
  login: string;
  token: string;
  attributes: HandshakeAttributesPayload;
};

Response

export type HandshakeResponse = {
  token: string;
  uuid: string;
};

400 - attributes are not valid
401 - give login, token not authenticated
201 - crated

Result Output

WEB_HOOK

Result output pushed to provided URL

GET /results/result-output

Headers

Authorization: Bearer ${token}

token - for authorization should be used token for session

Response

401 - Not authorized
404 - Process is not done
200 - OK

The same result what is pushed to the WEB_HOOK

UI Customization

You can customize what will be shown when checkout button in different state

done - button state when process done
failed - button state when process failed

<signd-checkout-button
  sid="YOR_UNIQ_TRANSACTION_ID"
  web-sdk-url={process.env.REACT_APP_SIGND_WEB_SDK_URL as string}
>
  <p slot="done">You done! We will send detail on your email address</p>
  <p slot="failed">
    Transaction failed <a>retry</a> or <a>go back to store</a>
  </p>
  <Button variant="outlined" onClick={onCustomButtonCheckoutHandler}>Buy $1</Button>
</signd-checkout-button>

Loading WebComponents polyfills

This library is build on top of LitElement and use the Web Components set of standards which are supported by all major browsers. For compatibility with older browsers, load the Web Components polyfills.

<head>
  <!-- Load the polyfills first -->
  <script src="https://unpkg.com/@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>
  <!-- Then afterwards, load components -->
  <script type="module" src="SIGND_CHECKOUT_BUTTON.js"></script>
</head>
<bod>
  <signd-checkout-button></signd-checkout-button>
</bod>

You can also load polyfills asynchronously

<script defer src="https://unpkg.com/@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>

<script type="module">
  window.WebComponents = window.WebComponents || { 
    waitFor(cb){ addEventListener('WebComponentsReady', cb) }
  }

  WebComponents.waitFor(async () => { 
    import('SIGND_CHECKOUT_BUTTON.js');
  });
</script>
<bod>
  <signd-checkout-button></signd-checkout-button>
</bod>