> ## Documentation Index
> Fetch the complete documentation index at: https://developers.orchestrasolutions.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Library Setup

> Install and configure the Orchestra Payments Library.

<Info>
  This page is part of the **Payments Library Guides**. Prefer direct API calls instead? See [REST API Guides](/guides/rest-api/charge).
</Info>

**Prerequisites:** [API key](/getting-started/generate-api-key), [Payment Gateway Account](/getting-started/add-payment-provider), and [eWallet Account](/guides/library/store-merchant-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.

<Note>
  Available on npm as <Icon icon="npm" /> <a href="https://www.npmjs.com/package/@orchestrasolutions/ewallet"><code>@orchestrasolutions/ewallet</code></a>.
</Note>

## Installation

```bash theme={null}
npm install @orchestrasolutions/ewallet
```

## Data Flow

<img src="https://mintcdn.com/orchestrasolutions/JxGWfuqQpaY3_0EL/images/payments-library-flow-d2.svg?fit=max&auto=format&n=JxGWfuqQpaY3_0EL&q=85&s=53016322a64e0a784a418c64f5fcd935" alt="Payments Library Data Flow" width="1404" height="1703" data-path="images/payments-library-flow-d2.svg" />

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

```javascript theme={null}
import * as eWallet from '@orchestrasolutions/ewallet';

const engine = new eWallet.Engine(sessionToken);
```

The `sessionToken` comes from your backend via [POST /EWalletOperations](/api-reference/ewalletoperations/start-an-ewallet-session). Here is how to create a session on your server:

<CodeGroup>
  ```javascript Node.js theme={null}
  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 });
  });
  ```

  ```python Python theme={null}
  @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']})
  ```
</CodeGroup>

### 2. Check Available Payment Methods

```javascript theme={null}
const available = await engine.checkAvailability();
// Returns: ["CardPay", "GooglePay", "PayPal", ...]
```

### 3. Display Buttons

Add container elements to your HTML:

```html theme={null}
<div id="card-button"></div>
<div id="gpay-button"></div>
<div id="paypal-button"></div>
```

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

Render buttons for available methods:

```javascript theme={null}
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

```javascript theme={null}
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](/api-reference/ewalletoperations/validate-operation-results) 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

<CardGroup cols={2}>
  <Card title="Supported Payment Methods" icon="credit-card" href="/guides/library/supported-payment-methods">
    CardPay, ApplePay, GooglePay, PayPal, BankPay, UPI
  </Card>

  <Card title="Library Reference" icon="book" href="/guides/library/reference">
    Button styling, result parsing, address collection, localization
  </Card>

  <Card title="Result Handling" icon="check" href="/guides/library/result-handling">
    Parse and validate payment results
  </Card>

  <Card title="Complete Example" icon="code" href="/guides/library/complete-example">
    End-to-end integration example
  </Card>
</CardGroup>