Skip to content

На этой странице

Merchant API - Invoices

The merchant block provides API for managing invoices - creation, retrieval, status changes, and configuration.

Interactive Testing

On this page you can test the API in real time! Enter your API key in the field below and click the "Test" buttons to send requests to the server https://cp-merch-dev.wsdemo.online/api.

If you encounter CORS errors:

  • Use the "📋 Copy curl" buttons to get ready-to-use commands
  • Execute commands in terminal or use Postman
  • Install a browser extension to disable CORS (e.g., "CORS Unblock")

Overview

The invoices API allows you to:

  • Create new invoices for payment acceptance
  • Retrieve invoice information
  • Change invoice status
  • Get summary statistics
  • Configure invoice parameters

Authentication

All API requests require authentication via Bearer token in the Authorization header.

POST

Create Invoice

POST /v1/invoices

Creates a new invoice with a payment address with specified parameters.

Параметры

ПараметрТипОбязательныйОписание
currencystringДаUnique coin identifier (e.g., eth, btc)
amountnumberДаNumber of coins in the invoice
externalIdstringНетExternal ID of the invoice

Ответы

201 Created

Invoice successfully created

400 Bad Request

Invalid request parameters

PUT

Change Invoice Status

PUT /v1/invoices

Changes the status of the specified invoice.

Параметры

ПараметрТипОбязательныйОписание
invoiceIdstringДаInvoice ID
statusstringДаNew invoice status

Ответы

201 Created

Status successfully changed

400 Bad Request

Invalid request parameters

GET

Get Invoice List

GET /v1/invoices/getAll

Returns a list of all invoices with filtering and pagination options.

Параметры

ПараметрТипОбязательныйОписание
pagenumberНетPage number (default 1)
perPagenumberНетItems per page (default 20)
statusarrayНетFilter by status
addressstringНетFilter by address
currencystringНетFilter by currency
fromstringНетStart date filter (YYYY-MM-DD)
tostringНетEnd date filter (YYYY-MM-DD)

Ответы

200 OK

Invoice list retrieved

GET

Get Invoice

GET /v1/invoices

Returns information about a specific invoice by its ID.

Параметры

ПараметрТипОбязательныйОписание
idstringДаInvoice ID

Ответы

200 OK

Invoice information retrieved

400 Bad Request

Invalid invoice ID

GET

Get Invoice by External ID

GET /v1/invoices/getByExternalId

Returns information about a specific invoice by its external ID.

Параметры

ПараметрТипОбязательныйОписание
externalIdstringДаExternal invoice ID

Ответы

200 OK

Invoice information retrieved

400 Bad Request

Invalid external ID

GET

Get Summary

GET /v1/invoices/summary

Returns information with the sum of all issued invoices and the sum of all received funds.

Ответы

200 OK

Summary information retrieved

GET

Get Invoice Settings

GET /v1/invoices/configureSettings

Retrieves current invoice configuration settings.

Ответы

200 OK

Settings retrieved

PUT

Configure Invoice Parameters

PUT /v1/invoices/configureSettings

Configures invoice parameters for various networks and currencies.

Параметры

ПараметрТипОбязательныйОписание
settingsobjectДаObject with invoice settings

Ответы

201 Created

Settings successfully updated

400 Bad Request

Invalid parameters

API Configuration

Create Invoice

bash
curl -X POST "https://cp-merch-dev.wsdemo.online/api/v1/invoices" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "eth",
    "amount": 0.001,
    "externalId": "demo_123"
  }'

Response:

json
{
  "id": "inv_abc123def456",
  "address": "0x742d35Cc6634C0532925a3b8D4C9db96590c6C87",
  "amount": "0.001",
  "currency": "eth",
  "externalId": "demo_123"
}

Get Invoice List

bash
curl -X GET "https://cp-merch-dev.wsdemo.online/api/v1/invoices/getAll?page=1&perPage=20" \
  -H "X-Api-Key: YOUR_API_KEY"

Response:

json
{
  "count": 150,
  "data": [
    {
      "id": "inv_abc123def456",
      "address": "0x742d35Cc6634C0532925a3b8D4C9db96590c6C87",
      "amount": "0.001",
      "received": "0.001",
      "currency": "eth",
      "symbol": "ETH",
      "network": "ethereum",
      "status": "completed",
      "createdAt": "2025-01-15T10:30:00Z",
      "externalId": "demo_123",
      "transactions": [
        {
          "id": "tx_123",
          "from": "0x123...",
          "to": "0x742d35Cc6634C0532925a3b8D4C9db96590c6C87",
          "amount": "0.001",
          "hash": "0xabc123...",
          "status": "confirmed",
          "block": 18500000
        }
      ]
    }
  ]
}

Get Invoice by ID

bash
curl -X GET "https://cp-merch-dev.wsdemo.online/api/v1/invoices?id=inv_abc123def456" \
  -H "X-Api-Key: YOUR_API_KEY"

Get Invoice by External ID

bash
curl -X GET "https://cp-merch-dev.wsdemo.online/api/v1/invoices/getByExternalId?externalId=demo_123" \
  -H "X-Api-Key: YOUR_API_KEY"

Get Summary

bash
curl -X GET "https://cp-merch-dev.wsdemo.online/api/v1/invoices/summary" \
  -H "X-Api-Key: YOUR_API_KEY"

Response:

json
[
  {
    "totalAmount": "10.5",
    "totalReceived": "8.3",
    "currencySlug": "btc"
  },
  {
    "totalAmount": "150.0",
    "totalReceived": "142.5",
    "currencySlug": "eth"
  }
]

Change Invoice Status

bash
curl -X PUT "https://cp-merch-dev.wsdemo.online/api/v1/invoices" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceId": "inv_abc123def456",
    "status": "completed"
  }'

Get Invoice Settings

bash
curl -X GET "https://cp-merch-dev.wsdemo.online/api/v1/invoices/configureSettings" \
  -H "X-Api-Key: YOUR_API_KEY"

Go HTTP Client

go
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "time"
)

func main() {
    // Create new invoice
    payload := map[string]interface{}{
        "currency":   "eth",
        "amount":     0.001,
        "externalId": "demo_123",
    }
    
    jsonData, _ := json.Marshal(payload)
    
    req, _ := http.NewRequest("POST", "https://cp-merch-dev.wsdemo.online/api/v1/invoices", bytes.NewBuffer(jsonData))
    req.Header.Set("X-Api-Key", "YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")
    
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
    
    body, _ := io.ReadAll(resp.Body)
    fmt.Printf("Created invoice: %s\n", body)
    
    // Get invoice list
    req2, _ := http.NewRequest("GET", "https://cp-merch-dev.wsdemo.online/api/v1/invoices/getAll?page=1&perPage=20", nil)
    req2.Header.Set("X-Api-Key", "YOUR_API_KEY")
    
    resp2, err := client.Do(req2)
    if err != nil {
        panic(err)
    }
    defer resp2.Body.Close()
    
    body2, _ := io.ReadAll(resp2.Body)
    fmt.Printf("Invoice list: %s\n", body2)
}

Data Structures

go
// Create invoice request
type CreateInvoiceRequest struct {
    Currency   string  `json:"currency"`
    Amount     float64 `json:"amount"`
    ExternalID string  `json:"externalId,omitempty"`
}

// Created invoice response
type CreatedInvoiceResponse struct {
    ID         string `json:"id"`
    Address    string `json:"address"`
    Amount     string `json:"amount"`
    Currency   string `json:"currency"`
    ExternalID string `json:"externalId"`
}

// Invoice information
type InvoiceResponse struct {
    ID          string        `json:"id"`
    Address     string        `json:"address"`
    Amount      string        `json:"amount"`
    Received    string        `json:"received"`
    Overpayment string        `json:"overpayment,omitempty"`
    Currency    string        `json:"currency"`
    Symbol      string        `json:"symbol"`
    Network     string        `json:"network"`
    Status      string        `json:"status"`
    CreatedAt   time.Time     `json:"createdAt"`
    ExternalID  string        `json:"externalId,omitempty"`
    Transactions []Transaction `json:"transactions"`
}

// Transaction
type Transaction struct {
    ID          string    `json:"id"`
    From        string    `json:"from"`
    To          string    `json:"to"`
    Amount      string    `json:"amount"`
    Hash        string    `json:"hash"`
    Status      string    `json:"status"`
    RateUSD     float64   `json:"rate_USD"`
    Block       int64     `json:"block"`
    CreatedDate time.Time `json:"createdDate"`
}

// Summary
type SummaryResponse struct {
    TotalAmount   string `json:"totalAmount"`
    TotalReceived string `json:"totalReceived"`
    CurrencySlug  string `json:"currencySlug"`
}

JavaScript Fetch

javascript
// Create new invoice
const createInvoice = async () => {
  const response = await fetch('https://cp-merch-dev.wsdemo.online/api/v1/invoices', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      currency: 'eth',
      amount: 0.001,
      externalId: 'demo_123'
    })
  });
  
  const invoice = await response.json();
  console.log('Created invoice:', invoice);
  
  // Get invoice list
  const listResponse = await fetch('https://cp-merch-dev.wsdemo.online/api/v1/invoices/getAll?page=1&perPage=20', {
    headers: {
      'X-Api-Key': 'YOUR_API_KEY'
    }
  });
  
  const invoicesList = await listResponse.json();
  console.log('Found invoices:', invoicesList.count);
  
  // Get invoice by ID
  const invoiceResponse = await fetch(`https://cp-merch-dev.wsdemo.online/api/v1/invoices?id=${invoice.id}`, {
    headers: {
      'X-Api-Key': 'YOUR_API_KEY'
    }
  });
  
  const invoiceDetails = await invoiceResponse.json();
  console.log('Invoice status:', invoiceDetails.status);
  
  // Get summary
  const summaryResponse = await fetch('https://cp-merch-dev.wsdemo.online/api/v1/invoices/summary', {
    headers: {
      'X-Api-Key': 'YOUR_API_KEY'
    }
  });
  
  const summary = await summaryResponse.json();
  summary.forEach(s => {
    console.log(`Currency ${s.currencySlug}: issued ${s.totalAmount}, received ${s.totalReceived}`);
  });
};

createInvoice();

Error Handling

javascript
try {
  const response = await fetch('https://cp-merch-dev.wsdemo.online/api/v1/invoices', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      currency: 'eth',
      amount: 0.001
    })
  });
  
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  
  const invoice = await response.json();
  console.log(invoice);
} catch (error) {
  console.error('API error:', error.message);
}

Python Requests

python
import requests
import json

# API configuration
API_BASE = 'https://cp-merch-dev.wsdemo.online/api/v1'
headers = {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

# Create new invoice
payload = {
    'currency': 'eth',
    'amount': 0.001,
    'externalId': 'demo_123'
}

response = requests.post(f'{API_BASE}/invoices', 
                        headers=headers, 
                        json=payload)

if response.status_code == 201:
    invoice = response.json()
    print(f"Created invoice: {invoice['id']}, address: {invoice['address']}")
    
    # Get invoice list
    list_response = requests.get(f'{API_BASE}/invoices/getAll?page=1&perPage=20', 
                                headers=headers)
    
    if list_response.status_code == 200:
        invoices_list = list_response.json()
        print(f"Found invoices: {invoices_list['count']}")
    
    # Get invoice by ID
    invoice_response = requests.get(f'{API_BASE}/invoices?id={invoice["id"]}', 
                                   headers=headers)
    
    if invoice_response.status_code == 200:
        invoice_details = invoice_response.json()
        print(f"Invoice status: {invoice_details['status']}")
    
    # Get summary
    summary_response = requests.get(f'{API_BASE}/invoices/summary', 
                                   headers=headers)
    
    if summary_response.status_code == 200:
        summary = summary_response.json()
        for s in summary:
            print(f"Currency {s['currencySlug']}: issued {s['totalAmount']}, received {s['totalReceived']}")
else:
    print(f"Error: {response.status_code}")

Error Handling

python
try:
    response = requests.post(f'{API_BASE}/invoices', 
                            headers=headers, 
                            json={
                                'currency': 'eth',
                                'amount': 0.001
                            })
    
    response.raise_for_status()  # Raises an HTTPError for bad responses
    invoice = response.json()
    print(invoice)
except requests.exceptions.HTTPError as e:
    print(f"HTTP error: {e}")
except requests.exceptions.RequestException as e:
    print(f"Request error: {e}")

PHP cURL

php
<?php
$apiKey = 'YOUR_API_KEY';
$baseUrl = 'https://cp-merch-dev.wsdemo.online/api/v1';

// Create new invoice
$payload = json_encode([
    'currency' => 'eth',
    'amount' => 0.001,
    'externalId' => 'demo_123'
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl . '/invoices');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Api-Key: ' . $apiKey,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 201) {
    $invoice = json_decode($response, true);
    echo "Created invoice: " . $invoice['id'] . ", address: " . $invoice['address'] . "\n";
    
    // Get invoice list
    $ch2 = curl_init();
    curl_setopt($ch2, CURLOPT_URL, $baseUrl . '/invoices/getAll?page=1&perPage=20');
    curl_setopt($ch2, CURLOPT_HTTPHEADER, [
        'X-Api-Key: ' . $apiKey
    ]);
    curl_setopt($ch2, CURLOPT_RETURNTRANSFER, true);
    
    $listResponse = curl_exec($ch2);
    $listHttpCode = curl_getinfo($ch2, CURLINFO_HTTP_CODE);
    curl_close($ch2);
    
    if ($listHttpCode === 200) {
        $invoicesList = json_decode($listResponse, true);
        echo "Found invoices: " . $invoicesList['count'] . "\n";
    }
    
    // Get summary
    $ch3 = curl_init();
    curl_setopt($ch3, CURLOPT_URL, $baseUrl . '/invoices/summary');
    curl_setopt($ch3, CURLOPT_HTTPHEADER, [
        'X-Api-Key: ' . $apiKey
    ]);
    curl_setopt($ch3, CURLOPT_RETURNTRANSFER, true);
    
    $summaryResponse = curl_exec($ch3);
    $summaryHttpCode = curl_getinfo($ch3, CURLINFO_HTTP_CODE);
    curl_close($ch3);
    
    if ($summaryHttpCode === 200) {
        $summary = json_decode($summaryResponse, true);
        foreach ($summary as $s) {
            echo "Currency {$s['currencySlug']}: issued {$s['totalAmount']}, received {$s['totalReceived']}\n";
        }
    }
} else {
    echo "Error: " . $httpCode . "\n";
}
?>

Error Handling

php
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl . '/invoices');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'currency' => 'eth',
    'amount' => 0.001
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Api-Key: ' . $apiKey,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if (curl_errno($ch)) {
    echo 'cURL error: ' . curl_error($ch) . "\n";
} elseif ($httpCode >= 400) {
    echo "HTTP error: " . $httpCode . "\n";
    echo "Response: " . $response . "\n";
} else {
    $invoice = json_decode($response, true);
    print_r($invoice);
}

curl_close($ch);
?>

Released under the MIT License.