Create and style hosted checkout pages

Checkout pages is where your store creates a payment page for one amount, with no products and no cart. A page is served on a domain of your own and styled by you, down to its CSS, and nothing on it names Coritan. The customer sees the amount and a billing form, then pays on your own MAEF parent site, the payment site. Nobody enters a card number on the page.

The section has three cards. Checkout domains holds the names that serve your pages. Default style designs how every page looks, with a preview. Pages creates pages and lists them. Each step below has the matching API call beside it, and Create hosted checkout pages with the Merchant API describes every field.

A hosted checkout page makes no store order, no invoice and no entry on your balance. You learn that a page is paid from its status, and you refund at your payment site.

• Coritan's staff turn checkout pages on for a store. Until they do, the page shows Checkout pages are not turned on for this store, and its Open a ticket asks support to turn them on.
• You need the Billing role or higher to open Checkout pages. Adding a domain, saving the style and creating or cancelling a page needs the Admin or Owner role. A member below that sees a note that changing these needs an owner or admin.
• Add at least one payment page for the mode and currency you charge in, and turn it on, as Take payments through your MAEF parent site describes. You do not need to turn on payment pages at checkout.
• Have a hostname you can add DNS records to, such as pay.example.com. It serves checkout pages only, so never use the address of your storefront. It can be on a different domain from the rest of your site.
• Register your checkout host with your payment site, the way you registered your storefront. The payment site must send customers back to the checkout host. We have not tested this against a live payment site, so make a small test payment first. Tell the payment site where to send the customer says why.

1. In the dashboard, open the organization, then Commerce, then Money, then Checkout pages.
2. On the Checkout domains card, select Add domain…. When the card has no domains yet, the same button is in its empty state.
3. Enter the Domain, such as pay.example.com, without https:// or a path. Select Add domain.
4. The domain opens in a drawer with its DNS records. Publish them at the DNS provider of the domain:
   • A TXT record at _coritan-checkout.<your domain>. Its value is a token we made for this domain. It proves you own the name.
   • A CNAME record at your domain, when the table lists one. It points the name at us. The table shows it only when our staff have set a target for it.
5. Select Verify now. A new record can take a while to reach us, so if the drawer says the record is missing, wait a few minutes and try again.

API: POST /commerce/checkout-domains with {"hostname": "pay.example.com"}, then POST /commerce/checkout-domains/{hostname}/verify.

The table shows each domain's Status: Waiting for DNS until the record is found, then Verified. After a domain is verified, we order its certificate. Its Certificate shows Being issued, then Active, and After it is verified before that. Pages open on the domain once the certificate is Active.

You can add up to 10 domains. The menu on a row has Show DNS records, Verify now and Remove domain…. Keep the records in place, because pages stop loading on the domain if they go.

We refuse a name that is not a hostname, a name the platform or App Deployment uses, your storefront's domain or address, and a name another organization holds. The message under Domain says which.

1. Open the row's menu and select Remove domain….
2. Type the domain's name, then select Remove domain.

Pages made on the domain stop loading, and a customer who opens one sees "Page not found". While a customer started to pay on a page there in the last 30 minutes, we refuse, and you remove the domain once that payment is done.

API: DELETE /commerce/checkout-domains/{hostname}.

The Default style card sets how every new page looks. A page keeps the style it was made with, so changing the default moves no page you made already.

1. On the Default style card, change what you want. The preview on the right draws the page a customer sees, in the style on screen, before you save. Choose Form, Processing, Paid, Failed, Expired or Cancelled under Page state to see each page.
2. Under Brand, choose the Theme, the Corners, the Font and the Layout. A font is a name for a set of fonts the customer's device already has: the page downloads none.
3. Enter the colours as hex values such as #0F2A57: Accent for the button and the links, Background behind the card, Card behind the words and Text. Leave one empty for its default. We change a text or link colour that would be hard to read.
4. Enter the Logo address, an https address. We read the image once and serve it from the checkout page itself. A logo we cannot read is left out.
5. Under Words, change the Heading, Message, Amount label, Billing title, Button label, Success title, Success message and Footer text. An empty one uses the words the field shows as its placeholder. An empty message or footer is left out of the page.
6. Select Add a link to add up to 3 footer links, each with a label of up to 30 characters and an address that starts with https:// or mailto:.
7. Under Advanced, write your own Custom CSS of up to 20,000 characters. The Class names to style tip lists the classes you can target. The CSS cannot load files or fonts, so url(), @import and @font-face are refused.
8. Select Save style. A message under a field says what to fix. The card's footer says how many changes are waiting, Discard drops them, and Reset to defaults… clears the saved style after you select Reset style.

API: PATCH /commerce/store with {"settings": {"checkout_style": {...}}}, and null clears the style. POST /commerce/checkout-pages/preview draws the preview. Style the page lists every key, the CSS we accept, the class names and the CSS variables.

When the CSS has something we refuse, the preview stops and the message names the first rule, property or value. Remove it and the preview follows.

1. On the Pages card, select New checkout page…. The button is in the card's header, or in its empty state when you have no pages.
2. Enter the Amount, in the currency you choose, such as 25.00, and choose the Currency from the store's.
3. Optionally, enter a Reference of up to 255 characters, such as an invoice number. It comes back in the API and in events.
4. Optionally, enter a Description of up to 120 characters. It names the payment line on your payment site. The customer never sees it on the checkout page.
5. Enter the Return address, which is required. It is where the customer came from, such as the invoice page on your site. We send the customer back there when they have paid or choose to leave. It is an https address of up to 2,000 characters, with no spaces and no sign-in details.
6. Optionally, enter a Success address. A customer who has paid goes there instead of to the return address.
7. Optionally, enter a Cancel address. A customer who leaves without paying goes there instead of to the return address.
8. Choose the Domain when you have more than one verified domain. With one, the dialog shows it.
9. Set Expires after, a whole number of hours from 1 to 720. It is 24 unless you change it.
10. Choose the Mode. Test uses your payment page for test payments. Live uses your live payment page, and is available once the store is live.
11. Optionally, select Style for this page only and enter a JSON object of style keys, such as {"accent_color": "#0f766e", "heading": "Pay your invoice"}. It wins over the default style for this page.
12. Select Create page.

API: POST /commerce/checkout-pages, with return_url always and success_url and cancel_url when you fill them in. The dashboard sends the amount in minor units, such as 2500. A request with no return_url answers 422. Send the customer back lists each field.

The Checkout page created dialog shows the page's address. Copy it and send it to your customer, or select Open page to see it. The page is in the Pages list with the status Open.

To copy the address later, open the row's menu and select Copy link, or Open page.

We add checkout_page=<id>&status=<status> to each address. Your server must not mark anything paid from that query, because anyone can type it. Read the page's status or take the commerce.checkout_page.paid event, as Confirm the payment on your server describes.

The Pages table lists each page with its Status, Amount, Domain, when it was paid or expires, and when it was Created. Filter it by All, Open, Processing, Paid, Failed, Cancelled or Expired. Load more shows older pages.

API: GET /commerce/checkout-pages, filtered by status.

1. Open the row's menu and select View returns…, or select the row.
2. The drawer shows the page's Address, Status, Amount, Reference, Return address, Customer email, Payment attempts and, once paid, the Order at the payment site. It also shows the Success address and the Cancel address when the page has them.
3. Under Returns, read what the payment site sent back, newest first. Older loads more.

An Unmatched return is a payment that could not pay the page: it came after you cancelled the page, a second time after the page was paid, or for another amount. Refund it at your payment site. A return that is Processed changed the page, and Ignored changed nothing.

API: GET /commerce/checkout-pages/{checkout_page_id}/events.

1. Open the row's menu and select Cancel page….
2. Select Cancel page to confirm, or Keep page to leave it.

A customer who opens the page then sees that it was cancelled, with a "Return to site" link to the return address. You can cancel an open, failed or expired page, and a processing page whose customer last tried more than 30 minutes ago. Before that, the dashboard says a customer is paying on it.

API: POST /commerce/checkout-pages/{checkout_page_id}/cancel.

Hosted checkout pages move no money, so you refund at your payment site. Nothing here records a refund, because a page is not a store order.

• Checkout domains shows your domain as Verified, with its certificate Active.
• The Pages list shows each page you create, and its link opens a page in your style, with the amount and the billing form.
• A customer who pays comes back to your checkout host, the page becomes Paid, the customer lands on your success address or return address, and View returns… shows the return as Processed. Your server learns of it from the page's status or the commerce.checkout_page.paid event, as Confirm the payment on your server describes.

The Checkout pages section is for owners, admins and billing

Your role is below Billing. Ask an owner to change it.

Checkout pages are not turned on for this store

Coritan's staff turn checkout pages on. Select Open a ticket to ask. Until then you can read the page, but no domain or page can be added and the style cannot be saved.

Add domain… or New checkout page… is missing

Only owners and admins see them, once staff have turned checkout pages on. Add domain… also goes when you have 10 domains. New checkout page… needs a verified domain.

Verify now says the record is missing

We did not find the TXT record at _coritan-checkout.<your domain> with the token the drawer shows. Check the name and the value at your DNS provider, wait a few minutes, and try again. You can check a domain 12 times an hour.

The certificate stays Being issued

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

Creating a page says there is no payment page

The store has no payment page that is turned on for that mode and currency. Open Payments in the message takes you to Payments, where you add one or turn it on.

Return address says "Enter the address the customer came from."

The field is required. Enter an https address of up to 2,000 characters, with no spaces and no sign-in details. The Success address and Cancel address take the same kind of address and can stay empty.

A customer paid but did not land on your site

Open View returns…. A page that is still Processing has not had your payment site's return. Once the page is Paid, the customer goes to the success address, or to the return address when you left it empty.

Live is not available

Your store is not live yet. Use Test, or take the store live as Take your store live describes.

The preview says a field is not valid

A colour is not a # and six hex digits, an address does not start with https://, or a text is too long. The message under the field says which.

A customer paid and the page stays Processing

We have not had your payment site's return. View returns… shows an empty list when none arrived. Check that the payment site sends customers back to your checkout host and not to your storefront. A payment site that sends customers only to the address it holds for your storefront needs your checkout host registered with it.

A return is Unmatched

The payment could not pay the page. Refund it at your payment site, and check the return's reason in the API's events.

Removing a domain says a customer is paying

A customer started to pay on a page there in the last 30 minutes. Remove the domain once that payment is done.

• Create hosted checkout pages with the Merchant API
• Take payments through your MAEF parent site
• Run your store from the Commerce tab
• Receive organization webhooks

GET https://api.coritan.com/api/v1/orgs/{org_slug}/commerce/checkout-pages lists the store's pages and POST creates one. The domains are under /commerce/checkout-domains.

curl "https://api.coritan.com/api/v1/orgs/acme/commerce/checkout-pages?status=open" \
  -H "Authorization: Bearer $CORITAN_TOKEN"