Sir CharglyDocumentation
SC
Sir Chargly
Back to Documentation

Sir Chargly SDK Reference

Complete reference for the @sirchargly/sdk package.

Installation

npm install @sirchargly/sdk
# or
yarn add @sirchargly/sdk

Quick Start

import SirChargly from '@sirchargly/sdk';

const client = new SirChargly('sk_dev_sirchargly_your_api_key');

// Create a fee estimate
const estimate = await client.estimates.create({
  amount: 10000,
  currency: 'USD',
  region: 'US-CA'
});

Client Initialization

`new SirChargly(apiKey, config?)`

Creates a new Sir Chargly client instance.

Parameters:

  • apiKey (string, required): Your Sir Chargly API key
  • config (object, optional):

    • - baseUrl (string): Custom API base URL (default: https://api.sirchargly.com)

    - timeout (number): Request timeout in milliseconds (default: 30000)

    - apiVersion (string): API version (default: '2025-01')

    Example:

    const client = new SirChargly('sk_dev_sirchargly_your_api_key', {
  timeout: 60000,
  apiVersion: '2025-01'
});

    Estimates Resource

    Calculate convenience fee estimates before creating charges.

    `client.estimates.create(params)`

    Calculate a convenience fee estimate.

    Parameters:

  • amount (number, required): Amount in cents (e.g., 10000 for $100.00)
  • currency (string, required): Three-letter ISO currency code (e.g., 'USD')
  • region (string, optional): Region code for compliance checking (e.g., 'US-CA')
  • cardType ('credit' | 'debit', optional): Card type for accurate calculation

    • Returns: Promise<Estimate>

    Example:

    const estimate = await client.estimates.create({
  amount: 10000,
  currency: 'USD',
  region: 'US-CA',
  cardType: 'credit'
});

console.log(`Base: $${estimate.baseAmount / 100}`);
console.log(`Fee: $${estimate.convenienceFee / 100}`);
console.log(`Total: $${estimate.totalAmount / 100}`);
console.log(`Compliant: ${estimate.compliant}`);

    Response:

    {
  baseAmount: 10000,
  convenienceFee: 320,
  totalAmount: 10320,
  feeBreakdown: {
    percentage: 2.9,
    flatFee: 0.30
  },
  compliant: true,
  region: 'US-CA'
}

    Charges Resource

    Create and manage payment charges with convenience fees.

    `client.charges.create(params)`

    Create a new charge with convenience fee.

    Parameters:

  • amount (number, required): Amount in cents
  • currency (string, required): Three-letter ISO currency code
  • customer (string, optional): Customer identifier
  • description (string, optional): Description for this charge
  • metadata (object, optional): Key-value pairs for additional information
  • region (string, optional): Region code
  • cardType ('credit' | 'debit', optional): Card type

    • Returns: Promise<Charge>

    Example:

    const charge = await client.charges.create({
  amount: 10000,
  currency: 'USD',
  customer: 'cust_123',
  description: 'Order #1234',
  metadata: {
    orderId: '1234',
    productIds: ['prod_abc', 'prod_xyz']
  }
});

console.log(`Charge ID: ${charge.id}`);
console.log(`Status: ${charge.status}`);
console.log(`Total: $${charge.totalAmount / 100}`);

    Response:

    {
  id: 'ch_123456',
  object: 'charge',
  amount: 10000,
  convenienceFee: 320,
  totalAmount: 10320,
  currency: 'USD',
  status: 'succeeded',
  created: 1704067200,
  customer: 'cust_123',
  description: 'Order #1234',
  metadata: { orderId: '1234' }
}

    `client.charges.retrieve(id)`

    Retrieve a charge by ID.

    Parameters:

  • id (string, required): Charge ID

    • Returns: Promise<Charge>

    Example:

    const charge = await client.charges.retrieve('ch_123456');

console.log(`Status: ${charge.status}`);
console.log(`Amount: $${charge.amount / 100}`);

    `client.charges.list(params?)`

    List all charges with pagination and filtering.

    Parameters:

  • limit (number, optional): Max results to return (1-100, default: 10)
  • starting_after (string, optional): Cursor for pagination (charge ID)
  • created (object, optional): Filter by creation timestamp

    • - gte (number): Return charges created on or after this timestamp

    - lte (number): Return charges created on or before this timestamp

    Returns: Promise<List<Charge>>

    Example:

    // Get 10 most recent charges
const charges = await client.charges.list({ limit: 10 });

// Get charges from last 30 days
const recentCharges = await client.charges.list({
  limit: 25,
  created: {
    gte: Math.floor(Date.now() / 1000) - 30 * 24 * 60 * 60
  }
});

// Paginate through charges
const nextPage = await client.charges.list({
  limit: 10,
  starting_after: charges.data[charges.data.length - 1].id
});

    Response:

    {
  object: 'list',
  url: '/v1/charges',
  data: [
    { id: 'ch_1', amount: 10000, ... },
    { id: 'ch_2', amount: 5000, ... }
  ],
  has_more: false
}

    Fee Configs Resource

    Manage convenience fee configuration settings.

    `client.feeConfigs.retrieve()`

    Get current fee configuration.

    Returns: Promise<FeeConfig>

    Example:

    const config = await client.feeConfigs.retrieve();

console.log(`Percentage: ${config.percentage}%`);
console.log(`Flat Fee: $${config.flatFee}`);
console.log(`Billing Mode: ${config.billingMode}`);

    Response:

    {
  percentage: 2.9,
  flatFee: 0.30,
  billingMode: 'direct',
  regions: { ... }
}

    `client.feeConfigs.update(params)`

    Update fee configuration.

    Parameters:

  • percentage (number, optional): Fee percentage (e.g., 2.9 for 2.9%)
  • flatFee (number, optional): Flat fee in dollars (e.g., 0.30 for $0.30)
  • billingMode ('direct' | 'separate', optional): Billing mode

    • Returns: Promise<FeeConfig>

    Example:

    const newConfig = await client.feeConfigs.update({
  percentage: 3.0,
  flatFee: 0.35,
  billingMode: 'separate'
});

console.log('Updated successfully');

    Regions Resource

    Check regional compliance requirements and regulations.

    `client.regions.retrieve(regionCode)`

    Get region information.

    Parameters:

  • regionCode (string, required): Region code (e.g., 'US-CA', 'US-NY', 'GB')

    • Returns: Promise<Region>

    Example:

    const region = await client.regions.retrieve('US-CA');

console.log(`Region: ${region.state || region.country}`);
console.log(`Max Percentage: ${region.maxPercentage}%`);
console.log(`Max Flat Fee: $${region.maxFlatFee}`);
console.log(`Requires Disclosure: ${region.requiresDisclosure}`);
console.log(`Allowed Cards: ${region.allowedCardTypes.join(', ')}`);

    Response:

    {
  regionCode: 'US-CA',
  country: 'US',
  state: 'California',
  allowedCardTypes: ['credit', 'debit'],
  maxPercentage: 4.0,
  maxFlatFee: 1.0,
  requiresDisclosure: true,
  disclosureText: 'A convenience fee will be added...'
}

    `client.regions.checkCompliance(params)`

    Check if a fee structure is compliant.

    Parameters:

  • region (string, required): Region code
  • percentage (number, required): Fee percentage to check
  • flatFee (number, required): Flat fee to check
  • cardType ('credit' | 'debit', required): Card type

    • Returns: Promise<ComplianceCheck>

    Example:

    const compliance = await client.regions.checkCompliance({
  region: 'US-CA',
  percentage: 3.5,
  flatFee: 0.30,
  cardType: 'credit'
});

if (compliance.compliant) {
  console.log('Fee structure is compliant');
} else {
  console.log(`Not compliant: ${compliance.reason}`);
}

    Response:

    {
  compliant: true
}
// or
{
  compliant: false,
  reason: 'Percentage exceeds maximum allowed (4.0%) for US-CA'
}

    Webhooks

    Verify webhook signatures to ensure events are from Sir Chargly.

    `SirChargly.webhooks.constructEvent(body, signature, secret)`

    Verify and parse a webhook event.

    Parameters:

  • body (string, required): Raw request body (do not parse JSON first)
  • signature (string, required): Value from 'Sir-Chargly-Signature' header
  • secret (string, required): Your webhook signing secret

    • Returns: WebhookEvent

    Throws: InvalidRequestError if signature is invalid

    Example:

    import { SirChargly } from '@sirchargly/sdk';

// In your webhook handler (Express)
app.post('/webhooks/sirchargly',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['sir-chargly-signature'];
    const body = req.body.toString();

    try {
      const event = SirChargly.webhooks.constructEvent(
        body,
        signature,
        process.env.SIRCHARGLEY_WEBHOOK_SECRET
      );

      // Handle the event
      switch (event.type) {
        case 'charge.succeeded':
          console.log('Charge succeeded:', event.data.object.id);
          break;
        case 'charge.failed':
          console.log('Charge failed:', event.data.object.id);
          break;
      }

      res.json({ received: true });
    } catch (err) {
      console.error('Webhook verification failed:', err.message);
      res.status(400).send('Invalid signature');
    }
  }
);

    Error Handling

    The SDK throws typed errors for different scenarios.

    Error Types

  • AuthenticationError: Invalid API key (401)
  • InvalidRequestError: Invalid parameters (400)
  • RateLimitError: Too many requests (429)
  • APIError: Server errors (5xx)
  • NetworkError: Network/timeout errors

    • Example

    import {
  SirChargly,
  AuthenticationError,
  InvalidRequestError,
  RateLimitError,
  APIError,
  NetworkError
} from '@sirchargly/sdk';

try {
  const charge = await client.charges.create({
    amount: 10000,
    currency: 'USD'
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof InvalidRequestError) {
    console.error('Invalid parameters:', error.message);
    console.error('Parameter:', error.param);
  } else if (error instanceof RateLimitError) {
    console.error('Too many requests, please retry later');
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  } else if (error instanceof APIError) {
    console.error('API error:', error.message);
    console.error('Status code:', error.statusCode);
  }
}

    Error Properties

    All errors extend SirCharglyError and include:

  • message (string): Error message
  • type (string): Error type identifier
  • code (string): Error code
  • statusCode (number): HTTP status code (if applicable)

    • TypeScript Support

    The SDK is written in TypeScript with complete type definitions.

    import SirChargly, {
  Estimate,
  Charge,
  FeeConfig,
  Region,
  ComplianceCheck,
  WebhookEvent
} from '@sirchargly/sdk';

const client = new SirChargly('sk_dev_sirchargly_your_api_key');

// Full type inference
const estimate: Estimate = await client.estimates.create({
  amount: 10000,
  currency: 'USD'
});

    Requirements

  • Node.js >= 18.0.0

    • Support

  • GitHub: https://github.com/sirchargly/sdk-node
  • Documentation: https://sirchargly.com/docs
  • Email: support@sirchargly.com

    • Ready to start charging convenience fees?

    Create your account and complete onboarding in minutes.

    No credit card required • 5-minute setup