Integration Guide
Accept crypto payments in 5 minutes. Zero blockchain knowledge required.
Get Your API Keys
Generate your keys from API Keys. You'll get:
- Secret Key (sk_...): Use on server-side to create payments.
- Public Key (pk_...): Use on client-side (optional).
Create Payment Session
Call our API from your backend:
const response = await fetch('https://pay.fogopulse.com/api/payment/initialize', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer ' + process.env.SECRET_KEY
},
body: JSON.stringify({
amount: 50.00,
currency: 'USD',
metadata: { order_id: '123' }
})
});
const { widget_url } = await response.json();Redirect Customer
Send the user to the returned URL:
// Redirect user to payment page window.location.href = widget_url;
Configure your widget branding in Settings to customize:
- Brand Logo: Your company logo displayed in the widget header
- Brand Color: Primary color for buttons and highlights
- Company URL: Link when users click your logo
// Widget automatically loads branding from your settings // Example: If you set brand color to #FF6B35, buttons will use that color // No additional configuration required!
React / Next.js
// app/api/create-payment/route.ts
import { NextResponse } from 'next/server';
export async function POST(request: Request) {
const { amount, currency } = await request.json();
const response = await fetch('https://pay.fogopulse.com/api/payment/initialize', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${process.env.WEB3_PAYSTACK_SECRET_KEY}`
},
body: JSON.stringify({ amount, currency })
});
return NextResponse.json(await response.json());
}
// components/PayButton.tsx
'use client';
export function PayButton({ amount }: { amount: number }) {
const handlePay = async () => {
const res = await fetch('/api/create-payment', {
method: 'POST',
body: JSON.stringify({ amount, currency: 'USD' })
});
const { widget_url } = await res.json();
window.location.href = widget_url;
};
return <button onClick={handlePay}>Pay with Crypto</button>;
}Python / Django
import requests
import os
def create_payment(amount, currency='USD'):
response = requests.post(
'https://pay.fogopulse.com/api/payment/initialize',
headers={
'Content-Type': 'application/json',
'Authorization': f'Bearer {os.getenv("WEB3_PAYSTACK_SECRET_KEY")}'
},
json={'amount': amount, 'currency': currency}
)
return response.json()
# In your view
def checkout(request):
payment = create_payment(100.00)
return redirect(payment['widget_url'])PHP
<?php
function createPayment($amount, $currency = 'USD') {
$ch = curl_init('https://pay.fogopulse.com/api/payment/initialize');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer ' . getenv('WEB3_PAYSTACK_SECRET_KEY')
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'amount' => $amount,
'currency' => $currency
]));
$response = curl_exec($ch);
curl_close($ch);
return json_decode($response, true);
}
// Usage
$payment = createPayment(100.00);
header('Location: ' . $payment['widget_url']);Q: How do I test the payment flow safely?
A: Use the Try Widget page in your dashboard. It uses real cryptocurrency but with strict $10 maximum limits. We recommend testing with $1-2 first.
Q: Where do I get my API keys?
A: Go to Dashboard → API Keys. You'll find your Secret Key (for server-side) and Public Key (for client-side). Never share your secret key publicly.
Q: How do I customize the payment widget?
A: Visit Dashboard → Settings and configure your brand logo, color, and company URL. Changes apply automatically to all payment widgets.
Q: Where do my funds go?
A: Set your settlement wallet in Settings. Funds go directly to your wallet (non-custodial). We never hold your funds.
Q: How do I track payments?
A: View all transactions in Dashboard → Transactions. Each payment includes blockchain explorer links for full transparency.
Q: How do I receive payment notifications?
A: Configure webhooks in Settings. We'll POST real-time payment updates to your server. See the Webhook section below for implementation details.
Q: What cryptocurrencies are supported?
A: We support 50+ cryptocurrencies across Bitcoin, Ethereum, Solana, BSC, and more. Customers can pay with any supported coin, and it's automatically converted to your preferred settlement token.
Q: How long do payments take?
A: Same-chain payments (ETH→USDC on Ethereum) take 3-5 minutes. Cross-chain swaps (BTC→USDC) take 15-45 minutes due to blockchain confirmations. Customers see real-time status updates.
Q: Are there any fees?
A: We charge a small affiliate commission (0.5% by default) built into the exchange rate. Customers also pay blockchain network fees (typically $1-3). No hidden fees.
Q: What if a customer sends the wrong amount?
A: Our widget requires customers to provide a refund address before generating the deposit address. If they send too little or too much, excess funds can be returned to their refund address.
- Webhook URL: Your server endpoint (e.g., https://yourdomain.com/api/webhooks/web3paystack) - We POST payment status here
- Success URL: Where to redirect customers after successful payment (e.g., https://yourdomain.com/payment/success?session_id={SESSION_ID})
- Cancel URL: Where to redirect if cancelled (e.g., https://yourdomain.com/payment/cancel)
Webhook Payload (POST to your webhook URL):
{
"event": "payment.completed",
"session_id": "sess_abc123",
"status": "completed",
"amount": "100.00",
"currency": "USD",
"customer_paid": "0.05 ETH",
"settled_amount": "100.00",
"settled_currency": "USDC",
"tx_hash": "0x742d35...",
"from_address": "0xabc123...",
"to_address": "0xdef456...",
"merchant_id": "your_merchant_id",
"timestamp": "2024-11-17T10:30:00Z"
}Events: payment.pending, payment.detected, payment.confirming, payment.completed, payment.failed
Verify Webhook Signature (REQUIRED for security):
const crypto = require('crypto');
app.post('/webhooks/web3paystack', (req, res) => {
// Get signature from header
const signature = req.headers['x-web3paystack-signature'];
const payload = JSON.stringify(req.body);
// Calculate expected signature
const expected = crypto
.createHmac('sha256', process.env.WEBHOOK_SECRET)
.update(payload)
.digest('hex');
// Verify signature matches
if (signature !== expected) {
console.error('Invalid webhook signature');
return res.status(401).send('Invalid signature');
}
// Process payment
const { event, session_id, status, settled_amount } = req.body;
if (event === 'payment.completed') {
// Update your database, send confirmation email, fulfill order, etc.
console.log(`Payment completed: ${session_id}`);
// Your business logic here...
}
res.status(200).send('OK');
});Callback URLs - How They Work:
Success URL:
After successful payment, customer is automatically redirected to your success URL with query parameter: ?session_id=sess_abc123
Example: https://yourdomain.com/payment/success?session_id=sess_abc123
Cancel URL:
If customer cancels or session expires, they're redirected here
Example: https://yourdomain.com/payment/cancel
- Complete widget_url for customers to pay
- Automatic token detection and conversion
- Real-time payment status updates
- Blockchain transaction details (tx_hash, confirmations, etc.)
- Automatic settlement to your wallet in preferred token
Conversion Times (Customer pays different token):
| Scenario | Processing Time | Details |
|---|---|---|
| ETH → BTC | 15-45 minutes | ETH needs 12 confirmations (~3 min), then swap happens, then BTC confirmations (10-40 min) |
| ETH → USDC (same chain) | 3-5 minutes | 12 ETH confirmations + instant swap on DEX |
| SOL → USDC | 1-2 minutes | Solana is very fast (400ms blocks) + quick swap |
| Same token (no conversion) | 1-3 minutes | Just blockchain confirmation time, no swap needed |
What This Means:
- All payments use real cryptocurrency on real blockchain networks
- Network fees are real and charged by the blockchain (typically $1-3)
- Settlements go to actual wallet addresses
- Transactions are visible on blockchain explorers