WolvPay API Documentation
Accept cryptocurrency with a REST API: create an invoice, send the customer to pay, and get a signed webhook when the payment is confirmed. Funds go straight to your own wallet.
Base URL
https://wolvpay.com/api/v1
Request & Response Format
application/json
Authentication
Authorization: Bearer <api_key>
Quickstart
The full integration is three steps. Everything below is copy-paste runnable once you set two environment variables.
| Variable | Where to get it | Used for |
|---|---|---|
WOLVPAY_API_KEY | Dashboard → API Keys | Calling the API (create / read invoices). |
WOLVPAY_WEBHOOK_SECRET | Dashboard → Webhooks (shown when you create the endpoint) | Verifying the X-WolvPay-Signature header on incoming webhooks. |
1. Create an invoice
Store the returned invoice_id next to your order, then send the customer to data.url.
curl -X POST https://wolvpay.com/api/v1/invoices \
-H "Authorization: Bearer $WOLVPAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": 25.00,
"currency": "USD",
"description": "Order #1234",
"white_label": false,
"redirect_url": "https://example.com/thanks"
}'const res = await fetch('https://wolvpay.com/api/v1/invoices', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.WOLVPAY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
amount: 25.0,
currency: 'USD',
description: 'Order #1234',
white_label: false,
redirect_url: 'https://example.com/thanks',
}),
});
const body = await res.json();
if (!body.success) throw new Error(`${body.error}: ${body.message}`);
const { invoice_id, url } = body.data; // save invoice_id with your order, redirect the customer to urlimport os, requests
res = requests.post(
"https://wolvpay.com/api/v1/invoices",
headers={"Authorization": f"Bearer {os.environ['WOLVPAY_API_KEY']}"},
json={
"amount": 25.00,
"currency": "USD",
"description": "Order #1234",
"white_label": False,
"redirect_url": "https://example.com/thanks",
},
timeout=15,
)
body = res.json()
if not body.get("success"):
raise RuntimeError(f"{body.get('error')}: {body.get('message')}")
invoice_id = body["data"]["invoice_id"] # save with your order
pay_url = body["data"]["url"] # redirect the customer here$ch = curl_init('https://wolvpay.com/api/v1/invoices');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_TIMEOUT => 15,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Authorization: Bearer ' . getenv('WOLVPAY_API_KEY'),
],
CURLOPT_POSTFIELDS => json_encode([
'amount' => 25.00,
'currency' => 'USD',
'description' => 'Order #1234',
'white_label' => false,
'redirect_url' => 'https://example.com/thanks',
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
if (empty($body['success'])) {
throw new RuntimeException(($body['error'] ?? 'Error') . ': ' . ($body['message'] ?? ''));
}
$invoiceId = $body['data']['invoice_id']; // save with your order
$payUrl = $body['data']['url']; // redirect the customer here2. Receive the webhook
Create a webhook endpoint in the dashboard. When the customer pays, WolvPay sends a signed
POST to it. Verify the signature, then act on the
status field. A complete handler is in Recommended Handler.
3. Fulfill on PAID only
Mark the order paid only when the status is PAID, and make that step idempotent
— the same event can be delivered more than once.
Authentication
The WolvPay API uses API keys to authenticate requests. Create and manage keys in the dashboard. Keys carry full access to your account’s invoices, so keep them secret: never commit them to Git, ship them in client-side code, or paste them into chat logs.
Send the key as a Bearer token on every request:
Authorization: Bearer <your-api-key>curl https://wolvpay.com/api/v1/coins \
-H "Authorization: Bearer $WOLVPAY_API_KEY"
A missing or invalid key returns 401 with
{"success": false, "error": "Unauthorized", ...}.
Coins
The Coins API returns the cryptocurrencies WolvPay supports, their minimum payable amounts and live prices.
Get Supported Coins
Returns every supported cryptocurrency with its current exchange rate in each supported fiat currency.
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"
// ... one entry per supported fiat currency
}
}
// ... one object per coin
]
}{
"success": false,
"error": "Not Found",
"code": 404,
"message": "No coins found."
}Response Parameters
| Parameter | Type | Description |
|---|---|---|
| success | boolean | Whether the request succeeded. |
| result | string | A short human-readable message. |
| code | number | HTTP status code of the response. |
| data | array | Array of supported cryptocurrency objects. |
| data[].coin | string | Coin code used in API calls (e.g. btc, erc20_usdc). See Supported Coins. |
| data[].name | string | Display name. |
| data[].logo | string | Path to the logo image. |
| data[].minimum_transaction_coin | string | Minimum payable amount, in that coin. Payments below this are not processed. |
| data[].prices | object | Map of fiat currency code to the price of one coin in that currency. |
Invoices
An invoice is a payment request. It expires 24 hours after creation. Only invoices
created by your API key’s account can be read or updated — anything else returns 404.
Hosted vs. white-label
- Hosted (
white_label: false): WolvPay returns a checkouturl. The customer picks a coin and pays there. The simplest option. - White-label (
white_label: true, the default): you build the checkout. Passcointo get the depositcoin_addressandcoin_amountimmediately, or omit it and call Update Invoice once the customer chooses.
amount in the fiat currency you choose. WolvPay converts it to
USD, rounds to 2 decimals, and that USD value is the amount in every response and webhook.
The minimum invoice is $1 USD, and each coin has its own minimum (see
minimum_transaction_coin in Get Coins).
Create an Invoice
Creates a new invoice a customer can pay with cryptocurrency.
Content-Type: application/json, not as form data.
This endpoint has no idempotency key — if a create request times out, call
List Invoices before retrying, or you may create a duplicate.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| amount | number | Yes | Amount to charge, in currency. Must be a positive number. |
| currency | string | No | Fiat currency code (e.g. USD, EUR). Defaults to USD. See Supported Currencies. |
| coin | string | No | Coin code to pay with (e.g. btc, ltc, erc20_usdc). White-label only: ignored when white_label is false. If omitted, status is AWAITING_SELECTION and available_coins is returned. |
| description | string | No | Free-text description shown on the invoice. |
| white_label | boolean | No | true (default) = you build the checkout; false = use the hosted checkout page and receive a url. |
| redirect_url | string | No | Where to send the customer after payment completes. |
Examples
{
"amount": 100.00,
"currency": "USD",
"description": "Invoice for Order #1234",
"white_label": false,
"redirect_url": "https://example.com/thank-you"
}{
"amount": 100.00,
"currency": "USD",
"coin": "ltc",
"description": "Invoice for Order #1234",
"white_label": true
}{
"amount": 100.00,
"currency": "EUR",
"white_label": true
}Response Parameters
| Parameter | Type | Description |
|---|---|---|
| success | boolean | Whether the request succeeded. |
| result | string | A short human-readable message. |
| code | number | HTTP status code (201 on success). |
| data.invoice_id | string | Unique invoice identifier. Store this with your order. |
| data.url | string | Hosted checkout URL. Hosted invoices only. |
| data.amount | number | Invoice amount in USD. White-label only. |
| data.description | string | Description, or null. White-label only. |
| data.status | string | AWAITING_PAYMENT (coin chosen) or AWAITING_SELECTION. White-label only. See Invoice Status. |
| data.coin | string | Selected coin code. White-label with coin only. |
| data.coin_amount | number | Amount the customer must send, in that coin. White-label with coin only. |
| data.coin_address | string | Deposit address. White-label with coin only. |
| data.minimum_transaction_coin | string | Smallest payable amount in that coin. White-label with coin only. |
| data.available_coins | array | Coin codes the customer may choose from. White-label without coin only. |
| data.redirect_url | string | The redirect URL, or null. White-label only. |
| data.created_at | string | Creation time, YYYY-MM-DD HH:MM:SS (server time). White-label only. |
| data.expires_at | string | Expiry time, same format. White-label only. |
{
"success": true,
"result": "Invoice created successfully",
"code": 201,
"data": {
"invoice_id": "a7d82ddf206ad975f5b3d2d3",
"url": "https://invoices.wolvpay.com/a7d82ddf206ad975f5b3d2d3"
}
}{
"success": true,
"result": "Invoice created successfully with selected cryptocurrency",
"code": 201,
"data": {
"invoice_id": "a7d82ddf206ad975f5b3d2d3",
"amount": 100,
"description": "Invoice for Order #1234",
"status": "AWAITING_PAYMENT",
"coin": "ltc",
"coin_amount": 1.13455866,
"coin_address": "MQvWK1vphyfV1F6...",
"minimum_transaction_coin": "0.002",
"redirect_url": null,
"created_at": "2026-06-01 15:24:48",
"expires_at": "2026-06-02 15:24:48"
}
}{
"success": true,
"result": "Invoice created successfully",
"code": 201,
"data": {
"invoice_id": "a7d82ddf206ad975f5b3d2d3",
"amount": 100,
"description": null,
"status": "AWAITING_SELECTION",
"redirect_url": null,
"created_at": "2026-06-01 15:24:48",
"expires_at": "2026-06-02 15:24:48",
"available_coins": ["btc", "ltc", "eth", "trx", "erc20_usdc"]
}
}{
"success": false,
"error": "Bad Request",
"code": 500,
"message": "The provided currency 'XYZ' is not supported. Refer to the documentation for supported currencies: https://wolvpay.com/docs"
}"code": 500 even though they are
client errors. Always branch on success, error and message, not on the
status code alone. See Errors.
Retrieve an Invoice
Retrieves an invoice. This is the authoritative source of truth for status — use it to confirm a webhook or to poll if a webhook never arrived.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| invoice_id | string | Yes | The invoice ID returned when it was created. |
{
"success": true,
"result": "Invoice retrieved successfully",
"code": 200,
"data": {
"invoice_id": "a7d82ddf206ad975f5b3d2d3",
"amount": 100,
"description": null,
"status": "AWAITING_SELECTION",
"coin": null,
"coin_amount": null,
"coin_received": 0,
"minimum_transaction_coin": null,
"coin_address": null,
"redirect_url": null,
"created_at": "2026-06-01 17:51:12",
"expires_at": "2026-06-02 17:51:12",
"available_coins": ["btc", "ltc", "eth", "doge", "trx", "erc20_usdc"]
}
}{
"success": true,
"result": "Invoice retrieved successfully",
"code": 200,
"data": {
"invoice_id": "a7d82ddf206ad975f5b3d2d3",
"amount": 100,
"description": "Invoice for Order #1234",
"status": "PAID",
"coin": "btc",
"coin_amount": 0.00234567,
"coin_received": "0.00234567",
"minimum_transaction_coin": "0.00008",
"coin_address": "bc1q...",
"redirect_url": "https://example.com/thank-you",
"created_at": "2026-06-01 10:30:00",
"expires_at": "2026-06-02 10:30:00"
}
}{
"success": true,
"result": "Invoice retrieved successfully",
"code": 200,
"data": {
"invoice_id": "a7d82ddf206ad975f5b3d2d3",
"url": "https://invoices.wolvpay.com/a7d82ddf206ad975f5b3d2d3",
"status": "AWAITING_PAYMENT"
}
}{
"success": false,
"error": "Not Found",
"code": 404,
"message": "Invoice not found."
}
coin_received is the total confirmed amount received so far, in the invoice’s coin.
Hosted invoices return only invoice_id, url and status.
Numeric fields may arrive as numbers or numeric strings — parse them, don’t compare types.
Update an Invoice
Selects the cryptocurrency for an invoice that was created without a coin and returns the
deposit address and amount.
AWAITING_SELECTION. Once a coin is selected it cannot be changed. For hosted invoices the customer
picks the coin on the hosted page.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| invoice_id (path) | string | Yes | The invoice to update. |
| coin | string | Yes | Coin code (e.g. btc, ltc, erc20_usdc). Must be one of the invoice’s available_coins. |
{ "coin": "btc" }{
"success": true,
"result": "Coin selected successfully for invoice",
"code": 200,
"data": {
"invoice_id": "a7d82ddf206ad975f5b3d2d3",
"amount": 100,
"description": null,
"status": "AWAITING_PAYMENT",
"coin": "ltc",
"coin_amount": 1.1345586566825505,
"coin_address": "MQvWK1vphyfV1F6...",
"minimum_transaction_coin": "0.002",
"redirect_url": null,
"updated_at": "2026-06-01 18:19:56"
}
}{
"success": false,
"error": "Bad Request",
"code": 400,
"message": "Missing required parameter: coin"
}List All Invoices
Returns your invoices, newest first, with pagination.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| page | integer | No | Page number. Defaults to 1. |
| limit | integer | No | Invoices per page. Default and maximum is 25. |
curl "https://wolvpay.com/api/v1/invoices?page=1&limit=25" \
-H "Authorization: Bearer $WOLVPAY_API_KEY"{
"success": true,
"result": "Transactions retrieved successfully",
"code": 200,
"data": {
"invoices": [
{
"invoice_id": "a7d82ddf206ad975f5b3d2d3",
"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": "2026-06-01 18:18:56",
"updated_at": "2026-06-01 18:19:56"
}
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_items": 59,
"total_pages": 3,
"has_next": true,
"has_previous": false,
"next_page": 2,
"previous_page": null
}
}
}Wallets
Read and rotate the payout addresses WolvPay forwards payments to, and lock them so they cannot be changed.
Reading works with any API key. Changing wallets or the lock needs Wallet access turned on
for that key on the API Keys page; without it these calls return 403.
A new address applies to new invoices only. Every invoice address keeps forwarding to the payout address that was set when the invoice was created, including any later payment sent to it.
List Wallets
Returns every supported coin with your payout address, whether it accepts payments, and the lock status.
GET /api/v1/wallets/{coin} returns a single coin.
{
"success": true,
"result": "Wallets retrieved successfully",
"code": 200,
"data": {
"lock": { "locked": false, "locked_until": null },
"wallets": [
{
"coin": "btc",
"name": "Bitcoin",
"network": "Bitcoin",
"address": "bc1qxupyncl2u2epsxec0lekysuf6ctn3mzz9jv7u2",
"enabled": true,
"updated_at": "2026-11-08T09:12:44Z"
}
// ... one object per supported coin; address is null until set
]
}
}Update a Wallet
Set a coin’s payout address, turn it on or off, or both. Fields you leave out stay as they are. The address is checked for the coin’s network (checksum included) before it is saved.
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| address | string | No | New payout address for this coin. |
| enabled | boolean | No | Whether new invoices can be paid with this coin. Needs an address. |
curl -X PUT https://wolvpay.com/api/v1/wallets/btc \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"address": "bc1qxupyncl2u2epsxec0lekysuf6ctn3mzz9jv7u2", "enabled": true}'// 403 Forbidden the key does not have Wallet access
// 404 Not Found unknown coin code
// 422 Unprocessable Entity invalid address for this network, a burn or contract address, or enabling without an address
// 503 Service Unavailable the address could not be checked with the payment network; retry shortly
// 423 Locked wallets are locked; the message says until when
{
"success": false,
"error": "Locked",
"code": 423,
"message": "Wallets are locked until 2026-12-08T09:12:44Z. Addresses can be changed after the lock ends."
}Wallet Lock
Lock all payout addresses for a number of days (1 to 365). While locked, no address can be changed from the
dashboard or the API. A lock can be extended but never shortened or lifted early, by anyone,
including WolvPay support. Asking for a shorter lock than the current one leaves it unchanged
("extended": false). GET /api/v1/wallets/lock returns the current status.
curl -X POST https://wolvpay.com/api/v1/wallets/lock \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"days": 30}'{
"success": true,
"result": "Wallets locked",
"code": 200,
"data": { "locked": true, "locked_until": "2026-12-08T09:12:44Z", "extended": true }
}
Monthly rotation: when locked_until has passed, call PUT /api/v1/wallets/{coin}
for each coin with the new address, then POST /api/v1/wallets/lock with {"days": 30}.
Webhooks
WolvPay sends an HTTPS POST to your server when a payment event happens, such as a payment being
confirmed or an invoice expiring. Use it to update your database, unlock access or send a receipt.
Every request is signed so you can prove it came from WolvPay.
Setup & Requirements
Create endpoints in the dashboard under Webhooks. Each endpoint gets its own signing secret.
| Requirement | Detail |
|---|---|
| Protocol | The URL must be https://. Plain http:// is rejected. |
| Hostname | A real domain name. IP addresses, localhost, and reserved names (.local, .test, .internal, .lan, .localhost, .example, .invalid, .intranet) are rejected. To develop locally, use a tunnel — see Local Development. |
| Limit | Up to 3 webhook endpoints per account. |
| Success | Any 2xx response counts as delivered. Anything else (or no response) is recorded as failed. |
| Origin IP | Requests come from 128.140.76.192. Allow-list it if your firewall is strict. |
| Headers | Content-Type: application/json and X-WolvPay-Signature: <hex hmac>. |
| Discord | If the URL is a Discord webhook URL, WolvPay posts a formatted embed instead of raw JSON (and sends no signature). |
When is a webhook sent? After WolvPay processes a blockchain payment event for one of your
invoices (for example a payment detected, confirmed, or short), and when an unpaid invoice expires. A webhook is
not sent just because an invoice was created. The invoice’s current status is in the payload —
use that field to decide what to do.
Verify Signatures
Each request carries X-WolvPay-Signature: the hex-encoded HMAC-SHA256 of the
raw request body, keyed with your webhook secret. Recompute it and compare in constant time.
Reject the request with 401 if it doesn’t match.
- Hashing the parsed JSON re-serialized by your framework. Whitespace and escaping change, and the signature won’t match. Hash the exact bytes you received (use a raw-body parser such as
express.raw()). - Using
==instead of a constant-time compare (hash_equals,timingSafeEqual,compare_digest). - Reading the header with the wrong case. HTTP headers are case-insensitive; in PHP use
$_SERVER['HTTP_X_WOLVPAY_SIGNATURE']. - Using your API key as the secret. The signing secret is the per-endpoint webhook secret.
$raw = file_get_contents('php://input'); // raw bytes, not json_decode'd
$signature = $_SERVER['HTTP_X_WOLVPAY_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $raw, getenv('WOLVPAY_WEBHOOK_SECRET'));
if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit('Invalid signature');
}
$event = json_decode($raw, true);
// ... handle $eventimport crypto from 'node:crypto';
export function isValidSignature(rawBody, header) {
const expected = crypto
.createHmac('sha256', process.env.WOLVPAY_WEBHOOK_SECRET)
.update(rawBody) // Buffer from express.raw(), NOT a parsed object
.digest('hex');
const a = Buffer.from(header ?? '');
const b = Buffer.from(expected);
return a.length === b.length && crypto.timingSafeEqual(a, b); // timingSafeEqual throws on length mismatch
}import hashlib, hmac, os
def is_valid_signature(raw_body: bytes, header: str | None) -> bool:
expected = hmac.new(
os.environ["WOLVPAY_WEBHOOK_SECRET"].encode(),
raw_body, # request.get_data(), NOT request.json
hashlib.sha256,
).hexdigest()
return hmac.compare_digest((header or "").encode(), expected.encode())Payload & Statuses
The body is a JSON object describing the invoice at the moment the webhook was sent:
{
"invoice_id": "a7d82ddf206ad975f5b3d2d3",
"amount": "100.00",
"description": "Invoice for Order #1234",
"status": "PAID",
"coin": "ltc",
"coin_amount": "1.13455866",
"coin_received": "1.13455866",
"coin_address": "MQvWK1vphyfV1F6...",
"redirect_url": "https://example.com/thank-you",
"created_at": "2026-06-01 15:24:48"
}| Field | Type | Description |
|---|---|---|
| invoice_id | string | The invoice this event is about. Match it to your order. |
| amount | string|number | Invoice amount in USD. |
| description | string|null | Description supplied at creation. |
| status | string | Current invoice status. This is the field to branch on. See Invoice Status. |
| coin | string | Coin code, lowercase (e.g. ltc). |
| coin_amount | string|number | Amount requested, in that coin. |
| coin_received | string|number | Total confirmed so far, in that coin (0 if nothing confirmed). |
| coin_address | string | The deposit address. |
| redirect_url | string|null | Redirect URL supplied at creation. |
| created_at | string | Invoice creation time, YYYY-MM-DD HH:MM:SS (server time, not ISO-8601). |
Statuses you should expect to receive and how to handle them:
| status | What to do |
|---|---|
| PAID | Fulfill the order (once). |
| CONFIRMING_PAYMENT | Payment seen, not final. Show “processing”; do not fulfill. |
| UNDERPAID | Customer sent too little. Flag for manual review or ask them to top up. |
| EXPIRED | Cancel the order or release reserved stock. |
| AWAITING_PAYMENT | No action needed. |
The same status can be delivered more than once, and deliveries are not guaranteed to arrive in order. Treat every webhook as a hint to re-check the invoice (see the handler below), not as the final word.
Recommended Handler
A production-shaped handler does five things, in this order:
- Read the raw body and verify the signature →
401if invalid. - Look the invoice up with
GET /invoices/{invoice_id}to get the authoritative status. A404means it isn’t one of your invoices (for example a Webhook Tester delivery) — acknowledge with200and ignore it. - If the status is
PAID, fulfill the order idempotently (keyed oninvoice_id). - Return
2xxquickly. - If something on your side fails (database down), return
5xxso the delivery shows as failed and you can resend it.
import express from 'express';
import crypto from 'node:crypto';
const app = express();
const API = process.env.WOLVPAY_API_BASE ?? 'https://wolvpay.com/api/v1';
function isValidSignature(rawBody, header) {
const expected = crypto.createHmac('sha256', process.env.WOLVPAY_WEBHOOK_SECRET)
.update(rawBody).digest('hex');
const a = Buffer.from(header ?? '');
const b = Buffer.from(expected);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
// Raw body is required for the signature. Do NOT put express.json() before this route.
app.post('/webhooks/wolvpay', express.raw({ type: '*/*' }), async (req, res) => {
if (!isValidSignature(req.body, req.get('X-WolvPay-Signature'))) {
return res.sendStatus(401);
}
const event = JSON.parse(req.body.toString('utf8'));
// Confirm with the API: authoritative status, and unknown invoices (test deliveries) are ignored.
const r = await fetch(`${API}/invoices/${encodeURIComponent(event.invoice_id)}`, {
headers: { Authorization: `Bearer ${process.env.WOLVPAY_API_KEY}` },
});
if (r.status === 404) return res.sendStatus(200); // not ours / test delivery
if (!r.ok) return res.sendStatus(502); // shows as failed, can be resent
const { data: invoice } = await r.json();
try {
if (invoice.status === 'PAID') {
await fulfillOrderOnce(invoice.invoice_id); // your code - MUST be idempotent
} else if (invoice.status === 'EXPIRED') {
await cancelOrder(invoice.invoice_id);
}
} catch (err) {
console.error(err);
return res.sendStatus(500);
}
res.sendStatus(200);
});
app.listen(3000);import hashlib, hmac, os
import requests
from flask import Flask, request, abort
app = Flask(__name__)
API = os.environ.get("WOLVPAY_API_BASE", "https://wolvpay.com/api/v1")
def is_valid_signature(raw: bytes, header: str | None) -> bool:
expected = hmac.new(os.environ["WOLVPAY_WEBHOOK_SECRET"].encode(), raw, hashlib.sha256).hexdigest()
return hmac.compare_digest((header or "").encode(), expected.encode())
@app.post("/webhooks/wolvpay")
def wolvpay_webhook():
raw = request.get_data() # raw bytes
if not is_valid_signature(raw, request.headers.get("X-WolvPay-Signature")):
abort(401)
event = request.get_json(force=True)
r = requests.get(
f"{API}/invoices/{event['invoice_id']}",
headers={"Authorization": f"Bearer {os.environ['WOLVPAY_API_KEY']}"},
timeout=10,
)
if r.status_code == 404:
return "", 200 # not ours / test delivery
if not r.ok:
abort(502) # shows as failed, can be resent
invoice = r.json()["data"]
try:
if invoice["status"] == "PAID":
fulfill_order_once(invoice["invoice_id"]) # your code - MUST be idempotent
elif invoice["status"] == "EXPIRED":
cancel_order(invoice["invoice_id"])
except Exception:
app.logger.exception("webhook handling failed")
abort(500)
return "", 200<?php
$raw = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WOLVPAY_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $raw, getenv('WOLVPAY_WEBHOOK_SECRET'));
if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit;
}
$event = json_decode($raw, true);
$api = getenv('WOLVPAY_API_BASE') ?: 'https://wolvpay.com/api/v1';
// Confirm with the API: authoritative status, and unknown invoices (test deliveries) are ignored.
$ch = curl_init($api . '/invoices/' . rawurlencode($event['invoice_id']));
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 10,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('WOLVPAY_API_KEY')],
]);
$body = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($code === 404) { http_response_code(200); exit; } // not ours / test delivery
if ($code !== 200) { http_response_code(502); exit; } // shows as failed, can be resent
$invoice = json_decode($body, true)['data'];
try {
if ($invoice['status'] === 'PAID') {
fulfill_order_once($invoice['invoice_id']); // your code - MUST be idempotent
} elseif ($invoice['status'] === 'EXPIRED') {
cancel_order($invoice['invoice_id']);
}
} catch (Throwable $e) {
error_log($e->getMessage());
http_response_code(500);
exit;
}
http_response_code(200);
WOLVPAY_API_BASE is optional. It exists so you can point the handler at a local mock during tests
(see Simulate Locally).
Delivery & Retries
- At-least-once, unordered. Make fulfillment idempotent on
invoice_id, and trust the invoice status from the API over the order webhooks arrive in. - Respond fast. Return
2xxwithin a few seconds. Do slow work (emails, third-party calls) in a background job after acknowledging. - Every attempt is logged. Open Dashboard → Webhooks to see each delivery’s request body, your HTTP status and your response body.
- Resend from the dashboard. A failed delivery can be re-sent. The resend uses the original payload (the status at the time), signed again with your secret, and is logged as a new delivery.
- Don’t rely on retries alone. If your server was down, call
GET /invoices/{id}for any order still pending — a periodic reconciliation job is cheap insurance.
Testing & Sandbox
Test your integration end to end without risking money. WolvPay does not have a separate sandbox environment, so this section shows exactly what you can test and how.
How to Test
| What you are testing | Use | Costs real crypto? |
|---|---|---|
| Your webhook endpoint (signature check, parsing, idempotency) | Webhook Tester — sends a real, signed webhook with fake data | No |
| Your webhook endpoint with no network at all | Simulate Locally — sign a payload yourself and POST it to localhost | No |
| Creating, reading, updating and listing invoices | The live API with your real key. Unpaid invoices expire on their own | No |
| The hosted checkout page and your redirect flow | Create a hosted invoice and open its url | No (until you pay) |
The full payment path (payment → PAID webhook → fulfillment) | Pay one small real invoice | Yes — a minimum-size payment plus network fee |
Recommended order: (1) Simulate Locally while writing the handler, (2) Webhook Tester against
your deployed URL, (3) one real minimum-size payment before going live. For step 3, check the smallest
allowed amount for your coin with Get Coins (minimum_transaction_coin); the
minimum invoice is $1 USD.
Webhook Tester
The Webhook Tester (Dashboard → Developers → Webhook Tester) sends a sample payload to one of your webhook endpoints, signed with that endpoint’s real secret, using the same delivery path and headers as production. It tests your URL, TLS, firewall, signature code and response handling.
| Setting | Detail |
|---|---|
| Requirements | A verified account and at least one active webhook endpoint. |
| Statuses | Pick one: PAID, AWAITING_PAYMENT, CONFIRMING_PAYMENT, UNDERPAID, EXPIRED. |
| Invoice ID | Optional. Letters, numbers, - and _, up to 64 characters. If blank, one is generated as test_ + 12 hex characters. |
| Limit | 10 test webhooks per hour per account. The remaining count is shown on the page. |
| Result | The page shows the HTTP status your server returned, your response body, and any connection error. 2xx = success. |
| Logging | Test deliveries appear in your webhook delivery log with the event type webhook.test. |
| Discord URLs | If the endpoint is a Discord webhook, the test posts the formatted embed instead of JSON. |
The test payload
{
"invoice_id": "test_9f2c4a1b7d3e",
"amount": "10.00",
"description": "Test invoice from WolvPay Webhook Tester",
"status": "PAID",
"coin": "BTC",
"coin_amount": "0.00015000",
"coin_received": "0.00015000",
"coin_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7Divf2N",
"redirect_url": "",
"created_at": "2026-06-01 12:00:00"
}coin_received is "0.00000000" for every status except PAID.
How tests differ from real events
- The invoice does not exist in WolvPay, so
GET /invoices/{invoice_id}returns404. A handler that confirms via the API (as recommended above) will correctly ignore test deliveries and never fulfill a fake order. coinis the uppercaseBTCin tests; real events use lowercase codes likebtc. Normalize before comparing.redirect_urlis an empty string in tests; real events send the URL ornull.- The amount is always
10.00and the address is a well-known sample address.
PAID event is
indistinguishable from a real one except for the invoice ID. Never hard-code logic that fulfills orders from an
unrecognized invoice_id.
Simulate Locally
You can test your handler with no network and no WolvPay account activity: build a payload, sign it with your webhook secret exactly as WolvPay does, and POST it to your local server. It also lets you test the cases the Webhook Tester can’t, such as a tampered body or a duplicate delivery.
export WOLVPAY_WEBHOOK_SECRET=local_test_secret
BODY='{"invoice_id":"local_test_001","amount":"10.00","description":"Local test","status":"PAID","coin":"btc","coin_amount":"0.00015000","coin_received":"0.00015000","coin_address":"1A1zP1eP5QGefi2DMPTfTL5SLmv7Divf2N","redirect_url":"","created_at":"2026-06-01 12:00:00"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WOLVPAY_WEBHOOK_SECRET" | awk '{print $NF}')
curl -i -X POST http://localhost:3000/webhooks/wolvpay \
-H "Content-Type: application/json" \
-H "X-WolvPay-Signature: $SIG" \
--data-binary "$BODY" # --data-binary keeps the bytes exactly as signedimport crypto from 'node:crypto';
const secret = process.env.WOLVPAY_WEBHOOK_SECRET ?? 'local_test_secret';
const body = JSON.stringify({
invoice_id: 'local_test_001',
amount: '10.00',
description: 'Local test',
status: 'PAID',
coin: 'btc',
coin_amount: '0.00015000',
coin_received: '0.00015000',
coin_address: '1A1zP1eP5QGefi2DMPTfTL5SLmv7Divf2N',
redirect_url: '',
created_at: '2026-06-01 12:00:00',
});
const signature = crypto.createHmac('sha256', secret).update(body).digest('hex');
const res = await fetch('http://localhost:3000/webhooks/wolvpay', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-WolvPay-Signature': signature },
body, // send the exact string that was signed
});
console.log(res.status, await res.text());import hashlib, hmac, json, os, requests
secret = os.environ.get("WOLVPAY_WEBHOOK_SECRET", "local_test_secret")
body = json.dumps({
"invoice_id": "local_test_001",
"amount": "10.00",
"description": "Local test",
"status": "PAID",
"coin": "btc",
"coin_amount": "0.00015000",
"coin_received": "0.00015000",
"coin_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7Divf2N",
"redirect_url": "",
"created_at": "2026-06-01 12:00:00",
}).encode()
signature = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
res = requests.post(
"http://localhost:3000/webhooks/wolvpay",
data=body, # send the exact bytes that were signed
headers={"Content-Type": "application/json", "X-WolvPay-Signature": signature},
)
print(res.status_code, res.text)local_test_001 isn’t a real invoice, so the
confirm-with-API step returns 404. To exercise your fulfillment code locally, set
WOLVPAY_API_BASE to a small mock server (or stub the lookup in your tests) that returns
{"success": true, "data": {"invoice_id": "local_test_001", "status": "PAID"}}.
Local Development
WolvPay can only deliver to a public https:// domain — localhost and IP addresses are
rejected when you save the endpoint. To receive real (or Webhook Tester) deliveries on your laptop, expose your local
server through an HTTPS tunnel:
cloudflared tunnel --url http://localhost:3000ngrok http 3000- Start your app (e.g. on port 3000) and the tunnel; copy the
https://…URL it prints. - In Dashboard → Webhooks, create an endpoint with
https://<tunnel-host>/webhooks/wolvpay. Copy its secret intoWOLVPAY_WEBHOOK_SECRET. - Send a test from the Webhook Tester and watch your logs.
- Deactivate or delete the endpoint when you finish — tunnel URLs are temporary.
Just want to inspect what WolvPay sends? Point an endpoint at a request-inspection URL such as webhook.site. You’ll see the exact headers and raw body (but you won’t be testing your own code).
Test Checklist
Run each of these before going live. Most can be done with Simulate Locally.
| Scenario | How | Expected result |
|---|---|---|
Valid signature, PAID | Webhook Tester, or a signed local request | 200. Order fulfilled exactly once. |
| Same event delivered twice | Send the identical request twice | 200 both times. Order still fulfilled once. |
| Tampered body | Change one character after signing | 401. Nothing happens. |
| Missing or empty signature | Omit the X-WolvPay-Signature header | 401. |
| Wrong secret | Sign with a different secret | 401. |
CONFIRMING_PAYMENT | Webhook Tester | 200. Order shown as processing, not fulfilled. |
UNDERPAID | Webhook Tester | 200. Flagged for review, not fulfilled. |
EXPIRED | Webhook Tester | 200. Order cancelled / stock released. |
Unknown invoice_id | Any test_ or local invoice | 200, ignored (the API lookup returns 404). |
| Your dependency is down | Stop your database, send a PAID event | 5xx, so the delivery is recorded as failed and can be resent. |
| Raw-body handling | Send JSON with extra spaces / unicode | Signature still verifies (you hash the raw bytes). |
| One real payment | Pay a minimum-size live invoice | PAID webhook arrives, order fulfilled, delivery shows 2xx in the dashboard. |
AI & Coding Agents
These docs are built to be consumed by tools such as Claude Code, Cursor, Copilot and ChatGPT as well as humans. Give your assistant one of the machine-readable sources below instead of letting it guess from memory, and have it follow the integration rules.
Machine-readable Docs
| Resource | Format | Use it for |
|---|---|---|
| /openapi.json | OpenAPI 3.1 | Generating a typed client, importing into Postman / Insomnia, or giving an agent exact request and response schemas. |
| /docs.md | Markdown | Pasting the whole guide into an assistant, including the webhook handler and testing sections. Same content as this page. |
| /llms.txt | Plain text | A short product summary for LLM crawlers, with links to the above. |
| Copy for AI button | Markdown | Copies the Markdown version of this page to your clipboard (top-right of the header). |
curl -s https://www.wolvpay.com/openapi.json -o wolvpay-openapi.json
curl -s https://www.wolvpay.com/docs.md -o wolvpay-docs.mdIntegration Rules
The facts an agent (or a new teammate) most often gets wrong. Treat these as requirements:
- Base URL is
https://wolvpay.com/api/v1. Auth isAuthorization: Bearer $WOLVPAY_API_KEY. Bodies are JSON (Content-Type: application/json), never form-encoded. - Secrets live in environment variables (
WOLVPAY_API_KEY,WOLVPAY_WEBHOOK_SECRET). Never hard-code, log or send them to the browser. - There is no sandbox. Do not invent a test base URL, test keys or a
test_modeparameter. Test with the Webhook Tester and locally signed requests. - Check
successfirst. Errors look like{"success": false, "error": "...", "code": 400, "message": "..."}. Some business-rule errors carry"code": 500; readmessage. amountin responses and webhooks is USD, regardless of thecurrencyyou sent.- Save
invoice_idwith your order at creation time. It is the join key for everything else. - Verify the webhook signature on the raw body with HMAC-SHA256 (hex) and a constant-time compare, using the per-endpoint webhook secret.
- Then confirm with
GET /invoices/{invoice_id}and fulfill only whenstatus === "PAID". A404there means ignore the webhook. - Be idempotent. Webhooks can repeat and arrive out of order. Key fulfillment on
invoice_id. - Return
2xxfast once handled; return5xxif your side failed so it can be resent. POST /invoicesis not idempotent. On a timeout, list invoices before retrying.- Respect rate limits: 100 requests/minute per key (
429+X-RateLimit-Reset); 40 invoices/hour and 800/day per account. - Webhook URLs must be public HTTPS domains (no IPs, no localhost). Use a tunnel for local development.
Starter Prompt
Paste this into your coding agent, filling in the bracketed parts. It points the agent at the right sources and encodes the rules above.
Integrate WolvPay crypto payments into this project.
Sources of truth (read these first, do not rely on memory):
- https://www.wolvpay.com/openapi.json
- https://www.wolvpay.com/docs.md
Stack: [e.g. Next.js 15 + Postgres]
Do this:
1. Add a server-side function createCheckout(order) that POSTs to /api/v1/invoices
with white_label=false and redirect_url=[our thank-you URL], and stores the
returned invoice_id on the order. Redirect the customer to data.url.
2. Add a POST /webhooks/wolvpay route that:
- reads the RAW body and verifies X-WolvPay-Signature (hex HMAC-SHA256 using
WOLVPAY_WEBHOOK_SECRET, constant-time compare) -> 401 on mismatch
- confirms via GET /api/v1/invoices/{invoice_id}; a 404 means ignore (200)
- fulfills the order ONLY when status === "PAID", idempotently on invoice_id
- returns 2xx quickly, 5xx if our own processing fails
3. Read WOLVPAY_API_KEY and WOLVPAY_WEBHOOK_SECRET from environment variables.
Never log or expose them.
4. WolvPay has NO sandbox or test keys. Write tests that sign a payload locally
(see the "Simulate Locally" section of the docs) and cover: valid PAID,
duplicate delivery, tampered body, missing signature, EXPIRED, unknown invoice.
Make the API base URL configurable (WOLVPAY_API_BASE) so tests can mock it.
5. Do not invent endpoints or fields that are not in the OpenAPI spec.Reference
Supported coins, fiat currencies and invoice statuses.
Supported Coins
Use the code in the coin parameter. A coin is only usable if you have enabled a
wallet for it in the dashboard. For live minimum amounts and prices, call Get Coins.
| Code | Asset | Network |
|---|---|---|
btc |
Bitcoin | Bitcoin |
bch |
Bitcoin Cash | Bitcoin Cash |
ltc |
Litecoin | Litecoin |
doge |
Dogecoin | Dogecoin |
eth |
Ethereum | Ethereum |
trx |
TRX | Tron |
erc20_usdc |
USDC | Ethereum (ERC-20) |
erc20_usdt |
USDT | Ethereum (ERC-20) |
bep20_usdc |
USDC | BNB Smart Chain (BEP-20) |
bep20_usdt |
USDT | BNB Smart Chain (BEP-20) |
polygon_pol |
POL | Polygon |
polygon_usdc |
USDC | Polygon |
polygon_usdt |
USDT | Polygon |
sol_sol |
Solana | Solana |
sol_usdc |
USDC | Solana |
sol_usdt |
USDT | Solana |
trc20_usdt |
USDT | Tron (TRC-20) |
Supported Fiat Currencies
Invoice amounts can be given in any of these currencies and are converted at the time of creation.
The stored and returned amount is always in USD.
| Currency Code | Currency Name |
|---|---|
AED |
United Arab Emirates Dirham |
AUD |
Australian Dollar |
BGN |
Bulgarian Lev |
BRL |
Brazilian Real |
CAD |
Canadian Dollar |
CHF |
Swiss Franc |
CNY |
Chinese Yuan |
COP |
Colombian Peso |
CZK |
Czech Koruna |
DKK |
Danish Krone |
EUR |
Euro |
GBP |
British Pound Sterling |
HKD |
Hong Kong Dollar |
HUF |
Hungarian Forint |
IDR |
Indonesian Rupiah |
INR |
Indian Rupee |
JPY |
Japanese Yen |
LKR |
Sri Lankan Rupee |
MXN |
Mexican Peso |
MYR |
Malaysian Ringgit |
NGN |
Nigerian Naira |
NOK |
Norwegian Krone |
PHP |
Philippine Peso |
PLN |
Polish Zloty |
RON |
Romanian Leu |
RUB |
Russian Ruble |
SEK |
Swedish Krona |
SGD |
Singapore Dollar |
THB |
Thai Baht |
TRY |
Turkish Lira |
TWD |
Taiwan Dollar |
UAH |
Ukrainian Hryvnia |
UGX |
Ugandan Shilling |
USD |
US Dollar |
VND |
Vietnamese Dong |
ZAR |
South African Rand |
Invoice Status Values
Invoices move through these statuses during their lifecycle:
| Status | Description |
|---|---|
AWAITING_SELECTION | Invoice created, but no cryptocurrency has been selected yet (white-label invoices created without coin). |
AWAITING_PAYMENT | Cryptocurrency selected. Waiting for the customer to pay. |
CONFIRMING_PAYMENT | A payment was detected and is waiting for blockchain confirmations. Do not fulfill yet. |
PAID | Payment confirmed. This is the only status on which you should fulfill the order. |
UNDERPAID | Payment received, but the amount is less than required. Review manually. |
EXPIRED | The invoice expired (24 hours after creation) without payment. |
Errors
WolvPay uses standard HTTP status codes plus a consistent JSON error body.
| Code | Description |
|---|---|
| 200 - OK | Everything worked as expected. |
| 201 - Created | An invoice was created. |
| 400 - Bad Request | Missing or invalid parameter. |
| 401 - Unauthorized | Missing, malformed or invalid API key. |
| 404 - Not Found | The invoice (or endpoint) does not exist, or belongs to another account. |
| 429 - Too Many Requests | You exceeded the per-key rate limit. See Rate Limits. |
| 500 - Server Error | Something went wrong on WolvPay's side or a business-rule check failed (see the note below). |
Error Response Format
{
"success": false,
"error": "Bad Request",
"code": 400,
"message": "Missing required parameter: amount"
}
Branch on success; show or log message. error is a short category
(Bad Request, Unauthorized, Not Found, Too Many Requests,
Internal Server Error, Rate Limit Exceeded).
Common messages
| HTTP | message | What to do |
|---|---|---|
| 401 | Authorization header is missing. | Send Authorization: Bearer <key>. |
| 401 | Invalid authorization format. Use Authorization: Bearer <your-api-key>. | Use the Bearer scheme. |
| 401 | Invalid API key. | Check the key in Dashboard → API Keys. |
| 400 | Missing required parameter: amount | Add the field to the JSON body. |
| 400 | Parameter 'amount' must be a positive number | Send a number greater than 0. |
| 404 | Invoice not found. | Wrong ID, or the invoice belongs to another account. |
| 404 | The requested endpoint does not exist. Please check the URL and try again. | Check the path and HTTP method. |
| 429 | Rate limit exceeded. Please try again later. | Wait until X-RateLimit-Reset. |
| 500* | The provided currency 'XYZ' is not supported... | Use a code from Supported Currencies. |
| 500* | The amount must be at least $1. | Increase the amount (USD equivalent). |
| 500* | No enabled wallets found for the user. | Add and enable a wallet in the dashboard. |
| 500* | No enabled wallets found for the user with sufficient balance. Minimum required USD amount is N. | Raise the amount, or enable a coin with a lower minimum. |
| 500* | The provided cryptocurrency code is not supported or not enabled for the user or the amount is below the minimum required for this wallet. | Pick a coin from available_coins. |
| 500* | The amount is below the minimum transaction amount for the selected cryptocurrency. | Raise the amount or choose another coin. |
| 500* | Invoice is not awaiting coin selection. Current status: ... | A coin is already set; the invoice can’t be changed. |
| 500* | This endpoint is only available for white-label invoices. | Hosted invoices pick the coin on the hosted page. |
| 500* | You are creating invoices too quickly. Maximum 40 invoices per hour... | Back off and retry later. |
| 500* | You have reached the daily invoice creation limit (800 per day)... | Wait, or contact support for a higher limit. |
* These are client-side problems that currently return HTTP 500 with a descriptive
message. Don’t blindly retry a 500 on POST /invoices — read the message first,
and remember the endpoint is not idempotent.
Rate Limits
| Limit | Scope | On exceed |
|---|---|---|
| 100 requests / minute | Per API key | 429 Too Many Requests with the headers below. |
| 40 invoices / hour | Per account | Invoice creation fails with a Rate Limit Exceeded error. |
| 800 invoices / day | Per account | Invoice creation fails with a Rate Limit Exceeded error. Contact support for more. |
| 10 test webhooks / hour | Per account (Webhook Tester) | The tester refuses until the hour rolls over. |
These headers help you track your per-key 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). |
async function wolvpay(path, init = {}) {
const res = await fetch(`https://wolvpay.com/api/v1${path}`, {
...init,
headers: {
Authorization: `Bearer ${process.env.WOLVPAY_API_KEY}`,
'Content-Type': 'application/json',
...init.headers,
},
});
if (res.status === 429) {
const resetAt = Number(res.headers.get('X-RateLimit-Reset')) * 1000;
await new Promise((r) => setTimeout(r, Math.max(resetAt - Date.now(), 1000)));
return wolvpay(path, init); // safe for GETs; do not auto-retry POST /invoices on timeouts
}
const body = await res.json();
if (!body.success) throw new Error(`${body.error}: ${body.message}`);
return body.data;
}