Sir CharglyDocumentation
SC
Sir Chargly

Back to Documentation

Sir Chargly - API Integration Guide

Complete guide to integrating Sir Chargly's convenience fee platform into your application.

Table of Contents

  1. Quick Start
  2. Authentication
  3. API Endpoints
  4. SDK Usage
  5. Testing
  6. Production Deployment

Quick Start

1. Install the SDK

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

2. Generate Your API Keys

Create your development API keys right here:

Loading...

3. Set Up Environment Variables

Add your keys to .env.local in your project root:

# Development keys (from above)
SIRCHARGLEY_PUBLISHABLE_KEY=pk_dev_sirchargly_...
SIRCHARGLEY_SECRET_KEY=sk_dev_sirchargly_...

# Production keys (when ready to go live)
# SIRCHARGLEY_PUBLISHABLE_KEY=pk_prod_sirchargly_...
# SIRCHARGLEY_SECRET_KEY=sk_prod_sirchargly_...

4. Try Your First API Call

Test the fee estimation API with different scenarios:

Loading...

Authentication

Sir Chargly uses API keys for authentication. There are two types:

Publishable Keys

Format: pk_dev_sirchargly_... or pk_prod_sirchargly_...

  • Used in client-side code
  • Safe to expose in frontend JavaScript
  • Used to initialize the SDK
  • Automatically detects environment (dev/prod) from prefix

Usage:

// Client-side (React, Vue, etc.)
const chargly = new SirChargly('pk_dev_sirchargly_...');

Secret Keys

Format: sk_dev_sirchargly_... or sk_prod_sirchargly_...

  • Used in server-side code only
  • NEVER expose in client-side code
  • Used for authenticated API requests
  • Has full access to your account

Usage:

// Server-side (API routes, backend)
const response = await fetch('https://api.sirchargly.com/v1/charges', {
  headers: {
    'Authorization': `Bearer ${process.env.SIRCHARGLEY_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
});

Environment Detection

Keys automatically determine the environment:

  • pk_dev_* / sk_dev_* → Development mode (test data)
  • pk_prod_* / sk_prod_* → Production mode (live data)

API Endpoints

Base URL: https://api.sirchargly.com/v1

Calculate Fee

Estimate convenience fee for a transaction

POST /v1/estimates/calculate
Cookie: session=... (or Authorization: Bearer sk_dev_sirchargly_...)
Content-Type: application/json

{
  "amount": 10000,
  "currency": "usd",
  "customerId": "cus_test_standard",
  "paymentMethod": "visa_credit"
}

Try it live:

Loading...

Create Charge

Process a payment with convenience fee

POST /v1/charges
Cookie: session=... (or Authorization: Bearer sk_dev_sirchargly_...)
Content-Type: application/json

{
  "amount": 10000,
  "currency": "usd",
  "customer": "cus_test_standard",
  "paymentMethod": "pm_card_visa",
  "description": "Order #1234"
}

Try creating a real test charge:

Loading...

SDK Usage

Initialization

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

const chargly = new SirChargly(
  process.env.NEXT_PUBLIC_SIRCHARGLEY_PUBLISHABLE_KEY!,
  {
    apiVersion: '2025-01',
    timeout: 30000, // 30 seconds
  }
);

Creating Payments

// Simple payment
const payment = await chargly.payments.create({
  amount: 10000,
  currency: 'usd',
  customer: 'cus_123',
});

// With metadata
const payment = await chargly.payments.create({
  amount: 10000,
  currency: 'usd',
  customer: 'cus_123',
  metadata: {
    orderId: '1234',
    productId: 'prod_456',
  },
});

// With specific region
const payment = await chargly.payments.create({
  amount: 10000,
  currency: 'usd',
  customer: 'cus_123',
  region: 'US-TX',
});

Estimating Fees

// Get fee estimate before charging
const estimate = await chargly.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}`);

Error Handling

try {
  const payment = await chargly.payments.create({
    amount: 10000,
    currency: 'usd',
  });
} catch (error) {
  if (error.type === 'AuthenticationError') {
    // Invalid API key
    console.error('Authentication failed');
  } else if (error.type === 'InvalidRequestError') {
    // Invalid parameters
    console.error('Invalid request:', error.message);
  } else if (error.type === 'APIError') {
    // Server error
    console.error('API error:', error.message);
  } else if (error.type === 'NetworkError') {
    // Network connectivity issue
    console.error('Network error');
  }
}

Testing

Test Mode

All development keys (pk_dev_*, sk_dev_*) operate in test mode:

  • No real charges are processed
  • Use test customers (pre-configured)
  • Separate from production data
  • Safe to experiment

Test Customer Scenarios

We provide pre-configured test customers for different compliance scenarios:

Loading...
Loading...
Loading...
Loading...
Loading...

Complete Workflow Example

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

const chargly = new SirChargly(process.env.SIRCHARGLEY_PUBLISHABLE_KEY!);

async function processOrder(orderId: string, amount: number) {
  try {
    // 1. Get fee estimate
    const estimate = await chargly.estimates.create({
      amount,
      currency: 'usd',
    });

    // 2. Show customer the total including fee
    console.log(`Order: $${amount / 100}`);
    console.log(`Convenience Fee: $${estimate.convenienceFee / 100}`);
    console.log(`Total: $${estimate.totalAmount / 100}`);

    // 3. Create the charge
    const charge = await chargly.charges.create({
      amount,
      currency: 'usd',
      metadata: { orderId },
    });

    // 4. Save charge ID to your database
    await saveChargeToDatabase(orderId, charge.id);

    return {
      success: true,
      chargeId: charge.id,
      totalAmount: charge.totalAmount,
    };
  } catch (error) {
    console.error('Payment failed:', error);
    return {
      success: false,
      error: error.message,
    };
  }
}

Try the complete flow:

Step 1: Calculate Estimate

Loading...

Step 2: Process Payment

Loading...

Production Deployment

Pre-Deployment Checklist

  • [ ] Thoroughly tested in development mode
  • [ ] Created production API keys in dashboard
  • [ ] Updated environment variables in production
  • [ ] Configured webhooks with production URL
  • [ ] Set up monitoring and alerts
  • [ ] Reviewed regional compliance requirements
  • [ ] Added error logging and tracking
  • [ ] Set up rate limiting
  • [ ] Configured HTTPS for webhooks
  • [ ] Added API key rotation plan

Environment Variables

Development:

SIRCHARGLEY_PUBLISHABLE_KEY=pk_dev_sirchargly_...
SIRCHARGLEY_SECRET_KEY=sk_dev_sirchargly_...
SIRCHARGLEY_WEBHOOK_SECRET=whsec_dev_...

Production:

SIRCHARGLEY_PUBLISHABLE_KEY=pk_prod_sirchargly_...
SIRCHARGLEY_SECRET_KEY=sk_prod_sirchargly_...
SIRCHARGLEY_WEBHOOK_SECRET=whsec_prod_...

Security Best Practices

  1. Never commit API keys to version control

    # .gitignore
.env.local
.env.production

  2. Use environment variables

    // ✅ Good
const key = process.env.SIRCHARGLEY_SECRET_KEY;

// ❌ Bad
const key = 'sk_prod_sirchargly_...';

  3. Use HTTPS for webhooks

    ✅ https://yourdomain.com/api/webhooks
❌ http://yourdomain.com/api/webhooks

Support

Resources

Getting Help

  • Email: support@sirchargly.com
  • Documentation: All Guides

Next Steps

Now that you've completed the integration:

  1. Test thoroughly with the interactive demos above
  2. Review the Testing Guide for more scenarios
  3. Check out the SDK Reference for advanced features
  4. When ready, create production API keys from your Dashboard