How to Add Digital Gold to Your Fintech App (2026 Integration Guide)

The short version: adding gold to your app is a small integration sitting on a large amount of regulated infrastructure. Vault custody, bullion sourcing, GST invoicing, KYC adjudication and settlement are all regulated, capital-intensive problems. A digital gold API hands you those. What you build is the screen, the button and the webhook handler.

Every consumer fintech in India eventually gets asked for gold. It is the savings instrument people actually understand, it sells in festival season without any persuasion, and it gives a wallet or a neobank something to offer that is not another lending product.

Then someone scopes the work and it stalls. You need a bullion supplier, insured vault space, a pricing engine that tracks the market, GST-compliant invoicing, PAN and Aadhaar verification, a settlement and reconciliation process, and a compliance position on all of it. That is a company, not a feature.

Digital gold is fractional 24K bullion held in an insured vault on your behalf, bought and sold in rupees rather than grams. We cover how it works in India separately. So the practical question is not “should we build gold” but “which parts do we refuse to build”. This guide walks through what a digital gold API actually gives you, the integration shape, and the specific engineering details that separate a good API from one you will be fighting in production. If you are still choosing a vendor, our comparison of digital gold API providers in India covers that decision first.

What you are outsourcing

The value is not the REST endpoints. It is everything sitting behind them.

Concern	Build it yourself	With an API
Bullion sourcing	Supplier contracts, minimum volumes, price negotiation	Included
Vault custody	Insured storage, audits, a custodian relationship	Included
Pricing engine	Live market feed, spread management, rate publishing	One endpoint
KYC adjudication	PAN and Aadhaar verification, decisioning, records	One flow
GST invoicing	3% GST, CGST/SGST split, compliant tax invoices	Generated for you
Settlement	Daily reconciliation, payouts, dispute handling	Monthly statement
Physical delivery	Minting, packaging, insured logistics	One endpoint
What you build	—	UI, auth, a webhook handler

The bottom row is the whole point. How long that takes depends on your stack and your compliance review, and we are not going to invent an average, for a reason we get to at the end.

Pick your integration depth first

This decision shapes everything after it, so make it before you write code. There are three shapes, and they trade control against effort.

Hosted webview, lowest code. You open a WebView pointed at a URL carrying a short-lived user code. The entire buy, sell, KYC and portfolio experience renders inside it. You write essentially no financial logic. You do not control the UI, and your margin is the commission rate, because the price on screen is not yours to set.

Raw API, full control. You call the endpoints directly and build every screen. More work, complete control over the experience, and the path that lets you set your own markup on top of the base rate.

Gifting and sending, no signup required. You move metal to any Indian mobile number, and the recipient claims it later. This is the path for rewards, cashback and festival campaigns, and it is the one most teams overlook. Send limits default to ₹1,00,000 a day, and ₹1 to ₹50,000 per transaction. The recipient does not need to be your user yet.

A useful rule: if gold is a feature of your product, take the webview. If gold is a product line, take the raw API.

Where the money sits

This is the architectural fact that shapes your integration, and it is worth knowing before you read any code.

Buys debit your wallet, not your user’s. You hold a prepaid float with OroPocket, on the Free tier, or a postpaid credit line on Pro. When your user buys a gram, your float is debited and their holding is credited. Collecting money from your user is your side of the flow, on whatever rails you already run.

Sells credit the end user, not you. Proceeds from a sale land in that user’s OroPocket INR wallet, from which they withdraw to their own bank account. This trips people up, so plan for it: you are not the settlement counterparty on the way out.

Commission settles monthly. Statements finalise on the 1st for the prior month and pay to your registered bank account. If you are on Pro and using merchant markup, your markup comes back on that same cycle, so it ties up working capital for up to a month.

Two consequences worth designing around. Your float running dry is a real production state, not a hypothetical, which is why the sandbox lets you reach it deliberately. And because a user’s balance is shared across every partner they have used, your slice can shrink without any API call from you. You will get a sell.completed webhook when that happens.

Your first buy, in four calls

Here is the shape against the live API. The base URL is https://api.oropocket.com/partner, and authentication is a bearer token where the prefix decides the environment. oro_test_… hits the sandbox, oro_live_… hits production. There is no separate hostname and no mode header to forget.

1. Register the user. You get back a user_code that identifies this person in every later call.

curl -X POST https://api.oropocket.com/partner/users/init \
  -H "Authorization: Bearer oro_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"mobile": "9876543210", "flow": "api"}'

2. Get a quote. This locks a price for ten minutes.

curl -X POST https://api.oropocket.com/partner/buy/quote \
  -H "Authorization: Bearer oro_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"user_code": "usr_...", "asset": "gold", "amount_inr": 1000}'

3. Confirm it. Note the Idempotency-Key. More on why below.

curl -X POST https://api.oropocket.com/partner/buy/confirm \
  -H "Authorization: Bearer oro_test_xxx" \
  -H "Idempotency-Key: order-4417-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{"quote_id": "qt_..."}'

4. Read the portfolio.

curl https://api.oropocket.com/partner/users/usr_.../portfolio \
  -H "Authorization: Bearer oro_test_xxx"

Every response uses the same envelope, which makes error handling boring in the way you want:

{ "success": true, "request_id": "req_9f2c...", "mode": "sandbox", "data": { } }

Failures swap data for an error object carrying a stable code. Every response also carries X-Request-ID, so when something goes wrong you have one string to quote in a support thread.

Why buying is two calls, not one

A quote is a price locked to a specific user and amount for a fixed window, which you then execute by reference. The quote-then-confirm split is the part engineers most often push back on.

Gold moves continuously. If a buy were a single call, the price on screen and the price paid would differ by however long the round trip took. You would own that difference. Quoting first pins the rate for ten minutes and hands you a quote_id. Your user sees a real number, decides, and confirms against that exact rate.

Two things make this safe in production. Confirmation is row-locked, so two concurrent confirms on the same quote cannot both settle. And an expired quote fails loudly with QUOTE_EXPIRED rather than silently repricing, so your user never gets charged a rate they did not agree to.

An idempotency key is a string you attach to a mutating request so the server can recognise a retry and return the first result instead of acting twice. It covers the other classic failure. If your request times out and you retry, the key ensures the second call returns the original result instead of buying twice. Keys stay valid for at least 24 hours, and a replay is flagged with an Idempotent-Replayed: true header so you can tell the difference. Neither Augmont nor SafeGold documents a safe-retry mechanism at all, which means on those APIs a timeout is a genuine ambiguity you have to resolve by hand.

Webhooks, not polling

Both Augmont and SafeGold expect you to poll an order-status endpoint to find out whether a trade completed. That means a scheduler, a backlog of in-flight orders, and a decision about how often to check. It also means a permanent gap between something happening and your system knowing it happened.

OroPocket pushes signed webhooks instead. Events include buy.completed, sell.completed, sip.created and sip.installment.

We compared all three developer surfaces in August 2026. Raw surface area is similar; what differs is the operational machinery around it.

Both vendors publish their developer documentation, so you can check these rows yourself: Augmont and SafeGold. Read as of August 2026.

One disclosure, because it matters for how you read this: Augmont is also our bullion supply and custody partner. We are comparing developer experience, not metal. They are a competitor at the API layer and a supplier underneath it, and you should weigh the table accordingly.

	OroPocket	Augmont	SafeGold
Documented endpoints	56	52	33
Trade webhooks	Yes	No, poll	No, poll
Documented idempotency	Yes	No	No
Stateful sandbox	Yes, funded	None	Staging host
Auto-compensation on failure	Yes	No	Manual refund
Hosted UI option	Yes	No	No

We include endpoint count only to show the comparison is not about surface area. SafeGold’s published navigation understates its own surface, so read that row loosely. The operational rows are the ones that change your architecture.

Each delivery carries an HMAC-SHA256 signature computed over the timestamp and the raw body joined by a dot, which is what makes replay attacks detectable:

You need the raw body, which Express does not keep by default. Capture it at parse time:

app.use(express.json({
  verify: (req, res, buf) => { req.rawBody = buf }   // Buffer, before parsing
}))

Then verify:

const crypto = require('crypto')

function verify(req, secret) {
  const ts  = req.get('X-OroPocket-Timestamp')
  const sig = req.get('X-OroPocket-Signature')        // "sha256=<hex>"
  if (!ts || !sig || !req.rawBody) return false

  // Reject stale deliveries. Number('') is 0 and Number(undefined) is NaN,
  // so check the parse rather than trusting the comparison.
  const age = Math.abs(Date.now() / 1000 - Number(ts))
  if (!Number.isFinite(age) || age > 300) return false

  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(`${ts}.${req.rawBody}`)                   // raw body, not parsed JSON
    .digest('hex')

  const a = Buffer.from(sig)
  const b = Buffer.from(expected)
  // timingSafeEqual throws on length mismatch, and the header is
  // attacker-controlled, so length-check before comparing.
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

Three things to get right, and all three are common sources of a broken first integration. Sign the raw body rather than a re-serialised object, because key order will not survive a round trip through your JSON parser. Length-check before timingSafeEqual, which throws a RangeError on mismatched buffers rather than returning false. And treat a missing or unparseable timestamp as a failure, since NaN > 300 evaluates to false and would otherwise wave the delivery through.

Delivery is retried five times with backoff of 30 seconds, 2 minutes, 10 minutes, 1 hour and 6 hours. The queue lives in a database, so it survives a restart on either end. Each event carries a unique X-OroPocket-Event-Id, which is what you deduplicate on.

The sandbox holds state

Most “sandboxes” in this category are either a stub that returns a fixed payload or a staging host that quietly shares production behaviour. Neither lets you test the cases that actually break.

This one keeps real state. Test users persist, balances move, trades settle, and it prices off the same live market feed as production. Only settlement is simulated. Your sandbox account is seeded with a ₹1,00,000 float. That matters more than it sounds. It means INSUFFICIENT_PARTNER_FUNDS is a state you can actually reach and write a handler for, rather than a paragraph in the docs you meet for the first time in production.

It also fires signed webhooks, stamped "mode": "sandbox", so you can build and test your handler before going live.

Fixed values drive the flows that would otherwise need a real person: OTP 1234, email code 123456, PAN ABCDE1234F approves while ZZZZZ9999Z rejects, and any withdrawal amount ending in .01 fails and then refunds, so you can exercise your failure path deliberately. POST /partner/sandbox/reset puts the float back.

What it costs, and who pays whom

This is where the model inverts. There is no per-call fee, no monthly platform fee and no minimum. Instead of paying for API access, you earn commission on the volume you drive.

	Free	Pro
Cost to integrate	₹0	₹0
Cost to go live	₹0	₹50,000 one-time
Commission on buys	1%	2%
Your own markup	—	Up to 5%, yours to keep
Billing	Prepaid float	Postpaid credit line
Sandbox	Full, stateful	Full, stateful

Commission is paid on gross rupees for every buy by a user attributed to you, including each SIP instalment. Attribution is set once, when the account is created. It is exclusive to one partner and runs for twelve months. Users who already had an OroPocket account never attribute, so this rewards genuinely new customers rather than re-counting existing ones.

Two details worth knowing before you model revenue. Sell commission of 0.25% exists, but only applies if your attributed users cross ₹3,00,00,000 of combined buy and sell volume in a calendar month. Below that it is voided for the month, with no carryover. And on Pro, the merchant markup is your real margin lever: you set a percentage on top of the base rate, the user pays the marked-up price, and the difference comes back to you the following month. It is returned on the monthly settlement cycle rather than instantly, so it does tie up working capital.

Going live

Onboarding is self-serve. You verify a mobile number, pick a use case, and the panel mints a sandbox key immediately. No sales call, no card, no approval queue before you can write code.

Production takes a six-step wizard: business details, settlement bank account, KYB documents, KYC of the authorised signatory, e-signing the agreement, and submit. Going live costs nothing on the Free tier. Once approved, you mint an oro_live_… key and every path stays identical, so nothing in your code changes except the token.

How long that takes depends on which path you took. On the hosted webview, plan for about three days from submitting the wizard to a live key: you are not writing financial logic, so the review is mostly your documents. On the raw API, plan for about two weeks, because we review your buy and sell flow, your webhook handler and your failure paths alongside the paperwork. Both assume your KYB documents are in order; incomplete paperwork is the usual reason a timeline slips.

What this API does not do

Worth stating plainly, because finding out mid-integration is expensive.

• No published SDK. You call raw HTTP. Verified webhook-signature snippets exist for Node, Python and PHP, but there is no package to install.
• No programmatic SIP creation. You will receive sip.created and sip.installment events, but SIPs are started by the end user inside the hosted embed. A raw-API partner cannot open one today.
• Whitelabel is on the roadmap. A fully whitelabelled site under your own domain is not shipping yet.
• No gold yield or leasing product. Both Augmont and SafeGold offer one. This is a genuine gap.
• No nominee support.
• Rate limits are modest. 120 requests per minute in general, but only 10 per minute per IP on public prices. If you want a live ticker in your own UI, cache our rate server-side rather than proxying every page view.
• The SLA is 99.00%, not the number you may have seen elsewhere on our site. That is roughly seven hours a month. Design your buy flow to fail gracefully.
• Key rotation has no overlap window. Minting a new token immediately revokes the old one, so rotation is a brief downtime event unless you coordinate the deploy. We would like to fix this.

One more thing that surprises people: a user has a single combined balance, and each partner sees only its own slice. If that user sells inside the OroPocket app, your slice can shrink without any API call from you. You will receive a sell.completed webhook when it happens, which is why you want the webhook handler built early rather than bolted on.

Digital gold is also not a bank deposit and not a regulated instrument under SEBI or RBI. Say so in your own product copy.

One thing in our favour while you weigh all of that: you get direct access to the people who built this. We answer the phone, and if something you need changed is reasonable, it has a decent chance of actually getting changed rather than joining a backlog.

Common questions

How long does a digital gold integration actually take?

It depends on the path. The hosted webview removes almost all of the build, so the timeline is dominated by approval: roughly three days once you submit the go-live wizard. The raw API means you build a buy and sell flow, a webhook handler and a KYC hand-off yourself, and approval takes about two weeks because we review those flows alongside your paperwork. Sandbox access is immediate on both paths, so you can start writing code the same day. The gate is usually your own compliance review, not the API.

Do I need my own KYC infrastructure?

No. PAN and Aadhaar verification run through the API, typically completing in about two minutes. KYC is also global rather than per-partner, so a user verified through any integration arrives at yours already verified.

What happens if a payment succeeds but fulfilment fails?

The wallet debit is automatically reversed and the order voided. You get an explicit error code rather than a silent inconsistency. The documented alternative on SafeGold is to not call confirm and refund the customer manually.

Can I set my own price?

On the Pro tier, yes. You can apply a markup of up to 5% over the base rate and keep the difference, settled the following month. On the Free tier and on the hosted webview, the displayed price is the platform rate.

Is digital gold taxed differently from physical gold?

No. Under the Finance Act 2024, for disposals on or after 23 July 2024, gains on gold held more than 24 months are long-term and taxed at 12.5% with no indexation benefit. Sold inside 24 months, the gain is added to income and taxed at slab rate. The treatment is the same whether the gold is physical, digital, an ETF or a mutual fund. Current rules and forms are published by the Income Tax Department; verified 10 August 2026. Our guide to gold and silver taxes covers the detail. Tax rules change. Confirm with a qualified advisor before acting.

Start with the sandbox

The fastest way to judge any API in this category is to try to break its sandbox. Register a user, buy a gram, force an INSUFFICIENT_PARTNER_FUNDS error, and make it deliver a webhook to your endpoint. If a sandbox cannot do those four things, you will be discovering its behaviour in production.

You can get a sandbox key from developers.oropocket.com without talking to anyone, and the quickstart is the four calls above with real payloads. If you are earlier in the process and still comparing options, start with the provider comparison, or the silver equivalent if that is your use case.