HypertronPayments API
Hosted checkout on the same pool.
The Payments API is for products that already have a payment experience: commerce, payroll, treasury, or any app that should keep owning checkout. Your server creates a Payment, Hypertron hosts checkout, the customer pays, you get a stateful object and HMAC-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 at least 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": "25.00",
"currency": "XLM",
"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. Private settlement on the live testnet pool is native XLM. USDC on the same circuits is on the production roadmap.
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. |
Assets
The live shielded pool is native XLM.
Payment objects can name a currency. That is not the same as a live private pool for that asset. Do not treat USDC or EURC as shielded-pool settlement today.
| Asset | Status |
|---|---|
| XLM | Live on Stellar testnet. Native SAC pool CB2SVTMG... Browser proving, private checkout, and indexed transfers. |
| USDC | Planned on the existing privacy circuits. Not a deployed shielded pool. Checkout and treasury will wire it after the USDC testnet pool is verified. |
| EURC | May appear as a payment-object currency for classic Stellar checkout. Not a live Hypertron shielded-pool asset. |
Environments
Test first. Move live deliberately.
A key only accesses data created in its own environment. Testnet checkout still hits the live native-XLM testnet pool (CB2SVTMG...) when privacy is on. See the protocol page for that trust model.