Registrar

Start an embedded payment to buy a domain at retail

Authorizes payment (manual capture) for a domain at the retail price. Returns a Stripe checkout session whose client_secret drives the embedded payment element. The domain is registered only after payment completes via POST /v1/registrar/fulfill; the card is captured strictly after the registrar settles, so a failed registration never charges the buyer. 503 when purchasing is disabled on the deployment.

ui_mode is optional and picks how the payment is shown. Leave it out (a null or an empty string counts as leaving it out), or send embedded, for Stripe Embedded Checkout. elements is Elements with the Checkout Sessions API: the caller renders the page and mounts only Stripe's Payment Element with the returned client_secret, so the page can wear its own theme; the session is created on a Stripe API version of the dahlia release train (the billing guide names the exact version), so mount it with a Stripe.js of that train. Authorizing now and capturing after registration works the same in both. The response's ui_mode says what was really created (embedded or elements; a domain payment has no redirect flow, so it is never hosted): an elements request answers embedded when Stripe could not create an Elements session, so read it before mounting anything. Any other ui_mode, hosted included, is a 400.

post/registrar/checkout

Request

  • Base URL: https://api.customdomain.ai/v1
  • URL: https://api.customdomain.ai/v1/registrar/checkout
  • Auth: HTTP bearer

Request body

domainstring required
return_urlstring uri required
ui_mode'embedded' | 'elements'

How the payment is shown. Leave it out (or send null or an empty string) for embedded: a domain payment has no redirect flow. Never send hosted.

Response

Stripe checkout session (embedded or elements)

idstring required
urlstring uri

hosted checkout URL (unused for embedded and elements sessions).

client_secretstring

mount Stripe Embedded Checkout or the elements checkout with this.

ui_mode'embedded' | 'elements'

How the session was really created. An elements request answers embedded when Stripe could not create an Elements session. A domain payment has no redirect flow, so it is never hosted.

Example response

{
  "id": "cs_test_123"
}

Changes

No recorded changes to this operation across all 1 revision of this API.