@infinitesolutions/cybersource-rest-client

A modern TypeScript/JavaScript client library for the CyberSource REST API, generated using swagger-typescript-api. This package provides type-safe access to all CyberSource payment processing and merchant services APIs with native fetch support and zero external dependencies.

📋 Overview

This client library is auto-generated from the CyberSource API specification using swagger-typescript-api. It includes comprehensive TypeScript definitions, uses native fetch API, and supports all CyberSource REST API endpoints.

✨ Features

• 🎯 Modern Architecture: Built with swagger-typescript-api using native fetch
• 🛡️ Type Safety: Full TypeScript support with comprehensive type definitions
• 📦 Zero Dependencies: No external runtime dependencies required
• 🔌 Single API Class: Simplified interface with organized endpoint groupings
• 🚀 NestJS Integration: Dedicated NestJS module available
• 🌐 Cross-Platform: Works in Node.js and modern browsers

🚀 NestJS Integration

For NestJS applications, we provide a dedicated module with built-in HTTP Signature authentication:

npm install @infinitesolutions/cybersource-nestjs

The NestJS package automatically handles:

• ✅ HTTP Signature authentication (RFC compliant)
• ✅ Request body hashing (SHA-256)
• ✅ Header generation and validation
• ✅ Secure credential management
• ✅ Error handling and logging

See the nestjs/ directory for complete documentation and examples.

🚀 Installation

As a Package Dependency

To use this package in another project, you can install it directly from the repository:

# Install from GitHub repository
npm install git+https://github.com/tsee9iii/cybersource-rest-client.git

# Or if you publish to npm
npm install @infinitesolutions/cybersource-rest-client

Manual Installation

git clone https://github.com/tsee9iii/cybersource-rest-client.git
cd cybersource-rest-client
npm install

🛠️ Setup

Before using the client, you'll need to configure your CyberSource credentials and merchant information.

Authentication

The library supports CyberSource's HTTP Signature authentication. You'll need:

• Merchant ID
• API Key ID (keyid)
• Shared Secret Key (Base64 encoded)

Important: For proper security implementation, use the NestJS package (@infinitesolutions/cybersource-nestjs) which includes automatic HTTP Signature authentication according to CyberSource specifications.

📖 Usage

Basic Import

import { Api } from "@infinitesolutions/cybersource-rest-client";

Initialize API Client

import { Api } from "@infinitesolutions/cybersource-rest-client";

// Configure the API client with HTTP Signature authentication
const cyberSourceApi = new Api({
  baseUrl: "https://apitest.cybersource.com", // Sandbox
  // baseUrl: "https://api.cybersource.com", // Production
  securityWorker: (securityData: any) => {
    // HTTP Signature authentication is handled by the NestJS package
    // For direct usage, implement authentication headers here
    return {
      // Your authentication headers would go here
      // See the NestJS package for a complete implementation
    };
  },
});

⚠️ Security Note: For production use, we strongly recommend using the NestJS package (@infinitesolutions/cybersource-nestjs) which includes built-in HTTP Signature authentication according to CyberSource's security requirements.

Example: Process a Payment

import { Api } from "@infinitesolutions/cybersource-rest-client";

const cyberSourceApi = new Api({
  baseUrl: "https://apitest.cybersource.com",
});

const paymentRequest = {
  clientReferenceInformation: {
    code: "TC50171_3",
  },
  processingInformation: {
    capture: false,
  },
  paymentInformation: {
    card: {
      number: "4111111111111111",
      expirationMonth: "12",
      expirationYear: "2031",
      securityCode: "123",
    },
  },
  orderInformation: {
    amountDetails: {
      totalAmount: "102.21",
      currency: "USD",
    },
    billTo: {
      firstName: "John",
      lastName: "Doe",
      address1: "1 Market St",
      locality: "san francisco",
      administrativeArea: "CA",
      postalCode: "94105",
      country: "US",
      email: "[email protected]",
      phoneNumber: "4158880000",
    },
  },
};

try {
  const response = await cyberSourceApi.pts.createPayment(paymentRequest);
  console.log("Payment processed successfully:", response.data);
} catch (error) {
  console.error("Payment failed:", error);
}

🎯 Available API Endpoints

This client provides access to all CyberSource REST API endpoints through organized namespaces:

Core Payment Processing (pts)

// Payment operations
cyberSourceApi.pts.createPayment(request);
cyberSourceApi.pts.capturePayment(id, request);
cyberSourceApi.pts.refundPayment(id, request);
cyberSourceApi.pts.voidPayment(id, request);
cyberSourceApi.pts.incrementAuth(id, request);

Token Management Service (tms)

// Customer and token management
cyberSourceApi.tms.createCustomer(request);
cyberSourceApi.tms.getCustomer(customerId);
cyberSourceApi.tms.updateCustomer(customerId, request);
cyberSourceApi.tms.deleteCustomer(customerId);

Risk Management (risk)

// Decision manager and fraud screening
cyberSourceApi.risk.createDecision(request);
cyberSourceApi.risk.addNegative(request);

Reporting

// Reports and transaction details
cyberSourceApi.reporting.searchTransactions(request);
cyberSourceApi.reporting.getTransactionDetails(id);

Subscription & Recurring Billing

• SubscriptionsApi - Subscription management
• SubscriptionsFollowOnsApi - Follow-on subscription operations
• PlansApi - Subscription plan management
• InvoicesApi - Invoice management
• InvoiceSettingsApi - Invoice configuration

Risk & Authentication

• PayerAuthenticationApi - 3D Secure authentication
• DecisionManagerApi - Fraud management
• VerificationApi - Card verification

Reporting & Analytics

• ReportsApi - Generate and retrieve reports
• ReportDefinitionsApi - Report configuration
• ReportDownloadsApi - Download reports
• ReportSubscriptionsApi - Report subscriptions
• TransactionDetailsApi - Transaction information
• SearchTransactionsApi - Transaction search

Merchant Services

• MerchantBoardingApi - Merchant onboarding
• BatchesApi - Batch processing
• SecureFileShareApi - File management
• WebhooksApi - Webhook management

Additional Services

• BinLookupApi - Bank identification number lookup
• TaxesApi - Tax calculation
• MicroformIntegrationApi - Secure acceptance
• UnifiedCheckoutCaptureContextApi - Unified checkout

And many more specialized APIs for comprehensive payment processing needs.

🔧 Configuration

Environment Setup

// Sandbox environment (for testing)
const basePath = "https://apitest.cybersource.com";

// Production environment
const basePath = "https://api.cybersource.com";

TypeScript Configuration

This package includes full TypeScript definitions. Make sure your tsconfig.json includes:

{
  "compilerOptions": {
    "target": "es2017",
    "module": "commonjs",
    "lib": ["es2017"],
    "declaration": true,
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

📚 Documentation

• CyberSource API Documentation
• CyberSource Developer Center
• Authentication Guide

🔒 Security Notes

• Never commit your API credentials to version control
• Use environment variables for sensitive configuration
• Always validate and sanitize input data
• Use HTTPS endpoints only
• Implement proper error handling for production use

🐛 Error Handling

import { PaymentsApi } from "@infinitesolutions/cybersource-rest-client";

try {
  const response = await paymentsApi.createPayment(paymentRequest);
  // Handle successful response
} catch (error) {
  if (error.response) {
    // API responded with error status
    console.error("API Error:", error.response.statusCode);
    console.error("Error details:", error.body);
  } else {
    // Network or other error
    console.error("Request failed:", error.message);
  }
}

🤝 Contributing

This is an auto-generated client library. For issues or feature requests related to the CyberSource API itself, please contact CyberSource support.

For issues specific to this TypeScript client:

1. Check the CyberSource API documentation
2. Verify your authentication configuration
3. Ensure you're using the correct API endpoint (sandbox vs production)

📄 License

This project follows CyberSource's API terms of service. Please refer to the CyberSource Developer Agreement for usage terms.

⚡ Generated Information

• Generator: Swagger Codegen v2.4.49
• API Version: 0.0.1 (CyberSource Merged Spec)
• Generated: Auto-generated from CyberSource OpenAPI specifications
• Base URL: https://apitest.cybersource.com (sandbox) / https://api.cybersource.com (production)

🔗 Related Resources

• CyberSource Developer Guides
• CyberSource SDK Samples
• Payment Processing Best Practices

Note: This is an unofficial client library generated from CyberSource's public API specifications. For official SDKs and support, please visit the CyberSource Developer Center.