Payments Library Setup

This guide installs the Payments Library, creates a payment session, and processes a first payment end to end.

Prerequisites

A PCI Booking merchant account.
Credentials configured for the payment methods you want to accept. See Payments Library Credentials.
If CardPay is enabled with 3D Secure, configure your 3DS merchant details first. Without them, PCI Booking’s default merchant is used and 3DS is limited to Visa and Mastercard.

Installation

npm

npm install @pcibooking/ewallet

import eWallet from '@pcibooking/ewallet';

Create a Session

Before initializing the library, your server must create a payment session with PCI Booking. The session defines the operation type (e.g. TOKENIZE, CHARGE) and returns a session token. Pass the session token to your frontend to initialize the library. For returning customers, the session can also carry up to 3 stored cards so the payer can pay with a saved card by entering only its CVV.

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',
    PaymentGatewayParameters: { 'SomePspParameterName': 'SomeValue' },
    AllowedeWalletAccountIds: ['my-applepay', 'my-googlepay'],
    CurrencyCode: 'USD',
    Amount: 99.99,
    CountryCode: 'US',
    AllowedBrands: ['VISA', 'MASTERCARD', 'AMEX'],
    CustomerEmail: 'customer@example.com',
    merchantReference: 'ORDER-12345',
    // Optional: offer previously tokenized cards for CVV-only payment (max 3)
    StoredCards: [{
      Token: 'a21af1bb711d4daf89ee095d22a51f47',
      Brand: 'MasterCard',
      LastDigits: '1234',
      ExpirationMonth: 12,
      ExpirationYear: 2030,
      NameOnCard: 'John Doe'
    }]
  })
});
const { token } = await response.json();
// Pass token to your frontend

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',
        'PaymentGatewayParameters': { 'SomePspParameterName': 'SomeValue' },
        'AllowedeWalletAccountIds': ['my-applepay', 'my-googlepay'],
        'CurrencyCode': 'USD',
        'Amount': 99.99,
        'CountryCode': 'US',
        'AllowedBrands': ['VISA', 'MASTERCARD', 'AMEX'],
        'CustomerEmail': 'customer@example.com',
        'merchantReference': 'ORDER-12345',
        # Optional: offer previously tokenized cards for CVV-only payment (max 3)
        'StoredCards': [{
            'Token': 'a21af1bb711d4daf89ee095d22a51f47',
            'Brand': 'MasterCard',
            'LastDigits': '1234',
            'ExpirationMonth': 12,
            'ExpirationYear': 2030,
            'NameOnCard': 'John Doe'
        }]
    }
)
token = response.json()['token']
# Pass token to your frontend

Minimal Working Example

import eWallet from '@pcibooking/ewallet';

async function startCheckout() {
  // Session token from your server (via Create Session API)
  const sessionToken = 'YOUR_SESSION_TOKEN';

  const engine = new eWallet.Engine(sessionToken);
  const methods = await engine.checkAvailability();

  engine.payBy(methods, function(result) {
    if (!result) {
      alert('Payment cancelled');
      return;
    }

    const [data, success] = engine.parseResultToken(result.token);
    if (data.clientSuccess && success) {
      // Send result.token to your server for validation
      console.log('Success, token:', result.token);
    }
  }, {
    containerSelector: '#payment-buttons'
  });
}

startCheckout();

Session tokens are single-use. Create a new session for each checkout attempt.

Server-Side Validation

After the customer completes the payment, your callback receives a result token. Send this token to your server and call the Validate Operation endpoint to confirm the result is authentic.

async function validatePaymentResult(resultToken) {
  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 data = await response.json();
  return data.valid; // true if the token is authentic
}

import requests

def validate_payment_result(result_token):
    response = requests.post(
        'https://service.pcibooking.net/api/eWalletOperation/validateResults',
        headers={
            'Authorization': 'APIKEY your-api-key',
            'Content-Type': 'text/plain'
        },
        data=result_token
    )
    data = response.json()
    return data['valid']  # True if the token is authentic

Start Here

Getting Started

Concepts

Guides

Capture Cards