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.

Field	Type	Description
`coin`	string	Coin identifier used in API calls (e.g. `btc`, `ltc`)
`name`	string	Full name (e.g. "Bitcoin")
`logo`	string	URL path to the coin logo
`minimum_transaction_coin`	string	Minimum payable amount
`prices`	object	Exchange rates keyed by fiat currency code

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:

Parameter	Type	Required	Description
`coin`	string	No	Cryptocurrency code (e.g. `btc`, `ltc`, `erc20_usdt`). Omit to let the customer choose.
`description`	string	No	Description shown on the invoice.
`white_label`	bool	No	`true` = white-label flow, `false` = hosted page. Defaults to `true`.
`redirect_url`	string	No	URL to redirect the customer after payment.

`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:

Exception	When
`WolvPay\Exceptions\WolvPayException`	Base exception / network / parse errors
`WolvPay\Exceptions\ApiException`	API returned a 4xx or 5xx HTTP status
`WolvPay\Exceptions\WebhookException`	Webhook signature verification failed

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

Status	Description
`AWAITING_SELECTION`	Invoice created, customer has not selected a cryptocurrency.
`AWAITING_PAYMENT`	Cryptocurrency selected, waiting for payment.
`CONFIRMING_PAYMENT`	Payment detected, waiting for blockchain confirmations.
`PAID`	Payment confirmed and complete.
`UNDERPAID`	Payment received but less than required.
`EXPIRED`	Invoice expired without payment.

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.

License

MIT — see LICENSE.

wolvpay / wolvpay-php

Maintainers

Package info

Statistics

Security