Runtime

The runtime API is what a site's own code calls. It is not for an agent. The platform puts three values in the code of the live site and of its draft:

Send the key as Authorization: Bearer $CLAVE_SITE_KEY.

A draft's key works only where a call says it does. Today that is GET /v1/runtime/site (the draft's address), the spam check, which runs on the draft's own address, mail to the site's own people (see below), files, which are the draft's own: its code never sees the live site's files, nor the other way, and test payments (see below). Any other call answers 403 not_on_a_draft, and the code shows that the thing is off on a draft. Use CLAVE_ENV to say so before the call. The draft's calls will open one at a time, each with a test equivalent of the live one.

The key can do only what a site's code may do: take money in, send mail with a limit, read its own payments, give money back under the rules below, and keep files. It cannot read or change anything else on the account.

An error answer is { "error": { "code": "...", "message": "...", "retryable": false } }. The code is stable. The message is for a person.

The site's address

GET /v1/runtime/site

The answer is 200 with { "url": "https://example.com" }: the address the site answers at now. This is the site's domain when one is attached and active, else the address Clave gave it.

A domain can change, so do not keep the value. In code that answers a request, use the request's own origin. Use this only where no request exists, for example a cron job that sends a mail with a link in it.

Send mail

POST /v1/runtime/mail

On a draft, mail goes only to a person with a role on the site: the owner, a collaborator or staff. It comes from Clave's sender with [Draft] before the subject, and needs no domain. A draft has its own daily count.

{ "to": "buyer@example.com", "subject": "Your order", "text": "It is on its way.", "reply_to": "shop@example.com" }

The answer is 202 with { "sent_to": "buyer@example.com" }. There is no attachment.

With html, the mail has two parts: the HTML, and text for mail apps that do not show HTML. Clave sends the HTML as it is and does not clean it. Escape all text that a visitor gives (names, messages) before you put it in the HTML.

The mail goes only from the site's own domain, after the owner turns mail on for it and the domain is verified (see Domains). Clave's own addresses never send a site's mail. Without a verified domain the answer is 409 mail_needs_domain. mail_paused means Clave or the mail service stopped the site's mail for its bounces or complaints, and no mail goes out (see Domains).

A site can send 100 mails in 24 hours, and a draft 20. Over the limit the answer is 429 mail_limit. All sites and drafts of one account can send 200 mails in 24 hours together. Over that limit the answer is 429 account_mail_limit. A mail that the mail service refuses still counts.

Take money

POST /v1/runtime/payments

{ "amount_minor": 2500, "description": "One lamp", "reference": "order_123", "hold_minutes": 30 }

The currency is the payout account's. The site's code computes the amount from its own prices. Never take an amount from the browser. A site can open 500 payments a day.

On a draft, the same calls take test money only, into the site's draft account. The payer pays with a test card, such as 4242 4242 4242 4242. The owner sets up the draft account once, with no form (see Payments). A draft can open 50 payments a day. A draft reads and refunds only its own payments, and the live key never reads a draft's payment. On a platform that takes no test payments, a draft's key answers 403 not_on_a_draft.

The answer is 201:

{
  "payment": {
    "id": "pay_...", "site_id": "site_...", "amount_minor": 2500, "currency": "eur",
    "description": "One lamp", "reference": "order_123", "status": "held",
    "expires_at": "...", "created_at": "...", "next_action": "..."
  },
  "pay_url": "https://api.heyclave.com/pay/..."
}

status is one of these:

After a part refund, the status stays paid and refunded_minor holds the total that went back. reference, paid_at, refunded_minor and refunded_at are absent when they have no value.

GET /v1/runtime/payments/{id} reads it again, with the same payment object. It has no late field. Money that arrives after the hold ran out does not make the payment paid: it stays expired, with no paid_at. Only the payment.settled event says so, with late: true.

Where the payer comes back from pay_url

The payer comes back to the site's payment_return_path (see Sites). With no path, they see a plain Clave page.

The hostname is the site's attached domain. With no domain, it is the site's Clave address. A payer of a draft's payment comes back to the draft's address. It is not always the hostname the payer started on, so do not keep the only copy of the order in the browser's storage. Use the address:

A payer can type these values. Show a status from them, but do not mark the order paid. The payment.settled event does that.

A payer who closes the provider's page, or uses the browser's back button, does not come back through Clave, and the site gets no parameter.

After stopped, the same pay_url works again until expires_at, while the payment is held.

The checkout form on the site's own page

POST /v1/runtime/payments/{id}/checkout

{ "return_path": "/thanks?order=order_123" }

The answer holds client_secret, publishable_key and, on some payout accounts, stripe_account. client_secret is the secret of a Checkout Session, not of a PaymentIntent. The page loads https://js.stripe.com/dahlia/stripe.js, calls Stripe(publishable_key, { stripeAccount }), then createEmbeddedCheckoutPage({ fetchClientSecret }), and mounts it. The card form is the provider's frame. No card number reaches the site.

Ask for a new session each time the page opens. After the payment, the payer comes back to return_path on the site's Clave address, also when the site has a domain. On a draft, it is the draft's address. Put the order's id in return_path.

The return page shows a status. It must not mark the order paid. The payment.settled event does that. See Code in a site.

If the answer is no_publishable_key, the owner of an own payout account sets the key in the app (Account, Getting paid), with set_publishable_key in a chat client, or with PUT /v1/account/payout-accounts/{id}/publishable-key:

{ "publishable_key": "pk_live_..." }

The hosted pay_url works meanwhile.

Give money back

POST /v1/runtime/payments/{id}/refund

{ "amount_minor": 1000, "reason": "cancelled in time" }

amount_minor is at most what was paid and not yet given back. 0 or no amount gives back all of it. The answer is 202 with { "id": "pay_...", "status": "refunding" }. The payment changes when the provider confirms, and then the payment.refunded event arrives.

The call needs one of these:

• A person. Forward the Clave-Identity header that the request to the site's code carried. The person must have payments:refund at the moment of the call. See Staff.
• The site alone. The owner turns on code_refunds in the site's clave.site.json (see Site settings). Then a call with no Clave-Identity works, and the audit trail says the site gave the money back. Use it for a refund that a rule decides, such as a cancellation inside the free window.

A Clave-Identity that is sent is always checked. A bad one gets 403 identity_required, also when code_refunds is on.

Check a visitor is a person

The same spam check the platform's forms use, for the site's own form.

GET /v1/runtime/turnstile answers with frame_url. Show it in an iframe (300 by 65) in the form. The frame sends the page a message { type: "clave-check", token } with postMessage. Put the token in the form, and in the action send it on:

Add &appearance=interaction-only to the address to show the check only when the visitor must click. Then the message also has visible: make the frame 0 high while it is false, and 65 high while it is true.

POST /v1/runtime/turnstile with { "token": "...", "remote_ip": "..." } answers { "success": true } only for a token solved on this site's page.

Keep files

A site on a plan that runs code can keep files: a photo that staff add, a PDF for each order. Clave keeps the bytes. Keep the names and who owns each file in the site's store. A file is data: a restore of the site does not bring it back.

POST /v1/runtime/files. Add ?public=1 for a public file.

The body is the file, with its Content-Length. Send its type as Content-Type. Forward the Clave-Identity header that the request to the site's code carried: only a person with a role on the site (owner, collaborator or staff) uploads, and Clave checks the role at the moment of the call.

The answer is 201:

{
  "id": "file_...", "public": true, "content_type": "image/png", "bytes": 48213,
  "path": "/_clave/img/file_...", "uploaded_by": "acct_...", "created_at": "..."
}

GET /v1/runtime/files/{id} answers with the bytes. The answer has Content-Security-Policy: sandbox and X-Content-Type-Options: nosniff, and Content-Disposition: attachment for all but a checked image. Return it to the browser as it is, and the file cannot run as a page of the site. Check who may see a private file before you return it.

DELETE /v1/runtime/files/{id} removes a file and gives its bytes back. The answer is 204. A public file can still be served for up to an hour.

GET /v1/runtime/files lists the files, newest first, with usage and limits. It pages with limit and cursor.

A file that is deleted still counts against the uploads.