# Take payments on your own payment pages

> Send shoppers to a payment page you host, refund what it took, and give a share of carts other ways to pay.

Source: https://www.coritan.com/docs/organizations/commerce/payments/

In the dashboard:

- /dashboard/organizations/…/commerce/payments: https://www.coritan.com/dashboard/organizations

**Payments** is where your store takes payments on pages you host yourself, and where you split checkout between ways to pay. A *payment page* runs on your own site, on your own payment account. Checkout sends the shopper there with a signed link, the page reads from Coritan what to charge, and the order is placed once the page reports the payment. *Payment routing* gives a share of new carts other ways to pay, such as card and PayPal, so that you can try them on real shoppers before you move everyone.

You sell the orders paid on a payment page yourself. Coritan is not their merchant of record: it moves none of their money, issues no invoice or credit note for them and adds nothing to your balance for them.

## Before you begin

- You need the Billing role or higher to open **Payments**. Adding or changing payment pages and payment routing needs the Admin or Owner role.
- Coritan's staff turn payment pages on for a store. Until they do, the **Payment pages** card says so, and its **Open a ticket** asks [support](https://www.coritan.com/dashboard/support) to turn them on.
- Build or install the page itself first. It needs an `https` address on a public host, and it must check the signed link, read what to charge and report each payment, as [Build a payment page for your store](/docs/organizations/storefront/commerce-payment-pages/) describes.
- Each region that should offer the page needs **Payment page** ticked under **Ways to pay**, in [Shipping](/docs/organizations/commerce/shipping/#add-a-region).

## Add a payment page

1. In the [dashboard](https://www.coritan.com/dashboard/organizations), open the organization, then **Commerce**, then **Money**, then **Payments**.
2. On the **Payment pages** card, select **New payment page…**.
3. Choose the **Mode**. **Test** offers the page to test carts, while you build and try it, and **Live** to live carts, where shoppers pay real money. A page keeps its mode, so add a second page for the other one.
4. Enter the **Name at checkout**, up to 80 characters, such as `Credit / Debit Card`. Optionally, add a **Description** of up to 300 characters, which the storefront shows under the name.
5. Under **Cards and wallets shown**, tick the marks the storefront shows beside the name. They change nothing on the page: what it takes is up to the page.
6. Enter the **Start address**, where checkout sends the shopper, such as `https://pay.example.com/start/`. It must be `https` on a public host, without a `#` part, and without the `session`, `expires`, `mode` and `sig` parameters, which the signed link adds.
7. Optionally, list the **Currencies** the page takes, such as `USD, EUR`. Leave it empty for any currency.
8. Set how long the **Signed link lasts**, from 5 to 1,440 minutes. It is how long the shopper has to open the page, and 30 minutes unless you change it.
9. Keep **Turned on** ticked to offer the page as soon as it is added.
10. Select **Add payment page**.

**Save these secrets now** then shows the page's two secrets, once, with the addresses the page calls:

| Field | What the page does with it |
| --- | --- |
| **Outbound secret** | Checks the signed link that brings each shopper. |
| **Inbound secret** | Signs each call the page makes to Coritan. |
| **Lookup address** | Reads what to charge. |
| **Events address** | Reports what became of the payment. |

Copy each one, or select **Copy all**, and put them in your payment page's settings. Then select **I have saved them**.

> [!WARNING]
> Nobody can show the secrets again once the dialog is closed. If they are lost, rotate them, which stops the old ones at once.

Each cart is offered one payment page: the first one added that is turned on, is in the cart's mode and takes the cart's currency. A store has up to 10 payment pages.

## Follow what a page reports

1. On the **Payment pages** card, select the page, or **Details and events…** in its menu.
2. Read the page's addresses and settings at the top. **Status** says whether it is turned on, and **Secrets** whether it has a pair.
3. Under **Recent events**, choose **All**, **Processed**, **Unmatched** or **Ignored**. **Older** loads the events before them.

Each event is a payment that succeeded, failed or is pending, with its amount, any message from the page and the page's own reference. **Open the order** opens the order it became or joined.

| Outcome | What it means |
| --- | --- |
| Processed | Coritan acted on it. A payment that succeeded became the cart's order, a failed one lets the shopper pay again, and a pending one keeps checkout waiting for the outcome. |
| Unmatched | The page took a payment that could not pay for the cart's order, and the event says why, such as a second payment for a cart already paid, or a cart that changed after the payment was started. Refund it at your payment page's provider. |
| Ignored | It changed nothing, because the payment was already closed or the page reported the same payment again. |

## Refund an order paid on a payment page

Coritan moves none of the money a payment page takes, so a refund happens in two places. Return the money to the shopper at your payment page's provider, then record the refund on the order, so that the order, what is left to refund and the shopper's refund notice show it.

1. Open the order in [Orders](/docs/organizations/commerce/orders/) and select **Record refund…**.
2. Choose what to refund, as for any [refund](/docs/organizations/commerce/orders/#refund-an-order).
3. Type the amount as the dialog shows it, then select the button that names it, such as `Record refund of $25.00`.
4. Confirm it is you if the dashboard asks.

The refund is recorded at once, and its entry on the timeline reminds you to return the money at the payment page's provider. The shopper is emailed the refund notice, and no credit note is issued. Cancelling the order records its refund in the same way.

### Refund payments that paid for no order

A payment page can take money that cannot pay for an order, as when a shopper pays twice, or pays after the cart changed. Coritan never refunds such a payment on its own. The **Payments to refund** card lists them, newest first:

- An order that received a second payment shows **To refund** until its refund is recorded, then **Refund recorded**. Open the order: its **Payment** card holds the payment, and **Record its refund…** records it once you have returned the money.
- **A payment with no order** is one that no order could take. Refund it at your payment page's provider, where the page's events give its amount and reference. There is no order to record it on.

The card shows **Nothing to refund** when there is none.

## Change, turn off or delete a page

Each action is in the menu on the page's row. The page's drawer also has **Edit payment page…** and **Rotate secrets…**.

**Edit payment page…**
: Change anything but the mode, then select **Save payment page**.

**Turn off…**
: Checkout stops offering the page to new carts. Payments already started on it can still be looked up and reported, so the page can finish them. Select **Turn off payment page** to confirm, and **Turn on** to offer the page again.

**Rotate secrets…**
: Makes a new outbound and inbound secret and shows them once. The old ones stop working at once: until the page has the new ones, it cannot check the links checkout sends it, and Coritan refuses what it signs. Type the page's name, then select **Rotate secrets**.

**Delete payment page…**
: Checkout stops offering the page, and it can no longer look up or report a payment. Type the page's name, then select **Delete payment page**. A page that a shopper may still be paying on cannot be deleted: turn it off instead, and delete it once those payments are done.

> [!CAUTION]
> Deleting a payment page cannot be undone, and neither can rotating its secrets.

## Route payments

*Payment routing* gives each new cart one of two routes. Most carts get the *default route*, and a share you choose gets the *rollout route*. Each route offers its own ways to pay, so you can keep your payment page on the default route, for example, and try card and PayPal on a tenth of carts.

1. On the **Payment routing** card, tick **Route payments**.
2. Under **Ways to pay on each route**, put each of **Payment page**, **Card**, **PayPal** and **Test payment** on the **Default route**, the **Rollout route** or **Neither route**. Each route needs at least one way to pay, and a way to pay is on one route at most.
3. Enter the **Rollout share**: the percentage of new carts given the rollout route, from 0 to 100 with up to two decimals. When **Coritan allows** shows a ceiling for your store, a higher share counts as the ceiling.
4. Optionally, set the limits in the table below.
5. Select **Save changes**.

A cart gets its route the first time checkout lists its ways to pay, and keeps it, even when the shopper signs in. The route follows the shopper rather than the visit: carts of the same signed-in customer, or else with the same email address, get the same route for as long as the share stays the same. Changing the share moves only the carts that have no route yet.

A cart is offered the ways to pay on its route that its region offers, and nothing else. A route never falls back on the other one: when none of its ways to pay can take a cart, such as a payment page that does not take the cart's currency, the cart is offered nothing. The card warns you when a route would leave live carts no way to pay.

| Limit | What it does |
| --- | --- |
| **Rollout orders a day** | Once the day's rollout orders reach it, new carts get the default route. Carts already on the rollout route keep it. |
| **Rollout revenue a day** | The same, in each currency, for what the day's rollout orders add up to. |
| **Largest rollout order** | A cart whose total is above it, in its currency, is offered the default route's ways to pay while its total stays above it. |
| **Always on the rollout route** | Email addresses, or `*@example.com` for a whole domain, one a line and up to 200. A cart with one of them, or a signed-in shopper with one, gets the rollout route whatever the share, the limits or its total. List your team's addresses to try the rollout route before shoppers do. |

A day runs from midnight in the organization's time zone, the **Timezone** under **Invoicing** in the [organization's settings](/docs/organizations/settings/#set-how-invoices-are-made), or in UTC when none is set. The daily limits count the orders of the cart's mode, and are checked when a cart is given its route. Without routing, every cart is offered every way to pay its region offers.

### Pause routing

While routing is on, a banner at the top of **Payments** reads **Payment routing is on**, with the share and the ways to pay on each route. To stop the rollout at once, select **Pause routing…**, then **Pause routing**. Every cart, those on the allow list included, is then offered the default route's ways to pay until you select **Resume routing**. Each cart keeps the route it was given, so resuming puts it back.

To end routing, untick **Route payments** and select **Save changes**.

### Read the routing stats

The **Routing stats** card shows what each route took, day by day. Choose **7 days**, **30 days** or **90 days**, and **Live** or **Test** carts.

- **Rollout share now** is the share that new carts get, with the ceiling applied.
- **Rollout orders today** and **Rollout revenue today** count the day's rollout orders, against the daily limits you set.
- The table lists each day, newest first, with each route's orders and revenue. Under the orders, it counts the carts given the route that day, the payments started on it and those that failed.

A cart counts on the day it was given its route, a payment on the day it started and an order on the day it was placed. In [Orders](/docs/organizations/commerce/orders/#find-an-order), an order paid on the rollout route carries a **Rollout** badge, **Any route** filters the list by route, and each order's **Details** name its **Payment route**.

## Result

- Checkout offers the payment page under its **Name at checkout**, to carts of its mode and currency in the regions that tick **Payment page**. A shopper who pays there gets an order whose payment method is Payment page, and whose **Seller of record** is your business.
- The page's **Recent events** show each payment it reported, and **Payments to refund** lists any that paid for no order.
- With routing on, **Routing stats** counts each route's carts, payments and orders from the day they start.

## Troubleshooting

**Payments** says it is for owners, admins and billing
: Your role is below Billing. Ask an owner to change it.

**Payment pages are not turned on for this store**
: Coritan's staff turn payment pages on. Select **Open a ticket** to ask. Until then, checkout offers no payment page, and none can be added.

**New payment page…** is missing
: Only owners and admins see it, once staff have turned payment pages on, and while the store has fewer than 10 pages.

Checkout does not offer the payment page
: The shopper's region must tick **Payment page** under **Ways to pay**, a page that is turned on must be in the cart's mode and take its currency, and the cart must not buy or spend a gift card. With routing on, the cart's route must hold **Payment page**.

The start address is refused
: It must be `https`, on a host that resolves to a public address, without a `#` part or the parameters that the signed link adds. The message under the field says which.

A page shows **No secrets**
: It has no pair of secrets, so checkout cannot offer it. Select **Rotate secrets…** to make a pair, and put them on the page.

The shopper paid, but no order appeared
: The page has not reported the payment yet. Checkout waits for the page's report for 15 minutes after the shopper was last sent to it, then reopens the cart, and a success that the page reports later still places the order. Read the page's **Recent events**, and check that it reports to the **Events address** and signs with the inbound secret.

An event is Unmatched
: The page took a payment that no order could take, and the event says why. Refund it at your payment page's provider. When it belongs to an order, record the refund there with **Record its refund…**.

Deleting a page says payments may still be paid
: A shopper may still be paying on it. Turn it off instead, and delete it once those payments are done.

A warning says live carts on a route would be offered no way to pay
: The route holds only **Test payment**, or only **Payment page** while no page is turned on. Add a way to pay to the route.

**Rollout share now** is lower than the share you saved
: Coritan set a ceiling for your store, shown under **Coritan allows**, and a higher share counts as the ceiling.

## Related

- [Fulfil, refund and cancel store orders](/docs/organizations/commerce/orders/)
- [Set up regions and shipping](/docs/organizations/commerce/shipping/)
- [Build a payment page for your store](/docs/organizations/storefront/commerce-payment-pages/)
- [Route carts between ways to pay](/docs/organizations/storefront/commerce-payment-routing/)

## With the API

`GET https://api.coritan.com/api/v1/orgs/{org_slug}/commerce/payment-connectors` lists the store's payment pages, which the API calls payment connectors, and `POST` adds one and answers its secrets. [Build a payment page for your store](/docs/organizations/storefront/commerce-payment-pages/) has every route, with the calls the page itself makes. Payment routing is the store's `payment_routing` setting, which `PATCH /commerce/store` changes, and `GET /commerce/payment-routing/stats` answers the stats, as [Route carts between ways to pay](/docs/organizations/storefront/commerce-payment-routing/) describes.

```bash
curl "https://api.coritan.com/api/v1/orgs/acme/commerce/payment-connectors" \
  -H "Authorization: Bearer $CORITAN_TOKEN"
```