API Reference

Complete reference documentation for all StateSet Commerce APIs

API Reference

Complete documentation for all StateSet Commerce Network APIs. All API endpoints are RESTful and return JSON responses.

🌐 Base URLs

Production

https://api.stateset.com/v1

🔑 Authentication

All requests must include your API key in the Authorization header:

Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc

📚 Core APIs

Stablecoin API

Issue, redeem, and transfer ssUSD stablecoins

Key Endpoints:

• POST /stablecoin/issue
• POST /stablecoin/redeem
• POST /stablecoin/transfer
• GET /stablecoin/balance

Payments API

Process payments and handle transactions

Key Endpoints:

• POST /payments/create
• GET /payments/{id}
• POST /payments/refund
• GET /payments/list

Orders API

Manage e-commerce orders and fulfillment

Key Endpoints:

• POST /orders/create
• PATCH /orders/{id}
• POST /orders/{id}/fulfill
• GET /orders/list

Finance API

Trade finance, factoring, and lending

Key Endpoints:

• POST /finance/invoices/factor
• POST /finance/po/finance
• POST /finance/loans/create
• GET /finance/options

AI Agents API

Deploy and manage autonomous agents

Key Endpoints:

• POST /agents/create
• POST /agents/{id}/execute
• GET /agents/{id}/activity
• PATCH /agents/{id}/config

Global Commerce API

Cross-border trade and compliance

Key Endpoints:

• POST /global/orders/create
• POST /global/compliance/check
• GET /global/tax/calculate
• POST /global/shipping/quote

🔧 Common Parameters

Pagination

Most list endpoints support pagination:

Parameter	Type	Description	Default
limit	integer	Number of records to return	10
starting_after	string	Cursor for pagination	null
ending_before	string	Cursor for reverse pagination	null

Example:

GET /v1/orders?limit=20&starting_after=ord_123

Filtering

List endpoints support filtering:

GET /v1/orders?status=pending&created[gte]=2024-01-01

Expanding Objects

Request nested objects in a single call:

GET /v1/orders/ord_123?expand[]=customer&expand[]=items.product

📨 Request Format

Headers

Header	Required	Description
Authorization	Yes	Bearer token with your API key
Content-Type	Yes*	application/json for POST/PUT/PATCH
Idempotency-Key	No	Unique key for safe retries
X-Account-Id	No	Act on behalf of a connected account

Request Body

All POST, PUT, and PATCH requests accept JSON:

{
  "amount": 100.00,
  "currency": "ssusd",
  "recipient": "stateset1abc...",
  "metadata": {
    "order_id": "12345",
    "customer_email": "[e-mail]"
  }
}

📤 Response Format

Success Response

{
  "id": "pay_1a2b3c4d",
  "object": "payment",
  "amount": 100.00,
  "currency": "ssusd",
  "status": "succeeded",
  "created": 1640995200,
  "metadata": {
    "order_id": "12345"
  }
}

Error Response

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "The 'amount' parameter is required",
    "param": "amount",
    "doc_url": "https://docs.stateset.com/errors/parameter_missing"
  }
}

🔄 Idempotency

Ensure safe retries with idempotency keys:

curl -X POST https://api.stateset.com/v1/payments \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: unique-key-123" \
  -d '{...}'

Idempotency keys are valid for 24 hours.

📊 Rate Limits

Plan	Requests/Second	Daily Limit	Burst
Free	10	1,000	20
Starter	100	100,000	200
Growth	1,000	10,000,000	2,000
Enterprise	Custom	Custom	Custom

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

🌍 CORS

The API supports CORS for browser-based requests:

// Browser request example
fetch('https://api.stateset.com/v1/account/balance', {
  headers: {
    'Authorization': 'Bearer pk_test_...' // Public key only
  }
})
.then(response => response.json())
.then(data => console.log(data));

🔐 Security

API Key Types

Key Type	Prefix	Usage
Secret	sk_test_ / sk_live_	Server-side only
Public	pk_test_ / pk_live_	Client-side safe
Restricted	rk_test_ / rk_live_	Limited permissions

Best Practices

1. Never expose secret keys in client-side code
2. Use HTTPS for all requests
3. Verify webhooks with signature validation
4. Implement retry logic with exponential backoff
5. Monitor rate limits and implement caching

📡 Webhooks

Register webhooks to receive real-time events:

POST /v1/webhooks
{
  "url": "https://yourapp.com/webhook",
  "events": ["payment.succeeded", "order.created"]
}

Learn more about webhooks →

🧪 Testing

Test Mode

Use test API keys to simulate transactions:

• No real money movement
• Immediate transaction processing
• Special test card numbers available

Test Data

Resource	Test ID Format	Example
Customer	cust_test_*	cust_test_123
Payment	pay_test_*	pay_test_456
Order	ord_test_*	ord_test_789

📱 SDK Support

Official SDKs available for:

Node.js

npm install @stateset/sdk

Python

pip install stateset

Go

go get github.com/stateset/stateset-go

View all SDKs →

🆘 Support Resources

API Status

Real-time API status and incidents

Postman Collection

Import our complete API collection

Discord Community

Get help from developers

Support Portal

Contact our support team