Sadad Payment Client

A Node.js client library for the Sadad Payment API, providing easy-to-use methods for managing payment orders.

Installation

npm install sadad-payment-client

Features

• ✅ Full TypeScript support with type definitions
• ✅ Promise-based API with async/await
• ✅ Complete Payment Orders API coverage
• ✅ Built-in authentication (API Key)
• ✅ Automatic error handling
• ✅ Configurable base URL and timeout

Quick Start

import { SadadClient } from 'sadad-payment-client';

// Initialize the client
const client = new SadadClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.sadad.example.com', // Optional
  timeout: 30000 // Optional, default 30000ms
});

Usage Examples

Create a Payment Order

const order = await client.paymentOrders.create({
  merchantId: 'merchant-uuid',
  amount: 100.50,
  description: 'Payment for order #123',
  merchantReferance: 'ORDER-123',
  successRedirectUrl: 'https://yoursite.com/payment/success',
  failureRedirectUrl: 'https://yoursite.com/payment/failure',
  expiresInMinutes: 60, // Optional
  metadata: JSON.stringify({ orderId: '123' }) // Optional
});

if (order.isApiSuccess) {
  console.log('Payment Link:', order.response?.paymentLink);
  console.log('Order ID:', order.response?.id);
  console.log('Order Identifier:', order.response?.orderIdentifier);
} else {
  console.error('Error:', order.message);
}

Get Payment Order by Identifier

const order = await client.paymentOrders.getByIdentifier(
  'order-identifier',
  true // skipPreview
);

if (order.isApiSuccess) {
  console.log('Order Status:', order.response?.status);
  console.log('Amount:', order.response?.amount);
  console.log('Merchant:', order.response?.merchantDisplayName);
}

Get Payment Order by Merchant Reference

const order = await client.paymentOrders.getByMerchantReference(
  'merchant-uuid',
  'ORDER-123'
);

if (order.isApiSuccess) {
  console.log('Order found:', order.response);
}

List Payment Orders for a Merchant

const orders = await client.paymentOrders.listByMerchant(
  'merchant-uuid',
  {
    begin: 0,        // Starting index (default: 0)
    count: 20,       // Number of items (default: 20)
    status: 'paid'   // Optional: filter by status
  }
);

if (orders.isApiSuccess) {
  console.log('Total Orders:', orders.totalCount);
  console.log('Page Count:', orders.pageCount);
  
  orders.response?.forEach(order => {
    console.log(`Order ${order.id}: ${order.amount} ${order.currency} - ${order.status}`);
  });
}

Cancel a Payment Order

const result = await client.paymentOrders.cancel({
  orderId: 'order-uuid',
  cancelReason: 'Customer requested cancellation'
});

if (result.isApiSuccess) {
  console.log('Order cancelled successfully');
} else {
  console.error('Cancellation failed:', result.message);
}

Get Internal Order Details

const details = await client.paymentOrders.getInternalById('order-uuid');

if (details.isApiSuccess) {
  console.log('Order Details:', details.response);
}

API Reference

SadadClient

Main client class for interacting with the Sadad API.

Constructor Options

interface SadadClientConfig {
  apiKey?: string;        // API Key for authentication
  baseUrl?: string;       // Base URL (optional)
  timeout?: number;       // Request timeout in ms (default: 30000)
}

Note: apiKey must be provided.

PaymentOrdersApi

All payment order operations are available through client.paymentOrders:

Methods

• create(request) - Create a new payment order
• getByIdentifier(orderIdentifier, skipPreview?) - Get order by identifier
• getByMerchantReference(merchantId, merchantReference) - Get order by merchant reference
• getInternalById(orderId) - Get internal order details
• listByMerchant(merchantId, options?) - List orders for a merchant with pagination
• cancel(request) - Cancel a payment order

Types

CreatePaymentOrderRequest

interface CreatePaymentOrderRequest {
  merchantId: string;              // Required: UUID of merchant
  amount: number;                  // Required: Payment amount (min: 0.01)
  successRedirectUrl: string;      // Required: Success redirect URL
  failureRedirectUrl: string;      // Required: Failure redirect URL
  description?: string;            // Optional: Max 250 chars
  merchantReferance?: string;      // Optional: Max 100 chars
  metadata?: string;               // Optional: Any metadata
  expiresInMinutes?: number;       // Optional: Min 1
}

PaymentOrderResponse

interface PaymentOrderResponse {
  id: string;
  merchantDisplayName: string;
  logoUrl: string;
  providerType: string;
  orderIdentifier: string;
  paymentLink: string;
  amount: number;
  status: string;
  description: string;
  metadata: string;
  createdAt: string;
  expiresAt: string;
  merchantReference: string;
  successRedirectUrl: string;
  failureRedirectUrl: string;
}

CancelPaymentOrderRequest

interface CancelPaymentOrderRequest {
  orderId: string;           // Required: UUID of order
  cancelReason: string;      // Required: Max 250 chars
}

Error Handling

The client automatically handles errors and provides meaningful error messages:

try {
  const order = await client.paymentOrders.create(orderRequest);
  
  if (!order.isApiSuccess) {
    console.error('API Error:', order.errorCodeStr, order.message);
  }
} catch (error) {
  console.error('Request failed:', error.message);
}

Authentication

The Sadad API supports two authentication methods:

API Key - Passed as X-API-Key header

You can provide either or both in the client configuration.

Development

Build

npm run build

This compiles TypeScript files from src/ to dist/.

Project Structure

sadad-payment-client/
├── src/
│   ├── index.ts              # Main entry point
│   ├── sadad-client.ts       # Main client class
│   ├── payment-orders.ts     # Payment Orders API
│   ├── http-client.ts        # HTTP client wrapper
│   └── types.ts              # TypeScript interfaces
├── dist/                     # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md

License

MIT

Support

For issues and questions, please refer to the Sadad API documentation or contact support.