Polar

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

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	One-time products, subscriptions, free trials and coupons. The buyer is sent to Polar's checkout page and back.
Paid meetings	The booking is paid on Polar's page. A cancelled booking is flagged Refund by hand, and you refund it in Polar.
Online 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.

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, 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.

Related: Payment Processing · Stripe