# Create Ramp Intent Create a standalone ramp intent for on-ramp (buy crypto) or off-ramp (sell crypto). A ramp intent represents a merchant-initiated ramp session that tracks the full lifecycle of a transaction — from creation through to completion or expiry. ## Request ### Headers :::caution Authenticated Endpoint This endpoint requires API key authentication. Include your API key in the `Authorization` header and your merchant ID in `x-merchant-id`. ::: ### Body Parameters :::tip KYC Behavior When `kycVerified: true`, the checkout widget skips ZenPays KYC verification entirely — use this when your platform has already verified the user's identity. When `kycVerified: false` (default), the widget checks the user's KYC status. If unverified, the customer is prompted to complete identity verification before proceeding. ::: ### Wallet Object ### Sample Request Body ```json { "userId": "usr_abc123", "kycVerified": false, "type": "buy", "wallets": [ { "network": "ethereum", "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28" } ], "fiatCurrency": "USD", "cryptoCurrency": "eth_ethereum", "amount": 100, "successUrl": "https://yourapp.com/success", "cancelUrl": "https://yourapp.com/cancel", "customerEmail": "customer@example.com", "metadata": { "orderId": "order_123" } } ``` ## Response ### Success (201 Created) ```json { "success": true, "data": { "intentId": "ri_1710345678000_a1b2c3d4e5f6g7h8", "redirectUrl": "https://checkout.zenpayz.com/payments/ramping/widget/ri_1710345678000_a1b2c3d4e5f6g7h8", "expiresAt": "2026-03-15T10:00:00.000Z" }, "message": "Ramp intent created" } ``` ### Response Fields :::info Intent Expiry Ramp intents automatically expire **1 hour** after creation. Once expired, the intent cannot be used and a new one must be created. ::: ### Error Responses ## Examples ```bash curl -X POST https://api.zenpayz.com/payment/api/v1/ramp-intents \ -H "Content-Type: application/json" \ -H "Authorization: Bearer zp_test_your_api_key" \ -H "x-merchant-id: merch_abc123" \ -H "x-request-id: req_$(date +%s)" \ -d '{ "userId": "usr_abc123", "kycVerified": false, "type": "buy", "wallets": [ { "network": "ethereum", "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28" } ], "fiatCurrency": "USD", "cryptoCurrency": "eth_ethereum", "amount": 100, "customerEmail": "customer@example.com", "successUrl": "https://yourapp.com/success", "cancelUrl": "https://yourapp.com/cancel" }' ``` ```javascript const response = await fetch('https://api.zenpayz.com/payment/api/v1/ramp-intents', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer zp_test_your_api_key', 'x-merchant-id': 'merch_abc123', 'x-request-id': `req_${Date.now()}`, }, body: JSON.stringify({ userId: 'usr_abc123', kycVerified: false, type: 'buy', wallets: [ { network: 'ethereum', address: '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28' }, ], fiatCurrency: 'USD', cryptoCurrency: 'eth_ethereum', amount: 100, customerEmail: 'customer@example.com', successUrl: 'https://yourapp.com/success', cancelUrl: 'https://yourapp.com/cancel', }), }); const { data } = await response.json(); console.log(`Intent ID: ${data.intentId}`); console.log(`Redirect to: ${data.redirectUrl}`); console.log(`Expires at: ${data.expiresAt}`); // Redirect the customer to the ramp widget window.location.href = data.redirectUrl; ``` ```python import requests import time response = requests.post( "https://api.zenpayz.com/payment/api/v1/ramp-intents", headers={ "Authorization": "Bearer zp_test_your_api_key", "x-merchant-id": "merch_abc123", "x-request-id": f"req_{int(time.time())}", }, json={ "userId": "usr_abc123", "kycVerified": False, "type": "buy", "wallets": [ {"network": "ethereum", "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28"} ], "fiatCurrency": "USD", "cryptoCurrency": "eth_ethereum", "amount": 100, "customerEmail": "customer@example.com", "successUrl": "https://yourapp.com/success", "cancelUrl": "https://yourapp.com/cancel", }, ) data = response.json()["data"] print(f"Intent ID: {data['intentId']}") print(f"Redirect to: {data['redirectUrl']}") print(f"Expires at: {data['expiresAt']}") ``` ## Intent Status Lifecycle ``` ┌──────────┐ │ created │ ← Initial state └────┬─────┘ │ First GET request │ ┌────▼─────┐ ┌────│ active │────┐ │ └────┬─────┘ │ │ │ │ ┌────▼────┐ ┌──▼───────┐ ┌▼──────────┐ │cancelled│ │completed │ │ expired │ └─────────┘ └──────────┘ └────────────┘ (terminal states) ``` ## Webhook Events When a ramp intent reaches a terminal state, ZenPay delivers a webhook to your configured endpoint. Configure webhooks in the merchant dashboard under **Developer Tools → Webhooks**. ### Events | Event | When | Description | |-------|------|-------------| | `ramp.completed` | Buy: crypto sent to wallet. Sell: fiat payout submitted. | The ramp flow finished successfully. | | `ramp.failed` | Crypto send or payout submission failed. | The ramp flow encountered an error. | ### Buy Ramp Completed (`ramp.completed`) Delivered when crypto has been sent to the customer's wallet address. ```json { "event_type": "ramp.completed", "payment_data": { "merchant_id": "m_abc123", "intentId": "ri_1710345678000_a1b2c3d4e5f6g7h8", "type": "buy", "status": "completed", "fiatCurrency": "USD", "cryptoCurrency": "eth_ethereum", "amount": 100, "chain": "ethereum", "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28", "fireblocksTxId": "fb_tx_9a8b7c6d5e4f", "completedAt": "2026-03-16T14:30:00.000Z" } } ``` ### Sell Ramp Completed (`ramp.completed`) Delivered when the fiat payout has been submitted to the customer's bank account. ```json { "event_type": "ramp.completed", "payment_data": { "merchant_id": "m_abc123", "intentId": "ri_1710345678000_a1b2c3d4e5f6g7h8", "type": "sell", "status": "completed", "fiatCurrency": "USD", "cryptoCurrency": "usdt_tron", "amount": 20, "payoutId": "po_xyz789", "payoutAmount": 19.50, "payoutCurrency": "USD", "completedAt": "2026-03-16T14:30:00.000Z" } } ``` ### Ramp Failed (`ramp.failed`) Delivered when the crypto send (buy) or payout submission (sell) fails. ```json { "event_type": "ramp.failed", "payment_data": { "merchant_id": "m_abc123", "intentId": "ri_1710345678000_a1b2c3d4e5f6g7h8", "type": "buy", "status": "failed", "fiatCurrency": "USD", "cryptoCurrency": "eth_ethereum", "amount": 100, "reason": "Crypto send failed", "failedAt": "2026-03-16T14:30:00.000Z" } } ``` ### Webhook Payload Fields ### Webhook Headers | Header | Description | |--------|-------------| | `X-ZenPay-Signature` | HMAC-SHA256 signature of the request body | | `X-Zenpay-Event` | Event type (e.g. `ramp.completed`) | | `X-Zenpay-Event-Id` | Unique delivery ID for deduplication | | `X-Zenpay-Timestamp` | ISO 8601 timestamp of delivery | | `X-Zenpay-Attempt` | Delivery attempt number (1, 2, or 3) | See the [Webhooks guide](/docs/guides/webhooks) for signature verification, retry behavior, and best practices. ## Next Steps - [Get Ramp Intent](/docs/rest-api/endpoints/ramp/get-ramp-intent) — Retrieve intent details and widget URL - [List Ramp Intents](/docs/rest-api/endpoints/ramp/list-ramp-intents) — Browse intent history - [On-Ramp Flow](/docs/examples/on-ramp-flow) — Complete buy integration guide - [Off-Ramp Flow](/docs/examples/off-ramp-flow) — Complete sell integration guide