Glossary
Definitions for every field name, status, and concept used across the Onmeta API.
API Credentials
apiKey / Client ID
Your merchant identifier. Obtained from Dashboard → Setup → API's Setup. Included in every API request as a header (x-api-key) or body field (apikey).
Client Secret The secret used to generate HMAC-SHA256 signatures for verifying webhooks. Never expose this in client-side code. Obtained from the same dashboard page as the Client ID.
accessToken
A short-lived JWT returned after calling POST /v1/users/login. Required for all user-specific API calls in the Authorization: Bearer <token> header. Expires after 15 min — use POST /v1/users/refresh-token or re-login to get a fresh token.
Order Identifiers
orderId Onmeta's unique identifier for an on-ramp or off-ramp order. Use this to poll order status, match webhook events, and reference orders in support requests.
txnHash / transactionHash
The blockchain transaction hash — a 66-character hex string starting with 0x that uniquely identifies a transaction on the blockchain. Use this to build a block explorer link for users (e.g., https://polygonscan.com/tx/<txnHash>).
Payment Fields
fiatAmount The transaction amount in the local fiat currency. Always a number, not a string.
sellTokenAmount
Off-ramp only. The amount of crypto the user wants to sell. Pass either fiatAmount or sellTokenAmount when creating an off-ramp order — not both.
paymentMode
The payment rail for fiat deposits. Values are returned by the Supported Currencies API. Common values: INR_UPI (UPI), INR_IMPS (bank transfer).
UTR — Unique Transaction Reference
A 12–22 digit number assigned by the banking system to every bank transfer or UPI payment in India. After a user completes payment, the UTR must be submitted via POST /v1/orders/utr to link the payment to the Onmeta order.
transferredAmount
Human-readable amount of crypto transferred to the user's wallet (e.g., "0.01"). Returned in order status and webhook payloads.
transferredAmountWei
The same amount expressed in the smallest token unit — wei for ETH-based tokens (e.g., "10000000000000000" for 0.01 ETH). Use this for precise on-chain calculations.
Token & Chain Fields
chainId Numeric identifier for a blockchain network. Common values:
| chainId | Network |
|---|---|
1 | Ethereum Mainnet |
56 | BNB Smart Chain |
137 | Polygon |
42161 | Arbitrum One |
Use the Fetch Tokens API to get supported tokens per chain.
buyTokenSymbol / sellTokenSymbol
The ticker symbol of the token (e.g., "USDT", "USDC", "ETH").
buyTokenAddress / sellTokenAddress
The smart contract address of the token on the given chainId. Use the zero address 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee for native tokens (ETH, MATIC).
metaData
An optional key-value object you pass when creating an order. Onmeta stores it and echoes it back in all webhook events for that order alongside internal fields like conversionRate and commission. Use it to attach your own reference IDs, user tags, or session data.
"metaData": {
"yourOrderRef": "ORD-12345",
"userId": "usr_abc"
}
KYC & Compliance (INR only)
KYC — Know Your Customer Identity verification required for all users before they can place orders. Covers PAN card, Aadhaar, selfie, and address. Integrated via the Upload KYC API or the KYC Widget.
KYB — Know Your Business Business verification required for merchants. Submitted via the Onmeta Merchant Dashboard before production API access is granted.
Penny drop The bank account verification method Onmeta uses. A small test transaction is sent to the account to confirm it is active and retrieve the account holder name, which is then matched against the user's KYC name (Aadhaar/PAN).
Webhook
X-Onmeta-Signature
The HMAC-SHA256 signature Onmeta attaches to every webhook request header. Compute HMAC-SHA256(clientSecret, JSON.stringify(requestBody)) on your server and compare it to this header to verify authenticity.
eventType
Field in the webhook payload indicating the type of event. Value is always "onramp" for on-ramp webhooks and "offramp" for off-ramp webhooks.
Merchant Wallet
Merchant wallet A pre-funded wallet that Onmeta assigns to high-volume off-ramp merchants. Instead of users sending crypto directly, they send to the merchant's wallet. Onmeta settles INR from the pre-funded pool. Requires a dedicated wallet address provisioned by the Onmeta tech team — contact them before using the Load Merchant Wallet API.
Order Statuses
See the full Order Status Guide for what each status means, what to show the user, and what action to take.
On-ramp: fiatPending → fiatReceived → orderReceived → transferred → completed | expired | cancelled | fiatRefundInitiated → refunding → refunded
Off-ramp: cryptoInit → fiatPending → completed