Payments API
Hosted checkout on the same pool.
The Payments API is for products that already have a payment experience. Your server creates a Payment, Hypertron hosts checkout, the customer pays, you get a stateful object and signed events. Checkout can spend into the shielded pool; the API does not replace the protocol.
Auth
Secret keys on the server. Never in the browser.
Bearer sk_test_ / sk_live_. Environment-scoped: a test key cannot read live payments. Keys are shown once. Store a hash, prefix, and last four.
| Header | Rule |
|---|---|
| Authorization | Required. Bearer secret. Not query, not body. |
| Content-Type | application/json on requests with a body. |
| Idempotency-Key | Required on POST /v1/payments. 1–255 chars, retained ≥ 24h. |
| X-Request-Id | Optional tracing. Response always echoes a request id. |
Amounts are decimal strings. Never floats. IDs are opaque prefixes (pay_, evt_). Dashboard session routes under /api/* are a different control plane — they are not this API.
Quickstart
Create your first checkout.
Use a test key while you build. Retries with the same idempotency key cannot produce a second payment.
1.Create a test key
Developer console → sk_test_ key. Copy it once.
2.Create a payment
amount, currency, optional customer and metadata.
3.Track the result
Poll the payment or subscribe to events.
curl -X POST "$HYPERTRON_API/v1/payments" \
-H "Authorization: Bearer $HYPERTRON_SECRET_KEY" \
-H "Idempotency-Key: order_1234" \
-H "Content-Type: application/json" \
-d '{
"amount": "125.00",
"currency": "USDC",
"description": "Order #1234",
"customer_email": "customer@example.com",
"metadata": { "order_id": "ord_1234" }
}'Keep secret keys on your server. Never expose sk_test_ or sk_live_ in browser code. Supported currencies: USDC, EURC, XLM.
Canonical resource
Payment is the object. Checkout is a URL.
v1 does not expose PaymentLink as the developer abstraction. Links remain an internal checkout mechanism.
01Create
POST /v1/payments with an idempotency key. Response includes checkout_url.
02Pay
Customer opens hosted checkout and pays from a Stellar wallet — privately if they hold covering notes.
03Confirm
Hypertron observes the chain (or pool events) and advances the payment object.
04Operate
Poll GET /v1/payments/:id or handle signed webhooks. Cancel while still open.
Events
Signed delivery, not a polling substitute you ignore.
Register endpoints in the developer console. Signing secrets are shown once. Verify HMAC before acting. Test delivery does not create a real PaymentEvent.
| Event | When |
|---|---|
| payment.created | Payment object accepted. |
| payment.pending | Customer action in flight. |
| payment.confirmed | Chain observation passed initial checks. |
| payment.completed | Terminal success. |
| payment.failed | Terminal failure. |
| payment.expired | Window elapsed unpaid. |
| payment.canceled | Merchant canceled an open payment. |
Environments
Test first. Move live deliberately.
A key only accesses data created in its own environment. Testnet checkout still hits the live testnet pool (CB2SVTMG…) when privacy is on — see the protocol page for that trust model.