Stripe

Updated 11 November 2026

Overview

This article covers the Stripe page. Stripe charges the shopper's card when a return needs a payment: an exchange that costs more than the item being returned on a policy that collects the difference, a Shop Now cart that costs more than the credit, a handling fee above the return's credit, a manual return where you choose to collect by card, invoice or shared link, and Instant Exchange, which saves the card and charges it if the return is not shipped by the ship-by date. It also refunds those charges when a return is cancelled, rejected, expires, or the replacement is out of stock.

Use the menu on the left to quickly navigate this article.

Before you start

• A Stripe account with its secret key and publishable key to hand, from the Stripe Dashboard under Developers > API keys.
• A policy outcome that needs a payment: Different priced exchanges set to collect, Shop Now, or Instant Exchange. The Shop Now and Instant Exchange cards read Connect Stripe until Stripe is connected.

The Stripe page

In the admin, go to Tools > Integrations > Stripe.

Screenshot

Tools > Integrations > Stripe, the status pill, the mode tag, the three key fields and the Save Changes and Disconnect Stripe buttons

• Secret key: sk_test_ for test mode or sk_live_ for live mode. It stays on the server and is used only to create payments and refunds; it is never sent to the shopper's browser.
• Publishable key: pk_test_ or pk_live_. Used by the shopper portal to collect card details.
• Webhook signing secret: optional. Needed only if you have set up a Stripe webhook that points at POST /api/webhooks/stripe. Find the signing secret in the Stripe Dashboard under Developers > Webhooks.

Click Save Changes. With a key saved each field reads Enter a new key to replace the saved one.

• Status: Not connected before a secret key is saved. Saved (verifying) while Stripe checks it. Connected with your business name once Stripe accepts it; the page then shows your Account, Business and Mode. Credentials cannot be read when the saved key can no longer be decrypted. If Stripe rejects the key, a banner reads Stripe rejected this secret: followed by Stripe's own message.
• Test mode / Live mode: a tag beside the status, set by the key's prefix.
• Open Stripe Dashboard: opens your Stripe API keys page in a new tab.
• Disconnect Stripe: at the foot of the page. The confirmation reads Disconnect Stripe? and says it clears all saved Stripe keys. Click Disconnect Stripe to confirm.

What the shopper sees

With no secret key saved, the portal still offers the outcome but blocks it at the review step: the card form reads Payments are temporarily unavailable. Please contact support to complete this return. and the submit button is disabled.

Important: That block only appears when no key is saved. With the keys saved and the switch on Tools > Integrations off, the portal still offers the outcome and ReturnZen creates no real charge. To stop shoppers submitting returns that need a payment, disconnect Stripe rather than switching it off.

What stops when Stripe is off, disconnected or unreadable

Switching Stripe off on Tools > Integrations keeps the keys saved and stops charges and refunds while it is off; switching it back on resumes them. Disconnecting clears every saved key. A key that is saved but cannot be read shows Credentials cannot be read on the tile and This store's saved Stripe key cannot be read. Save the key again on the Stripe settings page. on the page; charges refuse until the key is saved again.

On a manual return with a difference to collect, the payment box reads Collecting a payment needs an active Stripe connection on this store. while Stripe is off or disconnected. See Manual returns.

On an account set up by support with a key held on the server, disconnecting your own keys does not stop charges: the dialog says the server key keeps running Shop Now payments and refunds until you switch the Stripe integration off. The switch is what stops them.

How it works

A refund of a Stripe charge goes back to the card that paid it, not to the order in Shopify. The refund of the returned item itself is still made in Shopify. Stripe's own fees apply to every live charge and refund.

Every held card charge has a Refund Charge button on the return page. Say a shopper pays a 20.00 difference on Monday and switches the return to store credit on Tuesday. The return is held in Needs review with the banner The shopper's 20.00 USD card charge has not been refunded. Click Refund Charge, or refund it in Stripe manually. Click Refund Charge and the 20.00 goes back to the card and the return proceeds. With Stripe disconnected the banner reads Reconnect Stripe, or refund it in Stripe manually. instead; after a refund by hand, click Close Return. See Held returns.

When part of a charge was refunded in Stripe by hand, the charges card on the return page states both parts, for example 80.00 USD recorded on this return; 30.00 USD of it was refunded in Stripe, and 50.00 USD is not refunded.

Instant Exchange runs on Stripe too: the saved card, the optional 7-day hold and the charge on the ship-by date. A card that declines on the charge date is retried on two further nights; after a third decline the return is held, with a bell alert and a Retry button. See Instant Exchange.

FAQ

Do I need Stripe at all? Only if a return can need a payment: Different priced exchanges with the difference collected, Shop Now, Instant Exchange, a handling fee above the return's credit, or a manual return where you collect by card, invoice or link. Refunds, store credit and even exchanges all work without it.

Does the Stripe refund include the returned item? No. Stripe only refunds the card charge for the price difference or the Shop Now extra. The returned item is refunded or credited in Shopify as usual.

Please reach out to support@returnzen.app with any additional questions.