README

Official PHP SDK for the WolvPay cryptocurrency payment API.

What is WolvPay?

WolvPay is a secure, low-fee cryptocurrency payment processor built for developers and businesses. It lets you accept payments in Bitcoin, Litecoin, USDT, USDC, and many other cryptocurrencies — either through a hosted payment page (zero front-end work) or a fully white-label flow where you control the entire UI.

This is the official PHP SDK. It wraps the WolvPay REST API so you can create and manage invoices, verify webhook signatures, and handle payment events with clean, typed PHP code — no boilerplate required.

API docs: wolvpay.com/docs
Dashboard: wolvpay.com/home
Discord: wolvpay.com/discord

Requirements

• PHP 8.0 or higher
• ext-curl
• ext-json

Installation

composer require wolvpay/wolvpay-php

Quick Start

<?php

require_once 'vendor/autoload.php';

use WolvPay\WolvPayClient;

$client = new WolvPayClient('your_api_key_here');

// Create a hosted invoice
$invoice = $client->createInvoice(50.00, 'USD', [
    'description'  => 'Order #1001',
    'white_label'  => false,
    'redirect_url' => 'https://example.com/thank-you',
]);

// Redirect customer to the payment page
header('Location: ' . $invoice['url']);

Configuration

Instantiate the client with your API key from the WolvPay Dashboard.

use WolvPay\WolvPayClient;

$client = new WolvPayClient(getenv('WOLVPAY_API_KEY'));

Security: Never hard-code your API key. Use environment variables or a secrets manager.

API Reference

Coins

getCoins()

Retrieve all supported cryptocurrencies and their current exchange rates.

$coins = $client->getCoins();

foreach ($coins as $coin) {
    echo $coin['name'] . ': $' . $coin['prices']['USD'] . PHP_EOL;
}

Returns: Array of coin objects.

Invoices

createInvoice(float $amount, string $currency = 'USD', array $options = [])

Create a new payment invoice.

// Hosted invoice (customer pays on WolvPay's page)
$invoice = $client->createInvoice(100.00, 'USD', [
    'description'  => 'Invoice for Order #1234',
    'white_label'  => false,
    'redirect_url' => 'https://example.com/thank-you',
]);

echo $invoice['url']; // https://invoices.wolvpay.com/INVabc123...

// White-label invoice with a pre-selected coin
$invoice = $client->createInvoice(100.00, 'EUR', [
    'coin'        => 'btc',
    'white_label' => true,
]);

echo $invoice['coin_address']; // Bitcoin address to display to the customer
echo $invoice['coin_amount'];  // Amount in BTC

Options:

getInvoice(string $invoiceId)

Retrieve a specific invoice by ID.

$invoice = $client->getInvoice('INVabc123def456');

echo $invoice['status'];       // AWAITING_PAYMENT
echo $invoice['coin_amount'];  // e.g. 0.00367
echo $invoice['coin_address']; // e.g. bc1q...

updateInvoice(string $invoiceId, string $coin)

Select a cryptocurrency for a white-label invoice that was created without one.

Only available when the invoice status is AWAITING_SELECTION.

$updated = $client->updateInvoice('INVabc123def456', 'ltc');

echo $updated['coin_address']; // LTC address to display
echo $updated['coin_amount'];  // LTC amount to pay

listInvoices(int $page = 1, int $limit = 3)

List all your invoices with pagination.

$result = $client->listInvoices(page: 1, limit: 3);

foreach ($result['invoices'] as $invoice) {
    echo $invoice['invoice_id'] . ' — ' . $invoice['status'] . PHP_EOL;
}

// Pagination info
$pagination = $result['pagination'];
echo 'Page ' . $pagination['current_page'] . ' of ' . $pagination['total_pages'];

Webhooks

WolvPay sends webhook events to your endpoint when an invoice status changes. All requests originate from IP 128.140.76.192.

Verifying the Signature

<?php

use WolvPay\Webhook;
use WolvPay\Exceptions\WebhookException;

// Read the raw body BEFORE any framework parsing.
$rawPayload = file_get_contents('php://input');
$headers    = getallheaders();

$signature = Webhook::extractSignature($headers);

try {
    $event = Webhook::verify($rawPayload, $signature, getenv('WOLVPAY_WEBHOOK_SECRET'));
} catch (WebhookException $e) {
    http_response_code(401);
    exit();
}

// $event is now the verified, decoded payload.
$invoiceId = $event['invoice_id'];
$status    = $event['status'];

Webhook Payload

{
    "invoice_id": "INVabc123def456",
    "amount": 100.00,
    "description": "Order #1234",
    "status": "PAID",
    "coin": "BTC",
    "coin_amount": 0.00367,
    "coin_received": 0.00367,
    "coin_address": "1A2b3C4d5E6F7g8H9i0J",
    "redirect_url": "https://example.com/thank-you",
    "created_at": "2025-01-01T12:00:00Z"
}

Handling Events

switch ($event['status']) {
    case 'PAID':
        fulfillOrder($event['invoice_id']);
        break;
    case 'CONFIRMING_PAYMENT':
        // Payment detected, awaiting confirmations.
        break;
    case 'UNDERPAID':
        // Customer sent less than required.
        break;
    case 'EXPIRED':
        markOrderExpired($event['invoice_id']);
        break;
}

http_response_code(200);

Error Handling

The SDK throws three exception types, all extending \RuntimeException:

use WolvPay\Exceptions\ApiException;
use WolvPay\Exceptions\WolvPayException;

try {
    $invoice = $client->createInvoice(10.00);
} catch (ApiException $e) {
    // HTTP error from the API
    echo $e->getCode();        // HTTP status code (e.g. 400, 401, 404)
    echo $e->getMessage();     // Human-readable message
    print_r($e->getErrorData()); // Raw error object from the API
} catch (WolvPayException $e) {
    // Network error, JSON parse error, etc.
    echo $e->getMessage();
}

Invoice Status Reference

Rate Limits

The API allows 100 requests per minute per API key. Exceeding this returns a 429 response. The SDK will throw an ApiException with code 429.

Track your usage with the response headers:

• X-RateLimit-Limit — Max requests per minute
• X-RateLimit-Remaining — Remaining requests this window
• X-RateLimit-Reset — UTC epoch when the window resets

Supported Fiat Currencies

USD, EUR, GBP, AUD, CAD, CHF, JPY, CNY, HKD, SGD, INR, BRL, MXN, NOK, SEK, DKK, PLN, CZK, HUF, RON, TRY, RUB, UAH, NGN, ZAR, and more.

See the full list in the WolvPay docs.

Examples

See the examples/ directory:

• create-invoice.php — Hosted invoice creation and retrieval
• white-label.php — White-label flow with coin selection
• webhook-handler.php — Webhook signature verification and event handling

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you'd like to change.

Links

• WolvPay Website
• API Documentation
• Dashboard
• Discord Community
• Report an Issue

License

MIT — see LICENSE.