Skip to main content
A widget integration has four participants. Two are yours and two are Ripio’s:

​
The big picture

Your systems and Ripio’s meet in exactly two places: POST /auth, where you call Ripio, and the webhooks, where Ripio calls you. Everything in between — portfolio, market, quotes, executions — goes straight from the widget to the widget API, from the user’s device:
  • There’s nothing to proxy. Your app never calls the widget API, and your backend never sees the widget’s requests. Your page’s origin has to be registered with Ripio and its CSP has to allow the widget API — see Infrastructure requirements.
  • You never handle the session token. The widget gets it by redeeming the code and keeps it in memory: it never reaches your page, the URL or the browser’s storage.
  • client_secret stays on your server. It’s only used in step 1, server to server.

​
Opening the widget

Every time the widget opens, your backend requests a fresh code and the widget redeems it on its own: Two things can stop it short of Home:
  • The code doesn’t work — it expired, was already used, or never existed. The widget shows the “session ended” screen and fires ripio-session-expired.
  • The user can’t operate yet — for example, their identity verification isn’t complete. The widget fires ripio-handoff so you can take them to the right place in your app.

​
Buying crypto

From the user’s confirmation to your books, a buy involves your backend twice: once to approve it, if your account has transaction approval enabled, and once to learn how it ended. How the approval step ends decides what the user sees and whether a result follows: A few things the diagram doesn’t show:
  • A sell skips the approval step. Ripio holds the custody of the crypto being sold, so there’s nothing on your side to authorize. You still receive its transaction_result.
  • The result is asynchronous. transaction_result can reach your backend before or after the widget shows the success screen — don’t make one wait for the other. If you don’t acknowledge it with a signed response, Ripio retries it up to 3 times, with the same event_id.
  • A retry can ask you again. If confirming fails without a clear outcome — a timeout, a network error — and the user presses retry, your endpoint can receive a second transaction_approval_request for the same operation id, with a new event_id. Only transaction_result closes the operation.
See Webhooks for the payloads, the signatures and every cancel reason.

​
Renewing a session

A session lasts one hour from your POST /auth call and doesn’t extend with activity. When it ends, the widget asks your app for a new code instead of reloading the page: The new code can belong to a different external_ref — the widget starts from a clean state on every renewal. See Session lifecycle for every event and the WebView bridges.