Getting Started with Sir Chargly

Welcome! This guide will walk you through setting up Sir Chargly from scratch to your first successful charge with convenience fees.

Table of Contents

1. Connect Stripe
2. Create Your API Keys
3. How Sir Chargly Works
4. Set Up Test Customers
5. Adding Your First Charges
6. Complete Charging Flow
7. Key Things for Production
8. Next Steps

Connect Stripe

Sir Chargly uses Stripe to process payments. You'll need to connect your Stripe account before you can charge fees.

Development Environment

For testing, you can use Sir Chargly without connecting Stripe. We provide mock payment processing that simulates real charges.

Production Environment

For live charges, connect your Stripe account:

1. Go to your Dashboard Settings
2. Click "Connect Stripe Account"
3. Authorize Sir Chargly to access your Stripe account
4. You'll be redirected back with confirmation

Create Your API Keys

API keys authenticate your application with Sir Chargly. Generate your development keys here:

Managing Your Keys

After creating keys, you can manage them in your API Keys Dashboard where you can:

• Create additional keys
• View usage statistics
• Delete compromised keys
• Generate production keys (when Stripe is connected)

Security Best Practices

• Never commit keys to version control - Add .env.local to .gitignore
• Use environment variables - Store keys in .env.local or your hosting platform
• Rotate keys regularly - Create new keys and delete old ones periodically
• Keep secret keys private - Never expose secret keys in client-side code

How Sir Chargly Works

Sir Chargly calculates and applies convenience fees based on two key factors:

1. Customer Address

The customer's location determines which compliance rules apply. Different states and countries have different regulations about convenience fees.

Why it matters:

• Some regions don't allow convenience fees at all
• Some regions have maximum fee caps
• Some regions require specific disclosures

How to provide it: When collecting payment information, always capture the customer's billing address. This is passed to Sir Chargly via the customer parameter or billing_details in the payment method.

2. Payment Method Type

The type of card (credit, debit, prepaid) affects whether fees can be charged and how much.

Why it matters:

• Some regions allow fees on credit cards but not debit cards
• Fee percentages may vary by card type
• Card brand (Visa, Mastercard, Amex) can affect compliance

How to provide it: Payment method type is automatically detected when you collect card information using Stripe Elements (covered below).

Set Up Test Customers

We provide pre-configured test customers that simulate different compliance scenarios. This lets you test your integration without exposing actual regulatory details.

What These Test Customers Do

Each test customer is configured with:

• A specific US state location
• Pre-defined payment methods
• Compliance rules for that region

For example:

• cus_test_standard (Texas) - No restrictions, standard fees apply
• cus_test_blocked_region (Massachusetts) - Simulates a region where fees aren't allowed
• cus_test_card_restricted (California) - Simulates card-type restrictions

Adding Your First Charges

Sir Chargly provides several API endpoints for different operations. Try each one below to get familiar with the API.

1. Fee Estimation

Calculate the convenience fee before charging the customer. Always show customers the fee before completing a transaction.

API Documentation: POST /v1/estimates/calculate

2. Create Charge

Process a payment with convenience fee included. Use after showing the estimate and customer confirms payment.

API Documentation: POST /v1/charges

3. List Charges

Retrieve all charges for your account. Useful for building transaction history, generating reports, or syncing with your database.

API Documentation: GET /v1/charges

4. Retrieve Single Charge

Get details for a specific charge. Use to show transaction details, verify status, or check for refunds.

API Documentation: GET /v1/charges/:id

5. Update Charge

Update metadata or description of a charge. Use to add notes, update order information, or tag transactions.

API Documentation: PATCH /v1/charges/:id

Complete Charging Flow

Now let's put it all together. Here's how to integrate Sir Chargly into your payment flow.

Step 1: Collect Payment Information

Use Stripe Elements to securely collect card information. This keeps you PCI compliant by ensuring card data never touches your servers.

import { CardElement, useStripe, useElements } from '@stripe/react-stripe-js';
import { useState } from 'react';

function CheckoutForm({ amount, orderId }) {
const stripe = useStripe();
const elements = useElements();
const [processing, setProcessing] = useState(false);

const handleSubmit = async (event) => {
  event.preventDefault();
  if (!stripe || !elements) return;

  setProcessing(true);

  // Create payment method with billing address
  const { error, paymentMethod } = await stripe.createPaymentMethod({
    type: 'card',
    card: elements.getElement(CardElement),
    billing_details: {
      name: 'John Doe',
      address: {
        line1: '123 Main St',
        city: 'Austin',
        state: 'TX',        // Required for compliance
        postal_code: '78701',
        country: 'US'       // Required for compliance
      }
    }
  });

  if (error) {
    console.error(error);
    setProcessing(false);
    return;
  }

  // Send payment method ID to your backend
  await processPayment(paymentMethod.id);
  setProcessing(false);
};

return (
  <form onSubmit={handleSubmit}>
    <CardElement />
    <button type="submit" disabled={!stripe || processing}>
      {processing ? 'Processing...' : 'Pay Now'}
    </button>
  </form>
);
}

Step 2: Calculate Fee on Backend

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

const sirchargly = new SirChargly(process.env.SIRCHARGLY_SECRET_KEY);

export async function POST(req: Request) {
const { paymentMethodId, amount, customerId } = await req.json();

// 1. Calculate the convenience fee
const estimate = await sirchargly.estimates.calculate({
  amount: amount,
  currency: 'usd',
  customerId: customerId,
  paymentMethod: paymentMethodId
});

// 2. Return estimate to frontend to show customer
return Response.json({
  baseAmount: estimate.baseAmount,
  fee: estimate.fee,
  totalAmount: estimate.totalAmount
});
}

Step 3: Show Total to Customer

function PaymentSummary({ estimate }) {
return (
  <div>
    <p>Amount: ${(estimate.baseAmount / 100).toFixed(2)}</p>
    <p>Convenience Fee: ${(estimate.fee / 100).toFixed(2)}</p>
    <p className="font-bold">
      Total: ${(estimate.totalAmount / 100).toFixed(2)}
    </p>
    <button onClick={handleConfirmPayment}>
      Confirm Payment
    </button>
  </div>
);
}

Step 4: Process the Charge

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

const sirchargly = new SirChargly(process.env.SIRCHARGLY_SECRET_KEY);

export async function POST(req: Request) {
const { paymentMethodId, amount, customerId, orderId } = await req.json();

// Create the charge with convenience fee
const charge = await sirchargly.charges.create({
  amount: amount,
  currency: 'usd',
  customer: customerId,
  paymentMethod: paymentMethodId,
  description: `Order #${orderId}`,
  metadata: {
    orderId: orderId
  }
});

// Charge successful!
return Response.json({
  chargeId: charge.id,
  status: charge.status,
  totalCharged: charge.totalCharged
});
}

Congratulations!

You've successfully set up Sir Chargly and processed your first convenience fee charges! You now know how to:

• Connect Stripe and create API keys
• Calculate compliant convenience fees
• Create and manage charges
• Integrate the complete payment flow

Below are some key things to implement before going to production.

Key Things for Production

Handling Chargebacks

A chargeback occurs when a customer disputes a charge with their bank. Sir Chargly helps you track and respond to chargebacks.

How Chargebacks Work:

1. Customer disputes charge → Files complaint with bank
2. Bank initiates chargeback → Withdraws funds from your account
3. You're notified → Webhook sent to your system
4. Evidence deadline → Usually 7-21 days to respond
5. Bank decides → Reviews evidence and makes final decision

Chargeback Webhook:

{
  "type": "charge.dispute.created",
  "data": {
    "charge": "ch_sirchargly_abc123",
    "amount": 10320,
    "reason": "fraudulent",
    "status": "needs_response",
    "evidenceDeadline": 1704067200,
    "convenienceFee": 320
  }
}

Responding to Chargebacks:

API Documentation: POST /v1/disputes/:id/evidence

await sirchargly.disputes.submitEvidence('dp_abc123', {
  customerName: 'John Doe',
  customerEmail: 'john@example.com',
  customerSignature: 'https://...',
  receipt: 'https://...',
  shippingTracking: '1Z999AA10123456784',
  shippingCarrier: 'UPS',
  productDescription: 'Premium widget with express shipping',
  refundPolicy: 'https://yoursite.com/refund-policy'
});

Best Practices:

• Respond quickly - Don't wait until the deadline
• Be thorough - Provide all relevant documentation
• Clear evidence - Screenshots, emails, tracking numbers
• Document everything - Save all customer interactions

Processing Refunds

Refund a charge when a customer returns a product or cancels a service.

Full Refund:

API Documentation: POST /v1/refunds

const refund = await sirchargly.refunds.create({
  charge: 'ch_sirchargly_abc123',
  reason: 'requested_by_customer'
});

console.log(refund);
// {
//   id: 'rf_abc123',
//   charge: 'ch_sirchargly_abc123',
//   amount: 10320,  // Full amount including fee
//   status: 'succeeded'
// }

Partial Refund:

const refund = await sirchargly.refunds.create({
  charge: 'ch_sirchargly_abc123',
  amount: 5000, // Refund $50 of original $103.20
  reason: 'duplicate'
});

Convenience Fee on Refunds:

When you refund a charge:

• The full refunded amount is returned to the customer
• Convenience fees are automatically refunded proportionally
• Sir Chargly's fee is also reversed
• Stripe processing fees are NOT returned (Stripe policy)

Example:

• Original charge: $100.00 + $3.20 fee = $103.20
• Full refund: Customer gets $103.20 back
• Your account: Debited $103.20
• Stripe processing fee: You still pay (~$0.30)

Set Up Webhooks

Configure webhook endpoints to receive real-time notifications about charge events, disputes, and refunds.

See Webhooks Documentation for setup instructions.

Monitor Your Dashboard

Use the Dashboard to:

• Track all transactions
• View revenue analytics
• Monitor compliance status
• Manage API keys
• Review fee calculations

Next Steps

Review Advanced Topics

• Testing Guide - Comprehensive testing scenarios
• API Reference - Complete API documentation
• SDK Reference - All SDK methods and examples
• Compliance Guide - Regional fee regulations

Go Live

When you're ready for production:

1. Connect your Stripe account in Settings
2. Create production API keys in API Keys
3. Update environment variables in your hosting platform
4. Remove environment=development from API calls
5. Test with small real charges first
6. Set up webhook endpoints
7. Monitor your Dashboard for transactions

Get Help

• Email: support@sirchargly.com
• Documentation: All Guides
• Dashboard: View Your Account