Nefarious Pomegranate Magnate

    @xcoobee/payment-sdk
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.5 • Public • Published

    XcooBee Contactless Payment SDK for JavaScript

    Description

    The XcooBee contactless payment system is a complete shopping cart and checkout system that can be included in your projects (mobile or web) quickly. In order to fully use this, you will need a XcooBee account ( Professional, Business, or Enterprise) and an active “Payment Project” created.

    The SDK simplifies the generation of URLs and QRs. Smart QRs and URLs can cover many different use cases.

    The URLs can be sent to remote users or embedded in a website to quickly add a shopping cart system with a few lines. Examples of this could be "Pay" buttons or "Add to Cart" links for merchandise that is sold on the site.

    The URLs can help you build a very simply shopping system that is focused on cart and checkout. Nothing else is needed.

    Touchless smart QRs can be used with users that are directly in vicinity of your app or to start a shopping/payment process from physical media like signs and printed materials. Examples of this would include restaurant menus, flyers, catalogs, books, invoices, statements, etc..

    Prerequisites

    You will need to setup a XcooBee Payment Request project in order to obtain test and or production campaign codes. You can setup a free XcooBee Professional Account for this purpose and generate test keys.

    During the XcooBee account setup you will also be able to select your payment processor or setup one if needed.

    Installation

    Node

    npm i @xcoobee/payment-sdk
    

    Web

    For simple use directly download the minified build from our CDN via script tag you can add async option. Placement in HTML header section before <body> tag.

    <script src="https://app.xcoobee.net/scripts/sdk/xcoobee-pay-sdk.min.js"></script>
    
    

    As an alternative you can build the browser yourself and distribute via your own webservers:

    npm i @xcoobee/payment-sdk
    

    Follow the install steps with the build step to create distribution for web if needed. For node projects this is not needed.

    npm run build
    

    Documentation

    The SDK life cycle is composed of standard class init via a constructor + configuration object followed by using the appropriate method to generate the type of pay URL or QR needed for your operation.

    Direct Check Out Methods

    The direct check out methods allow you to create a URL or QR for payment of one specific amount. It is like an overall total to be paid to you. When end-user interacts (scans QR or clicks URL) they will be asked to make payment for that amount and any existing items in the cart will be removed.

    Methods in this group are:

    • createPayQr
    • createPayQrWithTip
    • createPayUrl
    • createPayUrlWithTip

    Cart Methods

    Cart methods allow for your users to assemble items in a shopping cart. The overall total is determined by the number and quantity of items in the cart. You can create URL and QR that will add to the cart. So you are only adding a single item amount. When end-user interacts (scans QR or clicks URL) this item will be placed in the cart and the user can continue shopping/interacting with your system to add more items before completing a final checkout.

    Methods in this group are:

    • createMultiSelectQr
    • createMultiSelectUrl
    • createMultiSelectWithCostQr
    • createMultiSelectWithCostUrl
    • createSingleItemQr
    • createSingleItemUrl
    • createSingleSelectQr
    • createSingleSelectUrl
    • createSingleSelectWithCostQr
    • createSingleSelectWithCostUrl
    • createExternalReferenceQr
    • createExternalReferenceUrl

    Please see API documentation for full information on each of these methods.

    Usage

    Browser Example

    //1. import browser SDK
    import { BrowserXcooBeePaymentSDK } from "../../dist/browser/browser";
    
    //2. init constructor with config object. Use your campaign and form id from XcooBee Project
    const sdk = new BrowserXcooBeePaymentSDK({ campaignId: "test", formId: "test" });
    
    //3. start generating QR or URL using cart or checkout methods
    sdk.createPayQr({ amount: 123, reference: "Order" }, 300).then((qr) => {
      const img = document.createElement("img");
    
      img.src = qr;
    
      document.body.appendChild(img);
    });

    Node Example

    // 1. Require the XcooBee SDK library
    const { NodeXcooBeePaymentSDK } = require("@xcoobee/payment-sdk/dist/node/node");
    
    // 2. initialize your session with campaign and form ids from XcooBee Project
    const sdk = new NodeXcooBeePaymentSDK({ campaignId: "test", formId: "test" });
      
    // 3. generate and use 
    sdk
      .createPayQr({ amount: 123, reference: "Order" }, 100)
      .then((base64) => {
          //you can render a QR by adding base 64 to src of img tag
          console.log(base64); console.log(base64);        
      });

    Example App

    Roundtrip notification

    Since end-users are using their own devices to complete payment you will need to setup an endpoint that can accept notification via webhook post from XcooBee.

    This is also done in your XcooBee Payment Request Project UI.

    XcooBee will deliver the result of payment processing to that endpoint. We have full stack example that shows this process in detail in our github repo that you can review for implementation.

    If you are using mobile devices you should also consider providing a specific device id that is originating the payment request when initializing the SDK library. You do this by adding the deviceId parameter.

    const sdk = new NodeXcooBeePaymentSDK({ campaignId: "test", formId: "test", deviceId: "78hs7yajsdiydsifsd83u78yhisd78yf7dyud" });

    The payment processing information will also contain this device id and allow you push notifications to it using your normal channels.

    If you are in development mode, you can also use a polling mechanism where you check the XcooBee network for the processing results. Please see our event poller example for how this can be done as well as our example full stack app.

    Full API

    See the complete documentation for node and browser.

    Deployment

    npm run build
    

    Tests

    npm test
    

    or

    npm run coverage
    

    Alternative renderers

    You can replace the bundled QR code generator with your own renderer.

    To use without QR generator or to provide your own please use this link

    Keywords

    none

    Install

    npm i @xcoobee/payment-sdk

    DownloadsWeekly Downloads

    10

    Version

    1.0.5

    License

    Apache-2.0

    Unpacked Size

    220 kB

    Total Files

    38

    Last publish

    Collaborators

    • xcoobee-npm
    • dhurlburtusa
    • alex-melnyk