Ordering a Domain

Short tutorial for prepaid domain ordering through the API.

Ordering a Domain

This is the shortest API flow for ordering a domain with prepaid billing.

1. Optional: check whether the domain can be ordered

Use GET /domains/{domainname} before starting the order.

Example:

GET /domains/example.hu

The response tells you which operations are possible for the domain, for example new or transfer.

2. Create the prepaid domain order

Create the pending domain service with POST /customers/{customer_id}/domains-prepay.

New registration example:

{
  "domain": "example.hu",
  "operation": "register",
  "years": 1,
  "currency": "HUF"
}

Transfer example:

{
  "domain": "example.hu",
  "operation": "transfer",
  "years": 0,
  "currency": "HUF"
}

Important:

  • The response returns the created pending service.
  • Keep response.id from this call. You will use it later as the service id.
  • For transfers, send operation: "transfer" and years: 0.

3. Find the invoice item and create the invoice

The prepaid order creates an unissued invoice item for the new pending service.

A simple way to get it is:

GET /customers/{customer_id}/services/{service_id}/valid_items

That route is documented here: GET /customers/{customer_id}/services/{service_id}/valid_items.

Take the created invoice item id, then create the invoice with POST /customers/{customer_id}/invoices.

Example request:

{
  "invoice_item_ids": [12345]
}

Keep response.data.id from the invoice response. That is the invoice id.

4. Pay the invoice

The invoice must be paid before the domain can be finalized.

You can do that either:

Credit payment example:

{
  "invoice_ids": [67890],
  "payment_method": "credit"
}

If you use another gateway through POST /customers/{customer_id}/invoices/pay, send the same invoice_ids with the selected payment_method and the required redirect URLs for that gateway.

5. Create the contact

Create the domain contact with POST /customers/{customer_id}/contacts.

Example request:

{
  "contact_type": "PRIVATE",
  "name": "John Doe",
  "ident": "1990-01-01",
  "country": "HU",
  "language": "en",
  "zip_code": "1138",
  "city": "Budapest",
  "street": "Example utca 1.",
  "contact": "John Doe",
  "email": "john@example.com",
  "phone_number": "+36.12345678"
}

Keep response.data.id from the contact response. That is the contact id you will use as contacts_owner.

Notes:

  • For LEGAL contacts, ident is the tax number instead of a birth date.
  • The final domain request usually uses the contact id. Contact email and the other owner details come from the contact record.

6. Find the correct datapending task

After the invoice is paid, the prepaid workflow creates or advances a customer task that must be used for the final domain creation.

List tasks:

GET /customers/{customer_id}/tasks

That route is documented here: GET /customers/{customer_id}/tasks.

Find the task that matches all of these:

  • module = service-create
  • result1 = item-paid
  • result2 = datapending
  • arg2 = {service_id} from step 2

Keep that task id. You will use it as prepay_task_id.

7. Create the domain

Finalize the domain with POST /customers/{customer_id}/domains.

New registration example:

{
  "domain": "example.hu",
  "registration_type": "new",
  "contacts_owner": 501,
  "prepay_task_id": 9876,
  "nameserver": "ns1.atw.hu"
}

Transfer example:

{
  "domain": "example.hu",
  "registration_type": "transfer",
  "contacts_owner": 501,
  "prepay_task_id": 9876,
  "nameserver": "ns1.atw.hu",
  "auth_code": "AUTH-CODE-123"
}

For transfers, auth_code is required.

You can also send other supported domain fields when your TLD flow needs them, but the required pieces for the prepaid flow are:

  • the domain name
  • the registration type
  • the owner contact id
  • the prepaid task id

State names

Some domain and service states use Hungarian names. The most important ones in this flow are:

  • BEJEGYZENDO: pending registration. The domain order has been created and is waiting to be registered.
  • VAROLISTA: waiting list. The domain is in a queued or waiting state instead of being ready for a normal new registration.
  • REGISZTRALVA: registered. The domain registration completed successfully.
  • SIKERTELEN: failed. The registration or related domain process did not complete successfully.
  • KARANTEN: quarantine. The domain is in an expired or redemption-like state, not in a normal active registered state.
  • paymentpending: the prepaid service exists, but the invoice has not been paid yet.
  • datapending: the invoice is paid, and the system is waiting for the final domain registration request.
  • active: the prepaid flow is completed and the linked service is active.

Summary

The short flow is:

  1. Optional GET /domains/{domainname}
  2. POST /customers/{customer_id}/domains-prepay
  3. Find the created invoice item and POST /customers/{customer_id}/invoices
  4. Pay the invoice
  5. POST /customers/{customer_id}/contacts
  6. GET /customers/{customer_id}/tasks and find the matching datapending task by arg2 = service_id
  7. POST /customers/{customer_id}/domains

After the last step, the customer has the domain order fully created in the system.