Installation

npm i @orchestrasolutions/ewallet

Quick Start

Initialize the Engine

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

| Parameter | Description | |-----------|-------------| | sessionToken | Required. Token obtained from the Orchestra 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',
        logoMaxHeight:     '48px',   // optional cap; this is the default
        logoMaxWidth:      '100%',   // optional cap; this is the default
        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, logoMaxWidth, logoMaxHeight, 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.

Logo size

branding.logoUrl accepts an image of any size: the hosted forms cap the rendered size and letterbox the image (object-fit: contain), so an oversized logo is scaled down instead of stretching the form. For the sharpest result, supply artwork that fits the space it is given:

| | Recommended | Notes | |---|---|---| | Height | 40px (48px cap) | Raise or lower the cap with branding.logoMaxHeight. | | Width | up to 320px | The form is about 400px wide; branding.logoMaxWidth caps it. | | Format | SVG, or PNG at 2x | A 2x raster (~80px tall) stays crisp on high-density screens. | | Background | Transparent | The logo sits on the form background, which colorPalette.background can change. |

The logo is rendered left-aligned at the top of the card-entry, CVV and stored-card forms, and is hidden entirely when UiOptions.hideLogo is set.

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.

Browser properties for 3D Secure

The hosted CardPay forms (card entry, CVV, stored card) collect the browser properties required for 3D Secure authentication and attach them to the encrypted card payload as browserProperties, which is sent to the server together with the card data. This is automatic - there is nothing to pass and no configuration to set - and it works in both popup and iframe display modes, since the form runs in the cardholder's own browser either way.

| Field | Description | |-------|-------------| | windowWidth | Challenge window width, in pixels. | | windowHeight | Challenge window height, in pixels. | | timeZoneOffsetMinutes | Difference between UTC and the cardholder's local time, in minutes (e.g. -120 for Israel Standard Time, -180 during DST). | | timeZoneName | Timezone name of the cardholder's local time (e.g. "Asia/Jerusalem"). | | userAgent | Browser User-Agent string. | | colorDepth | Browser color depth, in bits per pixel. | | browserScreenWidth | Screen width, in pixels. | | browserScreenHeight | Screen height, in pixels. | | browserLanguage | Browser language, from navigator.language (e.g. "he-IL"). | | browserJavascriptEnabled | Whether the browser has JavaScript enabled. | | browserJavaEnabled | Whether the browser has Java enabled. | | browserAcceptHeader | Content of the HTTP Accept header. A page cannot read its own request headers, so the wildcard value */* sent by script-initiated requests is reported. |

Obtaining Results

When the payment operation completes, the payBy() callback receives a result object with a .token property. Decode it with parseResultToken(result.token), then check clientSuccess and the success boolean before proceeding. Send result.token to your backend for server-side validation of the operation results.

const [data, success] = engine.parseResultToken(result.token);
if (data.clientSuccess && success) {
    // send result.token to your backend for validation
}

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 |

Supported Payment Methods

| Method | Description | Tokenization | |--------|-------------|--------------| | CardPay | Credit/debit cards with 3DS | Yes | | Apple Pay | Safari, iOS, macOS | Yes | | Google Pay | Chrome, Android | Yes | | PayPal | All browsers | Charge only | | BankPay | Open Banking / ACH | Charge only | | UPI | India instant payments | Charge only |

For detailed setup and browser compatibility, see the eWallet Docs.

Stored Cards (Returning Customers)

CardPay can also offer the customer's previously stored cards for CVV-only payment. Pass up to 3 stored cards (each card's token plus its display details) in the session creation request on your server; the card entry form then shows a "Pay by {brand} ****{last 4}" button per card alongside the option to enter another card. No client-side changes are needed - the library renders the stored-card selection automatically when the session includes stored cards. See the eWallet Docs for the session request details.

Getting Started

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.