API Reference

Base URLs

Authentication

Hedge Payments uses two authentication methods depending on the context:

API Key (Server-side)

Use your API secret key in the Authorization header for all server-side requests:

Authorization: Bearer sk_live_your_api_secret_key

JWT (Client-side)

For client-side SDK operations, use a short-lived JWT obtained from your server. JWTs are scoped to a specific customer and expire after 15 minutes.

// Server-side: generate a client token
const token = await hedge.clientTokens.create({
  customerId: 'cust_abc123',
  scopes: ['checkout', 'payment_methods']
})

// Client-side: pass the token to the SDK
<HedgeProvider clientToken={token.jwt}>
  <CheckoutForm />
</HedgeProvider>

Request / Response Format

• All request bodies must be JSON with Content-Type: application/json
• All responses are JSON encoded in UTF-8
• Monetary amounts are in cents (e.g., 9999 = $99.99)
• Timestamps are ISO 8601 format in UTC
• IDs use prefixed strings (e.g., pay_, cust_, evt_)

// Example request
curl -X POST https://api.hedgepayments.com/v1/payments \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 9999,
    "currency": "USD",
    "customer_email": "customer@example.com"
  }'

// Example response
{
  "id": "pay_abc123",
  "amount": 9999,
  "currency": "USD",
  "status": "pending",
  "created_at": "2024-06-15T10:30:00Z"
}

Rate Limits

API requests are limited to 100 requests per minute per API key. Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1718450460

If you exceed the limit, you will receive a 429 Too Many Requests response. Wait until the X-RateLimit-Reset timestamp before retrying.

Versioning

The current API version is v1. The version is included in the URL path:

https://api.hedgepayments.com/v1/payments

Breaking changes will be introduced in new versions. Non-breaking additions (new fields, new endpoints) may be added to the current version without notice.

Endpoints

Auth

Payments

Checkout

Merchants

Round-Ups

Webhooks