payment-gateway API
Unified off-chain payment microservice for Hello World DAO and FounderyOS. Consolidates three payment rails behind a single REST surface:
- Stripe — USD fiat (membership, donations, SaaS billing, courses, internal disbursements)
- Stripe Connect — marketplace buyer → vendor purchases with 30-day fee-split hold
- ICP / DOM crypto — ICRC-1 transfers to per-payment subaccounts with price oracles
Port: 3200 · Namespace: platform on AX42-U · Epic: PLATFORM-007 (completed 2026-04-19)
For the full reference including all endpoints, schemas, error codes, sequence diagrams, database schema, env vars, and scheduled jobs, see the root API reference at api/payment-gateway.md in the docs repo (also indexed in the API Documentation Index).
Quick Reference
Endpoints
| Method | Path | Purpose |
|---|---|---|
GET | /api/v1/health | Liveness / readiness probe (public) |
POST | /api/v1/payments | Create payment session (fiat or crypto) |
GET | /api/v1/payments/:id | Fetch payment status |
POST | /api/v1/payments/:id/verify | Verify on-chain crypto transfer |
POST | /api/v1/payments/:id/refund | Refund payment (Stripe only — crypto returns 501) |
POST | /api/v1/payouts/release | Manually release held marketplace fee split |
POST | /api/v1/vendors/onboard | Create / refresh Stripe Connect Express account |
POST | /api/v1/webhooks/stripe | Stripe webhook (public, HMAC-signed) |
POST | /api/v1/webhooks/stripe-connect | Stripe Connect webhook (separate secret) |
Authentication
All non-webhook endpoints require Authorization: Bearer <TOKEN_PAYMENT_GATEWAY> from the platform/service-tokens k8s Secret. Fails closed when SERVICE_TOKEN is unset. Webhooks verify via Stripe HMAC signatures (STRIPE_WEBHOOK_SECRET and STRIPE_CONNECT_WEBHOOK_SECRET — separate keys).
Provider Routing
| Currency | Provider | Notes |
|---|---|---|
usd | Stripe or Stripe Connect | Selected by payment type |
icp | IcpProvider | NNS XRC oracle |
dom | IcpProvider | Governance canister price oracle |
marketplace-purchase and marketplace-vendor-payout types always route to Stripe Connect. All other USD types route to standard Stripe.
Related
- Repository
- Full API reference
- dom-token — on-chain HeldBurn analogue to the 30-day fee-split hold
- governance —
get_current_dom_price()price oracle