Start an embedded payment to buy a domain at retail

Server URLloading...

POST

/registrar/checkout

Send

Authorization

Body

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.

Response Body

curl -X POST "https://example.com/registrar/checkout" \  -H "Content-Type: application/json" \  -d '{    "domain": "string",    "buyer": {      "email": "[email protected]"    },    "return_url": "http://example.com"  }'

{  "id": "cs_test_123",  "url": "http://example.com",  "client_secret": "string",  "ui_mode": "embedded"}

{  "code": "string",  "title": "string",  "details": "string"}

{  "code": "string",  "title": "string",  "details": "string"}

{  "code": "billing_required",  "title": "An active subscription is needed to connect new domains.",  "details": "This workspace has not started its subscription yet. Domains that are already connected keep working. An owner or admin can set up billing at https://app.customdomain.ai/app/billing."}

{  "code": "workspace_suspended",  "title": "This workspace is suspended.",  "details": "New domains, connect steps and domain purchases are refused while CustomDomain™ support has this workspace suspended. Contact support to have it resumed."}

{  "code": "string",  "title": "string",  "details": "string"}