Getting Started with Sir Chargly

Welcome to Sir Chargly! This guide will help you get up and running with convenience fee processing in minutes.

What is Sir Chargly?

Sir Chargly is a platform that helps businesses add legally-compliant convenience fees to credit card transactions. We handle all the complexity of regional compliance, fee calculations, and merchant processing so you can focus on your business.

Quick Start

1. Create Your Account

Visit sirchargly.com and click Sign Up to create your free account. You'll need:

Business email address

Company name

Basic business information

2. Complete Onboarding

After signing up, you'll go through our guided onboarding process:

Connect Stripe - Link your Stripe account for payment processing

Configure Fees - Set your convenience fee structure

Review Compliance - We'll verify your fee structure is compliant

Get API Keys - Receive your development and production API keys

3. Get Your API Keys

Once onboarding is complete:

Go to Dashboard → API Keys

You'll see two default keys:

- Development Key - For testing (uses test data)

- Production Key - For live transactions

Important: Save your secret keys immediately! They're only shown once during creation.

4. Install the SDK

Install the Sir Chargly SDK in your project:

npm:

npm install @sirchargly/sdk

yarn:

yarn add @sirchargly/sdk

5. Make Your First API Call

Create a simple fee estimate:

import SirChargly from '@sirchargly/sdk';

// Initialize with your secret key
const client = new SirChargly('sk_dev_sirchargly_your_key_here');

// Calculate convenience fee for a $100 transaction
const estimate = await client.estimates.create({
  amount: 10000, // Amount in cents ($100.00)
  currency: 'USD',
  region: 'US-CA' // Optional: California compliance check
});

console.log(estimate);
// {
//   baseAmount: 10000,
//   convenienceFee: 320,  // $3.20
//   totalAmount: 10320,   // $103.20
//   compliant: true
// }

6. Create Your First Charge

Process a payment with convenience fee:

const charge = await client.charges.create({
  amount: 10000,
  currency: 'USD',
  customer: 'cust_123',
  description: 'Order #1234'
});

console.log(charge);
// {
//   id: 'ch_abc123',
//   amount: 10000,
//   convenienceFee: 320,
//   totalAmount: 10320,
//   status: 'succeeded'
// }

Next Steps

Now that you've made your first API call, explore these guides:

Essential Guides

API Integration Guide - Complete integration walkthrough

SDK Reference - Full SDK documentation

Regional Compliance - Understanding compliance by state

Advanced Topics

Testing & Troubleshooting - Debug common issues

User Onboarding - Customer-facing implementation

API Reference - Complete REST API documentation

Key Concepts

Amount Format

All amounts in the API are in cents (or smallest currency unit):

10000 = $100.00

2500 = $25.00

150 = $1.50

This prevents floating-point errors and ensures precision.

Development vs Production

Development Keys (sk_dev_sirchargly_...):

Use test data only

No real charges created

Safe for testing

No fees charged

Production Keys (sk_prod_sirchargly_...):

Process real transactions

Real charges and fees

Use only when ready to go live

Regional Compliance

Different states have different convenience fee laws:

California: Allows up to 4% on credit cards

New York: Prohibits convenience fees entirely

Texas: Allows fees with disclosure requirements

Sir Chargly automatically checks compliance for your fee structure.

Common Use Cases

E-commerce Checkout

Add convenience fees to your checkout flow:

// 1. Get estimate during checkout
const estimate = await client.estimates.create({
  amount: cartTotal,
  currency: 'USD',
  region: userState
});

// 2. Display total to customer
displayTotal(estimate.totalAmount);

// 3. Create charge on payment
const charge = await client.charges.create({
  amount: cartTotal,
  currency: 'USD',
  customer: customerId
});

Invoice Payments

Add fees to invoice payments:

const charge = await client.charges.create({
  amount: invoiceAmount,
  currency: 'USD',
  customer: customerId,
  metadata: {
    invoiceId: 'INV-001',
    dueDate: '2024-02-01'
  }
});

Subscription Billing

Include fees in recurring charges:

// Calculate fee for subscription amount
const estimate = await client.estimates.create({
  amount: subscriptionAmount,
  currency: 'USD'
});

// Charge customer the total amount
const charge = await client.charges.create({
  amount: subscriptionAmount,
  currency: 'USD',
  customer: customerId,
  description: 'Monthly Subscription - February'
});

Best Practices

1. Always Show Fees to Customers

Transparency is legally required in most jurisdictions. Always display:

Base amount

Convenience fee amount

Total amount

Example:

Subtotal:        $100.00
Convenience Fee:   $3.20
----------------------------
Total:           $103.20

2. Check Compliance by Region

Always pass the customer's region for compliance checking:

const estimate = await client.estimates.create({
  amount: 10000,
  currency: 'USD',
  region: 'US-NY' // Check New York compliance
});

if (!estimate.compliant) {
  // Don't add fee - not allowed in this region
}

3. Handle Errors Gracefully

try {
  const charge = await client.charges.create({
    amount: 10000,
    currency: 'USD',
    customer: customerId
  });
} catch (error) {
  if (error.type === 'card_error') {
    // Show user-friendly message
    showError('Your card was declined. Please try another card.');
  } else {
    // Log for debugging
    console.error('Charge failed:', error);
  }
}

4. Use Metadata for Tracking

Add custom data to charges for easier tracking:

const charge = await client.charges.create({
  amount: 10000,
  currency: 'USD',
  customer: customerId,
  metadata: {
    orderId: 'ORD-12345',
    source: 'web',
    campaign: 'spring-sale'
  }
});

5. Test Thoroughly in Development

Use development keys extensively before going live:

Test with different amounts

Test different regions

Test error scenarios

Test with test credit cards

Getting Help

Documentation

API Reference - Complete REST API docs

SDK Reference - SDK methods and examples

Testing Guide - Debug common issues

Support

Email: support@sirchargly.com

Dashboard: Live chat in your dashboard

Status: status.sirchargly.com

Community

GitHub: github.com/sirchargly

Discord: Join our developer community

What's Next?

Ready to dive deeper? Check out: