IntegrationsRegistrar APIs: registration, renewal and transfer

Registrar APIs come in two broad families: HTTP APIs specific to a registrar, and EPP, the protocol registries themselves speak, defined for domains in RFC 5731 and for contacts in RFC 5733. Whichever you are talking to, the three core operations behave very differently, and an integration that treats them uniformly will get transfers wrong.

Registration: treat it as irreversible

A registration takes money and creates something that exists for the term you bought. There is no undo — a deletion inside the grace window is a registrar-specific courtesy, not a right, and it does not exist everywhere. Two consequences for an integration:

• Never retry blind. A registration whose answer was lost may have succeeded and been charged, or may still be completing. A retry then fails confusingly — the name is now registered, to you — or races an order that has not finished.
• Availability is not a reservation. A check that says available is a statement about a moment. Between the check and the registration somebody else can take it, and your error handling has to say that clearly rather than reporting a generic failure.

Renewal: the same, plus a double-charge risk

Renewal extends a registration by a term and charges for it. The failure mode that costs money is the double renewal: a lost answer, a retry, and a domain now paid for two extra terms. EPP's renew command carries the current expiry date so that a repeat is refused once the date has moved (RFC 5731, §3.2.3), and some registrar HTTP APIs offer the same guard. Where your registrar documents it, use it — but it only protects once the first renewal has moved the date. While that one is still pending, nothing has moved and the guard cannot tell a repeat from a first attempt.

Nor does the expiry date settle a lost answer by itself: an unchanged date can hide a renewal still in progress, and a changed one can be an automatic renewal or somebody else's. Domain renewal failures and reconciliation covers what to check instead.

Transfer: a protocol, not a call

A transfer is the one that breaks naive integrations. It is a conversation between the gaining registrar, the losing registrar and the registry, and it unfolds over days. ICANN's Transfer Policy governs the process for gTLDs, including the authorisation code, the losing registrar's opportunity to respond, and the conditions under which a transfer may be refused.

Model a transfer as a long-running request with its own states, and show the customer where it is. "Submitted", "awaiting the current registrar", "rejected — reason", "completed" are all things a customer will ask about, and a single boolean cannot answer.

Contacts are a separate object with their own rules

Registrant, administrative, technical and billing contacts are modelled separately in EPP and in most HTTP APIs. Changing a registrant is not the same as editing a field: for gTLDs it can trigger a change-of-registrant process with its own confirmations, and it can lock the domain against transfer for a period. Do not expose "edit contact" as a simple form without knowing which fields trigger that.

What to require of any registrar integration

1. Reads and effects are separated, and each operation is known to be one or the other. Availability checks, domain info, listings, and order or transfer status queries are reads and safe to repeat. Registration, renewal, transfer requests and contact or nameserver changes spend money or change a registration.
2. Every effecting operation has a lost-answer path that reconciles instead of retrying.
3. Error codes are mapped explicitly. An unrecognised code after a purchase is an unknown outcome, not a refusal — a refusal is a claim that nothing happened, and you cannot make that claim about a code you do not recognise.
4. Redirects on an effecting call are treated as suspicious. You paid for a request; what answered was not the endpoint you asked.
5. The registrar's own reference is recorded on success, because it is what any later support conversation will be about — and at acceptance too, where one is given before the order completes, because it is what a reconciliation will ask about.

Where GENV is with registrars

GENV ships adapters for several registrars — including Namecheap, NameSilo, Netistrar, Moniker, ResellerClub, Resell.biz, OpusDNS, Nominet and CoCCA — built from each provider's published documentation. The domain portfolio records what a business manages; the registrar operations are not routed in the shipped build, so GENV records domains and does not currently register, renew or transfer them. The adapters exist, are exercised against stand-ins, and await certification against real accounts.

Questions