# Polar

> Connect Polar, a merchant of record that handles sales tax — the Organization Access Token and its scopes, the webhook, sandbox and going live.

Source: https://support.estage.com/commerce-payments-polar
Part of the ESTAGE Support help center (https://support.estage.com). Full knowledge base: https://support.estage.com/llms-full.txt

---

**Polar** is a merchant of record: it sells on your behalf, works out the sales tax and pays it.
Buyers pay on Polar's own checkout page, where the tax is added, and come back to your site
afterwards. You connect it with a single token.

| Where | What Polar does |
| --- | --- |
| **[Order forms](https://support.estage.com/order-forms)** | One-time products, subscriptions, free trials and coupons. The buyer is sent to Polar's checkout page and back. |
| **[Paid meetings](https://support.estage.com/rooms-meeting-booking)** | The booking is paid on Polar's page. A cancelled booking is flagged **Refund by hand**, and you refund it in Polar. |
| **[Online store](https://support.estage.com/store)** | The storefront checkout, paid on Polar's page. |

## Before you start

- **A Polar organization.** The token belongs to one organization, and the money goes to it.
- **Sandbox or production.** Polar's sandbox is a separate account with its own organizations and
  tokens. ESTAGE takes a token from either and tells which one it is: a sandbox connection is
  marked **Sandbox**, and no real money moves.
- **Business Details** aren't required for Polar.

## Creating the token

1. In Polar, open **Settings** for your organization.
2. Under **Developers**, select **New Token**.
3. Name the token and pick an expiration date.
4. Select the scopes. ESTAGE needs `checkouts:write`, `products:write`, `discounts:write`,
   `orders:read`, `subscriptions:write`, `refunds:write`, `webhooks:write` and
   `organizations:read` — selecting all of them is simplest.
5. Create the token and copy it. It starts with `polar_oat_`.

Polar's guide: [Organization Access Tokens](https://polar.sh/docs/integrate/oat).

> **Caution**
>
> When the token expires, Polar stops accepting it and checkouts through Polar fail. Pick an
> expiration you'll remember, and save a new token in ESTAGE before it runs out.

## Connecting Polar

1. In Genesis, open **Settings → Payment Processing**.
2. On the **Polar** card, select **Connect**.
3. Paste the token into **Organization Access Token**.
4. Select **Connect My Account**.

*Polar connected* appears and the card shows **ACTIVE**, with your organization's name under it
(and **Sandbox** for a sandbox token). A token Polar doesn't accept gives *Failed to connect Polar*
with *Invalid API Key provided*.

From your CRM: **Settings → Payments**, **Connect** on Polar, paste the token, then **Connect**.

## The webhook

ESTAGE registers a webhook on your Polar organization as you connect; there's nothing to paste.
Through it ESTAGE records:

- subscription renewals, each as a new order;
- a purchase whose buyer closed the tab right after paying;
- full refunds you make in Polar;
- subscriptions Polar ends.

If the token lacks the `webhooks:write` scope, Polar refuses the webhook. You then see *Polar
connected, webhook not set up*, and the card carries **Webhook not set up**. Sales still work, but
renewals, refunds and purchases whose tab was closed aren't recorded. To fix it, create a token
with `webhooks:write` (or all scopes), open **Settings** on the Polar card, paste it into
**Organization Access Token** and select **Save token**. With the same token, the button reads
**Try the webhook again**.

**Settings** also shows whether the webhook works: *Webhook registered with Polar*, then the last
event once one arrives.

## Turning Polar on for products

1. In the CRM, open **Products** and then the product.
2. On the **Pricing** tab, add **Polar** under **Payment providers**.
3. Pick the price and currency, then select **Update**.
4. In the [order form](https://support.estage.com/order-forms-configuring), tick **Polar** in step 2.

There's nothing to set up in Polar for each product: ESTAGE creates what it needs there at the
first purchase. The **Currency** menu lists the currencies Polar can present; which of them your
organization may use is Polar's decision, and it refuses the rest at checkout.

## Testing and going live

1. Connect Polar with a sandbox token and turn it on for a product.
2. On your **published** site, buy the product. Polar's checkout doesn't open from the Genesis
   preview.
3. Check the order in the CRM under **Orders**.
4. To go live, open **Settings** on the Polar card, paste a production token into **Organization
   Access Token** and select **Save token**. Your products keep Polar; nothing else changes.

## Things worth knowing

- **Sales tax is Polar's.** The order in ESTAGE shows what the buyer paid before tax.
- **Coupons are applied on your form.** Buyers can't type a code on Polar's page. A coupon that
  would make a subscription free for good can't be used with Polar.
- **Free trials** save the buyer's card at Polar; the first charge comes when the trial ends.
- **Refunds:** a full refund in Polar marks the order refunded. A partial refund isn't recorded in
  ESTAGE.
- **One Polar organization on several projects** works. Each project registers its own webhook and
  records only its own sales.
- **Disconnecting** removes the webhook from Polar and takes Polar off your products, as with any
  gateway — see [Payment Processing](https://support.estage.com/commerce-payments#managing-a-connected-gateway).

Related: [Payment Processing](https://support.estage.com/commerce-payments) · [Stripe](https://support.estage.com/commerce-payments-stripe)