W3

Web3 Paystack

Integration Guide

Accept crypto payments in 5 minutes. Zero blockchain knowledge required.

Quick Start - 3 Simple Steps
Get started in under 5 minutes
1

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).
2

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();
3

Redirect Customer

Send the user to the returned URL:

// Redirect user to payment page
window.location.href = widget_url;
Widget Customization
Customize the payment widget to match your brand

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!
Complete Code Examples
Full integration examples for popular frameworks

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']);
Frequently Asked Questions (QA)
Common questions about integrating Web3 Paystack

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 & Callback URLs - Complete Guide
Receive real-time payment notifications and redirect users appropriately

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

Payment Processing & Conversion Times
Understanding how crypto payments work

Conversion Times (Customer pays different token):

ScenarioProcessing TimeDetails
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
SideShift API - Production Only
Important information about the live API environment

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

Safe Testing Strategy:

Use the Try Widget page with small amounts:

  • Start with $1-2 for initial testing
  • Maximum $10 enforced for safety
  • Real payments but minimal risk
  • Settles to your actual wallet