Installation

npm i @pcibooking/ewallet

Quick Start

Initialize the Engine

const engine = new eWallet.Engine(sessionToken, requiredAncillaryInfo, language, uiOptions);

| Parameter | Description | |-----------|-------------| | sessionToken | Required. Token obtained from the PCI Booking service | | requiredAncillaryInfo | Optional. Billing/shipping address requirements (applicable on most eWallets) | | language | Optional. Language code for UI localization. Supported languages: EN, ES, FR, DE, IT, PT, NL, PL, RU, JA, ZH, KO, AR, HE, TR, SV, NO, DA, FI, and more. | | uiOptions | Optional. Client-side UI options (see below) |

UI Options

The uiOptions object controls presentation of the library-rendered UI.

| Field | Type | Description | |-------|------|-------------| | hideLogo | boolean | When true, the merchant logo is not rendered at the top of the card-entry form. Defaults to false. | | displayMode | 'popup' or 'iframe' | How the CardPay card-entry form is presented. 'popup' (default) opens it in a separate, centered browser window. 'iframe' embeds it in an in-page iframe. | | iframeContainerSelector | string | Only used when displayMode is 'iframe'. CSS selector of the element that should host the iframe (e.g. '#card-form-host'). When provided, the iframe is embedded inline into that element. When omitted, the iframe is shown as a centered modal overlay on the page. |

const uiOptions = {
    hideLogo: true,
};
const engine = new eWallet.Engine(sessionToken, requiredAncillaryInfo, language, uiOptions);

CardPay form display mode

By default the CardPay card-entry form opens in a separate popup window. Set displayMode: 'iframe' to render it inside an in-page iframe instead:

// Centered modal overlay (no container selector)
const uiOptions = { displayMode: 'iframe' };

// Inline — embedded into an element you control
const uiOptions = { displayMode: 'iframe', iframeContainerSelector: '#card-form-host' };

const engine = new eWallet.Engine(sessionToken, requiredAncillaryInfo, language, uiOptions);

Note: displayMode applies to the CardPay form only. Other providers continue to use their standard flow.

Detect Available eWallets

const available = engine.checkAvailability();

Returns the list of eWallets available on the specific device and browser.

Start a Payment Session

engine.payBy(eWalletList, callback, buttonProperties, requiredAncillaryInfo, iframeStyleConfig);

Starts the payment process using the specified list of eWallet providers.

| Parameter | Description | |-----------|-------------| | eWalletList | Required. List of requested eWallet providers and their respective button properties | | callback | Required. Callback handler called when the payment operation completes | | buttonProperties | Optional. Button styling properties | | requiredAncillaryInfo | Optional. Per-call billing/shipping requirements (see below). When provided, overrides the value passed to the Engine constructor. Pass undefined when not used. | | iframeStyleConfig | Optional. Visual customization for the hosted CardPay forms (see below). |

CardPay form appearance customization

The iframeStyleConfig object re-skins the hosted CardPay forms (new card entry, CVV entry, and stored-card selection). It is applied to whichever presentation you chose via uiOptions.displayMode (popup or iframe), and every field is optional — anything you omit keeps its default styling.

const iframeStyleConfig = {
    // Named preset resolved server-side; explicit fields below override it
    themeName: 'midnight',

    // Semantic colors
    colorPalette: {
        primary:    '#6c2bd9', // accent: buttons, focus, caret
        background: '#ffffff', // form background
        text:       '#1a1a2e', // input + label text
        border:     '#d0d0e0', // input borders
        error:      '#d92b2b', // invalid fields + validation messages
        success:    '#1ea672', // completed/valid fields
    },

    // Field typography, per-state styling and chrome
    field: {
        typography: {
            fontFamily:    "'Roboto', sans-serif", // family name, or a web-font URL (e.g. a Google Fonts link)
            fontSize:      '15px',
            fontWeight:    '500',                   // '400' | '500' | '600' | '700'
            letterSpacing: '0.2px',
            textAlign:     'left',                  // 'left' | 'center' | 'right'
        },
        // Optional per-state overrides: base | focus | invalid | disabled | complete
        states: {
            base:  { caretColor: '#6c2bd9' },
            focus: { borderColor: '#6c2bd9', boxShadow: '0 0 0 3px rgba(108,43,217,0.2)' },
        },
        borderRadius:     '10px',
        borderStyle:      'solid',   // 'none' | 'solid' | 'dashed'
        padding:          '12px',
        placeholderColor: '#9a9ab0',
    },

    // Layout + labels
    layout: {
        fieldLayout:   'stacked',  // 'single-line' | 'stacked' | 'grouped' (expiry + CVC on one row)
        fieldSpacing:  '14px',
        showLabels:    true,
        labelPosition: 'top',      // 'top' | 'floating' | 'hidden'
    },

    // Branding extras
    branding: {
        logoUrl:           'https://example.com/logo.png',
        showCardBrandIcon: true,
        showSecurityBadge: false,
    },

    // Locale / reading direction (RTL supported)
    locale:    'en-US',
    direction: 'ltr',  // 'ltr' | 'rtl'
};

engine.payBy(eWalletList, callback, buttonProperties, undefined, iframeStyleConfig);

| Field | Description | |-------|-------------| | themeName | Optional named preset the form resolves server-side. Any explicit fields below override the preset. | | colorPalette | Semantic colors: primary, background, text, error, success, border. | | field | Input styling: typography, per-state overrides (states), borderRadius, borderStyle, padding, placeholderColor. | | layout | fieldLayout, fieldSpacing, showLabels, labelPosition. | | branding | logoUrl, showCardBrandIcon, showSecurityBadge. | | locale | BCP-47 locale applied to the form document. | | direction | 'ltr' or 'rtl' reading direction. |

Note: iframeStyleConfig applies to the CardPay hosted forms only. Other providers are unaffected.

Billing / shipping requirements

requiredAncillaryInfo controls whether the CardPay card-entry form also prompts the end customer for a billing and/or shipping address. It can be passed to the Engine constructor or, per call, to payBy (the payBy value wins when both are supplied).

const requiredAncillaryInfo = {
    billingInfo: {
        // Coarse control (legacy): 'MIN' = name/country/postal, 'FULL' = also street/city/state
        details: 'MIN',
        phoneRequired: false,
        emailAddressRequired: false,
    },
    shippingInfo: undefined,
};

For fine-grained control, set billingInfo.fields instead. When present, it overrides details, phoneRequired and emailAddressRequired, and only the fields marked true are prompted to the end customer:

const requiredAncillaryInfo = {
    billingInfo: {
        fields: {
            name:               true,
            countryCode:        true,
            postalCode:         true,
            addressLines:       false,  // street address
            locality:           false,  // city
            administrativeArea: false,  // state / province
            phoneNumber:        true,
            emailAddress:       false,
        },
    },
};

engine.payBy(eWalletList, callback, buttonProperties, requiredAncillaryInfo, undefined);

| Field | Description | |-------|-------------| | name | Full name of the addressee. | | countryCode | Country. | | postalCode | Postal / ZIP code. | | addressLines | Street address line(s). | | locality | City / town. | | administrativeArea | State / province. | | phoneNumber | Telephone number. | | emailAddress | Email address. |

The captured address is returned via engine.getBillingInfo() / engine.getShippingInfo() and is also attached to the encrypted card payload.

Obtaining Results

Use the following methods to get data on the current session:

| Method | Description | |--------|-------------| | getSessionType() | Returns the session type (CHARGE, TOKENIZE, etc.) | | parseResultToken() | Parses and returns the result token from the payment operation | | getBillingInfo() | Returns the billing information collected during the payment | | getShippingInfo() | Returns the shipping information collected during the payment |

Documentation

In order to use this library to process payments, you need to have an account with Orchestra. If you do not have one yet, please go to our website to sign up. If you already have an account, check out our documentation pages to read our integration guides, view the full API reference and see instructions on generating a session token for the library.

Support

For assistance, visit our contact form or email [email protected].

Changelog

See CHANGELOG.md for version history.