# Get Ramp Intent Retrieve the full details of a ramp intent, including the generated widget URL for embedding. This endpoint also manages automatic status transitions — the intent moves from `created` to `active` on the first GET request, and auto-expires if past its `expiresAt` timestamp. ## Request ### Headers :::note Public Endpoint This endpoint does not require authentication headers. It is designed to be called from your frontend or checkout page. ::: ### Path Parameters ## Response ### Success (200 OK) ```json { "success": true, "data": { "intent": { "intentId": "ri_1710345678000_a1b2c3d4e5f6g7h8", "type": "buy", "fiatCurrency": "USD", "cryptoCurrency": "eth_ethereum", "amount": 100, "status": "active", "kycStatus": "approved", "cancelReason": null, "wallets": [ { "network": "ethereum", "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28" } ], "userId": "usr_abc123", "kycVerified": true, "successUrl": "https://yourapp.com/success", "cancelUrl": "https://yourapp.com/cancel", "expiresAt": "2026-03-15T10:00:00.000Z", "metadata": {} }, "widgetUrl": "https://widget.onramper.com/...signed_url..." }, "message": "Ramp intent retrieved" } ``` ### Response Fields #### Intent Object #### Root Fields ### KYC Gating The response shape depends on the user's KYC status: **Scenario 1: KYC pre-verified by merchant** (`kycVerified: true` on the intent) Widget URL is returned immediately. No KYC prompts. **Scenario 2: KYC verified via ZenPays** (`kycVerified: false`, user already verified) Widget URL is returned. `kycRequired` is absent or `false`. **Scenario 3: KYC required** (`kycVerified: false`, user not verified) `widgetUrl` is `null`, `kycRequired` is `true`. If a verification session exists, `kycVerificationUrl` contains the URL. If not, call [`initiateKyc`](/docs/api-reference/ramp-intents#initiatekyc) (or the equivalent REST endpoint) to create a session. ```json { "success": true, "data": { "intent": { "intentId": "ri_1710345678000_a1b2c3d4e5f6g7h8", "type": "sell", "fiatCurrency": "INR", "status": "active", "wallets": [{ "network": "ethereum", "address": "0x742d..." }], "userId": "usr_abc123", "kycVerified": false, "expiresAt": "2026-03-15T10:00:00.000Z" }, "widgetUrl": null, "kycRequired": true, "kycVerificationUrl": "https://verify.zenpayz.com/session/abc123" }, "message": "Ramp intent retrieved" } ``` ### Automatic Behaviors | Condition | Action | |-----------|--------| | Intent status is `created` | Auto-transitions to `active` on first GET | | `expiresAt` has passed | Auto-transitions to `expired`, returns `widgetUrl: null` | | Widget URL not yet cached | Generates and caches the widget URL | | Intent in `awaiting_payout` phase | Skips widget URL generation (sell flow Phase 2) | ### Error Responses ## Examples ```bash curl https://api.zenpayz.com/payment/api/v1/ramp-intents/ri_1710345678000_a1b2c3d4e5f6g7h8 ``` ```javascript const intentId = 'ri_1710345678000_a1b2c3d4e5f6g7h8'; const response = await fetch( `https://api.zenpayz.com/payment/api/v1/ramp-intents/${intentId}` ); const { data } = await response.json(); const { intent, widgetUrl } = data; if (intent.status === 'expired') { console.log('Intent has expired — create a new one'); } else if (widgetUrl) { // Embed in an iframe const iframe = document.createElement('iframe'); iframe.src = widgetUrl; iframe.style.width = '100%'; iframe.style.height = '600px'; iframe.style.border = 'none'; document.getElementById('widget-container').appendChild(iframe); } ``` ```python import requests intent_id = "ri_1710345678000_a1b2c3d4e5f6g7h8" response = requests.get( f"https://api.zenpayz.com/payment/api/v1/ramp-intents/{intent_id}" ) data = response.json()["data"] intent = data["intent"] widget_url = data["widgetUrl"] print(f"Status: {intent['status']}") print(f"Type: {intent['type']}") if intent["status"] == "expired": print("Intent has expired — create a new one") elif widget_url: print(f"Widget URL: {widget_url}") ``` ## Next Steps - [Create Ramp Intent](/docs/rest-api/endpoints/ramp/create-ramp-intent) — Create a new ramp intent - [Update Ramp Intent Status](/docs/rest-api/endpoints/ramp/update-ramp-intent-status) — Manually transition status - [Widget URL](/docs/rest-api/endpoints/ramp/widget-url) — Alternative widget URL generation - [On-Ramp Flow](/docs/examples/on-ramp-flow) — Complete buy integration guide