Create hosted checkout pages with the Merchant API

A hosted checkout page is a page you create for one amount. It has no products and no cart. We serve it on a domain of your own, and your customer sees the amount, a billing form and your own words and look. When the customer sends the form, they go on to your MAEF parent site, the payment site, and pay there. Nobody enters a card number on the page, and nothing on it names Coritan.

You style the whole page yourself with a set of style keys and your own CSS. Hosted checkout pages are optional, and our staff turn them on for each store.

The page is not a store checkout. It makes no order, no invoice and no entry on your balance. We tell you when the page is paid, as Confirm the payment on your server describes, and you refund at your payment site.

The routes are under https://api.coritan.com/api/v1/orgs/{org_slug}/commerce, and the API reference lists them under Commerce. The dashboard does the same in Checkout pages, as Create and style hosted checkout pages describes.

• Our staff turn hosted checkout pages on for a store: in the admin console they tick "Allow hosted checkout pages" on the store's Payments card. Ask support. Until then, every write answers 409 with hosted_checkout_not_enabled, and the two lists answer with hosted_checkout_enabled: false.
• The store needs to be in test or live mode. A live page needs a live store.
• Add at least one payment page for the mode and currency you charge in, and turn it on. A store that has only hosted checkout pages can add payment pages without turning on payment pages at checkout.
• Have a hostname you can add DNS records to, such as pay.example.com. It serves checkout pages only.
• Creating and cancelling pages and managing domains takes an organization API key with the commerce.checkout:write scope, or a member's token with the Admin role or above. Reading them, and the preview, takes commerce.checkout:read, or the Billing role or above.

Send the key in the X-API-Key header, as Authenticate describes. The examples use $ORG_API_KEY and an organization called acme.

A checkout domain is a hostname that serves checkout pages and nothing else. Any other address on it answers a plain "Page not found". It can sit on a different domain from the rest of your site.

Add the hostname:

curl -X POST "https://api.coritan.com/api/v1/orgs/acme/commerce/checkout-domains" \
  -H "X-API-Key: $ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname": "pay.example.com"}'

The answer is 201 with the checkout_domain. Adding a name you already added answers with it as it is.

{
  "checkout_domain": {
    "hostname": "pay.example.com",
    "verified": false,
    "verified_at": null,
    "records": [
      {"type": "TXT", "name": "_coritan-checkout.pay.example.com", "value": "3f9c1d7a5b2e4c80a6d1f0e9b8c7a654"},
      {"type": "CNAME", "name": "pay.example.com", "value": "edge.example.net"}
    ],
    "certificate": "none",
    "created_at": "2026-10-14T09:30:00Z"
  }
}

Publish the records at the DNS provider of the domain:

Then ask us to check the TXT record:

curl -X POST "https://api.coritan.com/api/v1/orgs/acme/commerce/checkout-domains/pay.example.com/verify" \
  -H "X-API-Key: $ORG_API_KEY"

When the record is there, the answer has verified: true. We then order a certificate for the name, and certificate is one of:

GET /commerce/checkout-domains lists the domains, oldest first, with hosted_checkout_enabled, cname_target (a name or null) and limit. Read it again until certificate is active before you send a customer to a page.

curl -X DELETE "https://api.coritan.com/api/v1/orgs/acme/commerce/checkout-domains/pay.example.com" \
  -H "X-API-Key: $ORG_API_KEY"

The answer is {"deleted": true}. Pages already made on that hostname stop opening. While a page there is processing and its customer started to pay in the last 30 minutes, it answers 409 with domain_in_use. Remove the domain once that payment is done.

After the customer pays, the payment site sends them back to your checkout host with maef_complete, sig and maef_parent in the query. That return is how we learn the page is paid. We check its signature with the secret of your payment page, and nothing else makes a page paid.

We hand the payment site the return address of each page, https://<your checkout host>/c/<page id>/return, and your checkout host as the child site's domain. We also answer /thank-you on the checkout host. There we find the page from the signed order number in the return, or from the customer's email and the amount when the return has no order number.

If the return never arrives, the page stays processing. Troubleshooting says what to check.

A page needs an amount and a return_url, the address the customer came from. Everything else is optional.

curl -X POST "https://api.coritan.com/api/v1/orgs/acme/commerce/checkout-pages" \
  -H "X-API-Key: $ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500,
    "currency_code": "USD",
    "livemode": true,
    "reference": "INV-1042",
    "description": "Annual hosting plan",
    "return_url": "https://example.com/invoices/1042",
    "success_url": "https://example.com/thanks",
    "cancel_url": "https://example.com/invoices/1042?cancelled=1",
    "host": "pay.example.com",
    "expires_in_minutes": 4320,
    "style": {"heading": "Pay invoice INV-1042", "accent_color": "#0f766e"}
  }'

The answer is 201 with the page and its url, the address to send the customer to:

{
  "checkout_page": {
    "id": "chk_01j9k2m4n6p8q0r2s4t6v8w0x2",
    "livemode": true,
    "status": "open",
    "amount": 2500,
    "currency_code": "USD",
    "reference": "INV-1042",
    "description": "Annual hosting plan",
    "parent_product_id": 0,
    "host": "pay.example.com",
    "url": "https://pay.example.com/c/chk_01j9k2m4n6p8q0r2s4t6v8w0x2",
    "return_url": "https://example.com/invoices/1042",
    "success_url": "https://example.com/thanks",
    "cancel_url": "https://example.com/invoices/1042?cancelled=1",
    "email": null,
    "expires_at": "2026-10-17T09:35:00Z",
    "paid_at": null,
    "parent_order_id": null,
    "attempts": 0,
    "style": {"heading": "Pay invoice INV-1042", "accent_color": "#0f766e", "theme": null, "font": null, "custom_css": null},
    "created_at": "2026-10-14T09:35:00Z"
  }
}

The style is the merged style we saved on the page, with every key present. It is shortened here. success_url and cancel_url are null when you did not send them. email is the customer's address once they have sent the form, and parent_order_id is the payment site's own number for the payment once it is paid.

GET /commerce/checkout-pages/{checkout_page_id} answers one page. GET /commerce/checkout-pages lists them, newest first, and takes these query parameters:

The answer is {"checkout_pages": [...], "next_before_id": ..., "hosted_checkout_enabled": true}. next_before_id is null on the last page.

Every page needs a return_url, the address the customer came from. A page with no way back is never made. We send the customer back to your site in these situations:

We add checkout_page=<id>&status=<status> to the query of each address, and keep any query and fragment it already has. If the query already has a checkout_page or a status, ours replace them. We send the address as plain ASCII, so a host with other characters goes out as punycode and any other character is percent-encoded. status is the page's status at the moment we make the link: open, processing, paid, failed, canceled or expired. A customer can follow a link before we have applied the payment site's return, so the status can be behind.

Confirm the payment through the API or the event, never from that query, as Confirm the payment on your server describes.

Every key is optional. The page has a built-in look, and each key you set changes one part of it.

The store has a default style, which every page uses. Set it with PATCH /commerce/store, and send null to clear it:

curl -X PATCH "https://api.coritan.com/api/v1/orgs/acme/commerce/store" \
  -H "X-API-Key: $ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"settings": {"checkout_style": {"accent_color": "#0f766e", "font": "inter", "radius": "round"}}}'

This needs the commerce.store:write scope. GET /commerce/store shows the default in settings.checkout_style.

The style you send with a page is laid over the default. A key you send wins, a key you leave out keeps the default, and a key set to null goes back to its built-in value. We save the merged result on the page, so changing the default later does not move pages you made already.

A key that is not a style key, or has a bad value, answers 422 with field set to style.<key>, or to settings.checkout_style when you set the default.

A colour you choose is a starting point. We work out the other colours of the page from it (muted text, borders, the text on the button) and change a text or link colour that would be hard to read on the colour behind it. Text is plain text, and we escape it on the page. A line break in a one-line text, or a control character in any text, is refused. The three longer texts hold one paragraph, and we turn a line break in them into a space.

The page names a font stack and downloads no font. inter and plex use that font when the customer's device has it, and the closest sans-serif font when it does not.

The page shows the logo from a copy we make: we fetch the address once and place the image in the page itself. A logo we cannot fetch is left out of the page.

custom_css is added after the style above, so it can override anything. We accept style rules and @media and @supports blocks. Everything else is refused: when you send CSS, the request answers 422 with field set to style.custom_css and a message that names the first problem, and nothing is saved. We save the CSS rewritten in a compact form, so it reads back differently from what you sent.

The CSS cannot load anything. We refuse every way a stylesheet could name a file or run code:

• @import, @font-face, @keyframes, @namespace, @charset and @page.
• url(), image-set(), image(), element(), cross-fade() and src() in any value. A background or background-image can hold gradients only, so the CSS cannot load fonts or images.
• expression(), javascript:, behavior, binding, @, <, backslashes and comments inside values and selectors.

We also refuse a property that is not on our list. The families on the list are:

• Colour: color, accent-color, caret-color and color-scheme.
• Background: background and its parts, with gradients only for the image.
• Borders, outlines and corners: border and its parts (not border-image), border-radius and outline.
• Box model and position: margin, padding, width, height, their minimums and maximums, aspect-ratio, box-sizing, display, position (static, relative, absolute or sticky), top, right, bottom, left, inset, z-index, float, overflow and visibility.
• Type: font and every font-* property, line-height, letter-spacing, word-spacing, text-align, text-transform, text-decoration, text-overflow, text-indent, white-space, word-break and overflow-wrap.
• Layout: flex and grid properties, gap, order, align-*, justify-* and place-*.
• Effects: box-shadow, text-shadow, opacity, transition, transform, cursor, appearance and object-fit.
• content, which takes a string, none or normal.
• Custom properties that start with --.

Properties such as animation, filter, list-style and pointer-events are not on the list.

A selector can use element names, classes, ids, attribute selectors, pseudo classes, pseudo elements and combinators. !important is accepted.

The page marks its parts with these classes, and they stay the same between releases:

The page also sets CSS variables on :root, which your CSS can read with var() or set again: --accent, --on-accent, --bg, --surface, --text, --muted, --faint, --line, --line-strong, --panel, --link, --error, --error-bg, --ring, --radius, --radius-button, --radius-input, --font and --scheme.

{
  "theme": "dark",
  "accent_color": "#22c55e",
  "background_color": "#0b1020",
  "surface_color": "#131a2e",
  "text_color": "#e6e9f2",
  "radius": "round",
  "font": "inter",
  "layout": "card",
  "logo_url": "https://example.com/assets/logo.png",
  "heading": "Pay your invoice",
  "message": "Enter your billing details. You pay on the next page.",
  "amount_label": "Total due",
  "billing_title": "Billing address",
  "button_label": "Continue to payment",
  "footer_text": "Questions about this invoice? Write to billing@example.com.",
  "success_title": "Thank you",
  "success_message": "We received your payment.",
  "links": [
    {"label": "Terms", "url": "https://example.com/terms"},
    {"label": "Support", "url": "mailto:billing@example.com"}
  ],
  "custom_css": ".card { max-width: 520px; }\n.amount { letter-spacing: .02em; }\n.button { text-transform: uppercase; letter-spacing: .06em; }\n.input:focus { box-shadow: 0 0 0 3px rgba(34, 197, 94, .35); }\n@media (max-width: 520px) { .heading { font-size: 20px; } }"
}

POST /commerce/checkout-pages/preview draws a page with sample data and creates nothing. It takes the commerce.checkout:read scope, and answers 429 with rate_limited beyond 60 previews a minute for the organization.

curl -X POST "https://api.coritan.com/api/v1/orgs/acme/commerce/checkout-pages/preview" \
  -H "X-API-Key: $ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"style": {"theme": "dark", "accent_color": "#22c55e"}, "state": "paid"}' \
  | jq -r .html > preview.html

The answer is {"html": "<!doctype html>..."}, the page as a customer sees it. Open preview.html in a browser. A style the page would refuse answers the same 422 as a page does.

1. You create a page and send the customer its url.
2. The customer opens the page, which shows the amount and the billing form in your style.
3. The customer sends the form. We check it, and the page becomes processing. We hand the amount to your payment site, signed with its secret, as one payment line.
4. We send the customer to the payment site's own page, and they pay there.
5. The payment site sends the customer back to your checkout host with its signed result, as Tell the payment site where to send the customer describes. We check the signature and keep the return once.
6. A payment that succeeded makes the page paid. We send commerce.checkout_page.paid, and the customer goes to your success_url, or to your return_url when you gave no success_url, as Send the customer back describes.

A customer who sends the form again within 10 minutes with the same details goes to the same payment address, and we ask the payment site nothing.

A page takes a payment while it is open, processing or failed. A customer who opens a paid, canceled or expired page sees that, cannot pay, and has a link back to your site.

A payment that arrives after the page expired still pays it, when its amount and currency are the page's. Some payments cannot pay a page. We keep them as unmatched in the page's events, and we send commerce.checkout_page.refund_required so you refund them at your payment site. We refund nothing.

The same return, passed again, shows what the first one came to and sends no new event.

curl -X POST "https://api.coritan.com/api/v1/orgs/acme/commerce/checkout-pages/chk_01j9k2m4n6p8q0r2s4t6v8w0x2/cancel" \
  -H "X-API-Key: $ORG_API_KEY"

The answer is {"checkout_page": {...}}. You can cancel an open, failed or expired page, and a processing page whose last attempt is older than 30 minutes. Cancelling a cancelled page changes nothing.

GET /commerce/checkout-pages/{checkout_page_id}/events lists the signed returns of one page, newest first. It takes limit (1 to 200, 50 by default) and before_id, and answers {"events": [...], "next_before_id": ...}.

{
  "events": [
    {
      "id": 311,
      "page_id": "chk_01j8z4a7b2c9d3e6f5g8h1k0m4",
      "connector_id": 4,
      "event_id": "maef-98765-succeeded",
      "type": "payment.succeeded",
      "status": "processed",
      "detail": {
        "reference": "maef-parent-98765",
        "parent_order_id": "98765",
        "payment_status": "completed",
        "email": "ada@example.com",
        "amount": 2500,
        "currency_code": "USD",
        "wc_order_id": "2000000087",
        "outcome": "paid"
      },
      "created_at": "2026-10-14T10:02:41Z"
    }
  ],
  "next_before_id": null
}

type is payment.succeeded, payment.pending (held for review) or payment.failed. status is processed when the return changed the page, unmatched when it was a payment that cannot pay the page (detail.reason says why), and ignored when it changed nothing. connector_id is the id of your payment page, and page_id is the page's own chk_ id.

Read the page, or take the webhook. The checkout_page and status that we add to your success_url, return_url and cancel_url are in the customer's browser address, so anyone can type them. Never mark an invoice paid from them.

With the API, read the page and check that status is paid:

curl "https://api.coritan.com/api/v1/orgs/acme/commerce/checkout-pages/chk_01j9k2m4n6p8q0r2s4t6v8w0x2" \
  -H "X-API-Key: $ORG_API_KEY"

With a webhook, subscribe to the three events, or to *, as Receive commerce webhooks describes. Each event has an id that you can use to skip one you handled. resource.id is null: the page is data.checkout_page.

commerce.checkout_page.paid: the page was paid.

{
  "id": "evt_48311",
  "type": "commerce.checkout_page.paid",
  "livemode": true,
  "created_at": "2026-10-14T10:02:41Z",
  "resource": {"type": "checkout_page", "id": null},
  "data": {"checkout_page": "chk_01j9k2m4n6p8q0r2s4t6v8w0x2", "reference": "INV-1042", "amount": 2500, "currency_code": "USD", "parent_order_id": "98765", "email": "ada@example.com", "livemode": true}
}

commerce.checkout_page.failed: the payment site reported a failed payment.

{
  "id": "evt_48312",
  "type": "commerce.checkout_page.failed",
  "livemode": true,
  "created_at": "2026-10-14T10:04:09Z",
  "resource": {"type": "checkout_page", "id": null},
  "data": {"checkout_page": "chk_01j9k2m4n6p8q0r2s4t6v8w0x2", "reference": "INV-1042", "amount": 2500, "currency_code": "USD", "parent_order_id": "98766", "email": "ada@example.com", "livemode": true}
}

commerce.checkout_page.refund_required: a payment that cannot pay the page. amount is what the payment site took, which can differ from the page's amount. checkout_page, reference and currency_code can be null when the return named no page.

{
  "id": "evt_48320",
  "type": "commerce.checkout_page.refund_required",
  "livemode": true,
  "created_at": "2026-10-14T11:20:33Z",
  "resource": {"type": "checkout_page", "id": null},
  "data": {"checkout_page": "chk_01j9k2m4n6p8q0r2s4t6v8w0x2", "reference": "INV-1042", "amount": 2500, "currency_code": "USD", "parent_order_id": "98771", "email": "ada@example.com", "livemode": true, "reason": "second_payment"}
}

GET /commerce/events shows the same events to a caller with commerce.store:read, and shows the email of these three only to a caller who also has commerce.checkout:read.

You refund at your payment site. Nothing here moves money, books anything on your balance, issues an invoice or creates an order, because a hosted checkout page is not a store order.

A return that the payment site signed more than 15 minutes ago, and that we have not had before, is not taken. The customer sees that we could not confirm the payment, the page stays as it was, and you check the payment at your payment site.

When staff turn hosted checkout pages off for a store, the checkout host stops showing forms and taking payments. A return for a processing page is still taken.

Your checkout host opens each page you create in your style, with the amount and the billing form. A customer who pays at your payment site comes back to your host, the page is paid, the customer lands on your success_url or return_url, and you have the commerce.checkout_page.paid event and status: "paid" in the API.

409 with hosted_checkout_not_enabled

Staff have not turned hosted checkout pages on for the store. Ask support.

409 with checkout_domain_required

Add a checkout domain and verify it, as Set up a checkout domain describes.

409 with no_payment_page

The store has no payment page that is turned on for the page's mode and currency. Add or turn on a payment page, and check that its currencies list takes the currency.

409 with verification_failed

We did not find the TXT record. The answer says what we found. Publish _coritan-checkout.<hostname> with the token from records, wait a few minutes, and verify again.

certificate stays pending

The name must point at us before the certificate can be issued. Publish the CNAME record when records lists one, and read the domain again in a few minutes. When records lists none, ask support where to point the name.

422 with field set to style.custom_css

The message names the first rule, property or value we refused. Remove it and send the CSS again. Custom CSS lists what we accept.

The customer paid and the page stays processing

We have not had the payment site's return. Read the page's events: an empty list means no return reached us. Check that the payment site sends customers back to your checkout host and not to your storefront, as Tell the payment site where to send the customer describes. The payment site's own record of the payment shows whether the customer paid.

The page shows "We received your payment and are checking it"

The payment site held the payment for review, or sent a payment that cannot pay the page. Read the page's events and check for commerce.checkout_page.refund_required. Refund an unmatched payment at your payment site.

success_url or return_url opens, but the page is not paid

The address a customer opens proves nothing, and its status can be behind or typed by hand. Read the page with the API, and wait for the return if it is still processing.

422 and detail names ["body", "return_url"]

The request has no return_url. Add the address the customer came from, as Send the customer back describes.

422 with field set to return_url

The address is empty, is not https, is over 2,000 characters, or has spaces or sign-in details. The same limits apply to success_url and cancel_url.

A customer has no link back from a page

Every page that knows its page has one. A page that does not exist, and an error page, have none. Check the page's url for a typing mistake.

• Create and style hosted checkout pages
• Take payments through a MAEF parent site
• Sell with the Commerce API
• Create organization API keys
• Receive organization webhooks