Wipop JavaScript/TypeScript Client

A modern TypeScript/JavaScript client library for the Wipop payment processing API with full type safety and comprehensive error handling.

Features

• Card Charge Operations
  • Payment link generation
  • Refunds
  • Pre-authorization creation
  • Pre-authorization confirmation
  • Pre-authorization reversal
  • Token generation
  • One-click charges
  • Recurring charges
• Bizum Charge Operations
  • Payment link creation
  • Refunds
• Checkout Operations
  • Payment link generation
  • Payment button

Installation

# npm
npm install wipop-js-client

# yarn
yarn add wipop-js-client

# pnpm
pnpm add wipop-js-client

Before Getting Started

• Have completed the identification process during the Wipöp payment gateway contracting.
• Access the control panel in test mode (sandbox) from your account.
• Clearly define which method you will use to perform the integration in your system:

Required credentials:

• Merchant ID
• Secret API Key
• Terminal ID (default is 1 in sandbox)

Quick Start

import { 
  WipopClient, 
  WipopClientConfiguration, 
  Environment,
  CreateChargeParams,
  CreateChargeParamsBuilder,
  ChargeMethod,
  Currency,
  OriginChannel,
  Language,
  ProductType
} from 'wipop-js-client';

// Initialize client
const config = new WipopClientConfiguration(
  Environment.SANDBOX,
  'your-merchant-id',
  'your-secret-key'
);
const client = WipopClient.of(config);

// Create a charge using builder pattern
const charge = await client.chargeOperation().create(
  CreateChargeParamsBuilder.create()
    .method(ChargeMethod.CARD)
    .amount(100.00)
    .currency(Currency.EUR)
    .description('Payment for order #123')
    .productType(ProductType.PAYMENT_LINK)
    .terminal({ id: '1' })
    .build()
);

API Reference

Configuration

Basic Configuration

const config = new WipopClientConfiguration(
  Environment.SANDBOX, // Environment.PRODUCTION for production
  'your-merchant-id',
  'your-secret-key'
);

Advanced Configuration

import { WipopClientHttpConfiguration } from 'wipop-js-client';

const httpConfig = new WipopClientHttpConfiguration(
  30000 // request timeout (ms)
);

const config = new WipopClientConfiguration(
  Environment.SANDBOX,
  'merchant-id',
  'secret-key',
  httpConfig
);

Custom Environment

const config = new WipopClientConfiguration(
  'https://custom-api.wipop.es',
  'merchant-id',
  'secret-key'
);

Charge Operations

Payment Link

Create Card Charge

// Using builder pattern (recommended)
const cardCharge = await client.chargeOperation().create(
  CreateChargeParamsBuilder.create()
    .method(ChargeMethod.CARD)
    .amount(100.00)
    .currency(Currency.EUR)
    .description('Card payment')
    .orderId('order-123')
    .originChannel(OriginChannel.API)
    .productType(ProductType.PAYMENT_LINK)
    .capture(true)
    .terminal({ id: '1' })
    .build()
);

// Using object constructor
const cardCharge = await client.chargeOperation().create(
  new CreateChargeParams({
    method: ChargeMethod.CARD,
    amount: 100.00,
    currency: Currency.EUR,
    description: 'Card payment',
    orderId: 'order-123',
    productType: ProductType.PAYMENT_LINK,
    terminal: { id: '1' }
  })
);

Create Bizum Charge

const bizumCharge = await client.chargeOperation().create(
  CreateChargeParamsBuilder.create()
    .method(ChargeMethod.BIZUM)
    .amount(50.00)
    .currency(Currency.EUR)
    .description('Bizum payment')
    .orderId('order-456')
    .productType(ProductType.PAYMENT_LINK)
    .terminal({ id: '1' })
    .build()
);

To create charges associated with an existing customer, use the createCustomerCharge method with the customer ID:

Create Charge (Card/Bizum) specifying customer ID

const customerCharge = await client.chargeOperation().createCustomerCharge(
  'a00000000000000000000',
  CreateChargeParamsBuilder.create()
    .method(ChargeMethod.CARD) // or also ChargeMethod.BIZUM
    .amount(75.00)
    .currency(Currency.EUR)
    .description('Customer payment')
    .originChannel(OriginChannel.API)
    .productType(ProductType.PAYMENT_LINK)
    .terminal({ id: '1' })
    .build()
);

Confirm Charge

import { ConfirmChargeParams, ConfirmChargeParamsBuilder } from 'wipop-js-client';

// Using builder pattern
const confirmedCharge = await client.chargeOperation().confirm(
  't00000000000000000000',
  ConfirmChargeParamsBuilder.create()
    .tokenId('k000000000000000000')
    .build()
);

// Using object constructor
const confirmedCharge = await client.chargeOperation().confirm(
  't00000000000000000000',
  new ConfirmChargeParams({ tokenId: 'k000000000000000000' })
);

Refund Charge

import { RefundParams, RefundParamsBuilder } from 'wipop-js-client';

// Using builder pattern
const refundedCharge = await client.chargeOperation().refund(
  't00000000000000000000',
  RefundParamsBuilder.create()
    .amount(25.00)
    .build()
);

// Using object constructor
const refundedCharge = await client.chargeOperation().refund(
  't00000000000000000000',
  new RefundParams({ amount: 25.00 })
);

Reverse Charge

import { ReversalParams } from 'wipop-js-client';

const reversedCharge = await client.chargeOperation().reversal(
  't00000000000000000000',
  new ReversalParams().description('Transaction reversal')
);

Capture Charge

import { CaptureParams } from 'wipop-js-client';

const capturedCharge = await client.chargeOperation().capture(
  't00000000000000000000',
  new CaptureParams().amount(100.00)
);

Checkout Operations

Create Checkout

import { CheckoutParams, CheckoutParamsBuilder, ProductType } from 'wipop-js-client';

// Using builder pattern
const checkout = await client.checkoutOperation().createCheckout(
  CheckoutParamsBuilder.create()
    .amount(50.00)
    .currency(Currency.EUR)
    .description('Product purchase')
    .orderId('order-789')
    .redirectUrl('https://yoursite.com/success')
    .productType(ProductType.PAYMENT_LINK)
    .sendEmail(true)
    .build()
);

// Using object constructor
const checkout = await client.checkoutOperation().createCheckout(
  new CheckoutParams({
    amount: 50.00,
    currency: Currency.EUR,
    description: 'Product purchase',
    orderId: 'order-789',
    redirectUrl: 'https://yoursite.com/success',
    productType: ProductType.PAYMENT_LINK
  })
);

console.log('Checkout URL:', checkout.checkoutUrl);

Create Customer Checkout

const customerCheckout = await client.checkoutOperation().createCustomerCheckout(
  'customer-id',
  CheckoutParamsBuilder.create()
    .amount(100.00)
    .currency(Currency.EUR)
    .description('Customer checkout')
    .productType(ProductType.PAYMENT_LINK)
    .build()
);

Builder Pattern Support

The library supports both object constructor and fluent builder patterns for all parameter classes:

// Builder pattern (recommended)
const params = CreateChargeParamsBuilder.create()
  .method(ChargeMethod.CARD)
  .amount(100.00)
  .currency(Currency.EUR)
  .description('Payment')
  .productType(ProductType.PAYMENT_LINK)
  .build();

// Object constructor
const params = new CreateChargeParams({
  method: ChargeMethod.CARD,
  amount: 100.00,
  currency: Currency.EUR,
  description: 'Payment',
  productType: ProductType.PAYMENT_LINK
});

Language Support

The library includes support for internationalization with the Language class:

import { Language } from 'wipop-js-client';

// Create language instances
const spanish = Language.of('es', 'ES'); // Spanish (Spain)
const english = Language.of('en', 'US'); // English (United States)
const french = Language.of('fr', 'FR');  // French (France)

// Use in checkout parameters
const checkout = CheckoutParamsBuilder.create()
  .amount(100.00)
  .description('Product purchase')
  .language(spanish) // Sets language to 'es-ES'
  .productType(ProductType.PAYMENT_LINK)
  .build();

// Use in charge parameters
const charge = CreateChargeParamsBuilder.create()
  .method(ChargeMethod.CARD)
  .amount(100.00)
  .language(english) // Sets language to 'en-US'
  .productType(ProductType.PAYMENT_LINK)
  .build();

Supported Payment Methods

• CARD - Credit and debit card payments
• BIZUM - Spanish mobile payment system

Supported Currencies

• EUR - Euro
• Additional currencies as supported by the Wipop API

Transaction Status

The client uses the TransactionStatus enum for type-safe status handling:

• CHARGE_PENDING - Charge is pending processing
• COMPLETED - Transaction completed successfully
• ERROR - Transaction failed with error
• FAILED - Transaction failed
• IN_PROGRESS - Transaction is being processed

Error Handling

import { 
  WipopClientException, 
  ResponseStatus,
  CreateChargeParamsBuilder,
  CheckoutParamsBuilder,
  RefundParamsBuilder,
  ConfirmChargeParamsBuilder
} from 'wipop-js-client';

try {
  const charge = await client.chargeOperation().create(chargeParams);
} catch (error) {
  if (error instanceof WipopClientException) {
    console.error('Wipop API Error:', error.message);
    
    if (error.responseCode) {
      console.error('Error Code:', error.responseCode.code);
      console.error('Error Message:', error.responseCode.message);
      console.error('Error Level:', error.responseCode.level);
    }
  } else {
    console.error('Unexpected error:', error);
  }
}

Development

Prerequisites

• Node.js 16+
• TypeScript 5+

Scripts

# Build the project
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Format code
npm run format

# Check formatting
npm run format:check

Testing

The project uses Jest for testing with comprehensive test coverage:

# Run all tests
npm test

# Run specific test suite
npm test -- charge

# Generate coverage report
npm run test:coverage

TypeScript Support

This library is written in TypeScript and provides full type definitions. No additional @types packages are needed.

// Full IntelliSense and type checking
const charge: Charge = await client.chargeOperation().create(params);
const status: TransactionStatus = charge.status;

Support

For support and questions, please contact the support team or create an issue in the project repository.