Authentication

Every request carries a bearer token. The prefix decides the mode.

Pass your key in the Authorization header on every request:

Authorization: Bearer oro_live_xxxxxxxxxxxxxxxx

Tokens & modes

Field	Type		Description
oro_test_…	sandbox	optional	Stateful sandbox. Real prices, simulated settlement, no real money.
oro_live_…	live	optional	Production. Moves real money. Requires an approved go-live.

Generate and rotate keys from the API Keys page. Rotating a key immediately invalidates the previous one for that mode.

Treat oro_live_ keys like a password — they move real funds. Never embed them in client-side code or commit them to source control. Rotate immediately if one leaks.

Response envelope

Successful responses share a consistent shape:

{
  "success": true,
  "request_id": "req_9f2c…",
  "mode": "sandbox",
  "data": { /* endpoint payload */ }
}

Errors return a structured error object instead of data — see Errors.

Issuing a token via the API

Keys are normally generated from the dashboard, but you can also mint them programmatically. Both steps are tightly rate-limited (see rate limits).

POST/partner/auth/request-otp

Sends a one-time code to your registered partner mobile.

Field	Type		Description
mobile	string	required	Your registered 10-digit mobile, no country code.
mode	string	required	"live" or "sandbox" — which key you want to mint.

Field	Type	Description
message	string	Human-readable confirmation.
expires_in_seconds	number	OTP validity — 600 (10 minutes).
sandbox_otp	string	Sandbox only: the OTP is returned inline (always 1234) and no SMS is sent.

POST/partner/auth/verify-otp

Exchanges the code for a token. The full token is shown once — store it immediately.

Field	Type		Description
mobile	string	required	Same mobile you requested the OTP for.
otp	string	required	The code you received (1234 in sandbox).
mode	string	required	"live" or "sandbox" — must match the request.

Field	Type	Description
token	string	The full API key. Shown once and never again.
token_last4	string	Last 4 characters, for display and support.
mode	string	Which mode this key is for.
company_name	string	Your partner profile name.
issued_at	string	ISO timestamp.

# 1) request the OTP
curl -X POST https://api.oropocket.com/partner/auth/request-otp \
  -d '{"mobile":"9876543210","mode":"sandbox"}'

# 2) exchange it for a token (shown once)
curl -X POST https://api.oropocket.com/partner/auth/verify-otp \
  -d '{"mobile":"9876543210","otp":"1234","mode":"sandbox"}'

Token lifecycle

Event	What happens
Expiry	Never. Tokens stay valid until replaced or revoked.
Regenerate	Minting a new key for a mode instantly invalidates the previous key for that mode.
Revoke	You can revoke a key from the dashboard; an admin can also revoke it.
Rotation	Because there is exactly one key per mode, rotate by minting a new one and deploying it — the old one dies at that moment.

IP restriction (optional)

You can lock a key to the addresses your servers call from, so a leaked key is useless anywhere else. It is off by default and set per key under API keys → IP restriction: your Test key and your Live key each have their own switch and list.

Rule	Detail
What to list	Your servers' public (outgoing) addresses — IPv4 or IPv6 — or CIDR ranges such as 203.0.113.0/24. Up to 20 per key; ranges broader than /16 (IPv6: /32) are refused.
When it applies	Immediately on save. Any request with that key from an address not on the list is refused with 403 IP_NOT_ALLOWED; the response names the address we saw.
What it covers	Every call made with the key — including POST /partner/users/init, which opens the hosted embed, and payment orders. List every server that makes these calls, or new embed opens fail. Customers already inside the embed, payment pages and webhooks are not affected: they never use your key.
Turning it off	Any address can use the key again. The list is kept, so turning it back on restores it.
Before you switch it on	The editor shows the addresses that used the key most recently, and before saving warns you about every address from the last 7 days that the new list would refuse.

Calls made from a browser — including the dashboard Playground — come from that machine’s own internet address, not your servers’. If you restrict your Live key, test from Test mode or add your office address. If an integration partner runs the integration for you, list their servers’ addresses. Refused calls appear under Logs as IP_NOT_ALLOWED.

← Quickstart Environments & modes →