> ## 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 Reference

> Complete API reference for 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>

## Engine Constructor

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

const engine = new eWallet.Engine(
  sessionToken,           // Required: from POST /EWalletOperations
  requiredAncillaryInfo,  // Optional: address collection requirements
  language,               // Optional: UI language code
  uiOptions               // Optional: UI display options
);
```

| Parameter               | Type                                 | Description                                                                                                              |
| ----------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `sessionToken`          | `string`                             | Session token from your backend via [POST /EWalletOperations](/api-reference/ewalletoperations/start-an-ewallet-session) |
| `requiredAncillaryInfo` | `RequiredAncillaryInfo \| undefined` | Billing/shipping address requirements (see [Address Collection](#address-collection))                                    |
| `language`              | `string \| undefined`                | Language code for UI (see [Localization](#localization))                                                                 |
| `uiOptions`             | `UiOptions \| undefined`             | Display options for the CardPay form (see [UI Options](#ui-options))                                                     |

## UI Options

Control how the CardPay card-entry form is displayed. Other providers are not affected.

```javascript theme={null}
const uiOptions = {
  hideLogo: true,                          // hide merchant logo on card form
  displayMode: 'iframe',                   // 'popup' (default) or 'iframe'
  iframeContainerSelector: '#card-form'    // CSS selector for inline iframe host
};

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

| Field                     | Type                  | Description                                                                                                                                                                         |
| ------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hideLogo`                | `boolean`             | When `true`, the merchant logo is not rendered on the card-entry form. Defaults to `false`.                                                                                         |
| `displayMode`             | `'popup' \| 'iframe'` | `'popup'` (default) opens the card form in a separate browser window. `'iframe'` embeds it in-page.                                                                                 |
| `iframeContainerSelector` | `string`              | Only used when `displayMode` is `'iframe'`. CSS selector of the element that hosts the iframe (e.g. `'#card-form'`). When omitted, the iframe is shown as a centered modal overlay. |

<Note>
  `displayMode` applies to the CardPay form only. Apple Pay, Google Pay, PayPal, BankPay, and UPI continue to use their standard flows.
</Note>

## Localization

The library supports 20 languages. Pass a language code to the constructor:

```javascript theme={null}
const engine = new eWallet.Engine(sessionToken, undefined, 'de');
```

### Supported Languages

| Code | Language  | Code | Language   |
| ---- | --------- | ---- | ---------- |
| `en` | English   | `nl` | Dutch      |
| `de` | German    | `pl` | Polish     |
| `es` | Spanish   | `pt` | Portuguese |
| `fr` | French    | `ru` | Russian    |
| `it` | Italian   | `sv` | Swedish    |
| `he` | Hebrew    | `tr` | Turkish    |
| `cs` | Czech     | `zh` | Chinese    |
| `el` | Greek     | `ko` | Korean     |
| `fi` | Finnish   | `sk` | Slovak     |
| `no` | Norwegian | `sr` | Serbian    |

## checkAvailability()

Returns the list of payment methods available on the current device and browser:

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

Use this to filter which buttons to display. For example, Apple Pay is only available on Safari/iOS, and Google Pay only on Chrome/Android.

## payBy() Method

```javascript theme={null}
engine.payBy(
  eWalletList,           // Required: buttons to display
  callback,              // Required: called when payment completes
  buttonProperties,      // Optional: button styling
  requiredAncillaryInfo  // Optional: override address requirements
);
```

Each button is an object with `name` and `domEntitySelector`:

```javascript theme={null}
{ name: 'CardPay', domEntitySelector: '#card-button' }
```

## Button Styling

Customize button appearance with `ButtonProperties`:

```javascript theme={null}
const buttonProperties = {
  color: 'Dark',      // "Light" or "Dark"
  text: 'Pay',        // "None", "Pay", "Buy", "Subscribe", "Book", "Checkout", "Donate"
  width: '200px',
  height: '40px',
  logoPath: '/path/to/logo.png'  // Optional
};

engine.payBy(buttons, handleResult, buttonProperties);
```

## Parsing Results

Use `parseResultToken()` to decode the result token into structured data:

```javascript theme={null}
function handleResult(result) {
  if (!result) return;

  const [data, success] = engine.parseResultToken(result.token);
```

The method returns a tuple:

* `data` - The parsed result object containing payment details
* `success` - Boolean indicating if the token was successfully decoded (not whether the payment succeeded)

To determine if a payment succeeded, check `data.clientSuccess`:

```javascript theme={null}
  if (!data.clientSuccess) {
    console.error('Payment failed:', data.clientErrorMessage);
    return;
  }

  // Check which type of result we received
  if (data.upgChargeResults) {
    // Payment processed through a PSP (CardPay, ApplePay, GooglePay)
    console.log('Gateway:', data.upgChargeResults.gatewayName);
    console.log('Reference:', data.upgChargeResults.gatewayReference);
    console.log('Amount:', data.upgChargeResults.amount, data.upgChargeResults.currency);
  }

  if (data.directChargeResults) {
    // Payment processed directly (PayPal, BankPay, UPI)
    console.log('Success:', data.directChargeResults.success);
    console.log('Message:', data.directChargeResults.message);
  }

  if (data.tokenAndMaskedCardModel) {
    // Tokenization result
    console.log('Token:', data.tokenAndMaskedCardModel.token);
    console.log('Card:', data.tokenAndMaskedCardModel.bankCard.type);
    console.log('Last 4:', data.tokenAndMaskedCardModel.bankCard.number);

    if (data.tokenAndMaskedCardModel.threeDS) {
      console.log('3DS ECI:', data.tokenAndMaskedCardModel.threeDS.eci);
    }
  }
}
```

### getSessionType()

Returns the operation type for this session:

```javascript theme={null}
const sessionType = engine.getSessionType();
// "CHARGE", "TOKENIZE", "CHARGE_AND_TOKENIZE", or "PREAUTH_AND_TOKENIZE"
```

### getSelectedProviderName()

Returns which payment method the customer used:

```javascript theme={null}
function handleResult(result) {
  const provider = engine.getSelectedProviderName();
  console.log('Customer paid with:', provider);
  // "CardPay", "GooglePay", "ApplePay", "PayPal", "BankPay", or "UPI"
}
```

### Result Data Structure

```typescript theme={null}
EWalletResultData {
  clientSuccess: boolean;
  clientErrorMessage: any;

  // For PSP charges (CardPay, ApplePay, GooglePay)
  upgChargeResults?: {
    gatewayName: string;
    gatewayReference: string;
    authorizationCode: string;
    amount: number;
    currency: string;
    operationType: string;  // "Charge", "PreAuth", etc.
    operationResultCode: string;  // "Success", "Rejected", etc.
    operationResultDescription: string;  // Human-readable result message
    gatewayResultDescription: string;  // Message from the payment gateway
  };

  // For direct charges (PayPal, BankPay, UPI)
  directChargeResults?: {
    success: boolean;
    message: string;
    data: object;  // Provider-specific payload - structure varies by payment method. See note below.
  };

  // For tokenization
  tokenAndMaskedCardModel?: {
    token: string;
    bankCard: {
      type: string;      // "Visa", "MasterCard", etc.
      number: string;    // Masked: "************1234"
      expirationMonth: number;
      expirationYear: number;
      nameOnCard: string;
    };
    threeDS?: {
      eci: string;
      authenticationValue: string;
      xid: string;
      version: string;
    };
  };
}
```

<Note>
  `directChargeResults.data` is intentionally untyped. Its contents are provider-specific (PayPal, BankPay, UPI each return different fields) and may change as those providers update their APIs. Use `success` and `message` to determine the payment outcome - do not build logic that depends on the contents of `data`.
</Note>

## Address Collection

Request billing and/or shipping addresses from the payment method (supported by Google Pay, Apple Pay, PayPal).

### Configuration

```javascript theme={null}
const requiredAncillaryInfo = {
  billingInfo: {
    phoneRequired: true,
    emailAddressRequired: true,
    details: 'FULL'  // "MIN" or "FULL"
  },
  shippingInfo: {
    phoneRequired: false,
    emailAddressRequired: false
  }
};

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

### Address Levels

| Level    | Fields Included                                                                 |
| -------- | ------------------------------------------------------------------------------- |
| `"MIN"`  | name, countryCode, postalCode, phone (if required), email (if required)         |
| `"FULL"` | MIN fields + addressLines, locality (city), administrativeArea (state/province) |

### Retrieving Addresses

After payment completes, retrieve the collected addresses:

```javascript theme={null}
function handleResult(result) {
  if (!result) return;

  const billing = engine.getBillingInfo();
  if (billing) {
    console.log('Name:', billing.name);
    console.log('Email:', billing.emailAddress);
    console.log('Country:', billing.countryCode);
    console.log('Postal:', billing.postalCode);

    // FULL address fields (if requested)
    if (billing.addressLines) {
      console.log('Street:', billing.addressLines.join(', '));
      console.log('City:', billing.locality);
      console.log('State:', billing.administrativeArea);
    }
  }

  const shipping = engine.getShippingInfo();
  if (shipping) {
    console.log('Ship to:', shipping.name);
    console.log('Address:', shipping.addressLines?.join(', '));
  }
}
```

## Operations

The session operation (set when creating the session) determines what the library does:

| Operation              | Description                                            |
| ---------------------- | ------------------------------------------------------ |
| `CHARGE`               | Process payment immediately                            |
| `TOKENIZE`             | Store payment method, return token for later charges   |
| `CHARGE_AND_TOKENIZE`  | Process payment and return a token                     |
| `PREAUTH_AND_TOKENIZE` | Authorize payment and return a token for later capture |

<Note>
  Tokenization is only available for CardPay, ApplePay, and GooglePay. PayPal, BankPay, and UPI support charge only.
</Note>

## Payment Method Requirements

### CardPay, ApplePay, GooglePay

Requires a payment processor (PSP) configured in your Orchestra account. Pass `paymentGatewayAccountId` when creating the session.

Orchestra supports [{supportedIntegrations} payment gateways](https://orchestrasolutions.com/integrations/).

### ApplePay, GooglePay

In addition to PSP credentials, these require:

* Merchant registration with Apple/Google
* Domain verification
* A PSP that [supports 3DS](https://orchestrasolutions.com/integ-type/3d-secure/)

See [ApplePay Setup](/guides/library/applepay-setup) and [GooglePay Setup](/guides/library/googlepay-setup) for details.

### PayPal

Requires PayPal merchant credentials [configured in the Orchestra Portal](https://portal.orchestrasolutions.com/#/resource/eWalletAccount/create). See [PayPal Setup](/guides/library/paypal-setup) for details.

### BankPay

Requires an Open Banking or ACH provider account [configured in the Orchestra Portal](https://portal.orchestrasolutions.com/#/resource/eWalletAccount/create). [Contact our team](https://orchestrasolutions.com/contact/) to confirm regional support.

### UPI

Requires a UPI provider account [configured in the Orchestra Portal](https://portal.orchestrasolutions.com/#/resource/eWalletAccount/create). Only available for INR transactions in India.

## Related

<CardGroup cols={2}>
  <Card title="Library Setup" icon="gear" href="/guides/library/setup">
    Quick start guide
  </Card>

  <Card title="Supported Payment Methods" icon="credit-card" href="/guides/library/supported-payment-methods">
    All payment methods
  </Card>

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

  <Card title="Payments Library API" icon="code" href="/api-reference/ewalletoperations/overview">
    Backend endpoint reference
  </Card>
</CardGroup>