Web3 Pay Logo
Docs/API/Onramp Sessions

Onramp Sessions

Create and manage fiat-to-crypto onramp sessions. Sessions handle the entire payment flow from card payment to crypto delivery.

POST

/v1/onramp

Create a new onramp session. Returns a client secret for completing the payment via redirect or embedded widget.

Request Body

wallet_addressstringrequired
Recipient's wallet address where the purchased crypto will be delivered. Must be a valid address for the specified blockchain network (e.g., 0x... for Ethereum/Polygon/Base).
crypto_currencystringrequired
The cryptocurrency to purchase. Supported: ETH, USDC, USDT, MATIC
fiat_amountnumberrequired
Amount in fiat currency (in smallest unit, e.g., cents). Must be between $10-$10,000.
fiat_currencystringrequired
Fiat currency code. Supported: USD, EUR, GBP
networkstring
Blockchain network. Defaults based on crypto_currency. Options: ethereum, polygon, base
customer_emailstring
Customer's email for receipt and KYC. Recommended for better conversion.
metadataobject
Arbitrary key-value pairs to attach to the session. Useful for tracking orders.

Example Request

bash
-green-400">curl -X POST https://api.web3pay.io/v1/onramp \
  -H "X-API-Key: wp3_live_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f5fB",
    "crypto_currency": "ETH",
    "fiat_amount": 10000,
    "fiat_currency": "USD",
    "network": "ethereum",
    "customer_email": "user@example.com",
    "metadata": {
      "order_id": "ord_12345",
      "user_id": "usr_67890"
    }
  }'

Response

json
{
  "success": true,
  "data": {
    "session_id": "onramp_sess_abc123xyz",
    "client_secret": "onramp_cs_secret_def456",
    "redirect_url": "https://onramp.web3pay.io/s/abc123xyz",
    "expires_at": "2024-01-15T12:30:00Z",
    "estimated_crypto_amount": "0.0412",
    "fees": {
      "platform_fee": 1.50,
      "network_fee": 2.50,
      "processing_fee": 2.90,
      "total_fee": 6.90
    },
    "exchange_rate": 2427.18,
    "quote_expires_at": "2024-01-15T12:05:00Z"
  }
}

Response Fields

session_idstring
Unique identifier for this session. Use for tracking and status queries.
client_secretstring
Secret for completing payment. Pass to SDK or redirect URL.
redirect_urlstring
URL to redirect user for hosted checkout experience.
expires_atstring
ISO 8601 timestamp when session expires (30 minutes from creation).
estimated_crypto_amountstring
Estimated crypto amount the user will receive.
feesobject
Breakdown of all fees applied to this transaction.
exchange_ratenumber
Exchange rate used for the quote (fiat per 1 crypto unit).
quote_expires_atstring
When the exchange rate quote expires (typically 5 minutes).
GET

/v1/onramp

Retrieve the current status and details of an onramp session.

Query Parameters

session_idstringrequired
The session ID returned when creating the session.

Example Request

bash
-green-400">curl https://api.web3pay.io/v1/onramp?session_id=onramp_sess_abc123xyz \
  -H "X-API-Key: wp3_live_sk_your_api_key"

Response

json
{
  "success": true,
  "data": {
    "id": "tx_789xyz",
    "session_id": "onramp_sess_abc123xyz",
    "status": "completed",
    "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f5fB",
    "crypto_currency": "ETH",
    "crypto_amount": "0.0408",
    "fiat_currency": "USD",
    "fiat_amount": 10000,
    "network": "ethereum",
    "tx_hash": "0x1234567890abcdef...",
    "fees": {
      "platform_fee": 1.50,
      "network_fee": 2.50,
      "processing_fee": 2.90
    },
    "metadata": {
      "order_id": "ord_12345",
      "user_id": "usr_67890"
    },
    "created_at": "2024-01-15T12:00:00Z",
    "completed_at": "2024-01-15T12:08:00Z"
  }
}

Session Statuses

StatusDescription
pendingSession created, awaiting payment
processingPayment received, crypto transfer in progress
completedCrypto delivered to wallet
failedPayment or delivery failed
expiredSession expired before payment
POST

/v1/onramp/quote

Get a price quote without creating a session. Useful for showing estimated amounts before user commits.

bash
-green-400">curl -X POST https://api.web3pay.io/v1/onramp/quote \
  -H "X-API-Key: wp3_live_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "fiat_amount": 10000,
    "fiat_currency": "USD",
    "crypto_currency": "ETH",
    "network": "ethereum"
  }'
json
{
  "success": true,
  "data": {
    "fiat_amount": 10000,
    "fiat_currency": "USD",
    "crypto_currency": "ETH",
    "crypto_amount": "0.0412",
    "exchange_rate": 2427.18,
    "fees": {
      "platform_fee": 1.50,
      "network_fee": 2.50,
      "processing_fee": 2.90,
      "total_fee": 6.90
    },
    "expires_at": "2024-01-15T12:05:00Z"
  }
}

SDK Examples

JavaScript

javascript
400">import { Web3Pay } 400">from 400">'@web3pay/sdk';

400">const client = 400">new Web3Pay({
  apiKey: 400">'wp3_live_sk_your_api_key'
});

500">// Create session
400">const session = 400">await client.createSession({
  walletAddress: 400">'0x742d35Cc6634C0532925a3b844Bc9e7595f5fB',
  cryptoCurrency: 400">'ETH',
  fiatAmount: 10000,
  fiatCurrency: 400">'USD',
  metadata: { orderId: 400">'ord_12345' }
});

500">// Get session status
400">const status = 400">await client.getSession(session.session_id);
console.log(status.status); 500">// 400">'pending' | 400">'processing' | 400">'completed' | 400">'failed'

Python

python
400">import requests

headers = {
    400">&500">#039;X-API-Key': 400">'wp3_live_sk_your_api_key',
    400">&500">#039;Content-Type': 400">'application/json'
}

500"># Create session
response = requests.post(
    400">&500">#039;https://api.web3pay.io/v1/onramp',
    headers=headers,
    json={
        400">&500">#039;wallet_address': 400">'0x742d35Cc6634C0532925a3b844Bc9e7595f5fB',
        400">&500">#039;crypto_currency': 400">'ETH',
        400">&500">#039;fiat_amount': 10000,
        400">&500">#039;fiat_currency': 400">'USD'
    }
)

session = response.json()
print(session[400">&500">#039;data'][400">'redirect_url'])
Back to home
Was this page helpful?