Sir CharglyDocumentation
SC
Sir Chargly
Back to Documentation

Testing Guide

Complete guide for testing Sir Chargly convenience fee functionality with different regional compliance scenarios

Test Customers & Regions

Sir Chargly provides pre-configured test customers that demonstrate different regional compliance behaviors. Use these customers to test your integration without exposing actual regional regulations.

Strict Environment Enforcement

Development API Keys (sk_dev_sirchargly_*)

Can ONLY use these test customers:

  • cus_test_standard
  • cus_test_blocked_region
  • cus_test_card_restricted
  • cus_test_fee_adjusted

❌ Using any other customer ID will throw an error

Production API Keys (sk_prod_sirchargly_*)

Can ONLY use real customers (NOT test customers)

❌ Using test customers will throw an error

This prevents:
  • Accidentally charging real customers in development
  • Test data appearing in production
  • Confusion about which environment you're in

Test Scenario 1: Standard Fee (No Restrictions)

Test Customer: cus_test_standard
Region: US-TX (Texas)
Behavior: Standard convenience fee applied
Fee: 2.9% + $0.30
Card Types: All allowed (credit, debit, prepaid)
Test Card: Any Stripe test card
const estimate = await client.estimates.create({
  amount: 10000,
  currency: 'usd',
  customerId: 'cus_test_standard',
  paymentMethod: 'visa_credit'
});
// ✅ Fee: $320 (2.9% + $0.30)
// ✅ Total: $10,320

Use Case: Test basic fee calculation and charge creation.

Test Scenario 2: Region Blocked

Test Customer: cus_test_blocked_region
Region: US-MA (Massachusetts)
Behavior: Convenience fees not allowed
Fee: $0.00
Card Types: N/A (region blocked)
Test Card: Any Stripe test card
const estimate = await client.estimates.create({
  amount: 10000,
  currency: 'usd',
  customerId: 'cus_test_blocked_region',
  paymentMethod: 'visa_credit'
});
// ❌ Fee: $0.00 (blocked region)
// ⚠️ compliance.passed: false
// ⚠️ compliance.warnings: ["Convenience fees not permitted in this region"]

Use Case: Test handling of non-compliant regions and zero-fee scenarios.

Test Scenario 3: Card Type Restricted

Test Customer: cus_test_card_restricted
Region: US-CA (California)
Behavior: Only credit cards can be surcharged
Fee: Varies by card type
Card Types: Credit ✅ | Debit ❌ | Prepaid ❌
Credit: 4242 4242 4242 4242
Debit: 4000 0566 5566 5556
Credit Card Test (Allowed):
const estimate = await client.estimates.create({
  amount: 10000,
  currency: 'usd',
  customerId: 'cus_test_card_restricted',
  paymentMethod: 'visa_credit'  // ✅ Allowed
});
// ✅ Fee: $320 (2.9% + $0.30)
// ✅ compliance.passed: true
Debit Card Test (Blocked):
const estimate = await client.estimates.create({
  amount: 10000,
  currency: 'usd',
  customerId: 'cus_test_card_restricted',
  paymentMethod: 'visa_debit'  // ❌ Not allowed
});
// ❌ Fee: $0.00 (debit card blocked)
// ⚠️ compliance.passed: false

Use Case: Test card-type validation and compliance warnings.

Test Scenario 4: Fee Adjusted by Regulation

Test Customer: cus_test_fee_adjusted
Region: US-CO (Colorado)
Behavior: Regional cap limits fee to 2% maximum
Fee: 2.0% + $0.30 (capped)
Card Types: All allowed
Test Card: Any Stripe test card
const estimate = await client.estimates.create({
  amount: 10000,
  currency: 'usd',
  customerId: 'cus_test_fee_adjusted',
  paymentMethod: 'visa_credit'
});
// ✅ Fee: $230 (2.0% + $0.30, capped by regional rule)
// ✅ Total: $10,230
// ✅ compliance.passed: true
// ℹ️ fee.appliedRules: ["regional_percentage_cap"]

Use Case: Test regional fee caps and rule application.

Stripe Test Cards

Use these official Stripe test cards for testing:

Card NumberBrandTypeCVCExpiry
4242 4242 4242 4242VisaCreditAny 3 digitsAny future date
4000 0566 5566 5556VisaDebitAny 3 digitsAny future date
5555 5555 5555 4444MastercardCreditAny 3 digitsAny future date
5200 8282 8282 8210MastercardDebitAny 3 digitsAny future date
3782 822463 10005AmexCreditAny 4 digitsAny future date

Complete Test Workflow

1. Get Estimate First

Always calculate an estimate before charging:

import SirChargly from '@sirchargly/sdk';

const client = new SirChargly('sk_dev_sirchargly_your_key');

// Step 1: Get estimate
const estimate = await client.estimates.create({
  amount: 10000,
  currency: 'usd',
  customerId: 'cus_test_standard',
  paymentMethod: 'visa_credit'
});

console.log(`Base: $${estimate.baseAmount / 100}`);
console.log(`Fee: $${estimate.fee.amount / 100}`);
console.log(`Total: $${estimate.total / 100}`);
console.log(`Compliant: ${estimate.compliance.passed}`);

if (!estimate.compliance.passed) {
  console.log('Warnings:', estimate.compliance.warnings);
}

2. Show Estimate to Customer

const message = `
  Subtotal: $${estimate.baseAmount / 100}
  ${estimate.fee.label}: $${estimate.fee.amount / 100}
  Total: $${estimate.total / 100}
`;

3. Create Charge

const charge = await client.charges.create({
  amount: 10000,
  currency: 'usd',
  customer: 'cus_test_standard',
  paymentMethod: 'pm_card_visa',
  description: 'Order #12345'
});

console.log(`Charge ID: ${charge.id}`);
console.log(`Status: ${charge.status}`);
console.log(`Fee: $${charge.fee.amount / 100}`);

Compliance Testing Checklist

Use this checklist to verify your integration handles all compliance scenarios:

✓ Standard fee calculation - Test with cus_test_standard

  • Estimate shows correct fee amount
  • Charge succeeds with fee applied
  • compliance.passed = true

✓ Blocked region handling - Test with cus_test_blocked_region

  • Estimate returns $0 fee
  • compliance.passed = false
  • compliance.warnings array populated
  • Charge succeeds (with $0 fee)
  • UI shows why fee is $0

✓ Card type restrictions - Test with cus_test_card_restricted

  • Credit card: Fee applied
  • Debit card: $0 fee with warning
  • compliance.passed varies by card type
  • UI handles different card types

✓ Fee adjustments - Test with cus_test_fee_adjusted

  • Fee amount reflects regional cap (not merchant config)
  • fee.appliedRules shows which rules were applied
  • compliance.passed = true
  • UI shows adjusted fee correctly

✓ Error handling

  • Invalid customer ID
  • Invalid payment method
  • Missing required fields
  • Network errors

Next Steps

API Integration Guide

Complete API reference and integration steps

SDK Reference

SDK methods and examples

Support

Questions about testing?