Dashboard

WolvPay API Documentation

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

Base URL

https://wolvpay.com/api/v1

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, so be sure to keep them secure. Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, etc.

Add the following header to your requests to authenticate: 

Authorization: Bearer <your-api-key>

Coins

The Coins API allows you to retrieve information about supported cryptocurrencies and their details.

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 amount that can be paid in this cryptocurrency.
data[].prices object Object containing current exchange rates for various fiat currencies.
data[].prices.[currency] string Current price of the cryptocurrency in the specified fiat currency.

Invoices

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

Create an Invoice

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

POST /api/v1/invoices

Request Parameters

Parameter Type Required Description
amount number Yes The payment amount in the specified currency.
currency string No The currency code (e.g., USD, EUR). Defaults to USD. Read the Supported Currencies section for available options.
coin string No The cryptocurrency to accept (e.g., btc, ltc, erc20_usdc). Read the Supported Currencies section for available options. If not provided, invoice will stay on AWAITING_PAYMENT status and append available_coins array to the response. Refer to the Invoice Status section for more details.
description string No A description of the payment.
white_label boolean No Whether the invoice is for a white-label solution. Defaults to true.
redirect_url string No URL to redirect 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"
}

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 with all relevant information.
data.invoice_id string Unique identifier for the created invoice.
data.url string Hosted payment page URL (only for hosted invoices).
data.amount number The payment amount in the specified fiat currency.
data.description string Description of the payment (null if not provided).
data.status string Current status of the invoice. Refer to the Invoice Status section for possible values.
data.coin string Selected cryptocurrency code (only for white-label invoices).
data.coin_amount number Amount to be paid in the selected cryptocurrency.
data.coin_address string Cryptocurrency address where payment should be sent.
data.redirect_url string URL to redirect after payment completion (null if not provided).
data.created_at string Timestamp when the invoice was created.
data.expires_at string Timestamp when the invoice expires. 
{
  "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,
  "message": "Invoice retrieved successfully",
  "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",
    "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",
    "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. This is used when an invoice was created without specifying a coin and the customer needs to select one.

Note: This endpoint is only available for white-label invoices that were created without a coin. If the invoice already has a coin selected, you cannot update it. For hosted invoices, the coin must be selected 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 The cryptocurrency code to use for payment (e.g., btc, ltc, erc20_usdc). Read the Supported Currencies section for available options. 
{
  "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 list of invoices you've previously created with pagination.

GET /api/v1/invoices

Query Parameters

Parameter Type Required Description
page integer No The page number to retrieve. Default is 1.
limit integer No Number of invoices per page. Default is 3, 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"
      },
      {
        "invoice_id": "INV_abc123def456",
        "amount": "100.00",
        "description": null,
        "status": "AWAITING_SELECTION",
        "coin": null,
        "coin_amount": null,
        "coin_address": null,
        "fee_amount_coin": "0.00000000",
        "fee_amount_usd": "0.00",
        "apply_fee": 0,
        "white_label": 0,
        "redirect_url": null,
        "created_at": "2025-06-01 18:18:51",
        "updated_at": null
      },
      {
        "invoice_id": "INV_abc123def456",
        "amount": "100.00",
        "description": null,
        "status": "AWAITING_PAYMENT",
        "coin": "btc",
        "coin_amount": "0.00095132715370241",
        "coin_address": "MQvWK1vphyfV1F6",
        "fee_amount_coin": "0.00001903",
        "fee_amount_usd": "2.00",
        "apply_fee": 0,
        "white_label": 0,
        "redirect_url": null,
        "created_at": "2025-06-01 18:11:18",
        "updated_at": null
      }
    ],
    "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. You can use these notifications to trigger actions in your backend, like updating a database or sending emails.

Webhook Security

WolvPay signs every webhook request using your webhook secret. The signature is included in the X-WolvPay-Signature HTTP header. You should compute the HMAC-SHA256 hash of the raw request body using your secret and compare it with the received signature. 

$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 expectedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(req.body)
    .digest('hex');

  if (crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
    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_signature = hmac.new(
        webhook_secret.encode(),
        raw_payload,
        hashlib.sha256
    ).hexdigest()

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

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

Webhook Payload

The webhook will POST the following JSON structure to your endpoint:

{
    "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 coins.

Supported currencies

WolvPay supports the following fiat currencies for invoice amounts. All amounts are automatically converted to USD for processing:

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

Payment Status Values

Invoices can have the following status values throughout their lifecycle:

Status Description
AWAITING_SELECTION Invoice is created but customer hasn't 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 the success or failure of an API request.

Code Description
200 - OK Everything worked as expected.
400 - Bad Request The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized No valid API key provided.
402 - Request Failed The parameters were valid but the request failed.
404 - Not Found The requested resource doesn't exist.
429 - Too Many Requests Too many requests hit the API too quickly.
500, 502, 503, 504 - Server Errors 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 has rate limits to protect against abuse and ensure a reliable service for all users.

The current rate limit is 100 requests per minute per API key. If you exceed this limit, you'll receive a 429 Too Many Requests response.

The following headers are included in the response to help you manage your rate limits:

Header Description
X-RateLimit-Limit The maximum number of requests you're permitted to make per minute.
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
X-RateLimit-Reset The time at which the current rate limit window resets in UTC epoch seconds.