Reference

API reference

Base URL: https://cleargateway-api.onrender.com. All requests and responses are JSON. This page is generated from the API's own schemas, so it always matches what the API accepts.

Authentication

Merchant endpoints use Authorization: Bearer sk_test_…. Hosted-checkout endpoints use the payment's client secret in an x-client-secret header instead. Money amounts are integer strings in USDC base units (6 decimals). See Errors, limits & idempotency. A * marks required fields.

Payments Refunds Webhook endpoints Balance Hosted checkout (for custom checkout pages)

Payments

get/v1/payment_intentsList payment intents (cursor pagination, newest first)

Pass the last id of a page as starting_after to fetch the next page.

Path and query parameters

Field	Type	Details
limit (query)	integer	min 1, max 100, default 10
starting_after (query)	string	pattern ^pi_[0-9a-f]{32}$
status (query)	"created" \| "awaiting_payment" \| "confirming" \| "succeeded" \| "expired" \| "underpaid" \| "failed" \| "canceled" \| "refunded" \| "partially_refunded"
created_gte (query)	string (date-time)
created_lte (query)	string (date-time)

curl -X GET "https://cleargateway-api.onrender.com/v1/payment_intents" \
  -H "Authorization: Bearer $CLEARGATEWAY_API_KEY"

Response 200

Field	Type	Details
object*	"list"
data*	array<object>
has_more*	boolean
next_cursor*	string

post/v1/payment_intentsCreate a payment intent

Requires an Idempotency-Key header. amount is an integer string in USDC base units (6 decimals). The response includes checkout_url for the hosted checkout page.

Required header: idempotency-key

Request body

Field	Type	Details
amount*	string	pattern ^[1-9]\d{0,17}$
currency	"USDC"	default "USDC"
merchant_order_id	string	max length 255
metadata	object
customer_email	string (email)	max length 320
success_url	string (uri)	max length 2048
cancel_url	string (uri)	max length 2048
expires_in_seconds	integer	min 300, max 86400, default 3600

curl -X POST "https://cleargateway-api.onrender.com/v1/payment_intents" \
  -H "Authorization: Bearer $CLEARGATEWAY_API_KEY" \
  -H "Idempotency-Key: <unique per request>" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "25500000"
}'

Response 201

Field	Type	Details
id*	string
object*	"payment_intent"
mode*	"test" \| "live"
amount*	string
currency*	string
decimals*	number
fee_bps*	number
fee_amount*	string
merchant_amount*	string
status*	"created" \| "awaiting_payment" \| "confirming" \| "succeeded" \| "expired" \| "underpaid" \| "failed" \| "canceled" \| "refunded" \| "partially_refunded"
payment_method*	string
merchant_order_id*	string
metadata*	object
customer_email*	string
payer_address*	string
success_url*	string
cancel_url*	string
tx_hash*	string
confirmations*	number
requires_review*	boolean
expires_at*	string
succeeded_at*	string
created_at*	string
client_secret*	string
checkout_url*	string

get/v1/payment_intents/{id}Retrieve a payment intent

Path and query parameters

Field	Type	Details
id (path)*	string	pattern ^pi_[0-9a-f]{32}$

curl -X GET "https://cleargateway-api.onrender.com/v1/payment_intents/<id>" \
  -H "Authorization: Bearer $CLEARGATEWAY_API_KEY"

Response 200

Field	Type	Details
id*	string
object*	"payment_intent"
mode*	"test" \| "live"
amount*	string
currency*	string
decimals*	number
fee_bps*	number
fee_amount*	string
merchant_amount*	string
status*	"created" \| "awaiting_payment" \| "confirming" \| "succeeded" \| "expired" \| "underpaid" \| "failed" \| "canceled" \| "refunded" \| "partially_refunded"
payment_method*	string
merchant_order_id*	string
metadata*	object
customer_email*	string
payer_address*	string
success_url*	string
cancel_url*	string
tx_hash*	string
confirmations*	number
requires_review*	boolean
expires_at*	string
succeeded_at*	string
created_at*	string
client_secret*	string
checkout_url*	string

post/v1/payment_intents/{id}/cancelCancel an unpaid payment intent

Allowed only while created or awaiting_payment. A wallet payload already issued stays valid on-chain until its signature expiry; a payment landing after cancellation is flagged for review, never dropped.

Required header: idempotency-key

Path and query parameters

Field	Type	Details
id (path)*	string	pattern ^pi_[0-9a-f]{32}$

curl -X POST "https://cleargateway-api.onrender.com/v1/payment_intents/<id>/cancel" \
  -H "Authorization: Bearer $CLEARGATEWAY_API_KEY" \
  -H "Idempotency-Key: <unique per request>"

Response 200

Field	Type	Details
id*	string
object*	"payment_intent"
mode*	"test" \| "live"
amount*	string
currency*	string
decimals*	number
fee_bps*	number
fee_amount*	string
merchant_amount*	string
status*	"created" \| "awaiting_payment" \| "confirming" \| "succeeded" \| "expired" \| "underpaid" \| "failed" \| "canceled" \| "refunded" \| "partially_refunded"
payment_method*	string
merchant_order_id*	string
metadata*	object
customer_email*	string
payer_address*	string
success_url*	string
cancel_url*	string
tx_hash*	string
confirmations*	number
requires_review*	boolean
expires_at*	string
succeeded_at*	string
created_at*	string
client_secret*	string
checkout_url*	string

Refunds

get/v1/refundsList your refunds (newest first, cursor pagination)

Path and query parameters

Field	Type	Details
limit (query)	integer	min 1, max 100, default 20
starting_after (query)	string	max length 100
payment_intent_id (query)	string	pattern ^pi_[0-9a-f]{32}$

curl -X GET "https://cleargateway-api.onrender.com/v1/refunds" \
  -H "Authorization: Bearer $CLEARGATEWAY_API_KEY"

Response 200

Field	Type	Details
object*	"list"
data*	array<object>
has_more*	boolean
next_cursor*	string

post/v1/refundsRecord a refund request

Records the request only: nothing is sent on-chain yet. amount (USDC base units) defaults to everything still refundable. The total of all live refunds can never exceed the amount the customer paid. Emits refund.created.

Required header: idempotency-key

Request body

Field	Type	Details
payment_intent_id*	string	pattern ^pi_[0-9a-f]{32}$
amount	string	pattern ^[1-9]\d{0,17}$
to_address*	string
reason	string	max length 500

curl -X POST "https://cleargateway-api.onrender.com/v1/refunds" \
  -H "Authorization: Bearer $CLEARGATEWAY_API_KEY" \
  -H "Idempotency-Key: <unique per request>" \
  -H "Content-Type: application/json" \
  -d '{
  "payment_intent_id": "pi_...",
  "to_address": "0xCustomerWalletAddress"
}'

Response 201

Field	Type	Details
id*	string
object*	"refund"
payment_intent_id*	string
amount*	string
currency*	string
decimals*	number
status*	"requested" \| "approved" \| "processing" \| "succeeded" \| "failed" \| "rejected"
to_address*	string
tx_hash*	string
reason*	string
requested_by*	string
created_at*	string
updated_at*	string

get/v1/refunds/{id}Retrieve a refund

Path and query parameters

Field	Type	Details
id (path)*	string	pattern ^re_[0-9a-f]{32}$

curl -X GET "https://cleargateway-api.onrender.com/v1/refunds/<id>" \
  -H "Authorization: Bearer $CLEARGATEWAY_API_KEY"

Response 200

Field	Type	Details
id*	string
object*	"refund"
payment_intent_id*	string
amount*	string
currency*	string
decimals*	number
status*	"requested" \| "approved" \| "processing" \| "succeeded" \| "failed" \| "rejected"
to_address*	string
tx_hash*	string
reason*	string
requested_by*	string
created_at*	string
updated_at*	string

Webhook endpoints

get/v1/webhook_endpointsList webhook endpoints

curl -X GET "https://cleargateway-api.onrender.com/v1/webhook_endpoints" \
  -H "Authorization: Bearer $CLEARGATEWAY_API_KEY"

Response 200

Field	Type	Details
object*	"list"
data*	array<object>

post/v1/webhook_endpointsCreate a webhook endpoint

Returns the signing secret exactly once. Deliveries carry ClearGateway-Signature: t=<unix>,v1=<HMAC-SHA256 of "<t>.<raw body>">. In production the URL must be https and must not resolve to a private address.

Required header: idempotency-key

Request body

Field	Type	Details
url*	string (uri)	max length 2048
enabled_events	array<"*" \| "payment_intent.succeeded" \| "payment_intent.expired" \| "payment_intent.underpaid" \| "payment_intent.failed" \| "payment_intent.requires_review" \| "refund.created">

curl -X POST "https://cleargateway-api.onrender.com/v1/webhook_endpoints" \
  -H "Authorization: Bearer $CLEARGATEWAY_API_KEY" \
  -H "Idempotency-Key: <unique per request>" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com"
}'

Response 201

Field	Type	Details
id*	string
object*	"webhook_endpoint"
mode*	"test" \| "live"
url*	string
enabled_events*	array<string>
status*	"enabled" \| "disabled"
created_at*	string
secret	string

get/v1/webhook_endpoints/{id}Retrieve a webhook endpoint

Path and query parameters

Field	Type	Details
id (path)*	string	pattern ^we_[0-9a-f]{32}$

curl -X GET "https://cleargateway-api.onrender.com/v1/webhook_endpoints/<id>" \
  -H "Authorization: Bearer $CLEARGATEWAY_API_KEY"

Response 200

Field	Type	Details
id*	string
object*	"webhook_endpoint"
mode*	"test" \| "live"
url*	string
enabled_events*	array<string>
status*	"enabled" \| "disabled"
created_at*	string
secret	string

delete/v1/webhook_endpoints/{id}Delete a webhook endpoint

Stops future deliveries; pending deliveries to it are abandoned.

Path and query parameters

Field	Type	Details
id (path)*	string	pattern ^we_[0-9a-f]{32}$

curl -X DELETE "https://cleargateway-api.onrender.com/v1/webhook_endpoints/<id>" \
  -H "Authorization: Bearer $CLEARGATEWAY_API_KEY"

Response 200

Field	Type	Details
id*	string
object*	"webhook_endpoint"
deleted*	true

post/v1/webhook_endpoints/{id}/testSend a test event to this endpoint

Queues a webhook.test event; the delivery worker sends it like any other event.

Required header: idempotency-key

Path and query parameters

Field	Type	Details
id (path)*	string	pattern ^we_[0-9a-f]{32}$

curl -X POST "https://cleargateway-api.onrender.com/v1/webhook_endpoints/<id>/test" \
  -H "Authorization: Bearer $CLEARGATEWAY_API_KEY" \
  -H "Idempotency-Key: <unique per request>"

Response 202

Field	Type	Details
object*	"webhook_test"
endpoint_id*	string
queued*	boolean

Balance

get/v1/balanceMerchant totals, computed from the double-entry ledger

Derived from ledger entries on the merchant's receivable account, never by summing payment intents. Only confirmed (on-chain, final) payments and recorded refunds appear here.

curl -X GET "https://cleargateway-api.onrender.com/v1/balance" \
  -H "Authorization: Bearer $CLEARGATEWAY_API_KEY"

Response 200

Field	Type	Details
object*	"balance"
mode*	"test" \| "live"
currency*	string
decimals*	number
settled*	string
refunded*	string
net*	string
settled_payments*	number

Hosted checkout (for custom checkout pages)

get/v1/checkout/{intentId}Public-safe fields for rendering checkout

Public endpoint scoped to one intent. Authenticate with the intent's client secret via the x-client-secret header (or client_secret query parameter for EventSource, which cannot set headers).

Path and query parameters

Field	Type	Details
client_secret (query)	string	max length 200
intentId (path)*	string	pattern ^pi_[0-9a-f]{32}$

curl -X GET "https://cleargateway-api.onrender.com/v1/checkout/<intentId>" \
  -H "x-client-secret: <the payment's client secret>"

post/v1/checkout/{intentId}/wallet-paymentGet the signed payload for paying from a connected wallet

Public endpoint scoped to one intent. Authenticate with the intent's client secret via the x-client-secret header (or client_secret query parameter for EventSource, which cannot set headers). method=approve returns approval + pay arguments; method=authorization returns EIP-3009 typed data for a one-signature payment via payWithAuthorization.

Path and query parameters

Field	Type	Details
client_secret (query)	string	max length 200
intentId (path)*	string	pattern ^pi_[0-9a-f]{32}$

Request body

Field	Type	Details
payer_address*	string
method	"approve" \| "authorization"	default "approve"

curl -X POST "https://cleargateway-api.onrender.com/v1/checkout/<intentId>/wallet-payment" \
  -H "x-client-secret: <the payment's client secret>" \
  -H "Content-Type: application/json" \
  -d '{
  "payer_address": "0xCustomerWalletAddress"
}'

post/v1/checkout/{intentId}/deposit-addressGet (or create) a per-payment deposit address for sending USDC from an exchange

Public endpoint scoped to one intent. Authenticate with the intent's client secret via the x-client-secret header (or client_secret query parameter for EventSource, which cannot set headers). Idempotent: returns the same address on every call. The customer sends USDC on Base to this address; the platform detects, confirms and settles the payment automatically, with no signature from the customer.

Path and query parameters

Field	Type	Details
client_secret (query)	string	max length 200
intentId (path)*	string	pattern ^pi_[0-9a-f]{32}$

curl -X POST "https://cleargateway-api.onrender.com/v1/checkout/<intentId>/deposit-address" \
  -H "x-client-secret: <the payment's client secret>"

post/v1/checkout/{intentId}/onramp-sessionCreate a card / Apple Pay on-ramp session (Wert primary, Simplex secondary; provider picked per merchant)

Public endpoint scoped to one intent. Authenticate with the intent's client secret via the x-client-secret header (or client_secret query parameter for EventSource, which cannot set headers). The on-ramp delivers USDC to customer_wallet_address, which must belong to the customer (never the merchant's payout wallet, the splitter, or the USDC contract). That wallet then pays through /wallet-payment once funded; this endpoint never marks the intent paid.

Path and query parameters

Field	Type	Details
client_secret (query)	string	max length 200
intentId (path)*	string	pattern ^pi_[0-9a-f]{32}$

Request body

Field	Type	Details
customer_wallet_address*	string
customer_email	string (email)	max length 320

curl -X POST "https://cleargateway-api.onrender.com/v1/checkout/<intentId>/onramp-session" \
  -H "x-client-secret: <the payment's client secret>" \
  -H "Content-Type: application/json" \
  -d '{
  "customer_wallet_address": "0xCustomerWalletAddress"
}'

get/v1/checkout/{intentId}/statusPoll payment status

Public endpoint scoped to one intent. Authenticate with the intent's client secret via the x-client-secret header (or client_secret query parameter for EventSource, which cannot set headers).

Path and query parameters

Field	Type	Details
client_secret (query)	string	max length 200
intentId (path)*	string	pattern ^pi_[0-9a-f]{32}$

curl -X GET "https://cleargateway-api.onrender.com/v1/checkout/<intentId>/status" \
  -H "x-client-secret: <the payment's client secret>"

get/v1/checkout/{intentId}/status/streamServer-sent events stream of status changes

Path and query parameters

Field	Type	Details
client_secret (query)	string	max length 200
intentId (path)*	string	pattern ^pi_[0-9a-f]{32}$

curl -X GET "https://cleargateway-api.onrender.com/v1/checkout/<intentId>/status/stream" \
  -H "x-client-secret: <the payment's client secret>"