POST
/v1/invoices
Create invoice
Creates a payment invoice. Repeating an order_id returns the existing invoice (idempotent).
Body parameters
amount
string
required Amount in USDT, up to 8 decimals. Must meet the network minimum.
order_id
string
Your reference. Unique per merchant — repeated requests return the same invoice.
title
string
Shown to the buyer on the checkout page.
network
string
TRC20, BEP20, TON, POLYGON, ARBITRUM or SOLANA. Omit to let the buyer choose.
fee_payer
string
"buyer" (default) adds fees on top; "merchant" deducts them from your credit.
lifetime_minutes
integer
5–10080. Defaults to 60.
webhook_url
string
HTTPS endpoint for invoice events. Defaults to your dashboard webhook URL.
return_url
string
Where the "Go back to merchant" button leads after payment.
cancel_url
string
Where the buyer goes if they abandon the payment.
metadata
object
Arbitrary JSON echoed back in the invoice and webhooks.
Response 201
{
"uuid": "9b1f2c3e-5a4d-4e8f-9c21-7d3b8e6a1f00",
"status": "pending",
"order_id": "INV-1001",
"title": "Order #1001",
"amount": "10",
"currency": "USDT",
"platform_fee": "0.08",
"network_fee": "0.35",
"pay_amount": "10.43",
"merchant_net": "10",
"fee_payer": "buyer",
"network": "TRC20",
"address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
"memo": null,
"checkout_url": "https://zyvopay.com/pay/9b1f2c3e-5a4d-4e8f-9c21-7d3b8e6a1f00",
"qr_svg": "<svg …>",
"received_amount": "0",
"confirmations": 0,
"required_confirmations": 19,
"tx_hash": null,
"metadata": {
"customer_id": 42
},
"expires_at": "2026-10-16T22:00:00Z",
"paid_at": null,
"created_at": "2026-10-16T21:00:00Z"
}All requests must be signed — see Authentication.
BODY='{"amount":"10.00","order_id":"INV-1001","title":"Order #1001","network":"TRC20","webhook_url":"https://shop.example/zyvopay/webhook","return_url":"https://shop.example/thanks","metadata":{"customer_id":42}}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$ZYVO_SECRET" | cut -d" " -f2)
curl -X POST https://api.zyvopay.com/v1/invoices \
-H "X-Zyvo-Key: $ZYVO_KEY" \
-H "X-Zyvo-Signature: $SIG" \
-H "Content-Type: application/json" \
-d "$BODY"<?php
// composer require guzzlehttp/guzzle
$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.zyvopay.com/v1/']);
$body = json_encode([
'amount' => '10.00',
'order_id' => 'INV-1001',
'title' => 'Order #1001',
'network' => 'TRC20',
'webhook_url' => 'https://shop.example/zyvopay/webhook',
'return_url' => 'https://shop.example/thanks',
'metadata' => [
'customer_id' => 42,
],
]);
$response = $client->request('POST', 'invoices', [
'headers' => [
'X-Zyvo-Key' => getenv('ZYVO_KEY'),
'X-Zyvo-Signature' => hash_hmac('sha256', $body, getenv('ZYVO_SECRET')),
'Content-Type' => 'application/json',
],
'body' => $body,
]);
$data = json_decode((string) $response->getBody(), true);import crypto from 'node:crypto';
const body = JSON.stringify({
"amount": "10.00",
"order_id": "INV-1001",
"title": "Order #1001",
"network": "TRC20",
"webhook_url": "https://shop.example/zyvopay/webhook",
"return_url": "https://shop.example/thanks",
"metadata": {
"customer_id": 42
}
});
const signature = crypto.createHmac('sha256', process.env.ZYVO_SECRET).update(body).digest('hex');
const res = await fetch('https://api.zyvopay.com/v1/invoices', {
method: 'POST',
headers: {
'X-Zyvo-Key': process.env.ZYVO_KEY,
'X-Zyvo-Signature': signature,
'Content-Type': 'application/json',
},
body,
});
console.log(await res.json());import hmac, hashlib, json, os, requests
body = json.dumps({"amount":"10.00","order_id":"INV-1001","title":"Order #1001","network":"TRC20","webhook_url":"https://shop.example/zyvopay/webhook","return_url":"https://shop.example/thanks","metadata":{"customer_id":42}}, separators=(',', ':'))
signature = hmac.new(os.environ['ZYVO_SECRET'].encode(), body.encode(), hashlib.sha256).hexdigest()
r = requests.request('POST', 'https://api.zyvopay.com/v1/invoices', data=body, headers={
'X-Zyvo-Key': os.environ['ZYVO_KEY'],
'X-Zyvo-Signature': signature,
'Content-Type': 'application/json',
})
print(r.json())package main
import (
"bytes"
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"fmt"
"io"
"net/http"
"os"
)
func main() {
body := []byte(`{"amount":"10.00","order_id":"INV-1001","title":"Order #1001","network":"TRC20","webhook_url":"https://shop.example/zyvopay/webhook","return_url":"https://shop.example/thanks","metadata":{"customer_id":42}}`)
mac := hmac.New(sha256.New, []byte(os.Getenv("ZYVO_SECRET")))
mac.Write(body)
req, _ := http.NewRequest("POST", "https://api.zyvopay.com/v1/invoices", bytes.NewReader(body))
req.Header.Set("X-Zyvo-Key", os.Getenv("ZYVO_KEY"))
req.Header.Set("X-Zyvo-Signature", hex.EncodeToString(mac.Sum(nil)))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))
}