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 (Agentic Implementation)

Paste the following text in Claude/Cursor/Codex/etc.:

Create a payment intent using @orchestrapay/sdk with the amount we're trying to charge the customer. Read more instructions here: https://www.npmjs.com/package/@orchestrapay/sdk

Usage (Manual Implementation)

Basic Example

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

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

// 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.v202607
);

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

The API version is required when creating the client. Pinning to an explicit version means API releases that are not backward compatible (for example, the failure_url/success_url to return_url change) never break your integration silently:

const orchestrapay = new Orchestrapay(
  'orch_sk_test_...',
  ApiVersion.v202607  // Required since SDK v2
);

Supported versions: v202502, v202606, v202607. The constructor throws if the version is missing or unknown.

Migrating from SDK v1

In SDK v1 the version was optional and defaulted to the latest API version. In v2 you must pass it explicitly:

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

// v2
import Orchestrapay, { ApiVersion } from '@orchestrapay/sdk';
const orchestrapay = new Orchestrapay('orch_sk_test_...', ApiVersion.v202607);

If you relied on the v1 default, it used the latest version at request time, so pin to the current latest (ApiVersion.v202607) for identical behavior going forward.

Custom Logger

Add debugging with a custom logger:

const orchestrapay = new Orchestrapay(
  'orch_sk_test_...',
  ApiVersion.v202607,
  {
    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: {                 // Optional: cus_ ref, or upsert by `reference`
    reference: 'user_42',
    email: '[email protected]',
  },
  idempotency_key: 'key_123', // Optional: idempotency key
  metadata: {                 // Optional: echoed back on webhooks
    order_id: '12345'
  },
  webhooks: [                 // Optional: per-endpoint url + secret + events
    {
      url: 'https://example.com/webhooks/orchestrapay',
      secret: 'your_webhook_secret',
      events: ['payment.success', 'payment.canceled']
    }
  ],
  return_url: 'https://example.com/return', // Optional: hosted-page return URL
  timeout: 3600               // Optional: seconds until auto-cancel
});

// paymentIntent.payment_intent -> "pi_eu1_..."; paymentIntent.url -> hosted page

Retrieve a Payment Intent

const paymentIntent = await orchestrapay.paymentIntents.retrieve('pi_eu1_...');

List Payment Intents

const { data, has_more } = await orchestrapay.paymentIntents.list({
  limit: 25,
  status: 'success',
  created: { gte: 1704067200 },
});

Cancel a Payment Intent

const canceled = await orchestrapay.paymentIntents.cancel('pi_eu1_...');

Refunds

Create a Refund

const refund = await orchestrapay.refunds.create({
  payment_intent: 'pi_eu1_...', // Required: the payment intent to refund
  amount: 5000,                  // Required: amount in cents
  currency: 'usd',               // Required: must match the payment
});
// refund.refund -> "re_eu1_..."; refund.refundable_amount_left

Retrieve a Refund

const refund = await orchestrapay.refunds.retrieve('re_eu1_...');

List Refunds

const { data, has_more } = await orchestrapay.refunds.list({
  payment_intent: 'pi_eu1_...',
});

Customers

// Create, or update the existing one matched by `reference` (upsert)
const { customer } = await orchestrapay.customers.create({
  reference: 'user_42',
  email: '[email protected]',
});

const c = await orchestrapay.customers.retrieve(customer);
await orchestrapay.customers.update(customer, { first_name: 'Ada' });
const { data } = await orchestrapay.customers.list({ email: '[email protected]' });
await orchestrapay.customers.del(customer);

Webhooks

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

Configuring Webhooks

When creating a payment intent (or refund) you can attach multiple endpoints, each with its own secret and event subscriptions:

const paymentIntent = await orchestrapay.paymentIntents.create({
  amount: 10000,
  currency: 'usd',
  webhooks: [
    {
      url: 'https://api.example.com/webhooks/payments',
      secret: 'your_payments_secret',
      events: ['payment.success', 'payment.canceled', 'payment.attempt_failed']
    }
  ]
});

Supported Webhook Events

Payment (intent-level) Events

• payment.success - the intent was paid (terminal / immutable)
• payment.canceled - the intent was canceled or timed out (terminal / immutable)
• payment.attempt_failed - a single attempt failed; the intent is still open

Refund Events

• refund.pending - refund created, awaiting completion
• refund.success - refund completed
• refund.canceled - refund canceled or rejected

Verifying Webhooks

Orchestrapay does not HMAC-sign payloads. Each request carries the endpoint's secret in the Orchestrapay-Webhook-Secret header; compare it (constant-time) with verifyWebhookSecret:

import express from 'express';
import { verifyWebhookSecret, WEBHOOK_SECRET_HEADER } from '@orchestrapay/sdk';

const app = express();

app.post('/webhooks/orchestrapay', express.json(), (req, res) => {
  const received = req.headers[WEBHOOK_SECRET_HEADER];
  if (!verifyWebhookSecret(received, process.env.ORCHESTRAPAY_WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid webhook secret');
  }

  const event = req.body; // { id, type, created_at, data }
  switch (event.type) {
    case 'payment.success':
      console.log('Paid:', event.data.payment_intent);
      // Fulfill order, send receipt, etc.
      break;
    case 'payment.canceled':
      console.log('Canceled:', event.data.payment_intent);
      break;
  }

  // Respond 2xx quickly (within ~3s) before any heavy processing.
  res.status(200).send('OK');
});

Webhook Event Structure

Webhooks arrive as a Stripe-style envelope:

{
  id: string;          // Unique event id (evt_...); dedupe on this
  type: string;        // e.g. "payment.success"
  created_at: string;  // ISO 8601 timestamp
  data: object;        // The resource (payment / refund / payout)
}

Deliveries are at-least-once and unordered; deduplicate on event.id.

TypeScript Types for Webhooks

import {
  WebhookEvent,
  PaymentWebhookEvent,
  RefundWebhookEvent,
  verifyWebhookSecret,
  WEBHOOK_SECRET_HEADER,
} from '@orchestrapay/sdk';

// Type-safe, discriminated on `type`
function handleWebhook(event: WebhookEvent) {
  if (event.type === 'payment.success') {
    const paymentIntentId = event.data.payment_intent;
    // Handle success...
  }
}

Best Practices

1. Verify the secret - Reject requests whose Orchestrapay-Webhook-Secret header doesn't match
2. Use HTTPS - Webhook URLs must use HTTPS in production
3. Respond quickly - Return a 2xx within ~3 seconds, before any heavy processing
4. Handle idempotency - Process each event only once using event.id
5. Handle retries - Orchestrapay retries with exponential backoff for up to 3 days
6. Don't rely on order - Events may arrive out of order; trust the object's status

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

Error Handling

The SDK throws OrchestrapayError instances for all API errors:

import { OrchestrapayError, OrchestrapayErrorType } from '@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,
  Customer,
  CustomerCreateParams,
  OrchestrapayError,
  OrchestrapayErrorType,
  WebhookEvent,
  PaymentWebhookEvent,
  RefundWebhookEvent,
  verifyWebhookSecret,
  WEBHOOK_SECRET_HEADER,
} 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.