Sir CharglyDocumentation
SC
Sir Chargly
Back to Documentation

API Reference

Complete reference for the Sir Chargly REST API.

Base URL

https://api.sirchargly.com

Authentication

All API requests require authentication using your API key in the Authorization header:

Authorization: Bearer sk_dev_sirchargly_your_key_here

API Key Types

  • Development: sk_dev_sirchargly_... - Test mode, no real charges
  • Production: sk_prod_sirchargly_... - Live mode, real charges

    • Estimates

    Calculate convenience fee estimates before creating charges.

    Create Estimate

    Calculate a convenience fee estimate for a given amount.

    Endpoint: POST /v1/estimates

    Request Body:

    {
  "amount": 10000,
  "currency": "USD",
  "region": "US-CA",
  "cardType": "credit"
}

    Parameters:

    | Field | Type | Required | Description |

    |-------|------|----------|-------------|

    | amount | integer | Yes | Amount in cents (e.g., 10000 for $100.00) |

    | currency | string | Yes | Three-letter ISO currency code (e.g., "USD") |

    | region | string | No | Region code for compliance check (e.g., "US-CA") |

    | cardType | string | No | Card type: "credit" or "debit" |

    Response:

    {
  "object": "estimate",
  "baseAmount": 10000,
  "convenienceFee": 320,
  "totalAmount": 10320,
  "currency": "USD",
  "compliant": true,
  "region": "US-CA",
  "feeStructure": {
    "percentage": 2.9,
    "flatFee": 0.30
  }
}

    Example:

    curl -X POST https://api.sirchargly.com/v1/estimates \
  -H "Authorization: Bearer sk_dev_sirchargly_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "USD",
    "region": "US-CA"
  }'

    Charges

    Create and manage payment charges with convenience fees.

    Create Charge

    Create a new charge with convenience fee automatically calculated.

    Endpoint: POST /v1/charges

    Request Body:

    {
  "amount": 10000,
  "currency": "USD",
  "customer": "cust_123",
  "description": "Order #1234",
  "metadata": {
    "orderId": "ORD-1234",
    "source": "web"
  },
  "region": "US-CA",
  "cardType": "credit"
}

    Parameters:

    | Field | Type | Required | Description |

    |-------|------|----------|-------------|

    | amount | integer | Yes | Charge amount in cents |

    | currency | string | Yes | Three-letter ISO currency code |

    | customer | string | No | Customer identifier |

    | description | string | No | Description of the charge |

    | metadata | object | No | Key-value pairs for additional data |

    | region | string | No | Region code for compliance |

    | cardType | string | No | Card type: "credit" or "debit" |

    Response:

    {
  "id": "ch_abc123",
  "object": "charge",
  "amount": 10000,
  "convenienceFee": 320,
  "totalAmount": 10320,
  "currency": "USD",
  "status": "succeeded",
  "created": 1704067200,
  "customer": "cust_123",
  "description": "Order #1234",
  "metadata": {
    "orderId": "ORD-1234",
    "source": "web"
  }
}

    Example:

    curl -X POST https://api.sirchargly.com/v1/charges \
  -H "Authorization: Bearer sk_dev_sirchargly_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "USD",
    "customer": "cust_123",
    "description": "Order #1234"
  }'

    Retrieve Charge

    Retrieve details of a specific charge.

    Endpoint: GET /v1/charges/:id

    Response:

    {
  "id": "ch_abc123",
  "object": "charge",
  "amount": 10000,
  "convenienceFee": 320,
  "totalAmount": 10320,
  "currency": "USD",
  "status": "succeeded",
  "created": 1704067200,
  "customer": "cust_123"
}

    Example:

    curl https://api.sirchargly.com/v1/charges/ch_abc123 \
  -H "Authorization: Bearer sk_dev_sirchargly_your_key"

    List Charges

    List all charges for your account.

    Endpoint: GET /v1/charges

    Query Parameters:

    | Parameter | Type | Description |

    |-----------|------|-------------|

    | limit | integer | Number of charges to return (default: 10, max: 100) |

    | starting_after | string | Cursor for pagination |

    | customer | string | Filter by customer ID |

    | created[gte] | integer | Filter by creation timestamp (greater than or equal) |

    | created[lte] | integer | Filter by creation timestamp (less than or equal) |

    Response:

    {
  "object": "list",
  "data": [
    {
      "id": "ch_abc123",
      "amount": 10000,
      "convenienceFee": 320,
      "totalAmount": 10320,
      "status": "succeeded"
    }
  ],
  "has_more": false
}

    Example:

    # List recent charges
curl https://api.sirchargly.com/v1/charges?limit=10 \
  -H "Authorization: Bearer sk_dev_sirchargly_your_key"

# Filter by customer
curl "https://api.sirchargly.com/v1/charges?customer=cust_123" \
  -H "Authorization: Bearer sk_dev_sirchargly_your_key"

# Filter by date (last 30 days)
THIRTY_DAYS_AGO=$(date -v-30d +%s)
curl "https://api.sirchargly.com/v1/charges?created[gte]=$THIRTY_DAYS_AGO" \
  -H "Authorization: Bearer sk_dev_sirchargly_your_key"

    Fee Configurations

    Manage your convenience fee structure.

    Retrieve Fee Configuration

    Get your current fee configuration.

    Endpoint: GET /v1/fee-configs

    Response:

    {
  "object": "fee_config",
  "percentage": 2.9,
  "flatFee": 0.30,
  "minAmount": 50,
  "maxAmount": null,
  "billingMode": "direct"
}

    Example:

    curl https://api.sirchargly.com/v1/fee-configs \
  -H "Authorization: Bearer sk_dev_sirchargly_your_key"

    Update Fee Configuration

    Update your fee structure (requires approval for some changes).

    Endpoint: POST /v1/fee-configs

    Request Body:

    {
  "percentage": 3.5,
  "flatFee": 0.40,
  "minAmount": 50
}

    Response:

    {
  "object": "fee_config",
  "percentage": 3.5,
  "flatFee": 0.40,
  "minAmount": 50,
  "updated": true
}

    Regions

    Check regional compliance for convenience fees.

    Retrieve Region

    Get compliance information for a specific region.

    Endpoint: GET /v1/regions/:code

    Example: GET /v1/regions/US-CA

    Response:

    {
  "regionCode": "US-CA",
  "country": "US",
  "state": "California",
  "allowedCardTypes": ["credit"],
  "maxPercentage": 4.0,
  "maxFlatFee": null,
  "requiresDisclosure": true,
  "restrictions": "Maximum 4% on credit cards"
}

    Check Compliance

    Check if a fee structure is compliant in a region.

    Endpoint: POST /v1/regions/check-compliance

    Request Body:

    {
  "region": "US-CA",
  "percentage": 2.9,
  "flatFee": 0.30,
  "cardType": "credit"
}

    Response:

    {
  "compliant": true,
  "region": "US-CA",
  "reason": null
}

    Non-compliant Example:

    {
  "compliant": false,
  "region": "US-NY",
  "reason": "Convenience fees are not allowed in US-NY"
}

    Errors

    The API uses standard HTTP status codes and returns error details in JSON format.

    Error Response Format

    {
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "The 'amount' parameter is required",
    "param": "amount"
  }
}

    HTTP Status Codes

    | Code | Description |

    |------|-------------|

    | 200 | Success |

    | 400 | Bad Request - Invalid parameters |

    | 401 | Unauthorized - Invalid API key |

    | 403 | Forbidden - API key lacks required permissions |

    | 404 | Not Found - Resource doesn't exist |

    | 429 | Too Many Requests - Rate limit exceeded |

    | 500 | Internal Server Error |

    Error Types

    | Type | Description |

    |------|-------------|

    | api_error | Server error |

    | authentication_error | Invalid API key |

    | invalid_request_error | Invalid parameters |

    | rate_limit_error | Too many requests |

    | card_error | Payment card issue |

    Example Error Handling:

    try {
  const charge = await fetch('https://api.sirchargly.com/v1/charges', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_dev_sirchargly_your_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: 10000,
      currency: 'USD'
    })
  });

  if (!charge.ok) {
    const error = await charge.json();
    console.error('Error:', error.error.message);
  }
} catch (error) {
  console.error('Request failed:', error);
}

    Rate Limiting

    API requests are rate limited to prevent abuse:

  • Development: 100 requests per minute
  • Production: 1000 requests per minute

    • Rate limit headers are included in responses:

    X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

    Webhooks

    Receive real-time notifications about events in your account.

    Webhook Events

    | Event | Description |

    |-------|-------------|

    | charge.succeeded | Charge completed successfully |

    | charge.failed | Charge failed |

    | charge.refunded | Charge was refunded |

    | dispute.created | Customer disputed charge |

    Webhook Payload

    {
  "id": "evt_123",
  "type": "charge.succeeded",
  "data": {
    "object": {
      "id": "ch_abc123",
      "amount": 10000,
      "convenienceFee": 320,
      "status": "succeeded"
    }
  },
  "created": 1704067200
}

    Verifying Webhooks

    Use the SDK to verify webhook signatures:

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

const signature = request.headers['sir-chargly-signature'];
const body = request.body; // Raw body string

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

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

    Pagination

    List endpoints support cursor-based pagination:

    # First page
curl https://api.sirchargly.com/v1/charges?limit=10

# Next page (use last charge ID as cursor)
curl https://api.sirchargly.com/v1/charges?limit=10&starting_after=ch_xyz

    Versioning

    The API is versioned using the URL path:

    https://api.sirchargly.com/v1/charges

    Breaking changes will result in a new version (v2, v3, etc.). We maintain backward compatibility for at least 12 months after deprecation notices.

    Additional Resources

  • SDK Reference - JavaScript/TypeScript SDK documentation
  • Testing Guide - Testing and debugging
  • Regional Compliance - State-by-state rules

    • For support, contact support@sirchargly.com

    Ready to start charging convenience fees?

    Create your account and complete onboarding in minutes.

    No credit card required • 5-minute setup