HeadlessDomains Partners

Partner docs

Frontend integration guide

Use this when a reseller builds a downstream registrar frontend outside the shared partner portal.

Copy-paste implementation

Required flow

1. Preflight before paymentCall the partner API to validate the label, namespace, wholesale cost, Gems estimate, and balance readiness before collecting customer payment.
2. Collect payment outside HeadlessDomainsThe reseller collects retail payment with their own rails: Stripe, Bitcoin, HNS, invoice, manual approval, or another flow.
3. Register after payment succeedsAfter payment is complete, call the authenticated registration endpoint with an idempotency key and retail payment reference.
4. Keep GFA Gems fundedSuccessful provisioning debits the reseller's prepaid GFA Gems balance at the current wholesale quote.

Security rules

Never expose API secrets in browser JavaScriptUse a server-side endpoint, serverless function, or private backend for authenticated registration calls.
Use idempotency keysUse the payment intent, invoice id, or another stable reference so retries do not duplicate registrations.
Store the customer relationship downstreamThe partner owns customer login, receipts, support, and payment records. HeadlessDomains stores registry and billing state.

API outline

POST /api/v1/namespaces/{tld}/preflight
Authorization: Bearer hdpart_...

{
  "label": "alice",
  "years": 1
}

POST /api/v1/namespaces/{tld}/registrations
Authorization: Bearer hdpart_...

{
  "label": "alice",
  "years": 1,
  "registrant_email": "alice@example.com",
  "retail_payment_reference": "stripe_or_invoice_id",
  "idempotency_key": "stripe_or_invoice_id"
}