Returning to the App

Choose the right successUrl

We accept two forms for successUrl: an https:// URL or a custom scheme (myapp://return). Strongly prefer the former, in the form of a Universal Link (iOS) / App Link (Android): a custom scheme fails silently when the app is not installed, whereas an https URL falls back naturally onto a web page. We accept the custom scheme because it remains legitimate when you know the app is there.

successUrl: https://app.yourbrand.com/purchase/return

Appended identifiers

We automatically append the checkout identifiers to your URL:

https://app.yourbrand.com/purchase/return?sessionId=sess_KAriHKBIiMtyPFnmIjHor&paymentId=pay_tSHQZkFiAfKJwbmsFEJwd

The append is idempotent: if you already put ?sessionId= in your URL, it is not duplicated. A fragment (#…) is preserved, and the parameters are inserted before it.

These parameters are pointers, not proofs. They tell your app what to check; the answer always comes from your backend. See Granting Access with Webhooks.

The success screen

What the buyer sees on our success page depends on the returnMode you chose when creating the session — in APP_RETURN, a "Back to the app" button and an automatic redirect after 5 seconds.

The button is not a mere convenience: Safari and Chrome regularly refuse a navigation towards an application scheme that no user gesture has triggered. It is often the button that works, the automatic redirect being the shortcut when it goes through.

We do not detect whether your application is installed. The store badges are displayed because you chose APP_INSTALL, never because we would have guessed the app was missing. This is deliberate: every detection technique available here is either a fingerprint or a timing assumption that gets it wrong precisely for the buyer who would most need it to be right.

Device fallbacks

On a device without a touchscreen, APP_RETURN falls back to the plain confirmation — its button would point to an application that cannot be there — and no redirect takes place.

APP_INSTALL, on the other hand, is displayed everywhere, including on desktop: that is precisely the case of a buyer who saw your ad on a website and does not have the app yet. See Web-to-App Acquisition.

Next step

The user is back in your app. Do not trust the URL — refresh the access right from your own backend.