@devhubpty/cybersource

SDK for CyberSource 3DS payment integration with card tokenization, vaulting, and payment processing.

Built for Panama e-commerce platforms. Supports the complete CyberSource payment lifecycle: 3D Secure authentication (frictionless + challenge), card tokenization (TMS), authorize + capture payments, refunds, and voids.

Installation

pnpm add @devhubpty/cybersource @devhubpty/core

Quick Start

Server (Node.js / Express / Next.js API)

import {
  CyberSourceClient,
  CyberSourceEnvironment,
} from '@devhubpty/cybersource/server';

const client = new CyberSourceClient({
  merchantId: process.env.CYBERSOURCE_MERCHANT_ID!,
  keyId: process.env.CYBERSOURCE_KEY!,
  sharedSecretKey: process.env.CYBERSOURCE_SHARED_SECRET_KEY!,
  environment: CyberSourceEnvironment.Test,
});

// Create customer
const customer = await client.createCustomer({ customerId: 'user-123', email: '[email protected]' });

// Tokenize card (2-step)
const ii = await client.createInstrumentIdentifier({ cardNumber: '4111111111111111', securityCode: '123' });
const pi = await client.createPaymentInstrument({ cybersourceCustomerId: customer.id, instrumentIdentifierTokenId: ii.id, ... });

// 3DS authentication (3-step)
const setup = await client.setupAuthentication({ cybersourceCustomerId: customer.id, paymentInstrumentId: pi.id });
const enrollment = await client.checkEnrollment({ referenceId: setup.consumerAuthenticationInformation.referenceId, ... });
// If challenge: const validation = await client.validateAuthentication({ authenticationTransactionId: '...' });

// Process payment
const payment = await client.processPayment({ totalAmount: '25.99', currency: 'USD', auth3DSResult: { ... }, ... });

React (Browser)

import { useThreeDS, ThreeDSModal, ThreeDSStep } from '@devhubpty/cybersource/react';

function Checkout() {
  const threeDS = useThreeDS({
    onSetup: (p) => fetch('/api/cybersource/setup', { method: 'POST', body: JSON.stringify(p) }).then(r => r.json()).then(r => r.data),
    onCheckEnrollment: (p) => fetch('/api/cybersource/enroll', { method: 'POST', body: JSON.stringify(p) }).then(r => r.json()).then(r => r.data),
    onValidate: (p) => fetch('/api/cybersource/validate', { method: 'POST', body: JSON.stringify(p) }).then(r => r.json()).then(r => r.data),
  });

  return (
    <>
      <button onClick={() => threeDS.startAuth({ paymentInstrumentId: '...', cybersourceId: '...', amount: '25.99', currency: 'USD', billingAddress: { ... }, returnUrl: '...' })}>
        Pay
      </button>

      {threeDS.challengeRequired && (
        <ThreeDSModal
          challengeUrl={threeDS.challengeUrl!}
          challengeJwt={threeDS.challengeJwt!}
          onComplete={() => threeDS.completeChallenge('...')}
          onCancel={() => threeDS.reset()}
        />
      )}

      {threeDS.step === ThreeDSStep.Ready && <p>Authenticated! Ready to pay.</p>}
    </>
  );
}

Package Exports

| Import | Environment | Description | |--------|-------------|-------------| | @devhubpty/cybersource/server | Node.js | CyberSourceClient, cache, promisify, types | | @devhubpty/cybersource/react | Browser | Hooks, ThreeDSModal, types |

Documentation

• Getting Started
• Flow Diagrams (Mermaid)
• Integration Guide
• API Reference
• Environment Variables
• Database Model

Examples

• Express routes
• Express 3DS flow
• Next.js API routes
• Next.js checkout page
• React Native 3DS challenge

Environment Variables

| Variable | Description | |----------|-------------| | CYBERSOURCE_MERCHANT_ID | Merchant ID | | CYBERSOURCE_KEY | Key ID (UUID) for http_signature | | CYBERSOURCE_SHARED_SECRET_KEY | Shared secret (base64) | | CYBERSOURCE_RUN_ENVIRONMENT | apitest.cybersource.com or api.cybersource.com |

License

MIT

Contributors

• captainsparrow10
• Reddsito