API reference

All endpoints live under /api/v1 on the host where your Subsie instance runs. Authenticate with a secret key in the Authorization header:

Authorization: Bearer orven_sk_test_...   # or orven_sk_live_...

Test keys (orven_sk_test_) operate on Base Sepolia and see only test-mode data; live keys (orven_sk_live_) operate on Base mainnet and see only live data. Keys can be revoked at any time on the Developers page.

Errors return conventional status codes and a consistent envelope. details appears on validation failures with per-field messages; type is a deprecated alias of code.

{
  "error": {
    "code": "invalid_request_error",
    "type": "invalid_request_error",
    "message": "amount is required for payment mode",
    "details": [{ "field": "amount", "message": "Required" }]
  }
}

Creation endpoints accept an Idempotency-Key header (up to 200 characters). Replaying the same key with the same body within 24 hours returns the original response with an Idempotency-Replayed: true header; the same key with a different body returns 409. Keys are scoped to your merchant account, endpoint, and key mode — failed requests release the key for retry.

List endpoints return newest-first and share one scheme: limit (1–100, default 20) and starting_after (the id of the last item from the previous page).

{
  "object": "list",
  "data": [ ... ],
  "has_more": true
}

Requests are limited per key (120 per minute by default); a 429 response includes a Retry-After header in seconds. Monetary amounts are decimal strings in human USDC units with at most six decimal places — "25", "0.5", "9.99" — never floats.

Returns 201 with the session. Supports Idempotency-Key.

Returns the session, or 404 if it does not exist for your merchant and mode. Expiry is applied lazily: reading a session past its expires_at flips it to expired.

First send the refund on-chain from a verified settlement wallet to the payment's payer (same token), then report it here. Subsie fetches the receipt and requires a matching ERC-20 Transfer; re-reporting the same transaction returns the existing refund.

Returns 201 with the refund (200on an idempotent re-report). A transfer that doesn't match — wrong token, not from a verified wallet, not to the payer, or over the refundable amount — is rejected.

Returns the wallet with a verification object containing the message to sign and its expires_at (challenges live for one hour and are single-use). Registering an already-verified address returns it unchanged.

Returns the wallet with status: "verified". An expired or already-used challenge returns 400/409 — re-register to get a fresh one.

Revoking sets status: "revoked"; the wallet can no longer be used as a session recipient. Existing completed payments are unaffected.

Returns 201 including the signing secret (whsec_…) — shown only in this response. Supports Idempotency-Key; replays return the same endpoint without re-revealing the secret.

Returns 201with the enqueued webhook event. The delivery is real — signed with the endpoint's secret and retried on failure — but data.object is synthetic: its ids never resolve via the retrieval APIs.

List responses omit the secret. Deleting returns { "id": "we_…", "object": "webhook_endpoint", "deleted": true }.

Redelivers the event: a fresh delivery with the original payload byte-for-byte (same envelope id, so consumer dedupe treats both as one logical event) and a full retry budget. Returns 201 with the new webhook event, its resend_of set to the original root event id. Returns 409 while the original or an existing redelivery is still pending, and 400 if its endpoint is disabled.