Quickstart
Get started with Web3 Pay in under 5 minutes. This guide walks you through creating your first onramp session.
0Prerequisites
- A Web3 Pay account(Sign up here)
- API keys from your dashboard(Get keys)
- Connected wallet address for receiving payouts
1Get your API keys
Navigate to the API Keys section in your dashboard. You'll have two types of keys:
wp3_test_sk_...For development - no real payments
wp3_live_sk_...For production - real payments
Keep your secret keys safe
Never expose your secret keys in client-side code or commit them to version control.
2Create an onramp session
Make a POST request to create a new onramp session. Pass the recipient's wallet address where you want the crypto to be delivered. This returns a client secret you'll use to complete the payment.
Recipient Wallet Address
The wallet_address is where the purchased crypto gets sent after payment completes. This should be your user's wallet address.
-green-400">curl -X POST https://api.web3pay.io/v1/onramp \
-H "X-API-Key: wp3_test_sk_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f5fB",
"crypto_currency": "ETH",
"fiat_amount": 100,
"fiat_currency": "USD",
"network": "ethereum"
}'Response:
{
"success": true,
"data": {
"session_id": "onramp_sess_1234567890",
"client_secret": "onramp_cs_secret_abc123",
"redirect_url": "https://onramp.web3pay.io/s/abc123",
"expires_at": "2024-01-15T12:30:00Z",
"estimated_crypto_amount": "0.0412",
"fees": {
"platform_fee": 1.50,
"network_fee": 2.50,
"total_fee": 4.00
}
}
}3Complete the payment
You have two options to let your user complete the payment:
Redirect (Simplest)
Redirect your user to the hosted checkout page for a complete payment experience.
500">// Redirect to hosted checkout
window.location.href = session.data.redirect_url;Embedded Widget
Keep users on your site with our embeddable payment widget.
400">import { Web3Pay } 400">from 400">'@web3pay/sdk';
400">const client = 400">new Web3Pay({
apiKey: 400">'wp3_test_sk_your_api_key'
});
500">// Open the payment widget
client.openWidget(session.data.client_secret);
500">// Listen for completion
client.on(400">'success', (data) => {
console.log(400">'Payment complete!', data);
});4Handle the webhook
Set up a webhook endpoint to receive transaction status updates. Configure your webhook URL in the dashboard.
1500">// Express.js webhook handler2app.post(400">'/webhooks/web3pay', express.raw({400">type: 400">'application/json'}), (req, res) => {3 400">const signature = req.headers[400">'x-web3pay-signature'];4 400">const payload = req.body;5 6 500">// Verify signature (important!)7 400">const isValid = verifyWebhookSignature(payload, signature, webhookSecret);8 400">if (!isValid) {9 400">return res.status(400).send(400">'Invalid signature');10 }11 12 400">const event = JSON.parse(payload);13 14 400">switch (event.400">type) {15 400">case 400">'onramp.session.completed':16 console.log(400">'Crypto delivered!', event.data.tx_hash);17 500">// Update your database, notify user, etc.18 400">break;19 400">case 400">'onramp.session.failed':20 console.log(400">'Transaction failed:', event.data.session_id);21 400">break;22 }23 24 res.json({ received: 400">true });25});Test Cards
Use these test card numbers in test mode. Any future expiry and any 3-digit CVC works.
| Card Number | Result |
|---|---|
4242 4242 4242 4242 | Successful payment |
4000 0000 0000 0002 | Card declined |
4000 0000 0000 9995 | Insufficient funds |