Getting Started API
Base URLs, credentials, versioning and conventions
Getting Started — API Reference
Guides: Getting Started.
Base URLs
| Host | Paths |
|---|---|
https://api.goldrail.xyz | /api/<product>/* (canonical) and /api/genesis/<product>/* (release-train alias, same handlers) |
https://api.openconnect.cc | Same API. /connect/* = /api/connect/* |
Credentials
Each table of this reference gives the credential of every route (Auth column).
| Auth | Header | Who |
|---|---|---|
| API key | X-API-Key: gr_live_* / gr_test_* | A fintech or platform tenant. A Sub-Platform key (oc_live_*) also works on the routes that serve its tenant (for example /api/webhooks). |
| Sub-Platform key | X-API-Key: oc_live_* | A Sub-Platform with a payments module. The same product routes answer for its module; a route its key does not serve answers 404 ROUTE_NOT_AVAILABLE_FOR_SUB_PLATFORM_KEY. |
| Bearer | Authorization: Bearer <jwt> | A member, portal or end-user session. |
| Publishable key | X-Publishable-Key: pk_live_* / pk_test_* | Client-side SoftShell / embed calls. |
| POS device token | X-Pos-Device-Token | A device paired to a Connect Commerce POS session. |
| Public | — | No credential. |
Live keys (gr_live_*) need an approved KYB, except on a few onboarding paths (403 KYB_REQUIRED).
Versioning
Send Goldrail-Version: 2026-07-24.genesis (optional). On the Open Connect surface (/api/openconnect/*, /api/connect/*) the header is OpenConnect-Version. Without it the tenant pin, then the latest version, applies. The response echoes the version used.
Brand (Connect products)
The Connect products (/api/connect/*) serve every brand. Send Connect-Brand: connectpay | paylink | shogun, or call from the brand domain. Default: connectpay. See Brands.
Errors
Errors use one nested envelope: { "error": { "type", "code", "message", "doc_url", "request_id" } }. See Errors.
Money
Money-moving responses use a money object (usd, display, settled, fx, optional equivalents). Flat amount / amount_usd are removed on that closed list. Requests send amount + asset (for example XOF, XOFC), with sender / recipient objects for the parties. Add ?currencies=XOF,EUR for snapshot equivalents. Gift cards expose money (remaining) and face_money (face).