Open the embed on a screen

Add a launch object when you issue a user_code, and the embed opens on that screen instead of the home dashboard — with the values you chose already filled in.

A “Buy ₹500 of gold” button in your app can land the user on the buy sheet with ₹500 already entered. A “Start a wedding SIP” banner can land them on the SIP amount step. The user still reviews and confirms everything: a launch prefills, it never pays, sells or starts a SIP on its own.

Off by default. Ask your OroPocket contact to switch on Open the embed on a screen for your account. Until then, a request with launch returns 403 LAUNCH_NOT_ENABLED — requests without it are unaffected.

1. Add launch to /partner/users/init

POST/partner/users/initembed

Everything from the Hosted embed guide stays the same. Add one optional field:

Field	Type		Description
launch	object	optional	Where the embed opens, e.g. { "screen": "buy", "metal": "gold", "amount": 500 }. Omit it to open on the home dashboard.
launch.screen	string	required	One of the screens in the table below.
launch.metal	string	optional	"gold" (default) or "silver". For buy, sell, sip and coin_store.
launch.amount	number	optional	Rupees to prefill. Limits per screen below.
launch.grams	number	optional	Sell only, instead of amount. Up to 4 decimal places.
launch.frequency	string	optional	SIP only: "daily", "weekly" or "monthly".
launch.goal	string	optional	SIP only: emergency, phone, trip, wedding, vehicle, home, wealth or custom.
launch.goal_name	string	optional	SIP only: your own goal label (1–40 characters). Implies goal "custom".

curl -X POST https://api.oropocket.com/partner/users/init \
  -H "Authorization: Bearer oro_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "embed",
    "mobile": "9876543210",
    "launch": { "screen": "buy", "metal": "gold", "amount": 500 }
  }'

Response — the launch you sent comes back, normalised

{
  "success": true,
  "data": {
    "user_code": "usr_xxx",
    "embed_url": "https://connect.oropocket.com/?u=usr_yyy",
    "expires_at": "2026-09-26T09:22:00.000Z",
    "expires_in_seconds": 600,
    "user_existed": true,
    "mode": "live",
    "launch": { "screen": "buy", "metal": "gold", "amount": 500 }
  }
}

2. The screens

screen	Opens on
buy	The buy sheet, with amount prefilled (₹1–₹1,00,000, whole rupees). Without amount, it opens on the user's usual amount.
sell	The sell sheet, open. amount (₹) or grams — never both — capped at what the user can actually sell.
sip	SIP setup. amount is whole rupees, ₹100–₹1,00,000. With both goal and amount the user lands straight on the amount step; otherwise on the goal picker with your values filled in.
rewards	The rewards centre, on Refer & earn. Needs referrals enabled for your users.
spin	The rewards centre, on Spin the wheel. Needs spin enabled for your users.
transactions	The user's transaction history.
kyc	KYC status, where the user can continue verification.
sips	The user's list of SIPs.
coin_store	The coin store for metal. Needs coin delivery enabled for your users.
gift	The Shagun gift sheet, with amount prefilled (₹1–₹1,00,000). Needs Shagun enabled for your users.

A field a screen doesn't take is refused, not ignored — sending amount with spin returns INVALID_LAUNCH naming the field, so a typo never silently opens the wrong thing.

3. How it behaves

Once. The launch belongs to the single-use link you just minted. If the user refreshes, comes back from a payment, or opens the embed again later, they land on the dashboard. Mint a new link for a new launch.
Only from your server. The destination is stored with the link and never read from the URL, so a user cannot change where they land or what is filled in.
Prefill, not submit. Every screen opens with values in place; the user still taps Pay, Sell or Start SIP, and every normal limit and check applies when they do.
New users first sign up. A user verifying their mobile or completing their profile does that first, then lands on your screen.
Restrictions still win. If the account can't buy or sell right now, the user sees the same explanation they would get from tapping the button themselves.
Sandbox. Works with oro_test_ keys too — screens and prefills are identical; payments are blocked as usual in test mode.

4. Errors

Code	Meaning
400 INVALID_LAUNCH	Unknown screen, a field that screen doesn't take, or a value out of range. error.details.field names it. Nothing was minted.
400 INVALID_LAUNCH (field: launch)	launch was sent with flow "api". Launches only apply to the hosted embed.
403 LAUNCH_NOT_ENABLED	Opening the embed on a screen isn't switched on for your account yet. Ask OroPocket.
403 LAUNCH_SCREEN_UNAVAILABLE	That screen's feature is off for your users (e.g. spin, coin delivery, Shagun or referrals).
503 LAUNCH_NOT_READY	Temporarily unavailable. Retry, or omit launch to open on the dashboard.

A failed launch fails the whole request — no embed_url is issued. If you'd rather always open the embed, retry without launch on a 4xx.

Walkthrough: Open the embed on the buy sheet. UPI apps and payment pages inside your WebView still need the WebView & UPI setup.

← WebView & UPI setup Hosted whitelabel →