Domain Search and Hosted Checkout API Guide

Want to sell domain registrations from your own website? BillingServ can handle the registrar lookup and payment flow while you keep control of the customer experience. This guide shows how to search for available domain extensions, create a hosted checkout link, support checkout-first customers, and send customers back to your site after payment.

Before you start

Prepare:

A BillingServ v2 API key
Your BillingServ API base URL
A callback URL on your website
A configured domain registrar with the extensions you want to sell enabled
An existing BillingServ customer ID if you want to skip customer details during checkout

Keep the API key on your server. These requests should not run in browser code where visitors could inspect the credential.

Authentication

Send the API key as a bearer token with every request:

Authorization: Bearer <live_api_key>
Accept: application/json
Content-Type: application/json

The API uses the v2 base URL:

https://your-billingserv-domain.com/api/v2

1. Search for available domain extensions

Use POST /domain/lookup to check a name across the domain extensions enabled in your BillingServ account. Send the name without an extension. For example, use billingserv, not billingserv.com. The optional limit field controls how many extensions are checked. It accepts values from 1 to 50 and defaults to 50.

curl -X POST "https://your-billingserv-domain.com/api/v2/domain/lookup" \
  -H "Authorization: Bearer <live_api_key>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "billingserv",
    "limit": 10
  }'

The response includes one result for each enabled extension checked:

{
  "success": true,
  "domain": "billingserv",
  "registrar": "openprovider",
  "results": [
    {
      "domain": "billingserv.co.uk",
      "extension": "co.uk",
      "available": true,
      "premium": false
    },
    {
      "domain": "billingserv.com",
      "extension": "com",
      "available": false,
      "premium": false
    }
  ]
}

Use results with available: true when you build the domain selection step. Keep the premium value visible if premium domains need a different price or review process in your store.

2. Create a hosted checkout link

After the customer chooses a domain, call POST /checkout/create. BillingServ checks availability again before creating the checkout link. That second check helps prevent a customer from paying for a domain that became unavailable after the search. The request supports three checkout types:

Checkout type	Required fields
Existing package	`package_id`, `cycle_id`
One domain	`domain`, `years`
Multiple domains	`domains`, with a `domain` and `years` value for each item

Every checkout request also needs callback_url. customer_id is optional. When you provide it, it must belong to a BillingServ customer account. Here is a one-domain checkout request:

curl -X POST "https://your-billingserv-domain.com/api/v2/checkout/create" \
  -H "Authorization: Bearer <live_api_key>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "billingserv.co.uk",
    "years": 1,
    "customer_id": 123,
    "callback_url": "https://store.example.com/domain-complete"
  }'

BillingServ returns a hosted checkout URL:

{
  "success": true,
  "message": "Successfully",
  "url": "https://your-billingserv-domain.com/checkout/00000000-0000-0000-0000-000000000000"
}

Redirect the customer to url. The link is cached for 30 minutes and is invalidated after a completed payment. If the domain is unavailable, the API returns a 422 response and does not create a checkout link. If the registrar cannot confirm availability, the API returns 502.

3. Support checkout-first customers

You do not need a customer ID to create a domain checkout. Leave customer_id out when you want BillingServ to collect the customer’s details during the hosted checkout flow. If you provide customer_id, use the ID of an existing customer account. Client and staff account IDs are not valid for this endpoint.

4. Check out multiple domains in one flow

Send a domains array when the customer wants more than one registration. Each item needs a full domain name and a registration period in years.

curl -X POST "https://your-billingserv-domain.com/api/v2/checkout/create" \
  -H "Authorization: Bearer <live_api_key>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": [
      {
        "domain": "billingserv.co.uk",
        "years": 1
      },
      {
        "domain": "billingserv.com",
        "years": 1
      }
    ],
    "customer_id": 123,
    "callback_url": "https://store.example.com/domains-complete"
  }'

You can include up to 50 domains in one request. BillingServ checks every domain before returning the checkout link. Do not combine domains with domain, package_id, or cycle_id in the same request.

5. Keep package checkout working

The same endpoint still supports checkout for an existing package. Send package_id and cycle_id instead of domain fields:

{
  "package_id": 100,
  "cycle_id": 105,
  "customer_id": 123,
  "callback_url": "https://store.example.com/package-complete"
}

Use exactly one checkout type per request. This keeps package orders and domain registrations separate in the checkout flow.

6. Handle the payment callback

After the hosted checkout finishes, BillingServ redirects the customer to your callback_url. A successful payment includes:

?transaction_id=<gateway_transaction_id>&internal_transaction_id=<billingserv_transaction_id>&status=success&order_ref=<payment_session_code>&external_customer_id=<customer_id>

A failed payment includes:

?status=failed&external_customer_id=<customer_id>

external_customer_id is included when you supplied customer_id in the checkout request. Treat the callback as a browser return, not as your only payment confirmation. For server-side reconciliation, use the transaction and order identifiers with the BillingServ API and configure webhooks for payment events.

Error handling

Status	What it means
`401`	The API key is missing or invalid.
`403`	The authenticated key cannot use the endpoint.
`422`	The request is invalid or a requested domain is unavailable.
`429`	The domain availability rate limit was exceeded. The lookup endpoint allows 30 requests per minute per client.
`502`	The registrar could not confirm domain availability during checkout.

For a 422 response, show the returned error and ask the customer to choose another domain or correct the request. For a 502 response, retry from your server with a short backoff and keep the customer selection available.

Next steps

Read the API overview for authentication and response conventions. When you are ready to reconcile completed payments, use the webhook overview alongside the domain availability and hosted checkout API.

Getting Started

CMS

Customers

Invoices

InstantServ

Reports

Support

Settings

VPN

Account

Guides

Domain Search and Hosted Checkout API Guide

Before you start

Authentication

1. Search for available domain extensions

2. Create a hosted checkout link

3. Support checkout-first customers

4. Check out multiple domains in one flow

5. Keep package checkout working

6. Handle the payment callback

Error handling

Next steps

​Before you start

​Authentication

​1. Search for available domain extensions

​2. Create a hosted checkout link

​3. Support checkout-first customers

​4. Check out multiple domains in one flow

​5. Keep package checkout working

​6. Handle the payment callback

​Error handling

​Next steps

Before you start

Authentication

1. Search for available domain extensions

2. Create a hosted checkout link

3. Support checkout-first customers

4. Check out multiple domains in one flow

5. Keep package checkout working

6. Handle the payment callback

Error handling

Next steps