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

# Payments Library Overview

> Integrate PCI Booking's JavaScript library for card capture, Apple Pay, Google Pay, PayPal, BankPay, and UPI in your checkout page

The Payments Library (`@pcibooking/ewallet`) is a client-side JavaScript SDK that handles card capture and payment processing in your checkout page. It renders secure payment forms, manages communication with PCI Booking's servers, and supports multiple payment methods from a single integration point.

For how the Payments Library fits into the overall tokenization flow, see [Payments Library under Capture Cards](/capture-cards/payments-library).

## Key Capabilities

* **Card payments.** Render a secure card form (in popup or iframe mode) for credit and debit card entry with full 3D Secure support.
* **Digital wallets.** Accept Apple Pay, Google Pay, PayPal, BankPay, and UPI alongside card payments on the same checkout page.
* **Multiple operations.** Support for CHARGE, TOKENIZE, CHARGE\_AND\_TOKENIZE, PREAUTH\_AND\_TOKENIZE, and GATEWAY\_TOKENIZE, depending on the payment method.
* **PCI compliance.** Card data is captured inside PCI Booking's secure environment and never touches your servers, keeping you out of PCI DSS scope.

## How It Works

The Payments Library uses a session-based architecture with JWS (JSON Web Signature) signing for secure communication:

1. **Your server** calls the PCI Booking API to [create a session](/api-reference/payments-library/create-session), specifying the operation type and amount.
2. **Your frontend** initializes the Payments Library with the session token.
3. **The library** renders payment method buttons and forms based on the session configuration and the customer's device capabilities.
4. **The customer** selects a payment method and completes the transaction.
5. **PCI Booking** processes the payment and returns the result to your frontend callback.

## Architecture

The Payments Library follows a client-server model where sensitive operations happen on PCI Booking's servers and your frontend only handles the UI layer.

* **Session creation (server-side).** Your backend calls PCI Booking's API to create a session, specifying the operation type (CHARGE, TOKENIZE, CHARGE\_AND\_TOKENIZE, PREAUTH\_AND\_TOKENIZE, or GATEWAY\_TOKENIZE), the PSP credentials, amount, and currency. PCI Booking returns a signed JWS session token.
* **Library initialization (client-side).** Your frontend loads the `@pcibooking/ewallet` package and initializes it with the session token. The library verifies the token signature and configures itself based on the session parameters.
* **Payment method rendering.** The library detects the customer's device and browser capabilities, then renders only the payment methods that are available. For example, Apple Pay buttons appear only on Safari with a compatible device, and Google Pay buttons appear only in Chrome with a linked Google account.
* **Secure data handling.** Card form fields are rendered inside PCI Booking's secure environment (either an iframe or a popup). Card data is submitted directly from the form to PCI Booking's servers. Your page never has access to the raw card data, keeping you fully outside PCI DSS scope.
* **Result callback.** After the payment is processed (or the card is tokenized), PCI Booking calls your frontend callback function with the result, including the token, transaction status, and any error details.

## Supported Payment Methods

The library supports six payment methods from a single integration point: **CardPay** (credit and debit cards with 3D Secure), **Apple Pay**, **Google Pay**, **PayPal**, **BankPay** (Open Banking / ACH), and **UPI** (India instant payments). Each method has different supported operations and device requirements. See [Supported Payment Methods](/payments-library/supported-methods) for the full comparison.

## Credentials Setup

Each payment method requires credentials from the respective provider (Apple, Google, PayPal, etc.) stored in PCI Booking. See [Payments Library Credentials](/account-setup/payments-library-credentials) for the full list of required credentials per method.

## End-to-End Integration Example

This example shows the complete flow: creating a session on your server, loading the library on the client, and handling the payment result.

### Step 1: Create a Session (Server-Side)

<CodeGroup>
  ```javascript Node.js theme={null}
  // Server: create a session and return sessionId to the frontend
  const response = await fetch('https://service.pcibooking.net/api/eWalletOperation', {
    method: 'POST',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      operation: 'CHARGE',
      mode: 'LIVE',
      PaymentGatewayAccountId: 'my-gateway-credentials',
      AllowedeWalletAccountIds: 'my-applepay,my-googlepay',
      CurrencyCode: 'USD',
      Amount: 49.99,
      CountryCode: 'US',
      AllowedBrands: 'visa,mastercard,amex',
      CustomerEmail: 'customer@example.com'
    })
  });
  const { sessionId } = await response.json();
  // Return sessionId to your frontend (e.g. via API response)
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://service.pcibooking.net/api/eWalletOperation',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/json'
      },
      json={
          'operation': 'CHARGE',
          'mode': 'LIVE',
          'PaymentGatewayAccountId': 'my-gateway-credentials',
          'AllowedeWalletAccountIds': 'my-applepay,my-googlepay',
          'CurrencyCode': 'USD',
          'Amount': 49.99,
          'CountryCode': 'US',
          'AllowedBrands': 'visa,mastercard,amex',
          'CustomerEmail': 'customer@example.com'
      }
  )
  session_id = response.json()['sessionId']
  # Return session_id to your frontend (e.g. via API response)
  ```
</CodeGroup>

### Step 2: Load the Library and Present Payment UI (Client-Side)

```html theme={null}
<script src="https://cdn.jsdelivr.net/npm/@pcibooking/ewallet@latest/dist/index.js"></script>

<div id="payment-buttons"></div>

<script>
  async function startPayment(sessionToken) {
    // Initialize the engine with the session token from your server
    const engine = new eWallet.Engine(sessionToken, null, 'EN', {
      displayMode: 'iframe',
      iframeContainerSelector: '#card-form-container'
    });

    // Detect which payment methods are available on this device
    const methods = await engine.checkAvailability();

    // Render payment buttons and handle the result
    engine.payBy(methods, function(result) {
      if (!result) {
        console.log('Payment cancelled by user');
        return;
      }

      const [data, success] = engine.parseResultToken(result.token);
      if (data.clientSuccess && success) {
        // Send result.token to your server for validation
        fetch('/api/validate-payment', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ token: result.token })
        });
      }
    }, {
      containerSelector: '#payment-buttons'
    });
  }

  // Fetch the session token from your server, then start the payment flow
  fetch('/api/create-session')
    .then(res => res.json())
    .then(data => startPayment(data.sessionId));
</script>
```

### Step 3: Validate the Result (Server-Side)

<CodeGroup>
  ```javascript Node.js theme={null}
  // Server: validate the result token received from the frontend
  const response = await fetch('https://service.pcibooking.net/api/eWalletOperation/validateResults', {
    method: 'POST',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'text/plain'
    },
    body: resultToken
  });
  const { valid } = await response.json();
  if (valid) {
    // Payment is verified, fulfill the order
  }
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://service.pcibooking.net/api/eWalletOperation/validateResults',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'text/plain'
      },
      data=result_token
  )
  if response.json()['valid']:
      # Payment is verified, fulfill the order
      pass
  ```
</CodeGroup>

## Integration Guides

<CardGroup cols={3}>
  <Card title="Setup" icon="book" href="/payments-library/setup">
    Install the library, create a session, and run a working example
  </Card>

  <Card title="Supported Payment Methods" icon="book" href="/payments-library/supported-methods">
    All methods with browser support, device requirements, and supported operations
  </Card>

  <Card title="Library Reference" icon="code" href="/payments-library/reference">
    Full API surface: constructor parameters, methods, UI options, and operation types
  </Card>
</CardGroup>