List merchant invoices (paginated)
Returns a paginated list of invoices belonging to the authenticated merchant, optionally filtered by status / currency. Each item also includes deal-level info if the customer has already picked a payment method.
curl -X GET "https://api.example.com/v1/api/v1/invoices?page=25&per_page=25&status=pending¤cy=example_string&order=desc" \
-H "Content-Type: application/json" \
-H "X-Api-Key: YOUR_API_KEY"
import requests
import json
url = "https://api.example.com/v1/api/v1/invoices?page=25&per_page=25&status=pending¤cy=example_string&order=desc"
headers = {
"Content-Type": "application/json",
"X-Api-Key": "YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
print(response.json())
const response = await fetch("https://api.example.com/v1/api/v1/invoices?page=25&per_page=25&status=pending¤cy=example_string&order=desc", {
method: "GET",
headers: {
"Content-Type": "application/json",
"X-Api-Key": "YOUR_API_KEY"
}
});
const data = await response.json();
console.log(data);
package main
import (
"fmt"
"net/http"
)
func main() {
req, err := http.NewRequest("GET", "https://api.example.com/v1/api/v1/invoices?page=25&per_page=25&status=pending¤cy=example_string&order=desc", nil)
if err != nil {
panic(err)
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-Api-Key", "YOUR_API_KEY")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
fmt.Println("Response Status:", resp.Status)
}
require 'net/http'
require 'json'
uri = URI('https://api.example.com/v1/api/v1/invoices?page=25&per_page=25&status=pending¤cy=example_string&order=desc')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['Content-Type'] = 'application/json'
request['X-Api-Key'] = 'YOUR_API_KEY'
response = http.request(request)
puts response.body
{
"data": [
{
"amount": "1500.00",
"callback_url": "https://yoursite.com/webhooks/payment",
"created_at": "2026-04-26T12:00:00+00:00",
"currency": "UAH",
"customer_id": "user_12345",
"deal": {
"amount_fiat": "1537.50",
"conversion_rate": "41.50",
"deal_id": "8f1b2c3d-4e5f-6789-90ab-cdef12345678",
"expires_at": "2026-04-26T12:30:00+00:00",
"finished_at": "2026-04-26T12:08:31+00:00",
"mark_paid_at": "2026-04-26T12:07:55+00:00",
"merchant_usdt": "35.42",
"payment_method_code": "monobank",
"payment_method_name": "Monobank UA",
"status": "completed"
},
"expires_at": "2026-04-26T12:20:00+00:00",
"external_id": "order-2026-0001",
"fail_url": "https://yoursite.com/payment/failed",
"finished_at": "2026-04-26T12:08:31+00:00",
"invoice_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"method_selected": true,
"payment_link": "https://pay.app.com/a1b2c3d4-5678-90ab-cdef-1234567890ab",
"purpose": "Payment for Premium subscription",
"status": "success",
"success_url": "https://yoursite.com/payment/success"
}
],
"page": 1,
"per_page": 20,
"successful": true,
"total": 42,
"total_pages": 3
}
{
"successful": false,
"request_id": "a1b2c3d4-...",
"error": {
"code": "API_KEY_MISSING",
"message": "Missing X-Api-Key header"
}
}
{
"successful": false,
"request_id": "a1b2c3d4-...",
"error": {
"code": "API_KEY_INVALID",
"message": "Invalid or inactive API key"
}
}
{
"successful": false,
"request_id": "a1b2c3d4-...",
"error": {
"code": "OWNER_BLOCKED",
"message": "Merchant owner is blocked"
}
}
{
"successful": false,
"request_id": "a1b2c3d4-...",
"error": {
"code": "MERCHANT_BLOCKED",
"message": "Merchant is banned"
}
}
{
"successful": false,
"request_id": "a1b2c3d4-...",
"error": {
"code": "MERCHANT_NOT_ACTIVE",
"message": "Merchant is inactive"
}
}
{
"successful": false,
"request_id": "a1b2c3d4-...",
"error": {
"code": "INVOICES_NOT_FOUND",
"message": "No invoices found for this merchant"
}
}
{
"error": "Unprocessable Entity",
"message": "The request was well-formed but contains semantic errors",
"code": 422,
"details": [
{
"field": "password",
"message": "Password must be at least 8 characters long"
}
]
}
/api/v1/invoices
Page number (1-based)
Items per page (max 500)
Filter by invoice status: pending / success / fail / expired / canceled
Filter by currency code (case-insensitive ISO 4217)
Sort order by created_at
Request Preview
Response
Response will appear here after sending the request
Authentication
API Key for authentication. Merchant API Key.
Query Parameters
Page number (1-based)
Items per page (max 500)
Filter by invoice status: pending / success / fail / expired / canceled
Filter by currency code (case-insensitive ISO 4217)
Responses
Whether the request was successful
Current page number
Items per page
Total invoices matching the filter
Total pages
Internal invoice ID (UUID, == order_id)
External invoice ID set by the merchant at creation time
Customer identifier from the merchant's system
Free-form payment purpose / description
Invoice amount in fiat currency
ISO 4217 currency code
Invoice status: pending — awaiting payment, success — paid, expired — not paid in time, canceled — canceled, fail — failed.
Merchant webhook URL (effective for this invoice)
Customer redirect URL on success
Customer redirect URL on failure
URL to redirect the customer to the payment page
Invoice creation timestamp (ISO 8601 UTC)
Invoice TTL expiration. Note: after the customer picked a method the actual countdown runs at the deal level (deal.expires_at).
Final-state timestamp (ISO 8601 UTC). null while pending.
true if the customer already picked a payment method (deal exists), false if the invoice is still at the method-selection stage.
Deal-level info; null until the customer selects a payment method.
Unique request ID for debugging
Machine-readable error code
Human-readable description
Extra context (varies by error)
Unique request ID for debugging
Machine-readable error code
Human-readable description
Extra context (varies by error)
Unique request ID for debugging
Machine-readable error code
Human-readable description
Extra context (varies by error)
Last updated today
Built with Documentation.AI