Package Exports
- @orchestrapay/sdk
- @orchestrapay/sdk/types
Readme
Orchestrapay Node.js SDK
The official Node.js library for the Orchestrapay API.
Supercharge your checkout with Orchestrapay today.
Installation
npm install @orchestrapay/sdkUsage
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 createdpayment_intent.succeeded- Payment completed successfullypayment_intent.failed- Payment failed
Refund Events
refund.created- Refund was createdrefund.succeeded- Refund completed successfullyrefund.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
- Always verify signatures - Never trust webhook data without verification
- Use HTTPS - Webhook URLs must use HTTPS in production
- Respond quickly - Return 200 status within 5 seconds
- Handle idempotency - Process each event only once using
event.id - Handle retries - Orchestrapay will retry failed webhooks
- 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 errorAUTHENTICATION_ERROR- Invalid API keyCARD_ERROR- Card-specific errorIDEMPOTENCY_ERROR- Idempotency key conflictINVALID_REQUEST_ERROR- Invalid parametersRATE_LIMIT_ERROR- Rate limit exceededVALIDATION_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 buildClean
npm run cleanContributing
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 buildSupport
- Documentation: https://docs.orchestrapay.com
- Email: support@orchestrapay.com
- 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.