Orchestrapay Node.js SDK

The official Node.js library for the Orchestrapay API.

Supercharge your checkout with Orchestrapay today.

Installation

npm install @orchestrapay/sdk

Usage

Basic Example

const Orchestrapay = require('@orchestrapay/sdk');

const orchestrapay = new Orchestrapay('orch_sk_test_...');

// Create a payment intent
const paymentIntent = await orchestrapay.paymentIntents.create({
  amount: 10000, // Amount in cents ($100.00)
  currency: 'usd',
  customer: 'cus_abc123', // Customer reference
  metadata: {
    order_id: '12345'
  }
});

console.log(paymentIntent.payment_intent);

TypeScript Example

import Orchestrapay, { ApiVersion, PaymentIntentCreateResponse } from '@orchestrapay/sdk';

const orchestrapay = new Orchestrapay(
  'orch_sk_test_...',
  ApiVersion.v202502
);

const response: PaymentIntentCreateResponse = await orchestrapay.paymentIntents.create({
  amount: 10000,
  currency: 'usd',
});

console.log(response.payment_intent); // "pi_abc123..."

API Key

Get your API key from the Orchestrapay Dashboard.

API keys follow this format:

• Test mode: orch_sk_test_...
• Live mode: orch_sk_live_...

Configuration

API Version

Specify the API version when creating the client:

const orchestrapay = new Orchestrapay(
  'orch_sk_test_...',
  ApiVersion.v202502  // Optional, defaults to latest
);

Custom Logger

Add debugging with a custom logger:

const orchestrapay = new Orchestrapay(
  'orch_sk_test_...',
  ApiVersion.v202502,
  {
    logger: (level, data) => {
      if (level === 'error') {
        console.error('[Orchestrapay Error]', data);
      } else if (process.env.DEBUG) {
        console.log(`[Orchestrapay ${level}]`, data);
      }
    }
  }
);

API Reference

Payment Intents

Create a Payment Intent

const paymentIntent = await orchestrapay.paymentIntents.create({
  amount: 10000,              // Required: Amount in cents
  currency: 'usd',            // Required: ISO currency code
  customer: 'cus_abc123',     // Optional: Customer reference
  idempotency_key: 'key_123', // Optional: Idempotency key
  metadata: {                 // Optional: Custom metadata
    order_id: '12345'
  },
  webhooks: [                 // Optional: Webhook configurations
    {
      url: 'https://example.com/webhooks/orchestrapay',
      secret: 'whsec_your_secret_here',
      events: ['payment_intent.succeeded', 'payment_intent.failed']
    }
  ],
  timeout: 3600               // Optional: Timeout in seconds
});

Retrieve a Payment Intent

const paymentIntent = await orchestrapay.paymentIntents.get('pi_abc123...');

Refunds

Create a Refund

const refund = await orchestrapay.refunds.create({
  payment_intent: 'pi_abc123...', // Required: Payment intent to refund
  amount: 5000,                    // Optional: Amount to refund (defaults to full)
  reason: 'requested_by_customer', // Optional: Refund reason
  metadata: {                      // Optional: Custom metadata
    reason_code: 'RMA-123'
  }
});

Retrieve a Refund

const refund = await orchestrapay.refunds.get('re_abc123...');

Webhooks

Webhooks allow you to receive real-time notifications about events in your Orchestrapay account.

Configuring Webhooks

When creating a payment intent, you can configure multiple webhook endpoints with different event subscriptions:

const paymentIntent = await orchestrapay.paymentIntents.create({
  amount: 10000,
  currency: 'usd',
  webhooks: [
    {
      url: 'https://api.example.com/webhooks/payments',
      secret: 'whsec_main_secret',
      events: [
        'payment_intent.created',
        'payment_intent.succeeded',
        'payment_intent.failed'
      ]
    },
    {
      url: 'https://api.example.com/webhooks/refunds',
      secret: 'whsec_refunds_secret',
      events: [
        'refund.created',
        'refund.succeeded',
        'refund.failed'
      ]
    }
  ]
});

Supported Webhook Events

Payment Intent Events

• payment_intent.created - Payment intent was created
• payment_intent.succeeded - Payment completed successfully
• payment_intent.failed - Payment failed

Refund Events

• refund.created - Refund was created
• refund.succeeded - Refund completed successfully
• refund.failed - Refund failed

Verifying Webhook Signatures

Always verify webhook signatures to ensure requests are coming from Orchestrapay:

const express = require('express');
const { verifyWebhookSignature } = require('@orchestrapay/sdk');

const app = express();

// Use express.raw() to preserve the raw body for signature verification
app.post('/webhooks/orchestrapay',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-orchestrapay-signature'];
    const rawBody = req.body.toString();

    // Verify the signature
    const isValid = verifyWebhookSignature(
      rawBody,
      signature,
      'whsec_your_webhook_secret'
    );

    if (!isValid) {
      console.error('Invalid webhook signature');
      return res.status(401).send('Invalid signature');
    }

    // Parse and handle the webhook
    const payload = JSON.parse(rawBody);
    
    switch (payload.event) {
      case 'payment_intent.succeeded':
        console.log('Payment succeeded:', payload.data.payment_intent);
        // Fulfill order, send receipt, etc.
        break;
      
      case 'payment_intent.failed':
        console.log('Payment failed:', payload.data.payment_intent);
        // Notify customer, retry payment, etc.
        break;
    }

    // Always respond with 200 to acknowledge receipt
    res.status(200).send('OK');
  }
);

Webhook Payload Structure

{
  id: string;              // Unique event ID
  event: WebhookEvent;     // Event type
  created: number;         // Unix timestamp
  data: object;            // Event data (PaymentIntent, Refund, etc.)
  api_version: string;     // API version
}

TypeScript Types for Webhooks

import {
  WebhookEvent,
  WebhookConfig,
  PaymentIntentWebhookPayload,
  RefundWebhookPayload,
  verifyWebhookSignature,
} from '@orchestrapay/sdk';

// Type-safe webhook handler
function handleWebhook(payload: PaymentIntentWebhookPayload) {
  if (payload.event === 'payment_intent.succeeded') {
    const paymentIntentId = payload.data.payment_intent;
    // Handle success...
  }
}

Best Practices

1. Always verify signatures - Never trust webhook data without verification
2. Use HTTPS - Webhook URLs must use HTTPS in production
3. Respond quickly - Return 200 status within 5 seconds
4. Handle idempotency - Process each event only once using event.id
5. Handle retries - Orchestrapay will retry failed webhooks
6. Use raw body parser - Required for signature verification

See examples/webhooks-example.js for a complete webhook implementation.

Error Handling

The SDK throws OrchestrapayError instances for all API errors:

const { OrchestrapayError, OrchestrapayErrorType } = require('@orchestrapay/sdk');

try {
  const paymentIntent = await orchestrapay.paymentIntents.create({
    amount: 10000,
    currency: 'usd',
  });
} catch (error) {
  if (error instanceof OrchestrapayError) {
    console.error('Type:', error.type);
    console.error('Message:', error.message);
    console.error('Request ID:', error.requestId);
    console.error('Status Code:', error.statusCode);
    
    switch (error.type) {
      case OrchestrapayErrorType.AUTHENTICATION_ERROR:
        // Handle authentication error
        break;
      case OrchestrapayErrorType.INVALID_REQUEST_ERROR:
        // Handle invalid request
        break;
      case OrchestrapayErrorType.RATE_LIMIT_ERROR:
        // Handle rate limit
        break;
      default:
        // Handle other errors
    }
  }
}

Error Types

• API_ERROR - General API error
• AUTHENTICATION_ERROR - Invalid API key
• CARD_ERROR - Card-specific error
• IDEMPOTENCY_ERROR - Idempotency key conflict
• INVALID_REQUEST_ERROR - Invalid parameters
• RATE_LIMIT_ERROR - Rate limit exceeded
• VALIDATION_ERROR - Validation failed

TypeScript Support

The SDK is written in TypeScript and includes complete type definitions.

Import Types

import Orchestrapay, {
  ApiVersion,
  PaymentIntent,
  PaymentIntentCreateParams,
  PaymentIntentCreateResponse,
  Refund,
  RefundCreateParams,
  OrchestrapayError,
  OrchestrapayErrorType,
  WebhookEvent,
  WebhookConfig,
  PaymentIntentWebhookPayload,
  RefundWebhookPayload,
  verifyWebhookSignature,
} from '@orchestrapay/sdk';

Type-only Import

import type {
  PaymentIntent,
  PaymentIntentCreateResponse,
  Refund
} from '@orchestrapay/sdk/types';

Node.js Version Support

Runtime: This SDK supports Node.js 12.0.0 and above (tested via CI smoke tests).

Development: Contributing to this SDK requires Node.js 16+ for development tools (Jest, TypeScript, etc.). Your customers can still use Node.js 12+.

CI Testing:

• Full test suite (Jest): Node.js 16.x, 18.x, 20.x
• Smoke tests: Node.js 12.x, 14.x

Development

Build

npm run build

Clean

npm run clean

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• How to make commits using Conventional Commits
• Our semantic versioning and release process
• Development workflow and testing
• DTO naming conventions

Quick start for contributors:

# Install dependencies
npm install

# Make changes and commit using commitizen
npm run commit

# Build
npm run build

Support

• Documentation: https://docs.orchestrapay.com
• Email: [email protected]
• GitHub Issues: https://github.com/orchestrapay/npm-sdk/issues

License

Proprietary - Copyright (c) 2025 Orchestrapay, LLC. All Rights Reserved.

This SDK is provided for use with Orchestrapay services only. See the LICENSE file for full terms.