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

# Create Payments Library Session

> Create a new Payments Library session for tokenization or charge operations using digital wallets.

<Card title="Payments Library Setup Guide" icon="book" href="/payments-library/setup">
  Get started with the Payments Library
</Card>

Creates a session for a digital wallet operation. The session ID returned is used by the client-side Payments Library to present the payment UI to the payer.

## Error Responses

| Code    | HTTP Status | Condition                                                                                                     |
| ------- | ----------- | ------------------------------------------------------------------------------------------------------------- |
| `-1003` | `401`       | API key is missing or invalid.                                                                                |
| `-125`  | `400`       | A sandbox user attempted a `LIVE` mode operation. Sandbox users can only use `TEST` mode.                     |
| `-125`  | `400`       | Session creation failed due to invalid parameters (e.g. missing required fields, invalid wallet account IDs). |

## Parameter Constraints

* **operation**: Must be `TOKENIZE` or `CHARGE`.
* **mode**: Must be `TEST` or `LIVE`. Sandbox users are restricted to `TEST` only.
* **PaymentGatewayAccountId**: Must reference a valid stored credential ID.
* **AllowedeWalletAccountIds**: Comma-separated list of stored digital wallet credential IDs.
* **CurrencyCode**: Must be a valid ISO 4217 currency code.
* **CountryCode**: Must be a valid ISO 3166-1 alpha-2 country code.
* **CustomerEmail**: Must be a valid email format (when provided for 3DS).
* **CustomerPhone**: Digits only (when provided for 3DS).

<Info title="Tokenization and 3D Secure support by payment method">
  **Tokenization** (`TOKENIZE` operation) is only available for card pay, Apple Pay, and Google Pay. Other payment methods support charge only.

  **3D Secure** behavior varies by method:

  * **Apple Pay:** 3DS is always performed by Apple when the cardholder interacts with their device. The card always includes 3DS authentication results.
  * **Google Pay:** 3DS depends on cardholder interaction and device. If Google Pay performed two-factor authentication, the card includes the 3DS result.
  * **Card pay:** You choose whether to perform 3DS after the cardholder enters their card details. If enabled, PCI Booking performs 3DS and only proceeds if successful.
</Info>

## Parameters

### Headers

<ParamField header="Authorization" type="string" required>
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Operation

<ParamField body="operation" type="string" required>
  The type of operation to perform:

  * `TOKENIZE`: Retrieve card details from the digital wallet and store them as a token in PCI Booking's vault.
  * `CHARGE`: Retrieve card details from the digital wallet and submit a charge to the payment gateway.
</ParamField>

### Payment Gateway

<ParamField body="PaymentGatewayAccountId" type="string" required>
  The `credentialsId` of your payment gateway credentials, stored using the [Store Gateway Credentials](/api-reference/process-cards/store-credentials) method.
</ParamField>

<ParamField body="AllowedeWalletAccountIds" type="string" required>
  A comma-separated list of digital wallet credential IDs stored using the [Store Digital Wallet Credentials](/api-reference/payments-library-accounts/store-credentials) method.
</ParamField>

<ParamField body="FallbackUpgs" type="array">
  Fallback payment gateway accounts to try if the primary gateway fails. Each object contains the fallback gateway account details.
</ParamField>

### Transaction

<ParamField body="mode" type="string" required>
  The environment. Possible values: `TEST`, `LIVE`.
</ParamField>

<ParamField body="CurrencyCode" type="string" required>
  ISO 4217 currency code (e.g. `USD`, `EUR`).
</ParamField>

<ParamField body="Amount" type="number" required>
  The transaction amount.
</ParamField>

<ParamField body="CountryCode" type="string" required>
  ISO 3166-1 alpha-2 country code of the payer (e.g. `US`, `GB`).
</ParamField>

<ParamField body="AllowedBrands" type="string" required>
  Comma-separated list of accepted card brands. If the payer's card does not match, they are prompted to enter a different card.
</ParamField>

<ParamField body="PaymentNote" type="string">
  A note sent to and recorded by the payment processor.
</ParamField>

<ParamField body="merchantReference" type="string">
  Your own reference for this transaction (e.g. booking number, order ID).
</ParamField>

### 3D Secure

<ParamField body="CustomerEmail" type="string">
  The cardholder's email address for 3D Secure authentication. Must be a valid email format. Either `CustomerEmail` or `CustomerPhone` is required when performing 3DS.
</ParamField>

<ParamField body="CustomerPhone" type="string">
  The cardholder's phone number for 3D Secure authentication. Digits only (e.g. `00353112223344`). Either `CustomerEmail` or `CustomerPhone` is required when performing 3DS.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  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: 99.99,
      CountryCode: 'US',
      AllowedBrands: 'visa,mastercard,amex',
      CustomerEmail: 'customer@example.com',
      merchantReference: 'ORDER-12345'
    })
  });
  const data = await response.json();
  console.log(data.sessionId);
  ```

  ```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': 99.99,
          'CountryCode': 'US',
          'AllowedBrands': 'visa,mastercard,amex',
          'CustomerEmail': 'customer@example.com',
          'merchantReference': 'ORDER-12345'
      }
  )
  data = response.json()
  print(data['sessionId'])
  ```
</RequestExample>

## Response

The response contains the session details needed by the client-side Payments Library.

<ResponseExample>
  ```json 200 theme={null}
  {
      "sessionId": "abc123def456",
      "status": "Created"
  }
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```
</ResponseExample>