WolvPay API Documentation

Welcome to the WolvPay API documentation. Our API enables you to seamlessly integrate cryptocurrency invoicing into your business with a secure, low-fee payment processor.

Base URL

https://wolvpay.com/api/v1

Response Format

application/json

Authentication

Bearer <api_key>

Authentication

The WolvPay API uses API keys to authenticate requests. You can view and manage your API keys in the WolvPay Dashboard.

Your API keys carry many privileges — keep them secure. Do not share secret keys in publicly accessible areas such as GitHub or client-side code.

Add the following header to every authenticated request:

Authorization: Bearer <your-api-key>

Coins

The Coins API lets you retrieve information about supported cryptocurrencies and their current prices.

Get Supported Coins

Retrieves a list of all supported cryptocurrencies and their details.

GET /api/v1/coins

Response

{
  "success": true,
  "result": "Coins retrieved successfully",
  "code": 200,
  "data": [
    {
      "coin": "btc",
      "name": "Bitcoin",
      "logo": "assets/images/coins/btc.png",
      "minimum_transaction_coin": "0.000080000000000000",
      "prices": {
        "EUR": "93057.5144720163",
        "USD": "105649.8096322775"
        // ....
      }
    },
    {
      "coin": "ltc",
      "name": "Litecoin",
      "logo": "assets/images/coins/ltc.png",
      "minimum_transaction_coin": "0.002000000000000000",
      "prices": {
        "EUR": "77.8529331455",
        "USD": "88.3877848318"
        // ....
      }
    }
    // ....
  ]
}

{
  "success": false,
  "error": "Not Found",
  "code": 404,
  "message": "No coins found."
}

Response Parameters

Parameter	Type	Description
success	boolean	Indicates whether the request was successful.
result	string	A descriptive message about the operation result.
code	number	HTTP status code of the response.
data	array	Array of supported cryptocurrency objects.
data[].coin	string	Unique identifier for the cryptocurrency (used in API calls).
data[].name	string	Full name of the cryptocurrency.
data[].logo	string	URL path to the cryptocurrency logo image.
data[].minimum_transaction_coin	string	Minimum payable amount in this cryptocurrency.
data[].prices	object	Object containing current exchange rates for fiat currencies.
data[].prices.[currency]	string	Current price of the coin in the specified fiat currency.

Invoices

The Invoices API allows you to create, retrieve, and manage cryptocurrency invoices.

Create an Invoice

Creates a new payment invoice that customers can use to pay with cryptocurrency.

Note: Data must be sent as JSON in the request body, not as form data.

POST /api/v1/invoices

Request Parameters

Parameter	Type	Required	Description
amount	number	Yes	The payment amount in the specified currency.
currency	string	No	Currency code (e.g. USD, EUR). Defaults to USD. See Supported Currencies.
coin	string	No	Cryptocurrency to accept (e.g. btc, ltc, erc20_usdc). If omitted, status becomes AWAITING_SELECTION and available_coins is returned.
description	string	No	A description of the payment.
white_label	boolean	No	Whether to use the white-label flow. Defaults to true.
redirect_url	string	No	URL to redirect the customer after payment is completed.

{
  "amount": 100.00,
  "currency": "USD",
  "coin": "ltc",
  "description": "Invoice for Order #1234",
  "white_label": false,
  "redirect_url": "https://example.com/thank-you"
}

$url  = 'https://wolvpay.com/api/v1/invoices';
$data = json_encode([
    'amount'   => (float) $amount,
    'coin'     => $payment_method, // Optional
    'currency' => 'EUR',           // Optional
]);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $data,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'Authorization: Bearer <YOUR_API_KEY>',
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$json = json_decode($response, true);

Response Parameters

Parameter	Type	Description
success	boolean	Indicates whether the request was successful.
result	string	A descriptive message about the operation result.
code	number	HTTP status code of the response.
data	object	Contains the invoice data object.
data.invoice_id	string	Unique identifier for the created invoice.
data.url	string	Hosted payment page URL (hosted invoices only).
data.amount	number	Payment amount in the specified fiat currency.
data.description	string	Payment description (null if not provided).
data.status	string	Current invoice status. See Invoice Status section.
data.coin	string	Selected cryptocurrency code (white-label only).
data.coin_amount	number	Amount to pay in the selected cryptocurrency.
data.coin_address	string	Address where payment should be sent.
data.redirect_url	string	Post-payment redirect URL (null if not provided).
data.created_at	string	Invoice creation timestamp.
data.expires_at	string	Invoice expiry timestamp.

{
  "success": true,
  "result": "Invoice created successfully with selected cryptocurrency",
  "code": 201,
  "data": {
    "invoice_id": "INVabc123def456",
    "url": "https://invoices.wolvpay.com/INVabc123def456",
    "status": "AWAITING_PAYMENT"
  }
}

{
  "success": true,
  "result": "Invoice created successfully with selected cryptocurrency",
  "code": 201,
  "data": {
    "invoice_id": "INVabc123def456",
    "amount": 100,
    "description": null,
    "status": "AWAITING_PAYMENT",
    "coin": "ltc",
    "coin_amount": 0.0167,
    "coin_address": "MQvWK1vphyfV1F6",
    "redirect_url": null,
    "created_at": "2025-06-01 15:24:48",
    "expires_at": "2025-06-02 15:24:48"
  }
}

{
  "success": false,
  "error": "Bad Request",
  "code": 400,
  "message": "The provided cryptocurrency code is not supported or not enabled."
}

Retrieve an Invoice

Retrieves the details of an existing invoice.

GET /api/v1/invoices/{invoice_id}

Path Parameters

Parameter	Type	Required	Description
invoice_id	string	Yes	The ID of the invoice to retrieve.

{
  "success": true,
  "result": "Invoice retrieved successfully",
  "code": 200,
  "data": {
    "invoice_id": "INV_abc123def456",
    "amount": 100,
    "description": null,
    "status": "AWAITING_SELECTION",
    "coin": null,
    "coin_amount": null,
    "coin_received": 0,
    "coin_address": null,
    "redirect_url": null,
    "created_at": "2025-06-01 17:51:12",
    "expires_at": "2025-06-02 17:51:12",
    "available_coins": [
      "bch", "btc", "ltc", "bep20_usdc", "bep20_usdt",
      "eth", "sol_sol", "doge", "polygon_pol", "trx",
      "erc20_usdc", "polygon_usdc", "sol_usdc",
      "erc20_usdt", "polygon_usdt", "sol_usdt", "trc20_usdt"
    ]
  }
}

{
  "success": true,
  "result": "Invoice retrieved successfully",
  "code": 200,
  "data": {
    "invoice_id": "INV_abc123def456",
    "amount": 100.00,
    "description": "Invoice for Order #1234",
    "status": "PAID",
    "coin": "btc",
    "coin_amount": 0.00234567,
    "coin_received": 0.00234567,
    "coin_address": "MQvWK1vphyfV1F6",
    "redirect_url": "https://example.com/thank-you",
    "created_at": "2024-01-15 10:30:00",
    "expires_at": "2024-01-16 10:30:00"
  }
}

{
  "success": true,
  "result": "Invoice retrieved successfully",
  "code": 200,
  "data": {
    "invoice_id": "INV_abc123def456",
    "url": "https://invoices.wolvpay.com/INV_abc123def456",
    "status": "AWAITING_PAYMENT"
  }
}

{
  "success": false,
  "error": "Not Found",
  "code": 404,
  "message": "Invoice not found."
}

Update an Invoice

Updates an existing invoice by selecting a cryptocurrency. Used when an invoice was created without specifying a coin and the customer needs to choose one.

Note: This endpoint is only available for white-label invoices created without a coin. If a coin is already selected the invoice cannot be updated. For hosted invoices, coin selection happens on the hosted invoice page.

POST /api/v1/invoices/{invoice_id}

Path Parameters

Parameter	Type	Required	Description
invoice_id	string	Yes	The ID of the invoice to update.

Request Parameters

Parameter	Type	Required	Description
coin	string	Yes	Cryptocurrency code to use for payment (e.g. btc, ltc, erc20_usdc). See Supported Currencies.

{
  "coin": "btc"
}

Response

{
  "success": true,
  "result": "Coin selected successfully for invoice",
  "code": 200,
  "data": {
    "invoice_id": "INV_abc123def456",
    "amount": 100,
    "description": null,
    "status": "AWAITING_PAYMENT",
    "coin": "ltc",
    "coin_amount": 1.1345586566825505,
    "coin_address": "MQvWK1vphyfV1F6",
    "redirect_url": null,
    "updated_at": "2025-06-01 18:19:56"
  }
}

{
  "success": false,
  "error": "Bad Request",
  "code": 400,
  "message": "Missing required parameter: coin"
}

List All Invoices

Returns a paginated list of invoices you have previously created.

GET /api/v1/invoices

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number to retrieve. Defaults to 1.
limit	integer	No	Invoices per page. Default and maximum is 3.

{
  "success": true,
  "result": "Transactions retrieved successfully",
  "code": 200,
  "data": {
    "invoices": [
      {
        "invoice_id": "INV_abc123def456",
        "amount": "100.00",
        "description": null,
        "status": "AWAITING_PAYMENT",
        "coin": "ltc",
        "coin_amount": "1.1345586566826",
        "coin_address": "MQvWK1vphyfV1F6",
        "fee_amount_coin": "0.02269117",
        "fee_amount_usd": "2.00",
        "apply_fee": 0,
        "white_label": 1,
        "redirect_url": null,
        "created_at": "2025-06-01 18:18:56",
        "updated_at": "2025-06-01 18:19:56"
      }
      // ....
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 3,
      "total_items": 59,
      "total_pages": 20,
      "has_next": true,
      "has_previous": false,
      "next_page": 2,
      "previous_page": null
    }
  }
}

Webhooks

WolvPay uses webhooks to notify your application when an event occurs, such as an invoice being completed. Use these notifications to trigger backend actions like updating a database or sending confirmation emails.

Webhook Origin IP: All webhook requests originate from 128.140.76.192. You can whitelist this IP address on your server or firewall to ensure webhook deliveries are accepted.

Webhook Security

WolvPay signs every webhook request using your webhook secret. The signature is sent in the X-WolvPay-Signature HTTP header. Compute the HMAC-SHA256 hash of the raw request body with your secret and compare it against the received signature to verify authenticity.

Note: The header is sent as X-WolvPay-Signature but your server may normalise it to lower- or upper-case. Check your server's raw headers to confirm how it arrives.

$rawPayload = file_get_contents('php://input');
$headers    = getallheaders();
$signature  = $headers['X-WolvPay-Signature'] ?? '';

$computedSignature = hash_hmac('sha256', $rawPayload, 'your_webhook_secret');

if (!hash_equals($computedSignature, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

$data = json_decode($rawPayload, true);
// Process $data

const crypto     = require('crypto');
const express    = require('express');
const bodyParser = require('body-parser');

const app           = express();
const webhookSecret = 'your_webhook_secret';

app.use(bodyParser.raw({ type: 'application/json' }));

app.post('/webhooks/wolvpay', (req, res) => {
  const signature = req.headers['x-wolvpay-signature'];
  const expected  = crypto
    .createHmac('sha256', webhookSecret)
    .update(req.body)
    .digest('hex');

  if (crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    const data = JSON.parse(req.body.toString());
    // Process data
    res.sendStatus(200);
  } else {
    res.status(400).send('Invalid signature');
  }
});

import hmac
import hashlib
from flask import Flask, request, abort

app            = Flask(__name__)
webhook_secret = 'your_webhook_secret'

@app.route('/webhooks/wolvpay', methods=['POST'])
def handle_webhook():
    signature   = request.headers.get('X-WolvPay-Signature')
    raw_payload = request.get_data()

    expected = hmac.new(
        webhook_secret.encode(),
        raw_payload,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        abort(400, 'Invalid signature')

    data = request.get_json()
    # Process data
    return 'OK', 200

Webhook Payload

WolvPay will POST the following JSON structure to your endpoint on payment events:

{
  "invoice_id": "inv_4e5a2b3c",
  "amount": 100.00,
  "description": "Invoice for 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": "2023-09-15T14:30:00Z"
}

Currencies

WolvPay supports multiple cryptocurrencies and fiat currencies.

Supported Fiat Currencies

All invoice amounts can be specified in the following fiat currencies. Amounts are automatically converted to the equivalent cryptocurrency value at the time of invoice creation.

Currency Name	Currency Code
United Arab Emirates Dirham	`AED`
Australian Dollar	`AUD`
Bulgarian Lev	`BGN`
Brazilian Real	`BRL`
Canadian Dollar	`CAD`
Swiss Franc	`CHF`
Chinese Yuan	`CNY`
Czech Koruna	`COP`
Colombian Peso	`CZK`
Danish Krone	`DKK`
Euro	`EUR`
British Pound Sterling	`GBP`
Hong Kong Dollar	`HKD`
Hungarian Forint	`HUF`
Indonesian Rupiah	`IDR`
Indian Rupee	`INR`
Japanese Yen	`JPY`
Sri Lankan Rupee	`LKR`
Mexican Peso	`MXN`
Malaysian Ringgit	`MYR`
Nigerian Naira	`NGN`
Norwegian Krone	`NOK`
Philippine Peso	`PHP`
Polish Zloty	`PLN`
Romanian Leu	`RON`
Russian Ruble	`RUB`
Swedish Krona	`SEK`
Singapore Dollar	`SGD`
Thai Baht	`THB`
Turkish Lira	`TRY`
Taiwan Dollar	`TWD`
Ukrainian Hryvnia	`UAH`
Ugandan Shilling	`UGX`
US Dollar	`USD`
Vietnamese Dong	`VND`
South African Rand	`ZAR`

Invoice Status Values

Invoices transition through the following status values during their lifecycle:

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

Errors

WolvPay uses conventional HTTP response codes to indicate whether an API request succeeded or failed.

Code	Description
200 - OK	Everything worked as expected.
400 - Bad Request	The request was unacceptable, often due to a missing required parameter.
401 - Unauthorized	No valid API key provided.
402 - Request Failed	Parameters were valid but the request failed.
404 - Not Found	The requested resource does not exist.
429 - Too Many Requests	Too many requests hit the API too quickly.
500, 502, 503, 504 - Server	Something went wrong on WolvPay's end.

Error Response Format

{
  "error": {
    "type": "invalid_request_error",
    "message": "Missing required parameter: amount",
    "code": "missing_parameter",
    "param": "amount"
  }
}

Rate Limits

The WolvPay API enforces rate limits to maintain reliable service for all users.

The current limit is 100 requests per minute per API key. Exceeding this limit returns a 429 Too Many Requests response.

The following response headers help you track your rate limit usage:

Header	Description
`X-RateLimit-Limit`	The maximum number of requests permitted per minute.
`X-RateLimit-Remaining`	Requests remaining in the current rate limit window.
`X-RateLimit-Reset`	Time at which the current window resets (UTC epoch seconds).