DocsJavaScript SDK

JavaScript SDK

The official PayHub SDK for JavaScript and TypeScript. Full type safety, automatic retries, and idempotent requests.

TypeScript First

Full type definitions included

Auto Retry

Exponential backoff on failures

Idempotent

Safe retries with idempotency keys

Installation

Terminal

# npm
npm install @payhub/sdk

# yarn
yarn add @payhub/sdk

# pnpm
pnpm add @payhub/sdk

Initialization

app.ts

import { PayHubClient } from '@payhub/sdk';

const client = new PayHubClient({
  apiKey: process.env.PAYHUB_API_KEY,
  environment: 'sandbox', // or 'production'
});

Environments

Use sandbox for testing and production for live transactions.

Payments

Create and manage payments with the client.payments resource:

TypeScript

// Create a payment
const payment = await client.payments.create({
  amount: '100.00',
  currency: 'USDC',
  network: 'polygon',
  description: 'Order #12345',
  metadata: { orderId: '12345' },
});

// Get a payment
const payment = await client.payments.get('pay_abc123');

// List payments
const payments = await client.payments.list({
  limit: 20,
  status: 'completed',
});

// Get payment history
const history = await client.payments.getHistory('pay_abc123');

Webhook Verification

Verify webhook signatures to ensure authenticity:

TypeScript

// Verify webhook signature
const isValid = client.webhooks.verifySignature({
  payload: rawBody,
  signature: headers['x-payhub-signature'],
  timestamp: headers['x-payhub-timestamp'],
  secret: process.env.WEBHOOK_SECRET,
});

Networks

Query available networks and their status:

TypeScript

// List available networks
const networks = await client.networks.list();

// Check network status
const status = await client.networks.getStatus('polygon');

Error Handling

The SDK throws typed errors for different failure scenarios:

TypeScript

import { PayHubError, RateLimitError } from '@payhub/sdk';

try {
  const payment = await client.payments.create({ ... });
} catch (error) {
  if (error instanceof RateLimitError) {
    // Wait and retry
    await sleep(error.retryAfter);
    return retry();
  }

  if (error instanceof PayHubError) {
    console.error('API Error:', error.code, error.message);
  }

  throw error;
}

PayHubError

Base error class for all API errors

RateLimitError

Too many requests. Check retryAfter for wait time.

AuthenticationError

Invalid or missing API key

ValidationError

Invalid request parameters

TypeScript Support

Full type definitions are included. Import types for enhanced IDE support:

TypeScript

import type {
  Payment,
  PaymentStatus,
  CreatePaymentRequest,
  WebhookEvent,
  Network,
} from '@payhub/sdk';

// Full TypeScript support
const handlePayment = (payment: Payment) => {
  if (payment.status === 'completed') {
    fulfillOrder(payment.metadata.orderId);
  }
};

Networks REST API