Developers

Embedded purchase#

Let your users create and pay for a NAMES LEGAL site without leaving your application. You paste one line of code; a frame appears in your page and the whole purchase happens inside it.

Your user becomes a NAMES LEGAL customer, billed directly by NAMES LEGAL. You never handle payments, card data or passwords.

1. Get a sales channel#

Ask the NAMES LEGAL team for a sales channel. It holds:

Setting Purpose
Identifier (via) Your technical name, for example app-ecole.
Allowed sites The addresses of your application allowed to show the frame, one per line (https://app.example.com). The frame refuses to appear anywhere else.
Notification address Optional. Your server endpoint called when a site bought through you is ready.
Signing secret Generated for you. Signs the notifications.

2. Paste the code#

<script src="https://names.legal/static/embed/names-legal.js"
        data-via="app-ecole"
        data-lang="fr"
        data-email="direction@ecole.ch"
        data-name="École Horizon"
        data-first-name="Awa" data-last-name="Diop"
        data-ref="instance-42"></script>

The script inserts the frame where it stands and adjusts its height automatically.

Attribute Required Effect
data-via yes Your channel identifier.
data-lang no Language of the frame: en, fr, de, it, es, pt.
data-email, data-first-name, data-last-name no Pre-fill the account.
data-name no Name of the organisation; also used to suggest the site name.
data-site no Suggested site name (ecolehorizon → ecolehorizon.names.legal).
data-ref no Your identifier for this user. It comes back to you when the site is ready.
data-plan no Plan selected by default.

Prefer a plain frame? It works too:

<iframe src="https://names.legal/embed/app-ecole/?lang=fr&ref=instance-42"
        style="width:100%;max-width:640px;height:1100px;border:0"></iframe>

3. What your user sees#

  1. Plan: monthly or yearly, optional add-ons.
  2. Their site: name (availability checked while typing) and languages.
  3. Their account: username and password for their console.
  4. Payment: a secure payment window opens on top of your page. The payment is not inside the frame on purpose: some payment methods need the whole page, and the payment provider advises against nesting its checkout in frames.
  5. Site ready: the frame says so and offers to open the console.

The frame needs no third-party cookie, so it works in Safari and in browsers that block them.

4. Know when the site is ready#

In the page, without a server:

document.addEventListener("names-legal:ready", function (event) {
  console.log(event.detail.site_url, event.detail.console_url, event.detail.reference);
});

On your server, if you declared a notification address, you receive a signed site.ready event. See Webhooks.

Security#

  • The frame only displays on the addresses declared for your channel (Content-Security-Policy: frame-ancestors).
  • You never see the user's password or payment details.
  • The purchase form is protected against automated submissions and rate-limited.