### Webhook Payload Example

Source: https://wolvpay.com/docs

Example JSON structure of a webhook payload sent by WolvPay for payment events, including invoice details, amounts, and status.

```json
{
  "invoice_id": "inv_4e5a2b3c",
  "amount": 100.00,
  "description": "Invoice for Order #1234",
  "status": "PAID",
  "coin": "BTC",
  "coin_amount": 0.00367,
  "coin_received": 0.00367,
  "coin_address": "1A2b3C4d5E6F7g8H9i0J",
  "redirect_url": "https://example.com/thank-you",
  "created_at": "2023-09-15T14:30:00Z"
}
```

--------------------------------

### Invoice Creation Success Response

Source: https://wolvpay.com/docs

Example of a successful response when creating or selecting a coin for an invoice.

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

--------------------------------

### Create Invoice Response (Basic)

Source: https://wolvpay.com/docs

Example response for a successfully created invoice, including essential details like ID and status.

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

--------------------------------

### Retrieve Invoice Response (Paid)

Source: https://wolvpay.com/docs

Example response when retrieving a paid invoice, showing payment details and confirmation.

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

--------------------------------

### Create Invoice Response (Detailed)

Source: https://wolvpay.com/docs

Example response for a successfully created invoice with detailed payment information, including cryptocurrency specifics.

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

--------------------------------

### Retrieve Invoice Response (Awaiting Selection)

Source: https://wolvpay.com/docs

Example response when retrieving an invoice that is awaiting cryptocurrency selection. It lists available coins.

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

--------------------------------

### Retrieve Invoice Error Response (Not Found)

Source: https://wolvpay.com/docs

Example error response when attempting to retrieve an invoice that does not exist.

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

--------------------------------

### Get Supported Coins

Source: https://wolvpay.com/docs

Retrieves a list of all supported cryptocurrencies and their details, including current prices in various fiat currencies.

```APIDOC
## GET /api/v1/coins

### Description
Retrieves a list of all supported cryptocurrencies and their details.

### Method
GET

### Endpoint
/api/v1/coins

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

#### Response Example
```json
{
  "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"
      }
    }
  ]
}
```

#### Error Response (404)
```json
{
  "success": false,
  "error": "Not Found",
  "code": 404,
  "message": "No coins found."
}
```
```

--------------------------------

### Retrieve Invoice Response (Awaiting Payment - Hosted)

Source: https://wolvpay.com/docs

Example response when retrieving a hosted invoice that is awaiting payment. Includes the payment URL.

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

--------------------------------

### List Invoices Success Response

Source: https://wolvpay.com/docs

Example of a successful response when listing invoices, including invoice details and pagination information.

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

--------------------------------

### Invoice Creation Error Response

Source: https://wolvpay.com/docs

Example of an error response when a required parameter, such as 'coin', is missing during invoice creation.

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

--------------------------------

### Error Response for Get Supported Coins

Source: https://wolvpay.com/docs

This JSON structure represents an error response when no coins are found.

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

--------------------------------

### Create Invoice Error Response

Source: https://wolvpay.com/docs

Example error response when an unsupported or disabled cryptocurrency code is provided during invoice creation.

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

--------------------------------

### Create Invoice Request Body (JSON)

Source: https://wolvpay.com/docs

This is an example of the JSON request body used to create a new payment invoice. It specifies the amount, currency, cryptocurrency, and other optional details.

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

--------------------------------

### Get Supported Coins Response

Source: https://wolvpay.com/docs

This JSON structure represents a successful response when retrieving a list of supported cryptocurrencies and their details from the WolvPay API.

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

--------------------------------

### Verify Webhook Signature in PHP

Source: https://wolvpay.com/docs

Example of how to verify the authenticity of an incoming webhook request in PHP by comparing the computed signature with the one provided in the headers.

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

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

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

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

--------------------------------

### Verify Webhook Signature in Node.js

Source: https://wolvpay.com/docs

Example of how to verify the authenticity of an incoming webhook request in Node.js using crypto module. Ensure to use timingSafeEqual for security.

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

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

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

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

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

--------------------------------

### Update Invoice Request (Select Coin)

Source: https://wolvpay.com/docs

Example request body to update an existing invoice by selecting a cryptocurrency for payment. This is applicable for white-label invoices created without a specified coin.

```json
{
  "coin": "btc"
}
```

--------------------------------

### Verify Webhook Signature in Python (Flask)

Source: https://wolvpay.com/docs

Example of how to verify the authenticity of an incoming webhook request in Python using Flask. It compares the computed HMAC-SHA256 hash with the signature from the headers.

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

app            = Flask(__name__)
webhook_secret = 'your_webhook_secret'

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

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

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

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

--------------------------------

### Create Invoice Request (PHP cURL)

Source: https://wolvpay.com/docs

This PHP code snippet demonstrates how to create a WolvPay invoice using cURL. Ensure you replace '<YOUR_API_KEY>' with your actual API key.

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

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

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

$json = json_decode($response, true);
```

--------------------------------

### Rate Limits

Source: https://wolvpay.com/docs

Details on the WolvPay API rate limits, including the limit per minute and response headers for tracking usage.

```APIDOC
## Rate Limits

The WolvPay API enforces rate limits to maintain reliable service for all users. 
The current limit is **100 requests per minute** per API key. Exceeding this limit returns a `429 Too Many Requests` response. 
The following response headers help you track your rate limit usage:

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

--------------------------------

### Create an Invoice

Source: https://wolvpay.com/docs

Creates a new payment invoice that customers can use to pay with cryptocurrency. Data must be sent as JSON in the request body.

```APIDOC
## POST /api/v1/invoices

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

### Method
POST

### Endpoint
/api/v1/invoices

### Parameters
#### Request Body
- **amount** (number) - Required - The payment amount in the specified currency.
- **currency** (string) - Optional - Currency code (e.g. USD, EUR). Defaults to USD.
- **coin** (string) - Optional - Cryptocurrency to accept (e.g. btc, ltc, erc20_usdc). If omitted, status becomes AWAITING_SELECTION and available_coins is returned.
- **description** (string) - Optional - A description of the payment.
- **white_label** (boolean) - Optional - Whether to use the white-label flow. Defaults to true.
- **redirect_url** (string) - Optional - URL to redirect the customer after payment is completed.

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

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

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

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

$json = json_decode($response, true);
```
```

--------------------------------

### List All Invoices

Source: https://wolvpay.com/docs

Returns a paginated list of invoices you have previously created. Supports filtering by page number and number of invoices per page.

```APIDOC
## List All Invoices

### Description
Returns a paginated list of invoices you have previously created.

### Method
GET

### Endpoint
/api/v1/invoices

### Query Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number to retrieve. Defaults to 1.
- **limit** (integer) - Optional - Invoices per page. Default and maximum is 3.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **result** (string) - A message indicating the outcome of the request.
- **code** (integer) - The HTTP status code.
- **data** (object) - Contains the invoice data and pagination information.
  - **invoices** (array) - A list of invoice objects.
    - **invoice_id** (string) - The unique identifier for the invoice.
    - **amount** (string) - The total amount of the invoice.
    - **description** (string) - A description of the invoice.
    - **status** (string) - The current status of the invoice (e.g., 'AWAITING_PAYMENT').
    - **coin** (string) - The cryptocurrency used for the invoice.
    - **coin_amount** (string) - The amount of cryptocurrency for the invoice.
    - **coin_address** (string) - The cryptocurrency address for payment.
    - **fee_amount_coin** (string) - The fee amount in cryptocurrency.
    - **fee_amount_usd** (string) - The fee amount in USD.
    - **apply_fee** (integer) - Indicates if a fee is applied.
    - **white_label** (integer) - Indicates if white-labeling is applied.
    - **redirect_url** (string) - A URL to redirect the user after payment.
    - **created_at** (string) - The timestamp when the invoice was created.
    - **updated_at** (string) - The timestamp when the invoice was last updated.
  - **pagination** (object) - Contains pagination details.
    - **current_page** (integer) - The current page number.
    - **per_page** (integer) - The number of items per page.
    - **total_items** (integer) - The total number of items available.
    - **total_pages** (integer) - The total number of pages.
    - **has_next** (boolean) - Indicates if there is a next page.
    - **has_previous** (boolean) - Indicates if there is a previous page.
    - **next_page** (integer) - The number of the next page.
    - **previous_page** (integer) - The number of the previous page.

### Request Example
```
GET /api/v1/invoices?page=1&limit=3
```

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

--------------------------------

### Supported Fiat Currencies

Source: https://wolvpay.com/docs

List of fiat currencies supported by WolvPay for invoice amounts. Amounts are converted to cryptocurrency at the time of invoice creation.

```APIDOC
## Supported Fiat Currencies

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

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

--------------------------------

### Webhook Payload Structure

Source: https://wolvpay.com/docs

Details the JSON structure of the payload sent by WolvPay for payment events.

```APIDOC
## Webhook Payload

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

```json
{
  "invoice_id": "inv_4e5a2b3c",
  "amount": 100.00,
  "description": "Invoice for Order #1234",
  "status": "PAID",
  "coin": "BTC",
  "coin_amount": 0.00367,
  "coin_received": 0.00367,
  "coin_address": "1A2b3C4d5E6F7g8H9i0J",
  "redirect_url": "https://example.com/thank-you",
  "created_at": "2023-09-15T14:30:00Z"
}
```
```

--------------------------------

### API Errors

Source: https://wolvpay.com/docs

Information on HTTP response codes used by WolvPay to indicate API request success or failure, and the format of error responses.

```APIDOC
## Errors

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

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

#### Error Response Format
```json
{
  "error": {
    "type": "invalid_request_error",
    "message": "Missing required parameter: amount",
    "code": "missing_parameter",
    "param": "amount"
  }
}
```
```

--------------------------------

### Retrieve an Invoice

Source: https://wolvpay.com/docs

Retrieves the details of an existing invoice using its unique ID. This can be used to check the status and details of an invoice.

```APIDOC
## GET /api/v1/invoices/{invoice_id}

### Description
Retrieves the details of an existing invoice.

### Method
GET

### Endpoint
/api/v1/invoices/{invoice_id}

### Parameters
#### Path Parameters
- **invoice_id** (string) - Required - The ID of the invoice to retrieve.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates whether the request was successful.
- **result** (string) - A descriptive message about the operation result.
- **code** (number) - HTTP status code of the response.
- **data** (object) - Contains the invoice data object.
  - **invoice_id** (string) - Unique identifier for the invoice.
  - **url** (string) - Hosted payment page URL (hosted invoices only).
  - **amount** (number) - Payment amount in the specified fiat currency.
  - **description** (string) - Payment description (null if not provided).
  - **status** (string) - Current invoice status.
  - **coin** (string) - Selected cryptocurrency code (white-label only).
  - **coin_amount** (number) - Amount to pay in the selected cryptocurrency.
  - **coin_received** (number) - Amount received in cryptocurrency.
  - **coin_address** (string) - Address where payment should be sent.
  - **redirect_url** (string) - Post-payment redirect URL (null if not provided).
  - **created_at** (string) - Invoice creation timestamp.
  - **expires_at** (string) - Invoice expiry timestamp.
  - **available_coins** (array) - List of available cryptocurrencies for payment (if applicable).

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

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

#### Response Example (AWAITING_PAYMENT with URL)
{
  "success": true,
  "result": "Invoice retrieved successfully",
  "code": 200,
  "data": {
    "invoice_id": "INV_abc123def456",
    "url": "https://invoices.wolvpay.com/INV_abc123def456",
    "status": "AWAITING_PAYMENT"
  }
}

#### Error Response (404)
{
  "success": false,
  "error": "Not Found",
  "code": 404,
  "message": "Invoice not found."
}
```

--------------------------------

### Webhook Security Verification

Source: https://wolvpay.com/docs

Verifies the authenticity of incoming webhooks by comparing a computed signature with the signature provided in the request header.

```APIDOC
## Webhook Security

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

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

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

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

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

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

### Node.js Example
```javascript
const crypto     = require('crypto');
const express    = require('express');
const bodyParser = require('body-parser');

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

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

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

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

### Python (Flask) Example
```python
import hmac
import hashlib
from flask import Flask, request, abort

app            = Flask(__name__)
webhook_secret = 'your_webhook_secret'

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

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

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

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

--------------------------------

### Update an Invoice

Source: https://wolvpay.com/docs

Updates an existing invoice by selecting a cryptocurrency. This is applicable for white-label invoices created without a specified coin. If a coin is already selected, the invoice cannot be updated.

```APIDOC
## POST /api/v1/invoices/{invoice_id}

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

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

### Method
POST

### Endpoint
/api/v1/invoices/{invoice_id}

### Parameters
#### Path Parameters
- **invoice_id** (string) - Required - The ID of the invoice to update.

#### Request Parameters
- **coin** (string) - Required - Cryptocurrency code to use for payment (e.g. btc, ltc, erc20_usdc). See Supported Currencies.

### Request Example
```json
{
  "coin": "btc"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates whether the request was successful.
- **result** (string) - A descriptive message about the operation result.
- **code** (number) - HTTP status code of the response.
- **data** (object) - Contains the updated invoice data object.
  - **invoice_id** (string) - Unique identifier for the created invoice.
  - **url** (string) - Hosted payment page URL (hosted invoices only).
  - **status** (string) - Current invoice status.

#### Response Example (Hosted Invoice)
```json
{
  "success": true,
  "result": "Invoice created successfully with selected cryptocurrency",
  "code": 201,
  "data": {
    "invoice_id": "INVabc123def456",
    "url": "https://invoices.wolvpay.com/INVabc123def456",
    "status": "AWAITING_PAYMENT"
  }
}
```

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

#### Error Response (400)
{
  "success": false,
  "error": "Bad Request",
  "code": 400,
  "message": "The provided cryptocurrency code is not supported or not enabled."
}
```

--------------------------------

### Error Response Format

Source: https://wolvpay.com/docs

This is the standard JSON structure for API errors. It includes details about the error type, a human-readable message, an error code, and the parameter that caused the error if applicable.

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

--------------------------------

### Invoice Status Values

Source: https://wolvpay.com/docs

The different status values an invoice can have throughout its lifecycle.

```APIDOC
## Invoice Status Values

Invoices transition through the following status values during their lifecycle:

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

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.