Connect your Stripe account
Make a restricted key in Stripe with exactly the access Commerce Orbit needs, paste it in, and know what happens if the key stops working.
How-to guide6 min read
Commerce Orbit takes payments through your own Stripe account. Shoppers pay into your account, Stripe pays out to your bank, and Commerce Orbit takes no fee on orders. Card details go straight from the shopper to Stripe and never reach Commerce Orbit. Which payment methods shoppers see, such as cards, Apple Pay, Google Pay or Klarna, follows the payment methods you switch on in Stripe.
You give Commerce Orbit a restricted key: a key that can only do the things you tick, which you can remove in Stripe at any time. Only Admins can connect, change or remove the key, under Stripe in the sidebar. You need to be an administrator of the Stripe account.
Make a restricted key
- In the Stripe Dashboard, open Developers, then API keys.
- Select Create restricted key. If Stripe asks how you will use the key, choose the option for your own integration, so you can set the access yourself. Name it Commerce Orbit, so you recognise it later.
- Give it these permissions and leave everything else at None:
| Resource | Permission | What Commerce Orbit uses it for |
|---|---|---|
| PaymentIntents | Write | Takes the payment for each order and checks whether it went through. |
| Refunds | Write | Refunds customers from Commerce Orbit. |
| Disputes | Read | Shows disputed payments on the order. |
| Webhook endpoints | Write | Lets Stripe tell Commerce Orbit straight away when a payment succeeds, fails or is refunded. |
| Charges | Read | Reads payment details to match refunds and disputes. |
| Balance | Read | Reads your Stripe balance. |
| Payouts | Read | Reads payouts to your bank. |
Some features need a little more. Give the key these too if you use them, or add them later (see Features that need more access):
| Feature | Resource and permission |
|---|---|
| Payment links, for draft orders and for the difference after an order edit | Checkout Sessions: Write |
| Subscriptions | Customers, Products, Prices, Subscriptions and Invoices: Write |
| US sales tax | Tax calculations and Tax transactions: Write. Tax registrations: Read |
| Express checkout | Payment method domains: Write |
- Select Create key and copy it. It starts with
rk_live_orrk_test_. - Copy your publishable key from the same page too. It starts with
pk_live_orpk_test_. Checkout uses it to show Stripe's payment form.
Paste it in
On the Stripe screen, paste the restricted key and the publishable key, then connect. A full secret key, starting with sk_, also works, but it can do anything in your account, so a restricted key is safer. Commerce Orbit then:
- checks each permission with a harmless request and lists any that are missing
- reads your account's name, country and default currency
- creates a webhook endpoint in your Stripe account, named after your organisation, so Stripe can tell Commerce Orbit about payments
- stores the key and the webhook's signing secret encrypted, and never shows the key again
The screen then shows your account and whether it is live or in test mode.
If PaymentIntents is missing, shoppers can't pay by card: checkout says "This shop can't take card payments yet". Companies with invoice terms can still order on invoice. Without Webhook endpoints, payments still go through, but Commerce Orbit only notices them when it next asks Stripe, within about a minute. To fix the access, edit the key in Stripe and connect again with the same keys.
Features that need more access
Taking payments only needs the first table. The Payments page also lists the features that need more, and shows for each one whether your key has what it needs. Commerce Orbit checks with harmless requests that change nothing in your account: it checks when you connect, and again when you select Check again.
Until a feature has its access, Commerce Orbit leaves it out rather than letting a payment fail halfway:
- Payment links: draft orders can't be sent for payment, and an order edit that makes the order cost more is refused, with a message naming the access to add. Edits that cost the same or less still work.
- Subscriptions: products show only the one-off price, and a cart that already holds a subscription asks the customer to buy it once instead.
- US sales tax: you can't switch it on. If the access goes missing after you switched it on, carts to the United States say the order can't be placed, before anyone pays.
- Express checkout: the Apple Pay, Google Pay and Link buttons don't show. Customers pay at the normal checkout.
To add access, open Developers, then API keys in Stripe, select Edit key on the Commerce Orbit key, set the permissions and save. The key itself stays the same, so there is nothing to paste again. Then select Check again on the Payments page.
Express checkout
Express checkout puts Apple Pay, Google Pay and Link buttons on product pages and in the cart. Customers pay in one step with the address and card saved in their wallet, choose a delivery rate in the wallet, and land on their order page. On a product page the button buys only that product, so the rest of their cart stays. The buttons only show when the customer's device can use them and you have switched the method on in Stripe.
It is on once Stripe is connected. Turn it off under Express checkout on the Payments page.
Apple Pay only works on websites registered with your Stripe account. Commerce Orbit registers the hosted shop and your Website and Allowed websites from Shop settings when you connect Stripe and when you turn express checkout on, and shows whether each one is ready for Apple Pay, Google Pay and Link. Select Check again after you add a website.
Test and live keys
Use test keys first. With rk_test_ and pk_test_, orders go through as usual but no real money moves, and you pay with Stripe's test cards, such as 4242 4242 4242 4242.
When you are ready, connect your live keys the same way. A live secret key only works with a live publishable key, and a test key with a test key. Orders placed in test mode stay in Commerce Orbit: cancel them before you sell for real, so their stock comes back.
When a payment is missing
Commerce Orbit hears from Stripe as soon as a payment goes through. It also asks Stripe every minute about orders still waiting, once more before cancelling an unpaid one, and whenever the customer opens their order page. So an order that shows as paid in Stripe catches up here by itself, usually within a minute. See Orders.
If the key stops working
If someone removes the key in Stripe, or Stripe stops accepting it:
- checkout fails with "The payment couldn't start", followed by Stripe's reason. The order isn't placed and its stock comes back.
- card payments can't be refunded from Commerce Orbit
- orders on invoice still work
Orders and payments already made stay as they are. Make a new key and connect again, and everything carries on.
Remove the connection
Disconnect removes the webhook Commerce Orbit made in your Stripe account and forgets the key. Nothing else in Stripe changes: payments, refunds and payouts stay where they are. Without a connection, shoppers can't pay by card.
Was this page helpful?