> ## Documentation Index
> Fetch the complete documentation index at: https://www.billingserv.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Hosted Checkout

> Creates a short-lived hosted checkout URL for a package, one domain, or up to 50 domain registrations. Use `package_id` with `cycle_id` for an existing package, `domain` with `years` for one domain, or `domains` for multiple domain registrations. `callback_url` is required. `customer_id` is optional; when supplied, it must reference a customer account (`account_type` 2). The checkout link is cached for 30 minutes. When the customer opens it, BillingServ creates a checkout-only session, allows supported saved payment methods, and redirects back to `callback_url` after payment.

Use this endpoint when your own website owns the customer-facing dashboard but you still want BillingServ to host checkout and payment collection.

The endpoint creates a hosted checkout URL for an existing package, one domain, or up to 50 domains. `callback_url` is required and `customer_id` is optional. If you provide `customer_id`, it must be a customer account (`account_type` 2). When the customer opens the returned URL, BillingServ creates a checkout-only session so supported saved payment methods can be used without giving the customer access to the full BillingServ panel. The link expires after 30 minutes if it is not completed.

## Request

Send the request with an API key that has access to this endpoint:

```bash theme={null}
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://your-site.example/account/billing/return"
  }'
```

Choose one checkout type for each request:

| Checkout type    | Fields                                             |
| :--------------- | :------------------------------------------------- |
| Existing package | `package_id` and `cycle_id`                        |
| One domain       | `domain` and `years`                               |
| Multiple domains | `domains`, with `domain` and `years` for each item |

Leave out `customer_id` for checkout-first flows where BillingServ collects the customer's details. See the [domain search and hosted checkout guide](/docs/guides/domain-api-checkout) for complete domain lookup, multi-domain, and callback examples.

## Response

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

Redirect the customer to the returned `url`. If a requested domain is unavailable, the API returns `422` and does not create a checkout link.

## Callback

After payment, BillingServ redirects the customer back to `callback_url` with query parameters.

Successful payment includes:

```text theme={null}
?transaction_id=<gateway_transaction_id>&internal_transaction_id=<billingserv_transaction_id>&status=success&order_ref=<payment_session_code>&external_customer_id=<customer_id>
```

Failed payment includes:

```text theme={null}
?status=failed&external_customer_id=<customer_id>
```

Treat the callback as a browser return URL. For server-side reconciliation, use the returned IDs with the transactions, orders, or invoices API.


## OpenAPI

````yaml POST /checkout/create
openapi: 3.1.0
info:
  title: BillingServ API V2
  description: >-
    Resources and tools for developers to integrate with the BillingServ v2 API,
    including customer management, domain availability, hosted checkout,
    billing, and service operations. v1 is deprecated; use the v2 base URL and
    bearer-token authentication unless an endpoint states otherwise.
  version: '2.0'
servers:
  - url: https://demo.onlinebillingform.com/api/v2
    description: BillingServ demo API
security:
  - bearerAuth: []
tags:
  - name: Customer
  - name: Package
  - name: Group
  - name: Country
  - name: County
  - name: VPN
  - name: Invoice
  - name: Order
  - name: Module
  - name: Report
  - name: Marketing
  - name: Setting
  - name: Checkout
  - name: Domain
    description: Search enabled domain extensions and check domain availability.
  - name: Usage
  - name: Support
  - name: Licensing
  - name: Webhooks
    description: Outbound events sent by BillingServ to a configured customer endpoint.
paths:
  /checkout/create:
    post:
      tags:
        - Checkout
      summary: Create hosted checkout link
      description: >-
        Creates a short-lived hosted checkout URL for a package, one domain, or
        up to 50 domain registrations. Use `package_id` with `cycle_id` for an
        existing package, `domain` with `years` for one domain, or `domains` for
        multiple domain registrations. `callback_url` is required. `customer_id`
        is optional; when supplied, it must reference a customer account
        (`account_type` 2). The checkout link is cached for 30 minutes. When the
        customer opens it, BillingServ creates a checkout-only session, allows
        supported saved payment methods, and redirects back to `callback_url`
        after payment.
      operationId: POST_checkout_create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: >-
                Provide exactly one checkout type: an existing package, one
                domain, or a list of domains.
              oneOf:
                - $ref: '#/components/schemas/CheckoutPackageRequest'
                - $ref: '#/components/schemas/CheckoutDomainRequest'
                - $ref: '#/components/schemas/CheckoutDomainsRequest'
          application/x-www-form-urlencoded:
            schema:
              description: >-
                Provide exactly one checkout type: an existing package, one
                domain, or a list of domains.
              oneOf:
                - $ref: '#/components/schemas/CheckoutPackageRequest'
                - $ref: '#/components/schemas/CheckoutDomainRequest'
                - $ref: '#/components/schemas/CheckoutDomainsRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HostedCheckoutResponse'
              example:
                success: true
                message: Successfully
                url: >-
                  https://demo.onlinebillingform.com/checkout/00000000-0000-0000-0000-000000000000
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                errors: Invalid API Key
        '403':
          description: Authenticated key does not have permission for this endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                errors: Insufficient permissions for this endpoint.
        '422':
          description: Validation or domain availability error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              example:
                success: false
                errors:
                  - The requested domain is not available.
        '502':
          description: The domain registrar could not confirm availability
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                errors:
                  - Unable to check domain availability right now.
      security:
        - bearerAuth: []
components:
  schemas:
    CheckoutPackageRequest:
      type: object
      description: Creates hosted checkout for an existing package and billing cycle.
      properties:
        package_id:
          type: integer
          minimum: 1
          description: Package or order-group package ID to add to checkout.
        cycle_id:
          type: integer
          minimum: 1
          description: Billing cycle ID for the selected package.
        callback_url:
          type: string
          format: uri
          description: >-
            URL BillingServ redirects to after hosted checkout succeeds or
            fails.
        customer_id:
          type:
            - integer
            - 'null'
          minimum: 1
          description: >-
            Optional existing BillingServ customer user ID. If supplied, the
            user must have account_type 2.
      required:
        - package_id
        - cycle_id
        - callback_url
      additionalProperties: false
    CheckoutDomainRequest:
      type: object
      description: Creates hosted checkout for one available domain registration.
      properties:
        domain:
          type: string
          maxLength: 255
          description: >-
            Full domain name to register, including its extension, such as
            `billingserv.co.uk`.
        years:
          type: integer
          minimum: 1
          maximum: 10
          description: >-
            Registration period in years. The account domain setting may allow a
            lower maximum.
        callback_url:
          type: string
          format: uri
          description: >-
            URL BillingServ redirects to after hosted checkout succeeds or
            fails.
        customer_id:
          type:
            - integer
            - 'null'
          minimum: 1
          description: >-
            Optional existing BillingServ customer user ID. If supplied, the
            user must have account_type 2.
      required:
        - domain
        - years
        - callback_url
      additionalProperties: false
    CheckoutDomainsRequest:
      type: object
      description: >-
        Creates one hosted checkout containing up to 50 available domain
        registrations.
      properties:
        domains:
          type: array
          minItems: 1
          maxItems: 50
          items:
            $ref: '#/components/schemas/DomainCheckoutItem'
        callback_url:
          type: string
          format: uri
          description: >-
            URL BillingServ redirects to after hosted checkout succeeds or
            fails.
        customer_id:
          type:
            - integer
            - 'null'
          minimum: 1
          description: >-
            Optional existing BillingServ customer user ID. If supplied, the
            user must have account_type 2.
      required:
        - domains
        - callback_url
      additionalProperties: false
    HostedCheckoutResponse:
      type: object
      description: >-
        A hosted checkout URL created by BillingServ. The URL expires after 30
        minutes if it is not completed.
      properties:
        success:
          type: boolean
          const: true
        message:
          type: string
          example: Successfully
        url:
          type: string
          format: uri
          description: Hosted checkout URL to open or redirect the customer to.
      required:
        - success
        - message
        - url
      additionalProperties: true
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          const: false
        errors:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
            - type: object
              additionalProperties: true
      additionalProperties: true
    ValidationErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          const: false
        errors:
          oneOf:
            - type: array
              items:
                type: string
            - type: object
              additionalProperties: true
            - type: string
      additionalProperties: true
    DomainCheckoutItem:
      type: object
      properties:
        domain:
          type: string
          maxLength: 255
          description: Full domain name to register, including its extension.
        years:
          type: integer
          minimum: 1
          maximum: 10
          description: >-
            Registration period in years. The account domain setting may allow a
            lower maximum.
      required:
        - domain
        - years
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Use `Authorization: Bearer <live_api_key>`.'

````