Library Setup

This page is part of the Payments Library Guides. For what your backend does after capture, like charging stored tokens and refunds, see the REST API Guides.

Prerequisites: API key, Payment Gateway Account, and eWallet Account configured. The Orchestra Payments Library displays payment buttons and handles the payment UI. It supports card entry, Apple Pay, Google Pay, PayPal, bank payments, and UPI.

Available on npm as @orchestrasolutions/ewallet.

Installation

npm install @orchestrasolutions/ewallet

Data Flow

Your server creates a session with Orchestra and passes the JWT to the client. The client initializes the library, displays payment buttons, and handles customer interaction. After payment, the result JWT is returned to the client, which passes it to your server for validation with Orchestra.

Quick Start

1. Initialize the Engine

import * as eWallet from '@orchestrasolutions/ewallet';

const engine = new eWallet.Engine(sessionToken);

The sessionToken comes from your backend via POST /EWalletOperations. Here is how to create a session on your server:

app.post('/api/create-session', async (req, res) => {
  const response = await fetch('https://api.orchestrasolutions.com/EWalletOperations', {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.ORCHESTRA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      operation: 'CHARGE',
      paymentGatewayAccountId: process.env.PAYMENT_GATEWAY_ACCOUNT_ID,
      allowedeWalletAccountIds: ['card-payments', 'google-pay-prod'],
      allowedBrands: ['Visa', 'MasterCard', 'AMEX'],
      currencyCode: 'USD',
      countryCode: 'US',
      amount: 49.99,
      mode: 'TEST'
    })
  });

  const data = await response.json();
  res.json({ sessionToken: data.token });
});

@app.route('/api/create-session', methods=['POST'])
def create_session():
    response = requests.post(
        'https://api.orchestrasolutions.com/EWalletOperations',
        headers={
            'X-Api-Key': os.environ['ORCHESTRA_API_KEY'],
            'Content-Type': 'application/json'
        },
        json={
            'operation': 'CHARGE',
            'paymentGatewayAccountId': os.environ['PAYMENT_GATEWAY_ACCOUNT_ID'],
            'allowedeWalletAccountIds': ['card-payments', 'google-pay-prod'],
            'allowedBrands': ['Visa', 'MasterCard', 'AMEX'],
            'currencyCode': 'USD',
            'countryCode': 'US',
            'amount': 49.99,
            'mode': 'TEST'
        }
    )

    data = response.json()
    return jsonify({'sessionToken': data['token']})

Other Session Parameters

The example above uses the minimum. The session also accepts:

Parameter	Purpose
`paymentGatewayParameters`	Key-value pairs passed through to the processor. This is the only way to send processor-specific parameters, so check Additional Guidance for your gateway
`threeDsBrands`	Card brands to run 3D Secure for, where you want it on some brands and not others
`customerName`, `customerEmail`, `customerPhone`	Customer details, required by some processors and used on receipts
`billingAddress`, `shippingAddress`	Addresses, required by some processors and used in risk checks
`paymentNote`	A note shown with the payment
`merchantReference`	Your own reference for the transaction
`storedCards`	Up to three previously tokenized cards to offer the payer for a CVV-only payment
`fallbackUpgs`	Backup gateway accounts to try if the primary one fails, see Multi-Gateway Failover
`publicKey`	Public key for the session, where your integration uses one

operation decides what the session does: CHARGE, TOKENIZE, GATEWAY_TOKENIZE, CHARGE_AND_TOKENIZE or PREAUTH_AND_TOKENIZE. Use one of the combined values when you want to save the card at the same time as taking the payment, which is the usual starting point for scheduled payments.

2. Check Available Payment Methods

const available = await engine.checkAvailability();
// Returns: ["CardPay", "GooglePay", "PayPal", ...]

3. Display Buttons

Add container elements to your HTML:

<div id="card-button"></div>
<div id="gpay-button"></div>
<div id="paypal-button"></div>

Each payment method requires its own container element with a unique selector. If you add multiple payment methods, create a separate container for each.

Render buttons for available methods:

const buttons = [
  { name: 'CardPay', domEntitySelector: '#card-button' },
  { name: 'GooglePay', domEntitySelector: '#gpay-button' },
  { name: 'PayPal', domEntitySelector: '#paypal-button' }
].filter(btn => available.includes(btn.name));

engine.payBy(buttons, handleResult, undefined);

4. Handle Results

function handleResult(result) {
  if (!result) {
    console.log('Payment cancelled');
    return;
  }

  // Send token to your backend for validation
  fetch('/api/validate-payment', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ token: result.token })
  });
}

Your backend should validate the result token using POST /EWalletOperations/validateResults before fulfilling orders.

Payment Methods

Value	Description	Availability
`"CardPay"`	Credit/debit card form	All browsers
`"GooglePay"`	Google Pay	Chrome, Android
`"ApplePay"`	Apple Pay	Safari, iOS, macOS
`"PayPal"`	PayPal checkout	All browsers
`"BankPay"`	Bank transfer (Open Banking, ACH)	All browsers
`"UPI"`	Unified Payments Interface	All browsers

What’s Next

Supported Payment Methods

CardPay, ApplePay, GooglePay, PayPal, BankPay, UPI

Library Reference

Button styling, result parsing, address collection, localization

Result Handling

Parse and validate payment results

Complete Example

End-to-end integration example

Start Here

Beyond the Quickstart

Concepts

Orchestra Payments Library Guides

Orchestra REST API Guides

Utilities

Merchant Account Setup

Support

Changelog

Installation

Data Flow

Quick Start

1. Initialize the Engine

Other Session Parameters

2. Check Available Payment Methods

3. Display Buttons

4. Handle Results

Payment Methods

What’s Next

Supported Payment Methods

Library Reference

Result Handling

Complete Example

​Installation

​Data Flow

​Quick Start

​1. Initialize the Engine

​Other Session Parameters

​2. Check Available Payment Methods

​3. Display Buttons

​4. Handle Results

​Payment Methods

​What’s Next

Supported Payment Methods

Library Reference

Result Handling

Complete Example

Installation

Data Flow

Quick Start

1. Initialize the Engine

Other Session Parameters

2. Check Available Payment Methods

3. Display Buttons

4. Handle Results

Payment Methods

What’s Next