You build this integration yourself. There’s no Sphere connection to set up in the Primer Dashboard.
How it works
Tax depends on the customer’s address, so where the tax calculation fits depends on when you create the client session:
Either way, Primer Checkout shows the total including tax on the pay button. The rest of the flow is the same:
- After the payment is captured, your server records the sale in Sphere with the same tax calculation, so the tax you file matches the tax you charged.
- Refunds are recorded in Sphere as credit notes, and chargebacks as cancellations.
Before you begin
- A Sphere account, with an API key that can call both
calculate_taxand the Transaction API. - A Sphere product tax code for each product you sell. Ask Sphere which codes apply to you.
- A Primer account with a workflow that processes payments for your checkout.
- A Primer server-side integration that creates client sessions.
Integration steps
The examples below use an order with two lines, for a customer in New York: a Pro plan at $1,200.00 and two extra seats at $150.00 each.1
Create your products in Sphere
Sphere needs to know each product and its tax code before it can calculate tax on it. Create or update each product once, and again whenever your catalog changes:Use the same product ID in Sphere as the
itemId you use in Primer, so each line maps across directly.2
Calculate tax with Sphere
Once you have the customer’s address, call Sphere’s For a business customer, also pass their VAT or tax ID as
calculate_tax from your server. Send one line per order line. Each line’s amount is the line total after discounts, in the currency’s smallest unit (for example, cents). So $1,200.00 is sent as 120000.tax_id.The response has a sphere_tax_calculation_id and the tax for each line (shortened here):CALCULATION_ID stands for the sphere_tax_calculation_id value, a UUID. A line can have more than one entry in tax_amounts, one per tax that applies. The line’s tax is their sum: $106.50 for the Pro plan, and $26.62 for the extra seats. Store the sphere_tax_calculation_id with your order. You’ll need it in step 5.When no tax is due, for example where you aren’t registered, the response has empty or zero tax_amounts. It may or may not include a sphere_tax_calculation_id. If it does, pass it when you record the sale. If it doesn’t, record the sale without one.3
Add the tax to the client session
Set each line item’s
taxAmount to the tax Sphere returned for that line. taxAmount is the tax for the whole line, not per unit. Primer calculates the payment amount for each line as amount × quantity − discountAmount + taxAmount, so you never set the total yourself.How you do this depends on when you create the client session.- Address known before checkout
- Address collected in checkout
Calculate tax first (step 2), then create the client session with the tax and the customer’s address already in it:Primer Checkout shows the total including tax ($1,633.12) as soon as it loads. You don’t need to update the session or refresh Primer Checkout.If the customer can still change their address or order on the checkout page, calculate tax again and update the session, as shown in the other tab.
4
Don't let a payment start with out-of-date tax
This step matters most when the address is collected in checkout, or when the customer can change it there. Use a new idempotency key for each payment attempt. If you reuse the key after a declined payment, the customer’s retry fails.
refreshSession() has no effect once a payment has started, so tax must be final before the customer pays. Use primer:payment-start as a guard: if tax wasn’t calculated for the address currently on screen, abort the payment.If you fail open when Sphere is unavailable, let the payment continue in that case too. Otherwise the guard blocks every payment during an outage.5
Record the sale in Sphere
Once the payment is captured, record the sale in Sphere with Sphere records a total of $1,633.12, including $133.12 tax, matching what the customer paid. A few details matter here:
POST /v1/transactions.Confirm the payment on your server first, rather than relying on the browser. Either listen for the payment status webhook, or fetch the payment with GET /payments/{id}. Check that its status is SETTLED or PARTIALLY_SETTLED, and that its orderId and amount match your order. Don’t record the sale while the payment is SETTLING: some processors capture asynchronously, and a SETTLING payment can still be cancelled. Wait for the payment status webhook to report SETTLED.- Pass
sphere_tax_calculation_id. Sphere then records the exact tax the customer saw, instead of recalculating it. Lineexternal_idvalues and amounts must match the lines you sent tocalculate_tax, or Sphere rejects the calculation ID. - Send the customer’s tax ID. For a business customer, add
customer_tax_ids, for example[{ "tax_id": "DE123456789", "country": "DE" }]. Otherwise the sale is recorded without it, which matters most when there’s no calculation ID, such as a fail-open sale. - Use the order ID as
external_id. Sphere treats repeated requests with the sameexternal_idas the same transaction, so retries don’t create duplicates. - Set
finalized_onto when the payment was captured. Otherwise Sphere uses the time of the request, and a late retry could move the sale into a different tax period. - Convert amounts. Primer and
calculate_taxtake amounts in the currency’s smallest unit, as whole numbers (120000for $1,200.00). The Transaction API takes amounts in the main currency unit, as text ("1200.00").
confirmPayment in server/orders.js checks the payment with GET /payments/{id} and queues the sale, which server/outbox.js sends to Sphere.6
Record refunds as credit notes
For each refund, record a credit note in Sphere that’s linked to the original sale. A credit note reduces the amount, and the tax, of the original sale. Record one credit note per refund.For example, a $500.00 refund on the order above is split across its lines in proportion to their totals including tax: $400.00 from the Pro plan and $100.00 from the extra seats. Send the part of each that excludes tax:Because the credit note is linked to the original sale, Sphere calculates its tax in proportion to the original sale: $40.76 here, so the credit note totals $500.00. For later partial refunds, base the split on the amount not yet refunded on each line, so the amounts excluding tax clear every line exactly.Sphere rounds the tax on each credit note separately. After several partial refunds, the total tax credited can differ from the tax on the original sale by a cent.Primer refunds can be asynchronous. Record the credit note when the refund webhook confirms the refund, rather than when the refund request returns.In the example:
allocateRefund in server/refunds.js splits the refund across the lines, and confirmRefund records the credit note once Primer reports the refund settled.7
Cancel the sale on a chargeback
For a dispute that results in a chargeback, Sphere expects the original transaction to be cancelled.
Handle Sphere being unavailable
calculate_tax runs while the customer waits at checkout. Set a short timeout, such as 2 seconds, so a slow response can’t stall your checkout.
If Sphere doesn’t respond in time, or returns an error because it’s unavailable, you need to decide what happens to the customer’s payment. This is your decision.
- Fail open (Sphere’s recommendation): let the customer pay without tax. Primer Checkout shows the total without tax, and the payment goes ahead. Make sure the payment guard in step 4 allows this.
- Fail closed: block the payment until Sphere responds and tax is calculated.
If you fail open, still record the sale in Sphere, without a calculation ID. Sphere calculates the tax that was due on the sale and records it as owed. Mark these sales in
metadata so you can find them later.
Only fail open when Sphere is unavailable: timeouts, 429, and 5xx responses. Other 4xx responses mean Sphere couldn’t calculate tax for this request, and depend on the error:
customer_tax_location_invalid: Sphere couldn’t locate the address. Ask the customer to correct it.- Other errors, such as
invalid_product_tax_code, are problems in your setup that the customer can’t fix. Block the payment and fix the setup.
external_id until you get a response. Save each sale you need to record on your server, and keep retrying until Sphere confirms it, so no sale is lost if Sphere or your server is down.
In the example: failsOpen in server/sphere.js decides when to fail open, and server/worker.js retries queued Sphere writes until Sphere confirms them.
Other things to know
- Every sale. Calculate tax and record every sale, including sales in places where you aren’t registered. Sphere only returns tax where you’re registered.
- One tax calculation per order. Sphere’s API doesn’t stop you from using the same calculation ID on more than one transaction, but that isn’t intended. Make sure your server only uses a calculation ID for the order it was calculated for.
- Partial capture. Tax is due on the full order total once the order is issued to the customer, even if you capture less than you authorized. Record the full sale with its calculation ID. If the rest is never collected, record a credit note for the uncollected amount, split across lines as in step 6. For example, if you capture $1,000.00 of the $1,633.12 order and never collect the remaining $633.12, record a credit note for $633.12.
- Address validation. Sphere uses a third-party mapping service to resolve addresses, so it may place an incomplete or invalid address (for example, a US ZIP code that doesn’t exist, with no state) in a jurisdiction rather than return an error. Validate addresses before you calculate tax.
- Business customers and reverse charge. Pass the customer’s tax ID as
tax_id. In some countries, a business customer accounts for the tax themselves instead of paying it to you. This is called reverse charge. When it applies, Sphere returnstaxability_reason: reverse_chargewith zero tax. Sphere checks tax IDs with the tax authority where it can. The first time it sees a tax ID, that check happens in the background, so during checkout Sphere can only check the ID’s format. - Recurring and merchant-initiated payments. Each charge is a separate sale. Calculate tax for each charge, set
taxAmounton the line items of the payment request, and record the sale in Sphere with its ownexternal_idand calculation ID. Don’t reuse the calculation ID from an earlier charge. - Up-to-date rates. A calculation ID doesn’t expire, but rates change. Calculate tax as close to payment as you can, and again whenever the address or order changes.
- Currencies. Sphere accepts any ISO 4217 currency. The Transaction API currently stores two decimal places for every currency, so amounts in three-decimal currencies, such as KWD, are rounded.
Test your integration
- In your Primer sandbox, use a test card to create a successful payment.
- Calculate tax for addresses in places where you’re registered and where you’re not, and with and without a business tax ID. Check the tax per line, the reason for any zero-tax lines, and the total shown on the pay button.
- Change the address after tax is calculated, then try to pay. The guard in step 4 should block the payment.
- Decline a payment, then retry. The retry should succeed, because it uses a new idempotency key.
- Complete a payment, then check the transaction in Sphere. Its tax should match the tax calculation exactly.
- Make one or more partial refunds that add up to the full amount. The credit notes in Sphere should add up to the original sale, both net and tax.
POST /v1/transactions/{external_id}/cancel when you’re done, so they aren’t included in your filings.
Troubleshooting
Limitations
- Address from the payment form or a wallet. This integration assumes you have the address before payment, either from earlier in your flow or from your own form on the checkout page. If the address comes from the card form’s billing address fields, or from the Apple Pay or Google Pay sheet, you can’t recalculate tax before the payment starts. For wallets, the Express Checkout shipping address events can provide an address to calculate tax from.
- Tax-inclusive pricing. With inclusive pricing, Sphere returns the tax contained in the price (for example, $9.09 on $100 at 10%). Primer adds
taxAmounton top ofamount, so you’d need to setamountto the price minus the tax. This guide covers tax-exclusive pricing only.