OpenAPI Dashboard

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>
Using an AI coding agent? Paste /docs.md or /openapi.json into your assistant, or press Copy for AI in the header. See AI & Coding Agents.

Quickstart

The full integration is three steps. Everything below is copy-paste runnable once you set two environment variables.

VariableWhere to get itUsed for
WOLVPAY_API_KEYDashboard → API KeysCalling the API (create / read invoices).
WOLVPAY_WEBHOOK_SECRETDashboard → 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 url
import 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 here

2. 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.

No sandbox: WolvPay has no separate test environment or test API keys. Your API key always talks to the live service. See Testing & Sandbox for how to test safely without spending money.

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.

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"
        // ... one entry per supported fiat currency
      }
    }
    // ... one object per coin
  ]
}
{
  "success": false,
  "error": "Not Found",
  "code": 404,
  "message": "No coins found."
}

Response Parameters

ParameterTypeDescription
successbooleanWhether the request succeeded.
resultstringA short human-readable message.
codenumberHTTP status code of the response.
dataarrayArray of supported cryptocurrency objects.
data[].coinstringCoin code used in API calls (e.g. btc, erc20_usdc). See Supported Coins.
data[].namestringDisplay name.
data[].logostringPath to the logo image.
data[].minimum_transaction_coinstringMinimum payable amount, in that coin. Payments below this are not processed.
data[].pricesobjectMap 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 checkout url. The customer picks a coin and pays there. The simplest option.
  • White-label (white_label: true, the default): you build the checkout. Pass coin to get the deposit coin_address and coin_amount immediately, or omit it and call Update Invoice once the customer chooses.
Amounts: you send 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.

Note: Send the body as JSON with 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.
POST /api/v1/invoices

Request Parameters

ParameterTypeRequiredDescription
amountnumberYesAmount to charge, in currency. Must be a positive number.
currencystringNoFiat currency code (e.g. USD, EUR). Defaults to USD. See Supported Currencies.
coinstringNoCoin 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.
descriptionstringNoFree-text description shown on the invoice.
white_labelbooleanNotrue (default) = you build the checkout; false = use the hosted checkout page and receive a url.
redirect_urlstringNoWhere 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

ParameterTypeDescription
successbooleanWhether the request succeeded.
resultstringA short human-readable message.
codenumberHTTP status code (201 on success).
data.invoice_idstringUnique invoice identifier. Store this with your order.
data.urlstringHosted checkout URL. Hosted invoices only.
data.amountnumberInvoice amount in USD. White-label only.
data.descriptionstringDescription, or null. White-label only.
data.statusstringAWAITING_PAYMENT (coin chosen) or AWAITING_SELECTION. White-label only. See Invoice Status.
data.coinstringSelected coin code. White-label with coin only.
data.coin_amountnumberAmount the customer must send, in that coin. White-label with coin only.
data.coin_addressstringDeposit address. White-label with coin only.
data.minimum_transaction_coinstringSmallest payable amount in that coin. White-label with coin only.
data.available_coinsarrayCoin codes the customer may choose from. White-label without coin only.
data.redirect_urlstringThe redirect URL, or null. White-label only.
data.created_atstringCreation time, YYYY-MM-DD HH:MM:SS (server time). White-label only.
data.expires_atstringExpiry 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"
}
Heads-up: some business-rule failures on this endpoint (unsupported currency, amount under $1, no enabled wallet, invoice rate limit) currently come back with "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.

GET /api/v1/invoices/{invoice_id}

Path Parameters

ParameterTypeRequiredDescription
invoice_idstringYesThe 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.

Note: Only available for white-label invoices still in AWAITING_SELECTION. Once a coin is selected it cannot be changed. For hosted invoices the customer picks the coin on the hosted page.
POST /api/v1/invoices/{invoice_id}

Request Parameters

ParameterTypeRequiredDescription
invoice_id (path)stringYesThe invoice to update.
coinstringYesCoin 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.

GET /api/v1/invoices

Query Parameters

ParameterTypeRequiredDescription
pageintegerNoPage number. Defaults to 1.
limitintegerNoInvoices 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.

GET /api/v1/wallets
{
  "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.

PUT /api/v1/wallets/{coin}

Request Body

ParameterTypeRequiredDescription
addressstringNoNew payout address for this coin.
enabledbooleanNoWhether 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.

POST /api/v1/wallets/lock
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.

RequirementDetail
ProtocolThe URL must be https://. Plain http:// is rejected.
HostnameA 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.
LimitUp to 3 webhook endpoints per account.
SuccessAny 2xx response counts as delivered. Anything else (or no response) is recorded as failed.
Origin IPRequests come from 128.140.76.192. Allow-list it if your firewall is strict.
HeadersContent-Type: application/json and X-WolvPay-Signature: <hex hmac>.
DiscordIf 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.

Common mistakes:
  • 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 $event
import 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"
}
FieldTypeDescription
invoice_idstringThe invoice this event is about. Match it to your order.
amountstring|numberInvoice amount in USD.
descriptionstring|nullDescription supplied at creation.
statusstringCurrent invoice status. This is the field to branch on. See Invoice Status.
coinstringCoin code, lowercase (e.g. ltc).
coin_amountstring|numberAmount requested, in that coin.
coin_receivedstring|numberTotal confirmed so far, in that coin (0 if nothing confirmed).
coin_addressstringThe deposit address.
redirect_urlstring|nullRedirect URL supplied at creation.
created_atstringInvoice creation time, YYYY-MM-DD HH:MM:SS (server time, not ISO-8601).

Statuses you should expect to receive and how to handle them:

statusWhat to do
PAIDFulfill the order (once).
CONFIRMING_PAYMENTPayment seen, not final. Show “processing”; do not fulfill.
UNDERPAIDCustomer sent too little. Flag for manual review or ask them to top up.
EXPIREDCancel the order or release reserved stock.
AWAITING_PAYMENTNo 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:

  1. Read the raw body and verify the signature → 401 if invalid.
  2. Look the invoice up with GET /invoices/{invoice_id} to get the authoritative status. A 404 means it isn’t one of your invoices (for example a Webhook Tester delivery) — acknowledge with 200 and ignore it.
  3. If the status is PAID, fulfill the order idempotently (keyed on invoice_id).
  4. Return 2xx quickly.
  5. If something on your side fails (database down), return 5xx so 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 2xx within 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.

There is no test mode and there are no test API keys. Every API key works against the live service and every invoice is a real invoice. Two things keep this safe: creating an invoice is free (it only costs money if someone actually sends crypto to it), and unpaid invoices simply expire after 24 hours.

How to Test

What you are testingUseCosts real crypto?
Your webhook endpoint (signature check, parsing, idempotency)Webhook Tester — sends a real, signed webhook with fake dataNo
Your webhook endpoint with no network at allSimulate Locally — sign a payload yourself and POST it to localhostNo
Creating, reading, updating and listing invoicesThe live API with your real key. Unpaid invoices expire on their ownNo
The hosted checkout page and your redirect flowCreate a hosted invoice and open its urlNo (until you pay)
The full payment path (payment → PAID webhook → fulfillment)Pay one small real invoiceYes — 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.

SettingDetail
RequirementsA verified account and at least one active webhook endpoint.
StatusesPick one: PAID, AWAITING_PAYMENT, CONFIRMING_PAYMENT, UNDERPAID, EXPIRED.
Invoice IDOptional. Letters, numbers, - and _, up to 64 characters. If blank, one is generated as test_ + 12 hex characters.
Limit10 test webhooks per hour per account. The remaining count is shown on the page.
ResultThe page shows the HTTP status your server returned, your response body, and any connection error. 2xx = success.
LoggingTest deliveries appear in your webhook delivery log with the event type webhook.test.
Discord URLsIf 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} returns 404. A handler that confirms via the API (as recommended above) will correctly ignore test deliveries and never fulfill a fake order.
  • coin is the uppercase BTC in tests; real events use lowercase codes like btc. Normalize before comparing.
  • redirect_url is an empty string in tests; real events send the URL or null.
  • The amount is always 10.00 and the address is a well-known sample address.
If you don’t verify with the API and instead trust the webhook body, a test 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 signed
import 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)
Your handler will ignore these by design. 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:3000
ngrok http 3000
  1. Start your app (e.g. on port 3000) and the tunnel; copy the https://… URL it prints.
  2. In Dashboard → Webhooks, create an endpoint with https://<tunnel-host>/webhooks/wolvpay. Copy its secret into WOLVPAY_WEBHOOK_SECRET.
  3. Send a test from the Webhook Tester and watch your logs.
  4. 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.

ScenarioHowExpected result
Valid signature, PAIDWebhook Tester, or a signed local request200. Order fulfilled exactly once.
Same event delivered twiceSend the identical request twice200 both times. Order still fulfilled once.
Tampered bodyChange one character after signing401. Nothing happens.
Missing or empty signatureOmit the X-WolvPay-Signature header401.
Wrong secretSign with a different secret401.
CONFIRMING_PAYMENTWebhook Tester200. Order shown as processing, not fulfilled.
UNDERPAIDWebhook Tester200. Flagged for review, not fulfilled.
EXPIREDWebhook Tester200. Order cancelled / stock released.
Unknown invoice_idAny test_ or local invoice200, ignored (the API lookup returns 404).
Your dependency is downStop your database, send a PAID event5xx, so the delivery is recorded as failed and can be resent.
Raw-body handlingSend JSON with extra spaces / unicodeSignature still verifies (you hash the raw bytes).
One real paymentPay a minimum-size live invoicePAID 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

ResourceFormatUse it for
/openapi.jsonOpenAPI 3.1Generating a typed client, importing into Postman / Insomnia, or giving an agent exact request and response schemas.
/docs.mdMarkdownPasting the whole guide into an assistant, including the webhook handler and testing sections. Same content as this page.
/llms.txtPlain textA short product summary for LLM crawlers, with links to the above.
Copy for AI buttonMarkdownCopies 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.md

Integration Rules

The facts an agent (or a new teammate) most often gets wrong. Treat these as requirements:

  1. Base URL is https://wolvpay.com/api/v1. Auth is Authorization: Bearer $WOLVPAY_API_KEY. Bodies are JSON (Content-Type: application/json), never form-encoded.
  2. Secrets live in environment variables (WOLVPAY_API_KEY, WOLVPAY_WEBHOOK_SECRET). Never hard-code, log or send them to the browser.
  3. There is no sandbox. Do not invent a test base URL, test keys or a test_mode parameter. Test with the Webhook Tester and locally signed requests.
  4. Check success first. Errors look like {"success": false, "error": "...", "code": 400, "message": "..."}. Some business-rule errors carry "code": 500; read message.
  5. amount in responses and webhooks is USD, regardless of the currency you sent.
  6. Save invoice_id with your order at creation time. It is the join key for everything else.
  7. Verify the webhook signature on the raw body with HMAC-SHA256 (hex) and a constant-time compare, using the per-endpoint webhook secret.
  8. Then confirm with GET /invoices/{invoice_id} and fulfill only when status === "PAID". A 404 there means ignore the webhook.
  9. Be idempotent. Webhooks can repeat and arrive out of order. Key fulfillment on invoice_id.
  10. Return 2xx fast once handled; return 5xx if your side failed so it can be resent.
  11. POST /invoices is not idempotent. On a timeout, list invoices before retrying.
  12. Respect rate limits: 100 requests/minute per key (429 + X-RateLimit-Reset); 40 invoices/hour and 800/day per account.
  13. 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.

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

StatusDescription
AWAITING_SELECTIONInvoice created, but no cryptocurrency has been selected yet (white-label invoices created without coin).
AWAITING_PAYMENTCryptocurrency selected. Waiting for the customer to pay.
CONFIRMING_PAYMENTA payment was detected and is waiting for blockchain confirmations. Do not fulfill yet.
PAIDPayment confirmed. This is the only status on which you should fulfill the order.
UNDERPAIDPayment received, but the amount is less than required. Review manually.
EXPIREDThe invoice expired (24 hours after creation) without payment.

Errors

WolvPay uses standard HTTP status codes plus a consistent JSON error body.

CodeDescription
200 - OKEverything worked as expected.
201 - CreatedAn invoice was created.
400 - Bad RequestMissing or invalid parameter.
401 - UnauthorizedMissing, malformed or invalid API key.
404 - Not FoundThe invoice (or endpoint) does not exist, or belongs to another account.
429 - Too Many RequestsYou exceeded the per-key rate limit. See Rate Limits.
500 - Server ErrorSomething 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

HTTPmessageWhat to do
401Authorization header is missing.Send Authorization: Bearer <key>.
401Invalid authorization format. Use Authorization: Bearer <your-api-key>.Use the Bearer scheme.
401Invalid API key.Check the key in Dashboard → API Keys.
400Missing required parameter: amountAdd the field to the JSON body.
400Parameter 'amount' must be a positive numberSend a number greater than 0.
404Invoice not found.Wrong ID, or the invoice belongs to another account.
404The requested endpoint does not exist. Please check the URL and try again.Check the path and HTTP method.
429Rate 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

LimitScopeOn exceed
100 requests / minutePer API key429 Too Many Requests with the headers below.
40 invoices / hourPer accountInvoice creation fails with a Rate Limit Exceeded error.
800 invoices / dayPer accountInvoice creation fails with a Rate Limit Exceeded error. Contact support for more.
10 test webhooks / hourPer account (Webhook Tester)The tester refuses until the hour rolls over.

These headers help you track your per-key usage:

HeaderDescription
X-RateLimit-LimitThe maximum number of requests permitted per minute.
X-RateLimit-RemainingRequests remaining in the current rate limit window.
X-RateLimit-ResetTime 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;
}