Get a single merchant invoice by order_id or external_id
Returns a single invoice (and the linked deal, if any) belonging to the authenticated merchant.
invoice_ref accepts either:
- our internal
order_id(UUID assigned by the platform), or - the merchant's own
external_id(whatever the merchant supplied at invoice creation).
Lookup is scoped to the authenticated merchant, so an external_id from another merchant cannot be retrieved. order_id is tried first; if no match is found, external_id is tried next.
Returns 404 if neither lookup matches.
curl -X GET "https://api.example.com/v1/api/v1/invoices/example_string" \
-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/example_string"
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/example_string", {
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/example_string", 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/example_string')
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
{
"successful": true,
"data": {
"invoice_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"external_id": "order-2026-0001",
"customer_id": "user_12345",
"purpose": "example_string",
"amount": "1500.00",
"currency": "UAH",
"status": "example_string",
"callback_url": "example_string",
"success_url": "example_string",
"fail_url": "example_string",
"payment_link": "example_string",
"created_at": "example_string",
"expires_at": "example_string",
"finished_at": "example_string",
"method_selected": true,
"deal": {
"deal_id": "8f1b2c3d-4e5f-6789-90ab-cdef12345678",
"status": "example_string",
"sub_status": "example_string",
"payment_method_code": "monobank",
"payment_method_name": "Monobank UA",
"amount_fiat": "example_string",
"conversion_rate": "example_string",
"merchant_usdt": "example_string",
"expires_at": "example_string",
"finished_at": "example_string",
"mark_paid_at": "example_string"
}
}
}
{
"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": "INVOICE_NOT_FOUND",
"message": "Invoice not found"
}
}
{
"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/{invoice_ref}Invoice identifier — either our order_id (UUID) or the merchant's external_id
Request Preview
Response
Response will appear here after sending the request
Authentication
API Key for authentication. Merchant API Key.
Path Parameters
Invoice identifier — either our order_id (UUID) or the merchant's external_id
Responses
Whether the request was successful
Full invoice info as exposed via merchant external API.
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