API Reference

All merchant API calls use HMAC authentication. The base URL is https://api.oncharge.io.

Authentication

Every request must include three headers:

The signing string is: {timestamp}.{METHOD}.{path}.{sha256(body)}

The HMAC key is the SHA256 hash of your API secret. Requests with timestamps older than 5 minutes are rejected.

POST endpoints also accept an Idempotency-Key header to prevent duplicate processing.

POST /v1/checkout/sessions

Create a new checkout session. Returns a session ID, iframe URL, and pay token.

{
  "amount": 9999,
  "currency": "USD",
  "reference": "order-42",
  "return_url": "https://shop.example.com/thank-you",
  "order_id": "42",
  "customer_email": "shopper@example.com",
  "customer_phone": "+15551234567"
}

Response (201):

{
  "session_id": "cs_abc123...",
  "status": "created",
  "iframe_url": "/checkout/cs_abc123...?token=pt_...",
  "pay_token": "pt_...",
  "created_at": "2026-02-07T12:00:00Z",
  "expires_at": "2026-02-07T12:30:00Z"
}

GET /v1/checkout/sessions/{id}

Retrieve the current status of a checkout session. Status values: created, pending, authorized, captured, refused, cancelled, error, expired.

POST /v1/checkout/sessions/{id}/cancel

Cancel an authorized (not yet captured) payment. Only works when session status is authorized.

POST /v1/refunds

Request a refund for a captured payment.

{
  "session_id": "cs_abc123...",
  "amount": 5000,
  "currency": "USD",
  "reference": "refund-42"
}

Response (201):

{
  "refund_id": "ref_xyz789...",
  "session_id": "cs_abc123...",
  "status": "refund_requested",
  "psp_reference": "PSP_REF_...",
  "amount": 5000,
  "currency": "USD"
}

Error Responses

All errors return a JSON body with error and message fields:

{
  "error": "invalid_signature",
  "message": "HMAC signature verification failed"
}

Common error codes: missing_auth, invalid_key, timestamp_expired, invalid_signature, rate_limited, global_ban, not_found, invalid_state.