API documentation

Accept USDT and other cryptocurrencies through a REST API: create invoices, issue static addresses, receive signed webhooks and withdraw funds.

Introduction

The API lets you create invoices payable in cryptocurrency, issue static deposit addresses, receive payment notifications and withdraw funds. All requests use HTTPS; request and response bodies are UTF-8 encoded JSON.

Base URLhttps://paymeusd.com
  • Amounts are sent and returned as strings ("49.90") to preserve precision.
  • Dates use ISO 8601, UTC.
  • Assets are written as network:SYMBOL: tron:USDT, bsc:USDT, bitcoin:BTC.

Quick start

  1. Get an API key. Sign up and create a key in the dashboard: Integration → API keys.
  2. Create an invoice with POST /v1/invoices and redirect the customer to payment_url.
  3. Handle the webhook. Accept invoice.paid at your url_callback, verify the signature and fulfil the order.

The customer picks the coin and network on the payment page, and the exchange rate is locked for the lifetime of the invoice.

Authentication

Pass your secret key in the Authorization header:

Authorization: Bearer sk_live_9fQ…
  • sk_live_… is a live key, sk_test_… is a test-mode key.
  • A key grants full access to the account, including withdrawals. Keep it on your server only — never in a browser or a mobile app.
  • The key is shown only once, when it is created. If a key is compromised, revoke it in the dashboard — it stops working immediately.

Errors

On error, the API returns an HTTP 4xx/5xx status and a body like this:

{ "error": "insufficient_balance", "message": "insufficient USDT balance (152 required including the fee)" }

error is a stable machine-readable code — base your logic on it. message is a human-readable description and may change.

Languagemessage is in Russian by default. Send the Accept-Language: en header to get it in English. The error code is the same in every language.
HTTPCodeWhen
400validation_errorInvalid request parameters
400unsupported_currency, unknown_asset, asset_not_allowedThe currency or asset is not supported
400invalid_address, amount_too_small, insufficient_balancePayout errors
401unauthorizedThe key is missing, invalid or revoked, or the account is not active
404not_foundThe object does not exist or belongs to another account
400invalid_idempotency_keyThe Idempotency-Key header is empty, longer than 255 characters or contains non-printable or non-ASCII characters
409order_existsThis order_id already exists with different parameters
409idempotency_in_progressA request with this Idempotency-Key is still in progress — retry in a few seconds
422idempotency_key_mismatchThis Idempotency-Key has already been used with a different request — use a new key
409invoice_lockedThe invoice can no longer be changed or cancelled
409nothing_to_refundNothing to refund for this invoice: no payments, or everything has already been refunded
400refund_too_largeThe refund amount exceeds the amount received for the invoice
400batch_invalidThe batch payout was not created: invalid rows or insufficient balance — see details
403address_not_whitelisted, address_not_active_yetThe payout address whitelist is on: the address is not on the list or is not active yet (new addresses become active after 24 h)
403refund_requires_cabinetWith the whitelist on, refunds can only be made from the dashboard
429rate_limitedToo many requests — retry after the time given in the message
500internal_errorFailure on the service side — retry later; if it persists, contact support
503rate_unavailable, network_unavailableThe exchange rate is temporarily unavailable or the network is down — retry later

Idempotency

Any POST request to /v1/… can be safely retried after a network error or a timeout if you send the Idempotency-Key header — a unique string you generate for each operation (a UUID v4 works well) and repeat in every attempt of that operation:

POST /v1/payouts
Authorization: Bearer sk_live_9fQ…
Idempotency-Key: 5f0c8d1e-3b7a-4c2e-9f61-2a8d4e7b1c03
  • The first request is processed as usual, and its response (status code and body) is saved. A retry with the same key and the same parameters is not processed again: it receives the saved response with the Idempotent-Replayed: true header — no second invoice, payout or refund is created.
  • A key is scoped to your account and kept for 24 hours; after that it can be used again.
  • The same key with a different method, path or request body returns 422 idempotency_key_mismatch: a new operation needs a new key.
  • While the first request with this key is still in progress, a retry receives 409 idempotency_in_progress — retry in a few seconds. If the first request was interrupted by a failure on the service side, the key is released for a retry after a couple of minutes.
  • 2xx and 4xx responses are saved: a retry returns the same error — fix the request and send it with a new key. 5xx responses are not saved: a retry with the same key processes the request again.
  • A key is 1 to 255 printable ASCII characters, otherwise 400 invalid_idempotency_key. GET requests do not need the header and ignore it.
  • The official SDKs (Node.js, Python, PHP) send a key automatically and, on failure, retry POST requests with the same key.

We especially recommend a key for payouts and refunds — they move money.

Retries by order_id

Even without the header, repeating a request with the same order_id and the same parameters does not create a new invoice or payout — it returns the existing object. If the parameters differ (another amount or address), the API returns 409 order_exists.

The exception is expired or cancelled invoices: they release the order number. If the customer comes back after the invoice has expired, create an invoice with the same order_id — you get a new invoice with a new id (the amount may change). Old invoices stay in the history and can be found with GET /v1/invoices?order_id=….

Invoices

An invoice is a request to pay a specific amount. The customer opens payment_url, selects a coin and network and sends funds to a unique address. Once the network confirms the transfer, the amount minus the fee is credited to your balance.

pending→confirming→paid
StatusMeaning
pendingAwaiting payment
confirmingPayment detected, waiting for network confirmations
partialPart of the amount received; the customer can pay the rest before the invoice expires
paid / paid_overPaid in full / overpaid — you can fulfil the order
underpaidExpired with only part of the amount received
expiredExpired without payment
cancelledCancelled by you

Payments that arrive after the invoice expires, and payments in another coin, are credited to your balance as well — you receive a payment.confirmed webhook with kind = late or unexpected.

Invoice object

Returned by all invoice methods and delivered in invoice.* webhooks.

idstring
Invoice ID (UUID).
order_idstring
Your order number. Unique among invoices that have not expired; once an invoice expires or is cancelled, you can create a new invoice with the same number.
statusstring
Invoice status: pending, confirming, partial, paid, paid_over, underpaid, expired, cancelled.
is_finalboolean
true — the status will not change anymore.
amountstring
Invoice amount in currency.
currencystring
Invoice currency: fiat (USD, EUR…) or crypto (USDT, BTC…).
amount_usdstring
Amount equivalent in US dollars at the rate when the coin was selected.
descriptionstring | null
Description shown to the customer.
assetstring | null
Selected asset as network:SYMBOL, e.g. tron:USDT. null until the customer chooses.
networkstring | null
Network ID (tron, ethereum, bsc…).
network_namestring | null
Human-readable network name.
symbolstring | null
Ticker of the selected coin.
token_standardstring | null
Token standard: TRC-20, ERC-20, BEP-20, SPL… null for native coins.
pay_amountstring | null
Amount to send in the selected coin.
paid_amountstring
Amount confirmed by the network.
pending_amountstring
Amount detected but not yet confirmed.
remaining_amountstring | null
Amount still to be paid.
addressstring | null
Payment address — unique per invoice (except TON).
memostring | null
Transfer comment — required for TON.
payment_uristring | null
URI for a QR code (bitcoin:, solana:, ton://) or the plain address.
required_confirmationsinteger | null
Network confirmations required before the payment is credited.
fee_levelstring | null
Network fee level for the customer: low, medium, high.
settle_secinteger | null
Estimated time until the payment is credited, in seconds.
rate_usdstring | null
USD rate of the selected coin, locked when the coin was selected.
currency_is_fiatboolean
The invoice currency is fiat.
payment_urlstring
Payment page URL — redirect the customer here.
url_successstring | null
Where to send the customer after payment.
url_returnstring | null
Where to send the customer if they leave without paying.
expires_atstring
Payment deadline (ISO 8601).
paid_atstring | null
When the invoice was paid.
created_atstring
When the invoice was created.
metadataobject | null
Your data passed at creation.
customerobject | null
Buyer details for the invoice and receipt: {name, company, tax_id, address, email} (empty ones are null). null — no buyer specified. email — from the shop or entered by the buyer on the payment page.
documentsobject
Documents for the buyer — print-ready pages that can be saved as PDF, in the invoice language (?lang= for another one): invoice_url — the invoice (always present), receipt_url — the payment receipt (null until the invoice is paid: paid / paid_over). Links use your own domain if one is connected. Seller details are set in the dashboard: “Branding” → “Business details for invoices and receipts”.
regionstring | null
Region of the payment link, if set at creation: ru or global. null — as in the store settings.
payment_urlsobject
Payment page URL in every region where the service has a domain: {ru, global}. Useful if you know the customer’s country yourself. An empty object means no regional domains are configured.
langstring | null
Payment page language passed at creation (en, ru, pt…). null — picked from the customer’s browser.
buyer_countrystring | null
Client country (ISO 3166-1 alpha-2), if set at creation. null — the country is detected from the customer.
p2p_methodsstring[] | null
Additional payment methods of the invoice (if the service administrator enabled them for you): method IDs set at creation. null — all available, [] — none.
p2p_currencystring
Which currency the customer pays in with the additional payment methods: invoice — only in the invoice currency, convert — in the customer’s currency at the rate. The effective value: the one set at creation, otherwise the store setting; if there are no such methods in the invoice currency — convert.
crypto_offboolean
true — crypto payment is turned off for this invoice (crypto: false was passed at creation).
themestring | null
Payment page theme, if set at creation: light or dark. null — as in the store branding.
paymentsPayment[]
Incoming payments for the invoice.
refunded_amountstring
Amount refunded (or being refunded) to the customer, in the invoice coin.
refundsPayout[]
Refunds for the invoice — Payout objects with kind: "refund".
Example
{
  "id": "6722fb9d-ed9e-4710-9f08-c9b63600b25a",
  "order_id": "1001",
  "amount": "49.9",
  "currency": "EUR",
  "amount_usd": "55.24",
  "description": "Payment for order 1001",
  "currency_is_fiat": true,
  "payment_url": "https://paymeusd.com/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a",
  "url_success": "https://shop.example/thanks",
  "url_return": null,
  "expires_at": "2026-11-13T10:04:05.253Z",
  "created_at": "2026-11-13T09:04:05.253Z",
  "metadata": {
    "user_id": 42
  },
  "lang": null,
  "region": null,
  "payment_urls": {
    "ru": "https://pay-shop.ru/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a",
    "global": "https://paymeusd.com/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a"
  },
  "buyer_country": null,
  "p2p_methods": null,
  "p2p_currency": "convert",
  "crypto_off": false,
  "theme": null,
  "customer": {
    "name": null,
    "company": "Acme GmbH",
    "tax_id": "DE123456789",
    "address": null,
    "email": "billing@acme.example"
  },
  "documents": {
    "invoice_url": "https://paymeusd.com/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a/invoice",
    "receipt_url": "https://paymeusd.com/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a/receipt"
  },
  "status": "paid",
  "is_final": true,
  "network": "tron",
  "network_name": "TRON",
  "token_standard": "TRC-20",
  "asset": "tron:USDT",
  "symbol": "USDT",
  "pay_amount": "55.24",
  "paid_amount": "55.24",
  "pending_amount": "0",
  "remaining_amount": "0",
  "address": "TTRfafDmUho6qSvPUxJ5c8aq7Rp121Ukat",
  "memo": null,
  "payment_uri": "TTRfafDmUho6qSvPUxJ5c8aq7Rp121Ukat",
  "required_confirmations": 19,
  "fee_level": "medium",
  "settle_sec": 57,
  "rate_usd": "1",
  "paid_at": "2026-11-13T09:05:28.416Z",
  "payments": [
    {
      "id": "82a1a806-9162-4a3f-9109-e927ed7d6206",
      "network": "tron",
      "network_name": "TRON",
      "asset": "tron:USDT",
      "currency": "USDT",
      "amount": "55.24",
      "tx_hash": "b1f3c8a95e0d4a7c9e2f6b3d1a8c7e5f4b2d9a6c3e1f8b7a5d4c2e9f6b3a1d8c",
      "from": "TPyjyZfsYaXStgz2NmAraF1uZcMtkgNan5",
      "confirmations": 19,
      "required_confirmations": 19,
      "status": "confirmed",
      "kind": "invoice",
      "fee": "0.5524",
      "credited_amount": "54.6876",
      "explorer_url": "https://tronscan.org/#/transaction/b1f3c8a95e0d4a7c9e2f6b3d1a8c7e5f4b2d9a6c3e1f8b7a5d4c2e9f6b3a1d8c",
      "detected_at": "2026-11-13T09:04:31.112Z",
      "confirmed_at": "2026-11-13T09:05:28.416Z"
    }
  ],
  "refunded_amount": "0",
  "refunds": []
}

Create an invoice

POST/v1/invoices

Creates an invoice and returns a payment page link. The amount can be set in fiat — it is converted into the coin the customer selects at the current rate.

Request body

amountstringrequired
Amount, e.g. "49.90".
currencystringrequired
Currency of the amount: USD, EUR, RUB, UAH, KZT, GBP, TRY or a coin ticker (USDT, BTC…).
order_idstringrequired
Your unique order number (up to 128 characters). Ensures idempotency.
lifetime_minutesinteger
Payment window: 5 to 43200 minutes (30 days). Default: 60. For invoices longer than a day the coin amount is valid for 60 minutes after the coin is chosen; if the customer comes back later it is re-quoted at the current rate, and a payment detected more than 30 minutes after that window is counted at the rate at the time it is credited.
assetstring
Preselect the coin and network, e.g. tron:USDT — the customer sees the payment details without the selection step.
allowed_assetsstring[]
Restrict the payment options, e.g. ["tron:USDT","bsc:USDT"].
descriptionstring
Description for the customer (up to 500 characters).
url_callbackstring
Webhook URL for this invoice. Defaults to the URL set in the dashboard.
url_successstring
“Back to store” button after payment.
url_returnstring
Return button for customers who leave without paying.
metadataobject
Arbitrary data — returned in responses and webhooks.
regionstring
Which region’s domain to use in payment_url: ru — for customers in Russia (via a server in Russia), global — for everyone else (via Cloudflare). Defaults to the store setting “Where are your customers”.
langstring
Payment page language: en, ru, uk, kk, uz, az, es, pt (Brazil), fr, de, it, pl, tr, ar, fa, hi, id, vi, th, zh (Simplified), ja, ko. A region suffix is allowed (pt-BR). Unsupported languages are ignored. The customer can switch the language on the page.
customerobject
Buyer details for the invoice and payment receipt (all fields optional): name — contact person (up to 200 characters), company — company (up to 200), tax_id — tax ID: VAT ID, EIN… (up to 64), address — address (up to 500), email — a link to the receipt is sent there after payment (once, in the lang language). Without email, the payment page asks the buyer for it before they choose a payment method and saves it to customer.email.
buyer_countrystring
Client country — a two-letter ISO 3166-1 code (RU, KZ…). If additional payment methods by country are enabled for your store, the customer sees only this country’s methods — regardless of their IP and time zone.
p2p_methodsstring[]
Which additional payment methods to show (if enabled for your store): method IDs or codes. Omitted — all available for the customer’s country, [] — none.
p2p_currencystring
Additional payment methods: invoice — only in the invoice currency, without conversion (a USD invoice is paid in USD); convert — in the customer’s currency at the rate (a customer from a country with its own currency pays in it). Omitted — as in the store settings (convert by default). If there are no such methods in the invoice currency, convert applies.
cryptoboolean
false — no crypto payment: only the additional payment methods, if enabled (otherwise the no_payment_methods error). Default: true.
themestring
Payment page theme: light or dark. Defaults to the store branding (dashboard → “Branding”).

Response

Object Invoice.

Errors

validation_error unsupported_currency unknown_asset invalid_country no_payment_methods order_exists rate_unavailable

Request
curl -X POST "https://paymeusd.com/v1/invoices" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "49.90",
  "currency": "EUR",
  "order_id": "1001",
  "description": "Payment for order 1001",
  "url_callback": "https://shop.example/webhooks/crypto",
  "url_success": "https://shop.example/thanks",
  "metadata": {
    "user_id": 42
  },
  "customer": {
    "company": "Acme GmbH",
    "tax_id": "DE123456789",
    "email": "billing@acme.example"
  }
}'
const res = await fetch('https://paymeusd.com/v1/invoices', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "amount": "49.90",
    "currency": "EUR",
    "order_id": "1001",
    "description": "Payment for order 1001",
    "url_callback": "https://shop.example/webhooks/crypto",
    "url_success": "https://shop.example/thanks",
    "metadata": {
      "user_id": 42
    },
    "customer": {
      "company": "Acme GmbH",
      "tax_id": "DE123456789",
      "email": "billing@acme.example"
    }
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/v1/invoices');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
      'amount' => "49.90",
      'currency' => "EUR",
      'order_id' => "1001",
      'description' => "Payment for order 1001",
      'url_callback' => "https://shop.example/webhooks/crypto",
      'url_success' => "https://shop.example/thanks",
      'metadata' => ['user_id' => 42],
      'customer' => ['company' => "Acme GmbH", 'tax_id' => "DE123456789", 'email' => "billing@acme.example"],
  ]),
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.post(
    "https://paymeusd.com/v1/invoices",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
        "amount": "49.90",
        "currency": "EUR",
        "order_id": "1001",
        "description": "Payment for order 1001",
        "url_callback": "https://shop.example/webhooks/crypto",
        "url_success": "https://shop.example/thanks",
        "metadata": {
            "user_id": 42
        },
        "customer": {
            "company": "Acme GmbH",
            "tax_id": "DE123456789",
            "email": "billing@acme.example"
        }
    },
)
res.raise_for_status()
data = res.json()
Response 201
{
  "id": "6722fb9d-ed9e-4710-9f08-c9b63600b25a",
  "order_id": "1001",
  "amount": "49.9",
  "currency": "EUR",
  "amount_usd": "55.24",
  "description": "Payment for order 1001",
  "currency_is_fiat": true,
  "payment_url": "https://paymeusd.com/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a",
  "url_success": "https://shop.example/thanks",
  "url_return": null,
  "expires_at": "2026-11-13T10:04:05.253Z",
  "created_at": "2026-11-13T09:04:05.253Z",
  "metadata": {
    "user_id": 42
  },
  "lang": null,
  "region": null,
  "payment_urls": {
    "ru": "https://pay-shop.ru/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a",
    "global": "https://paymeusd.com/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a"
  },
  "buyer_country": null,
  "p2p_methods": null,
  "p2p_currency": "convert",
  "crypto_off": false,
  "theme": null,
  "customer": {
    "name": null,
    "company": "Acme GmbH",
    "tax_id": "DE123456789",
    "address": null,
    "email": "billing@acme.example"
  },
  "documents": {
    "invoice_url": "https://paymeusd.com/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a/invoice",
    "receipt_url": null
  },
  "status": "pending",
  "is_final": false,
  "network": null,
  "network_name": null,
  "token_standard": null,
  "asset": null,
  "symbol": null,
  "pay_amount": null,
  "paid_amount": "0",
  "pending_amount": "0",
  "remaining_amount": null,
  "address": null,
  "memo": null,
  "payment_uri": null,
  "required_confirmations": null,
  "fee_level": null,
  "settle_sec": null,
  "rate_usd": null,
  "paid_at": null,
  "payments": [],
  "refunded_amount": "0",
  "refunds": []
}

Retrieve an invoice

GET/v1/invoices/{id}

Current state of the invoice with all its payments.

Path parameters

idstringrequired
Invoice ID.

Response

Object Invoice.

Errors

not_found

Request
curl "https://paymeusd.com/v1/invoices/6722fb9d-ed9e-4710-9f08-c9b63600b25a" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch('https://paymeusd.com/v1/invoices/6722fb9d-ed9e-4710-9f08-c9b63600b25a', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/v1/invoices/6722fb9d-ed9e-4710-9f08-c9b63600b25a');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('API_KEY'),
  ],
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.get(
    "https://paymeusd.com/v1/invoices/6722fb9d-ed9e-4710-9f08-c9b63600b25a",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
Response 200
{
  "id": "6722fb9d-ed9e-4710-9f08-c9b63600b25a",
  "order_id": "1001",
  "amount": "49.9",
  "currency": "EUR",
  "amount_usd": "55.24",
  "description": "Payment for order 1001",
  "currency_is_fiat": true,
  "payment_url": "https://paymeusd.com/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a",
  "url_success": "https://shop.example/thanks",
  "url_return": null,
  "expires_at": "2026-11-13T10:04:05.253Z",
  "created_at": "2026-11-13T09:04:05.253Z",
  "metadata": {
    "user_id": 42
  },
  "lang": null,
  "region": null,
  "payment_urls": {
    "ru": "https://pay-shop.ru/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a",
    "global": "https://paymeusd.com/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a"
  },
  "buyer_country": null,
  "p2p_methods": null,
  "p2p_currency": "convert",
  "crypto_off": false,
  "theme": null,
  "customer": {
    "name": null,
    "company": "Acme GmbH",
    "tax_id": "DE123456789",
    "address": null,
    "email": "billing@acme.example"
  },
  "documents": {
    "invoice_url": "https://paymeusd.com/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a/invoice",
    "receipt_url": "https://paymeusd.com/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a/receipt"
  },
  "status": "paid",
  "is_final": true,
  "network": "tron",
  "network_name": "TRON",
  "token_standard": "TRC-20",
  "asset": "tron:USDT",
  "symbol": "USDT",
  "pay_amount": "55.24",
  "paid_amount": "55.24",
  "pending_amount": "0",
  "remaining_amount": "0",
  "address": "TTRfafDmUho6qSvPUxJ5c8aq7Rp121Ukat",
  "memo": null,
  "payment_uri": "TTRfafDmUho6qSvPUxJ5c8aq7Rp121Ukat",
  "required_confirmations": 19,
  "fee_level": "medium",
  "settle_sec": 57,
  "rate_usd": "1",
  "paid_at": "2026-11-13T09:05:28.416Z",
  "payments": [
    {
      "id": "82a1a806-9162-4a3f-9109-e927ed7d6206",
      "network": "tron",
      "network_name": "TRON",
      "asset": "tron:USDT",
      "currency": "USDT",
      "amount": "55.24",
      "tx_hash": "b1f3c8a95e0d4a7c9e2f6b3d1a8c7e5f4b2d9a6c3e1f8b7a5d4c2e9f6b3a1d8c",
      "from": "TPyjyZfsYaXStgz2NmAraF1uZcMtkgNan5",
      "confirmations": 19,
      "required_confirmations": 19,
      "status": "confirmed",
      "kind": "invoice",
      "fee": "0.5524",
      "credited_amount": "54.6876",
      "explorer_url": "https://tronscan.org/#/transaction/b1f3c8a95e0d4a7c9e2f6b3d1a8c7e5f4b2d9a6c3e1f8b7a5d4c2e9f6b3a1d8c",
      "detected_at": "2026-11-13T09:04:31.112Z",
      "confirmed_at": "2026-11-13T09:05:28.416Z"
    }
  ],
  "refunded_amount": "0",
  "refunds": []
}

List invoices

GET/v1/invoices

Invoices, newest first. Handy for looking up an invoice by your order number.

Query parameters

order_idstring
Find an invoice by your order number.
statusstring
Filter by status.
limitinteger
1 to 100, default 20.

Response

An object with an items list.

Request
curl "https://paymeusd.com/v1/invoices?order_id=1001" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch('https://paymeusd.com/v1/invoices?order_id=1001', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/v1/invoices?order_id=1001');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('API_KEY'),
  ],
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.get(
    "https://paymeusd.com/v1/invoices?order_id=1001",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
Response 200
{
  "items": [
    {
      "id": "6722fb9d-ed9e-4710-9f08-c9b63600b25a",
      "order_id": "1001",
      "amount": "49.9",
      "currency": "EUR",
      "amount_usd": "55.24",
      "description": "Payment for order 1001",
      "currency_is_fiat": true,
      "payment_url": "https://paymeusd.com/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a",
      "url_success": "https://shop.example/thanks",
      "url_return": null,
      "expires_at": "2026-11-13T10:04:05.253Z",
      "created_at": "2026-11-13T09:04:05.253Z",
      "metadata": {
        "user_id": 42
      },
      "lang": null,
      "region": null,
      "payment_urls": {
        "ru": "https://pay-shop.ru/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a",
        "global": "https://paymeusd.com/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a"
      },
      "buyer_country": null,
      "p2p_methods": null,
      "p2p_currency": "convert",
      "crypto_off": false,
      "theme": null,
      "customer": {
        "name": null,
        "company": "Acme GmbH",
        "tax_id": "DE123456789",
        "address": null,
        "email": "billing@acme.example"
      },
      "documents": {
        "invoice_url": "https://paymeusd.com/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a/invoice",
        "receipt_url": "https://paymeusd.com/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a/receipt"
      },
      "status": "paid",
      "is_final": true,
      "network": "tron",
      "network_name": "TRON",
      "token_standard": "TRC-20",
      "asset": "tron:USDT",
      "symbol": "USDT",
      "pay_amount": "55.24",
      "paid_amount": "55.24",
      "pending_amount": "0",
      "remaining_amount": "0",
      "address": "TTRfafDmUho6qSvPUxJ5c8aq7Rp121Ukat",
      "memo": null,
      "payment_uri": "TTRfafDmUho6qSvPUxJ5c8aq7Rp121Ukat",
      "required_confirmations": 19,
      "fee_level": "medium",
      "settle_sec": 57,
      "rate_usd": "1",
      "paid_at": "2026-11-13T09:05:28.416Z",
      "payments": [
        {
          "id": "82a1a806-9162-4a3f-9109-e927ed7d6206",
          "network": "tron",
          "network_name": "TRON",
          "asset": "tron:USDT",
          "currency": "USDT",
          "amount": "55.24",
          "tx_hash": "b1f3c8a95e0d4a7c9e2f6b3d1a8c7e5f4b2d9a6c3e1f8b7a5d4c2e9f6b3a1d8c",
          "from": "TPyjyZfsYaXStgz2NmAraF1uZcMtkgNan5",
          "confirmations": 19,
          "required_confirmations": 19,
          "status": "confirmed",
          "kind": "invoice",
          "fee": "0.5524",
          "credited_amount": "54.6876",
          "explorer_url": "https://tronscan.org/#/transaction/b1f3c8a95e0d4a7c9e2f6b3d1a8c7e5f4b2d9a6c3e1f8b7a5d4c2e9f6b3a1d8c",
          "detected_at": "2026-11-13T09:04:31.112Z",
          "confirmed_at": "2026-11-13T09:05:28.416Z"
        }
      ],
      "refunded_amount": "0",
      "refunds": []
    }
  ]
}

Cancel an invoice

POST/v1/invoices/{id}/cancel

Cancels a pending invoice that has not received any payments yet.

Path parameters

idstringrequired
Invoice ID.

Response

Object Invoice.

Errors

not_found invoice_locked

Request
curl -X POST "https://paymeusd.com/v1/invoices/6722fb9d-ed9e-4710-9f08-c9b63600b25a/cancel" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch('https://paymeusd.com/v1/invoices/6722fb9d-ed9e-4710-9f08-c9b63600b25a/cancel', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/v1/invoices/6722fb9d-ed9e-4710-9f08-c9b63600b25a/cancel');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('API_KEY'),
  ],
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.post(
    "https://paymeusd.com/v1/invoices/6722fb9d-ed9e-4710-9f08-c9b63600b25a/cancel",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
Response 200
{
  "id": "6722fb9d-ed9e-4710-9f08-c9b63600b25a",
  "order_id": "1001",
  "amount": "49.9",
  "currency": "EUR",
  "amount_usd": "55.24",
  "description": "Payment for order 1001",
  "currency_is_fiat": true,
  "payment_url": "https://paymeusd.com/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a",
  "url_success": "https://shop.example/thanks",
  "url_return": null,
  "expires_at": "2026-11-13T10:04:05.253Z",
  "created_at": "2026-11-13T09:04:05.253Z",
  "metadata": {
    "user_id": 42
  },
  "lang": null,
  "region": null,
  "payment_urls": {
    "ru": "https://pay-shop.ru/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a",
    "global": "https://paymeusd.com/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a"
  },
  "buyer_country": null,
  "p2p_methods": null,
  "p2p_currency": "convert",
  "crypto_off": false,
  "theme": null,
  "customer": {
    "name": null,
    "company": "Acme GmbH",
    "tax_id": "DE123456789",
    "address": null,
    "email": "billing@acme.example"
  },
  "documents": {
    "invoice_url": "https://paymeusd.com/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a/invoice",
    "receipt_url": null
  },
  "status": "cancelled",
  "is_final": true,
  "network": null,
  "network_name": null,
  "token_standard": null,
  "asset": null,
  "symbol": null,
  "pay_amount": null,
  "paid_amount": "0",
  "pending_amount": "0",
  "remaining_amount": null,
  "address": null,
  "memo": null,
  "payment_uri": null,
  "required_confirmations": null,
  "fee_level": null,
  "settle_sec": null,
  "rate_usd": null,
  "paid_at": null,
  "payments": [],
  "refunded_amount": "0",
  "refunds": []
}

Refund the customer

POST/v1/invoices/{id}/refund

Creates a refund for a paid invoice — a payout in the same coin and network the customer paid with. You can refund the full amount or part of it; several partial refunds are allowed as long as their total does not exceed the amount received. The refund amount and the network fee for sending it are debited from your balance; the service fee for receiving the payment is not refunded. From then on the refund is processed like a regular payout (large ones after review), and status updates arrive as refund.* webhooks. We recommend sending the Idempotency-Key header (see “Idempotency”): then retrying the request after a network error does not create a second refund, even without order_id.

Path parameters

idstringrequired
Invoice ID.

Request body

addressstringrequired
Customer address on the invoice network. Ask the customer for it: the sender address on the blockchain often belongs to an exchange, and funds sent there will not reach the customer.
amountstring
Amount in the invoice coin. Defaults to everything not yet refunded.
memostring
Transfer comment — needed when refunding to an exchange on TON.
reasonstring
Refund reason — for your records.
order_idstring
Your refund ID. Repeating the request with it returns the same refund.
url_callbackstring
Webhook URL for this refund.

Response

Object Payout.

Errors

not_found nothing_to_refund refund_too_large invalid_address amount_too_small insufficient_balance

Request
curl -X POST "https://paymeusd.com/v1/invoices/6722fb9d-ed9e-4710-9f08-c9b63600b25a/refund" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "address": "TPyjyZfsYaXStgz2NmAraF1uZcMtkgNan5",
  "reason": "Out of stock"
}'
const res = await fetch('https://paymeusd.com/v1/invoices/6722fb9d-ed9e-4710-9f08-c9b63600b25a/refund', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "address": "TPyjyZfsYaXStgz2NmAraF1uZcMtkgNan5",
    "reason": "Out of stock"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/v1/invoices/6722fb9d-ed9e-4710-9f08-c9b63600b25a/refund');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
      'address' => "TPyjyZfsYaXStgz2NmAraF1uZcMtkgNan5",
      'reason' => "Out of stock",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.post(
    "https://paymeusd.com/v1/invoices/6722fb9d-ed9e-4710-9f08-c9b63600b25a/refund",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
        "address": "TPyjyZfsYaXStgz2NmAraF1uZcMtkgNan5",
        "reason": "Out of stock"
    },
)
res.raise_for_status()
data = res.json()
Response 201
{
  "id": "c3b1e0a2-5d4f-4e8a-9b7c-1f2e3d4c5b6a",
  "kind": "refund",
  "invoice_id": "6722fb9d-ed9e-4710-9f08-c9b63600b25a",
  "batch_id": null,
  "reason": "Out of stock",
  "order_id": "refund-1001-k3x9qa",
  "status": "queued",
  "network": "tron",
  "network_name": "TRON",
  "asset": "tron:USDT",
  "currency": "USDT",
  "address": "TPyjyZfsYaXStgz2NmAraF1uZcMtkgNan5",
  "memo": null,
  "amount": "55.24",
  "fee": "2",
  "total_debited": "57.24",
  "tx_hash": null,
  "explorer_url": null,
  "error": null,
  "created_at": "2026-11-13T09:04:05.395Z",
  "completed_at": null
}

Static addresses

A static address is assigned to a user of your service: every deposit to it is credited to your balance and reported with a payment.confirmed webhook with kind: "static" and your order_id. Ideal for balance top-ups in games, services and wallets — no invoices needed.

StaticWallet object

A user’s static address on one network.

idstring
Static address ID.
order_idstring
Your user ID.
networkstring
Network.
network_namestring
Network name.
assetsstring[]
Coins accepted at this address.
addressstring
Deposit address.
memostring | null
Comment — required for TON.
created_atstring
When it was created.
Example
{
  "id": "d20a74ce-7eab-4e3b-9258-8b0ce17807ac",
  "order_id": "user-42",
  "network": "tron",
  "network_name": "TRON",
  "assets": [
    "TRX",
    "USDT"
  ],
  "address": "THVC1jg4h9qkbU7STd1PGsrWzfXCJ5Z4es",
  "memo": null,
  "created_at": "2026-11-13T09:04:05.353Z"
}

Get a static address

POST/v1/static-wallets

Returns the user’s address on the network. Calling again with the same order_id and network returns the same address.

Request body

networkstringrequired
Network ID: tron, bsc, ethereum, solana, ton…
order_idstringrequired
Your user ID.
url_callbackstring
Webhook URL for this address.

Response

Object StaticWallet.

Errors

network_unavailable

Request
curl -X POST "https://paymeusd.com/v1/static-wallets" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "network": "tron",
  "order_id": "user-42"
}'
const res = await fetch('https://paymeusd.com/v1/static-wallets', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "network": "tron",
    "order_id": "user-42"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/v1/static-wallets');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
      'network' => "tron",
      'order_id' => "user-42",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.post(
    "https://paymeusd.com/v1/static-wallets",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
        "network": "tron",
        "order_id": "user-42"
    },
)
res.raise_for_status()
data = res.json()
Response 201
{
  "id": "d20a74ce-7eab-4e3b-9258-8b0ce17807ac",
  "order_id": "user-42",
  "network": "tron",
  "network_name": "TRON",
  "assets": [
    "TRX",
    "USDT"
  ],
  "address": "THVC1jg4h9qkbU7STd1PGsrWzfXCJ5Z4es",
  "memo": null,
  "created_at": "2026-11-13T09:04:05.353Z"
}

Payments

All incoming transfers to your addresses: invoice payments, static address deposits, late and “unexpected” payments.

Payment object

An incoming blockchain transfer.

idstring
Payment ID.
networkstring
Network the transfer arrived on.
network_namestring
Network name.
assetstring
Asset as network:SYMBOL.
currencystring
Coin ticker.
amountstring
Transfer amount.
tx_hashstring
Transaction hash.
fromstring | null
Sender address (if known).
confirmationsinteger
Current number of confirmations.
required_confirmationsinteger
Confirmations required before crediting.
statusstring
pending — waiting for confirmations, confirmed — credited, failed — reverted or dropped from the chain.
kindstring
invoice — invoice payment; static — static address deposit; unexpected — a different coin or network; late — after the invoice expired.
feestring | null
Service fee (after crediting).
credited_amountstring | null
Amount credited to the balance, net of the fee.
explorer_urlstring
Link to the transaction in a block explorer.
detected_atstring
When the payment was detected on-chain.
confirmed_atstring | null
When it was credited.
Example
{
  "id": "82a1a806-9162-4a3f-9109-e927ed7d6206",
  "network": "tron",
  "network_name": "TRON",
  "asset": "tron:USDT",
  "currency": "USDT",
  "amount": "55.24",
  "tx_hash": "b1f3c8a95e0d4a7c9e2f6b3d1a8c7e5f4b2d9a6c3e1f8b7a5d4c2e9f6b3a1d8c",
  "from": "TPyjyZfsYaXStgz2NmAraF1uZcMtkgNan5",
  "confirmations": 19,
  "required_confirmations": 19,
  "status": "confirmed",
  "kind": "invoice",
  "fee": "0.5524",
  "credited_amount": "54.6876",
  "explorer_url": "https://tronscan.org/#/transaction/b1f3c8a95e0d4a7c9e2f6b3d1a8c7e5f4b2d9a6c3e1f8b7a5d4c2e9f6b3a1d8c",
  "detected_at": "2026-11-13T09:04:31.112Z",
  "confirmed_at": "2026-11-13T09:05:28.416Z"
}

List payments

GET/v1/payments

Payments, newest first. In addition to the Payment fields, each item contains invoice_id and static_wallet_id.

Query parameters

kindstring
Filter: invoice, static, unexpected, late.
limitinteger
1 to 100, default 50.

Response

An object with an items list.

Request
curl "https://paymeusd.com/v1/payments" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch('https://paymeusd.com/v1/payments', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/v1/payments');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('API_KEY'),
  ],
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.get(
    "https://paymeusd.com/v1/payments",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
Response 200
{
  "items": [
    {
      "id": "82a1a806-9162-4a3f-9109-e927ed7d6206",
      "network": "tron",
      "network_name": "TRON",
      "asset": "tron:USDT",
      "currency": "USDT",
      "amount": "55.24",
      "tx_hash": "b1f3c8a95e0d4a7c9e2f6b3d1a8c7e5f4b2d9a6c3e1f8b7a5d4c2e9f6b3a1d8c",
      "from": "TPyjyZfsYaXStgz2NmAraF1uZcMtkgNan5",
      "confirmations": 19,
      "required_confirmations": 19,
      "status": "confirmed",
      "kind": "invoice",
      "fee": "0.5524",
      "credited_amount": "54.6876",
      "explorer_url": "https://tronscan.org/#/transaction/b1f3c8a95e0d4a7c9e2f6b3d1a8c7e5f4b2d9a6c3e1f8b7a5d4c2e9f6b3a1d8c",
      "detected_at": "2026-11-13T09:04:31.112Z",
      "confirmed_at": "2026-11-13T09:05:28.416Z",
      "invoice_id": "6722fb9d-ed9e-4710-9f08-c9b63600b25a",
      "static_wallet_id": null
    }
  ]
}

Balances

Balances are kept per coin: USDT received on different networks adds up. You can withdraw it on any supported network.

Get balances

GET/v1/balances

Amounts available for withdrawal, per coin.

Response

An object with an items list.

Request
curl "https://paymeusd.com/v1/balances" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch('https://paymeusd.com/v1/balances', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/v1/balances');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('API_KEY'),
  ],
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.get(
    "https://paymeusd.com/v1/balances",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
Response 200
{
  "items": [
    {
      "currency": "USDT",
      "available": "1254.18"
    },
    {
      "currency": "BTC",
      "available": "0.01832"
    }
  ]
}

Payouts

A payout transfers funds from your balance to an external address. The amount and fee are debited from the balance as soon as the payout is created; if the payout is rejected or fails, the funds are returned.

pending_approval→queued→processing→completed

Small payouts are sent automatically, large ones after manual review. The fee and minimum amount for each network are in GET /v1/assets.

Payout object

A withdrawal to an external address.

idstring
Payout ID.
kindstring
payout — withdrawal from your balance; refund — refund to a customer for an invoice.
invoice_idstring | null
For a refund — the invoice ID.
batch_idstring | null
Batch ID, if the payout was created by a batch payout.
reasonstring | null
Refund reason, if provided.
order_idstring
Your payout ID (idempotency).
statusstring
pending_approval → queued → processing → completed; also failed and rejected (the funds go back to the balance).
networkstring
Payout network.
network_namestring
Network name.
assetstring
Asset as network:SYMBOL.
currencystring
Coin ticker.
addressstring
Recipient address.
memostring | null
Comment (for TON and exchanges).
amountstring
Amount the recipient receives.
feestring
Withdrawal fee.
total_debitedstring
Debited from the balance: amount + fee.
tx_hashstring | null
Transaction hash once sent.
explorer_urlstring | null
Link to the transaction.
errorstring | null
Reason for rejection or delay.
created_atstring
When it was created.
completed_atstring | null
When the network confirmed it.
Example
{
  "id": "41a6f86e-263f-4c35-bf06-f94ad715e04b",
  "kind": "payout",
  "invoice_id": null,
  "batch_id": null,
  "reason": null,
  "order_id": "withdraw-77",
  "status": "queued",
  "network": "tron",
  "network_name": "TRON",
  "asset": "tron:USDT",
  "currency": "USDT",
  "address": "TPyjyZfsYaXStgz2NmAraF1uZcMtkgNan5",
  "memo": null,
  "amount": "150",
  "fee": "2",
  "total_debited": "152",
  "tx_hash": null,
  "explorer_url": null,
  "error": null,
  "created_at": "2026-11-13T09:04:05.395Z",
  "completed_at": null
}

Create a payout

POST/v1/payouts

Queues a payout. Repeating with the same order_id returns the existing payout. We also recommend sending the Idempotency-Key header (see “Idempotency”): a retry after a network error or a timeout returns the same response and debits nothing again.

Request body

networkstringrequired
Network ID, e.g. tron.
currencystringrequired
Coin ticker, e.g. USDT.
addressstringrequired
Recipient address on this network — the format is validated.
amountstringrequired
Amount the recipient receives (the fee is added on top).
order_idstringrequired
Your unique payout ID.
memostring
Comment — required when withdrawing to an exchange on TON.
url_callbackstring
Webhook URL for this payout.

Response

Object Payout.

Errors

invalid_address amount_too_small insufficient_balance order_exists network_unavailable

Request
curl -X POST "https://paymeusd.com/v1/payouts" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "network": "tron",
  "currency": "USDT",
  "address": "TPyjyZfsYaXStgz2NmAraF1uZcMtkgNan5",
  "amount": "150",
  "order_id": "withdraw-77"
}'
const res = await fetch('https://paymeusd.com/v1/payouts', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "network": "tron",
    "currency": "USDT",
    "address": "TPyjyZfsYaXStgz2NmAraF1uZcMtkgNan5",
    "amount": "150",
    "order_id": "withdraw-77"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/v1/payouts');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
      'network' => "tron",
      'currency' => "USDT",
      'address' => "TPyjyZfsYaXStgz2NmAraF1uZcMtkgNan5",
      'amount' => "150",
      'order_id' => "withdraw-77",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.post(
    "https://paymeusd.com/v1/payouts",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
        "network": "tron",
        "currency": "USDT",
        "address": "TPyjyZfsYaXStgz2NmAraF1uZcMtkgNan5",
        "amount": "150",
        "order_id": "withdraw-77"
    },
)
res.raise_for_status()
data = res.json()
Response 201
{
  "id": "41a6f86e-263f-4c35-bf06-f94ad715e04b",
  "kind": "payout",
  "invoice_id": null,
  "batch_id": null,
  "reason": null,
  "order_id": "withdraw-77",
  "status": "queued",
  "network": "tron",
  "network_name": "TRON",
  "asset": "tron:USDT",
  "currency": "USDT",
  "address": "TPyjyZfsYaXStgz2NmAraF1uZcMtkgNan5",
  "memo": null,
  "amount": "150",
  "fee": "2",
  "total_debited": "152",
  "tx_hash": null,
  "explorer_url": null,
  "error": null,
  "created_at": "2026-11-13T09:04:05.395Z",
  "completed_at": null
}

Batch payout

POST/v1/payouts/batch

Up to 500 payouts in one request — salaries, affiliate payouts, winnings. Every row is validated first, and the balance is checked for each coin; either all payouts are created or none (400 batch_invalid, per-row results in details). With validate_only: true the request only validates. After that, each payout behaves like a regular one: above the daily limit it waits for approval. Repeating with the same reference returns the same batch; without reference, the Idempotency-Key header protects against duplicates (we recommend always sending it).

Request body

itemsobject[]required
Payouts: network, currency, address, amount, optionally memo and order_id (defaults to <reference>-<number>).
referencestring
Your batch ID for idempotency.
validate_onlyboolean
Validate only, without creating anything: the response is 200 {valid, count, errors, rows, totals} — per-row results and per-coin totals against your balance.
url_callbackstring
Webhook URL for the payout.* events of the batch payouts.

Response

An object with an items list.

Errors

batch_invalid batch_too_large batch_empty address_not_whitelisted

Request
curl -X POST "https://paymeusd.com/v1/payouts/batch" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reference": "salary-2026-11",
  "items": [
    {
      "network": "tron",
      "currency": "USDT",
      "address": "TPyjyZfsYaXStgz2NmAraF1uZcMtkgNan5",
      "amount": "250"
    },
    {
      "network": "bsc",
      "currency": "USDT",
      "address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
      "amount": "180"
    }
  ]
}'
const res = await fetch('https://paymeusd.com/v1/payouts/batch', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "reference": "salary-2026-11",
    "items": [
      {
        "network": "tron",
        "currency": "USDT",
        "address": "TPyjyZfsYaXStgz2NmAraF1uZcMtkgNan5",
        "amount": "250"
      },
      {
        "network": "bsc",
        "currency": "USDT",
        "address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
        "amount": "180"
      }
    ]
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/v1/payouts/batch');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
      'reference' => "salary-2026-11",
      'items' => ['0' => {"network":"tron","currency":"USDT","address":"TPyjyZfsYaXStgz2NmAraF1uZcMtkgNan5","amount":"250"}, '1' => {"network":"bsc","currency":"USDT","address":"0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed","amount":"180"}],
  ]),
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.post(
    "https://paymeusd.com/v1/payouts/batch",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
        "reference": "salary-2026-11",
        "items": [
            {
                "network": "tron",
                "currency": "USDT",
                "address": "TPyjyZfsYaXStgz2NmAraF1uZcMtkgNan5",
                "amount": "250"
            },
            {
                "network": "bsc",
                "currency": "USDT",
                "address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
                "amount": "180"
            }
        ]
    },
)
res.raise_for_status()
data = res.json()
Response 201
{
  "batch": {
    "id": "b1c2d3e4-0000-4000-8000-000000000001",
    "reference": "salary-2026-11",
    "source": "api",
    "count": 2,
    "totals": {
      "USDT": {
        "amount": "430",
        "fee": "3"
      }
    },
    "statuses": {
      "queued": 2
    },
    "created_at": "2026-11-13T09:04:05.395Z"
  },
  "items": [
    {
      "id": "41a6f86e-263f-4c35-bf06-f94ad715e04b",
      "kind": "payout",
      "invoice_id": null,
      "batch_id": "b1c2d3e4-0000-4000-8000-000000000001",
      "reason": null,
      "order_id": "salary-2026-11-1",
      "status": "queued",
      "network": "tron",
      "network_name": "TRON",
      "asset": "tron:USDT",
      "currency": "USDT",
      "address": "TPyjyZfsYaXStgz2NmAraF1uZcMtkgNan5",
      "memo": null,
      "amount": "250",
      "fee": "2",
      "total_debited": "152",
      "tx_hash": null,
      "explorer_url": null,
      "error": null,
      "created_at": "2026-11-13T09:04:05.395Z",
      "completed_at": null
    }
  ]
}

Retrieve a payout batch

GET/v1/payouts/batch/{id}

Batch totals and the current status of every payout in it.

Path parameters

idstringrequired
Batch ID.

Response

An object with an items list.

Errors

not_found

Request
curl "https://paymeusd.com/v1/payouts/batch/6722fb9d-ed9e-4710-9f08-c9b63600b25a" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch('https://paymeusd.com/v1/payouts/batch/6722fb9d-ed9e-4710-9f08-c9b63600b25a', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/v1/payouts/batch/6722fb9d-ed9e-4710-9f08-c9b63600b25a');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('API_KEY'),
  ],
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.get(
    "https://paymeusd.com/v1/payouts/batch/6722fb9d-ed9e-4710-9f08-c9b63600b25a",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
Response 200
{
  "batch": {
    "id": "b1c2d3e4-0000-4000-8000-000000000001",
    "reference": "salary-2026-11",
    "source": "api",
    "count": 2,
    "totals": {
      "USDT": {
        "amount": "430",
        "fee": "3"
      }
    },
    "statuses": {
      "completed": 1,
      "queued": 1
    },
    "created_at": "2026-11-13T09:04:05.395Z"
  },
  "items": [
    {
      "id": "41a6f86e-263f-4c35-bf06-f94ad715e04b",
      "kind": "payout",
      "invoice_id": null,
      "batch_id": "b1c2d3e4-0000-4000-8000-000000000001",
      "reason": null,
      "order_id": "salary-2026-11-1",
      "status": "queued",
      "network": "tron",
      "network_name": "TRON",
      "asset": "tron:USDT",
      "currency": "USDT",
      "address": "TPyjyZfsYaXStgz2NmAraF1uZcMtkgNan5",
      "memo": null,
      "amount": "250",
      "fee": "2",
      "total_debited": "152",
      "tx_hash": null,
      "explorer_url": null,
      "error": null,
      "created_at": "2026-11-13T09:04:05.395Z",
      "completed_at": null
    }
  ]
}

Retrieve a payout

GET/v1/payouts/{id}

Current payout status and transaction hash.

Path parameters

idstringrequired
Payout ID.

Response

Object Payout.

Errors

not_found

Request
curl "https://paymeusd.com/v1/payouts/6722fb9d-ed9e-4710-9f08-c9b63600b25a" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch('https://paymeusd.com/v1/payouts/6722fb9d-ed9e-4710-9f08-c9b63600b25a', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/v1/payouts/6722fb9d-ed9e-4710-9f08-c9b63600b25a');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('API_KEY'),
  ],
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.get(
    "https://paymeusd.com/v1/payouts/6722fb9d-ed9e-4710-9f08-c9b63600b25a",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
Response 200
{
  "id": "41a6f86e-263f-4c35-bf06-f94ad715e04b",
  "kind": "payout",
  "invoice_id": null,
  "batch_id": null,
  "reason": null,
  "order_id": "withdraw-77",
  "status": "completed",
  "network": "tron",
  "network_name": "TRON",
  "asset": "tron:USDT",
  "currency": "USDT",
  "address": "TPyjyZfsYaXStgz2NmAraF1uZcMtkgNan5",
  "memo": null,
  "amount": "150",
  "fee": "2",
  "total_debited": "152",
  "tx_hash": "7c0de4b1a9f2e8d3c6b5a4f7e2d1c9b8a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1",
  "explorer_url": "https://tronscan.org/#/transaction/7c0de4b1a9f2e8d3c6b5a4f7e2d1c9b8a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1",
  "error": null,
  "created_at": "2026-11-13T09:04:05.395Z",
  "completed_at": "2026-11-13T09:06:12.004Z"
}

List payouts

GET/v1/payouts

Payouts, newest first.

Query parameters

order_idstring
Find a payout by your ID.
statusstring
Filter by status.
limitinteger
1 to 100, default 50.

Response

An object with an items list.

Request
curl "https://paymeusd.com/v1/payouts" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch('https://paymeusd.com/v1/payouts', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/v1/payouts');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('API_KEY'),
  ],
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.get(
    "https://paymeusd.com/v1/payouts",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
Response 200
{
  "items": [
    {
      "id": "41a6f86e-263f-4c35-bf06-f94ad715e04b",
      "kind": "payout",
      "invoice_id": null,
      "batch_id": null,
      "reason": null,
      "order_id": "withdraw-77",
      "status": "queued",
      "network": "tron",
      "network_name": "TRON",
      "asset": "tron:USDT",
      "currency": "USDT",
      "address": "TPyjyZfsYaXStgz2NmAraF1uZcMtkgNan5",
      "memo": null,
      "amount": "150",
      "fee": "2",
      "total_debited": "152",
      "tx_hash": null,
      "explorer_url": null,
      "error": null,
      "created_at": "2026-11-13T09:04:05.395Z",
      "completed_at": null
    }
  ]
}

Coins and networks

Supported assets and their parameters: confirmations, minimum amounts, withdrawal fees, current rates. The table below shows the service’s live data.

Asset IDNetworkDecimalsConfs≈ SettlementMin. paymentPayout fee
bitcoin:BTCBitcoin8220 min0.000010.0002
ethereum:ETHEthereum18122 min0.000010.0005
ethereum:USDTEthereum ERC-206122 min0.015
ethereum:USDCEthereum ERC-206122 min0.015
bsc:BNBBNB Smart Chain181510 sec0.00010.0005
bsc:USDTBNB Smart Chain BEP-20181510 sec0.010.5
bsc:USDCBNB Smart Chain BEP-20181510 sec0.010.5
polygon:POLPolygon18321 min0.010.5
polygon:USDTPolygon ERC-206321 min0.010.5
polygon:USDCPolygon ERC-206321 min0.010.5
arbitrum:ETHArbitrum One18205 sec0.000010.0005
arbitrum:USDTArbitrum One ERC-206205 sec0.010.5
arbitrum:USDCArbitrum One ERC-206205 sec0.010.5
optimism:ETHOptimism182040 sec0.000010.0005
optimism:USDTOptimism ERC-2062040 sec0.010.5
optimism:USDCOptimism ERC-2062040 sec0.010.5
base:ETHBase182040 sec0.000010.0005
base:USDCBase ERC-2062040 sec0.010.5
avalanche:AVAXAvalanche C-Chain1835 sec0.0010.02
avalanche:USDTAvalanche C-Chain ERC-20635 sec0.010.5
avalanche:USDCAvalanche C-Chain ERC-20635 sec0.010.5
plasma:XPLPlasma181010 sec0.010.5
plasma:USDTPlasma ERC-2061010 sec0.010.5
kaia:KAIAKaia1835 sec0.11
kaia:USDTKaia ERC-20635 sec0.010.5
celo:CELOCelo181010 sec0.10.5
celo:USDTCelo ERC-2061010 sec0.010.5
celo:USDCCelo ERC-2061010 sec0.010.5
kava:KAVAKava18320 sec0.10.5
kava:USDTKava ERC-206320 sec0.010.5
mantle:MNTMantle182040 sec0.10.5
mantle:USDTMantle ERC-2062040 sec0.010.5
tron:TRXTRON61955 sec11
tron:USDTTRON TRC-2061955 sec0.012
solana:SOLSolana93215 sec0.00010.005
solana:USDTSolana SPL63215 sec0.011
solana:USDCSolana SPL63215 sec0.011
ton:TONTON915 sec0.010.05
ton:USDTTON615 sec0.011

Greyed-out rows are coins needed only for gas: they are accepted as an “unexpected” payment but not offered to the customer.

Asset object

A coin on a specific network.

idstring
Asset ID network:SYMBOL.
symbolstring
Ticker.
namestring
Coin name.
networkstring
Network ID.
network_namestring
Network name.
standardstring | null
Token standard.
contractstring | null
Token contract address.
decimalsinteger
Decimal places on the network.
confirmationsinteger
Confirmations before crediting.
min_amountstring
Minimum payment amount — smaller payments are ignored.
rate_usdstring | null
Current USD rate.
payableboolean
Whether invoices can be paid with this coin.
payout_feestring
Withdrawal fee.
min_payoutstring
Minimum withdrawal amount.
Example
{
  "id": "tron:USDT",
  "symbol": "USDT",
  "name": "Tether USD",
  "network": "tron",
  "network_name": "TRON",
  "standard": "TRC-20",
  "contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "decimals": 6,
  "confirmations": 19,
  "min_amount": "0.01",
  "rate_usd": "1",
  "payable": true,
  "payout_fee": "2",
  "min_payout": "5"
}

List assets

GET/v1/assets

All assets currently available for payments and withdrawals.

Response

An object with an items list.

Request
curl "https://paymeusd.com/v1/assets" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch('https://paymeusd.com/v1/assets', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/v1/assets');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('API_KEY'),
  ],
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.get(
    "https://paymeusd.com/v1/assets",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
Response 200
{
  "items": [
    {
      "id": "tron:USDT",
      "symbol": "USDT",
      "name": "Tether USD",
      "network": "tron",
      "network_name": "TRON",
      "standard": "TRC-20",
      "contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
      "decimals": 6,
      "confirmations": 19,
      "min_amount": "0.01",
      "rate_usd": "1",
      "payable": true,
      "payout_fee": "2",
      "min_payout": "5"
    }
  ]
}

Current domains

GET/v1/domains

The service’s primary domain in each region: ru — for customers in Russia, global — for everyone else. If a domain gets blocked, the service switches to a backup one — this method always returns the current domain. No API key required.

Response

JSON — see the example on the right.

Request
curl "https://paymeusd.com/v1/domains" \
  
const res = await fetch('https://paymeusd.com/v1/domains', {
  method: 'GET',
  headers: {
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/v1/domains');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
  ],
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.get(
    "https://paymeusd.com/v1/domains",
    
)
res.raise_for_status()
data = res.json()
Response 200
{
  "regions": {
    "ru": {
      "active": "https://pay-shop.ru"
    },
    "global": {
      "active": "https://paymeusd.com"
    }
  },
  "fallback": "https://paymeusd.com"
}

Service status

GET/v1/status

Whether the service is working right now: the API and payment page, payment crediting, webhooks, payouts and each network. level: operational, degraded (delays), outage, maintenance. Also lists open incidents and scheduled maintenance. Text fields (text, name, level_text, status_text) are for display — in Russian by default, in English with Accept-Language: en; base your logic on level and id. The human-readable version is the /status page, the incident feed is /status/feed.atom. No API key required.

Response

JSON — see the example on the right.

Request
curl "https://paymeusd.com/v1/status" \
  
const res = await fetch('https://paymeusd.com/v1/status', {
  method: 'GET',
  headers: {
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/v1/status');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
  ],
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.get(
    "https://paymeusd.com/v1/status",
    
)
res.raise_for_status()
data = res.json()
Response 200
{
  "status": {
    "level": "operational",
    "text": "All systems operational"
  },
  "components": [
    {
      "id": "api",
      "group": "service",
      "name": "API and payment page",
      "level": "operational",
      "level_text": "Operational"
    },
    {
      "id": "net:tron",
      "group": "networks",
      "name": "TRON",
      "level": "operational",
      "level_text": "Operational"
    }
  ],
  "incidents": {
    "active": [],
    "scheduled": [],
    "recent": []
  },
  "updated_at": "2026-11-13T09:04:05.000Z"
}

Invoice currencies

GET/v1/currencies

Currencies you can set the invoice amount in (currency in POST /v1/invoices): fiat at the current rate and the coins of connected networks. For coins, the networks they can be received on are listed. Use code in requests; name is a display name (in English with Accept-Language: en).

Response

An object with an items list.

Request
curl "https://paymeusd.com/v1/currencies" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch('https://paymeusd.com/v1/currencies', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/v1/currencies');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('API_KEY'),
  ],
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.get(
    "https://paymeusd.com/v1/currencies",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
Response 200
{
  "items": [
    {
      "code": "USD",
      "type": "fiat",
      "name": "US Dollar",
      "rate_usd": "1",
      "networks": []
    },
    {
      "code": "EUR",
      "type": "fiat",
      "name": "Euro",
      "rate_usd": "1.1",
      "networks": []
    },
    {
      "code": "USDT",
      "type": "crypto",
      "name": "Tether USD",
      "rate_usd": "1",
      "networks": [
        "tron",
        "bsc",
        "ethereum",
        "solana",
        "ton"
      ]
    }
  ]
}

Recurring payments

Subscriptions to your services: SaaS, online services, memberships. Cryptocurrency cannot be charged automatically, so a subscription is a schedule of invoices, reminders to the customer and statuses.

  1. Create a plan — POST /v1/plans: amount and period, optionally a trial.
  2. Create a subscription — POST /v1/subscriptions with the customer’s email. Without a trial, the invoice for the first period is issued immediately: send the customer to current_invoice.payment_url.
  3. The rest is automatic: before the paid period ends (3 days ahead by default), the customer receives an invoice for the next period (by email and in Telegram), and a reminder one day before. Payment extends the subscription from the end of the current period, and you receive a subscription.renewed webhook.
pending / trialing→active→past_due→expired
StatusMeaning
pendingAwaiting the first payment. If none arrives before the grace period ends — expired
trialingTrial period; the invoice for the first period arrives before it ends
activePaid until current_period_end — provide the service
past_dueThe period has ended and the invoice is unpaid. We wait grace_days days (3 by default) — it is up to you whether to keep providing the service
cancelledCancelled: by you, by the customer on the subscription page, or at the end of the period after renewal was cancelled
expiredNot paid before the grace period ended
  • A subscription invoice is a regular invoice: its order_id looks like sub-<subscription id>-<period number>, it carries metadata.billing_subscription_id, and it triggers the usual invoice.* webhooks. Funds are credited to your balance as usual.
  • Reminders to the customer: emails (in Russian or English, depending on locale) when a new invoice is issued, ahead of the due date (the number of days is a service setting), when the payment is overdue and when the subscription is stopped. On the subscription page (customer_url) the customer can turn on Telegram reminders.
  • Price and period are locked at signup: changes to a plan apply to new subscriptions only.
  • Monthly periods are counted from the original day: a subscription started on January 31 renews on February 28 (29), then on March 31.

Subscription webhooks

Sent to the webhook URL from the dashboard and signed like all other webhooks. data contains the Subscription object; invoice-related events also include invoice (same shape as current_invoice).

EventWhen
subscription.createdSubscription created
subscription.invoice_createdInvoice for the next period issued (+ invoice)
subscription.renewedInvoice paid, period extended (+ invoice)
subscription.past_dueThe period has ended, the invoice is unpaid
subscription.cancel_scheduled, subscription.resumedRenewal cancelled / resumed (the subscription stays active until the end of the period)
subscription.cancelledSubscription cancelled
subscription.expiredNot paid before the grace period ended

Plan object

A plan: amount and billing period.

idstring
Plan ID (UUID).
namestring
Name — shown to the customer in emails and on the subscription page.
descriptionstring | null
Description for the customer.
amountstring
Amount per period.
currencystring
Currency of the amount: fiat (USD, EUR…) or a coin (USDT…) — same as for invoices.
intervalstring
Period unit: day, week, month, year.
interval_countinteger
Units per period: interval=month, interval_count=3 — quarterly.
trial_daysinteger
Trial period in days (0 — no trial).
grace_daysinteger
How many days after the period ends we wait for payment (status past_due) before stopping the subscription.
allowed_assetsstring[] | null
Coins accepted for payment, e.g. ["tron:USDT","bsc:USDT"]. null — any.
archivedboolean
true — the plan is archived: no new subscriptions, existing ones continue.
archived_atstring | null
When the plan was archived.
created_atstring
When the plan was created.
Example
{
  "id": "5d0c1b8e-2f4a-4c3b-9e7d-1a2b3c4d5e6f",
  "name": "Pro",
  "description": "Up to 10 projects and priority support",
  "amount": "29",
  "currency": "USD",
  "interval": "month",
  "interval_count": 1,
  "trial_days": 14,
  "grace_days": 3,
  "allowed_assets": null,
  "archived": false,
  "archived_at": null,
  "created_at": "2026-11-13T09:00:00.000Z"
}

Subscription object

A customer subscription. Delivered in subscription.* webhooks.

idstring
Subscription ID (UUID).
statusstring
pending, trialing, active, past_due, cancelled, expired — see the table above.
plan_idstring
Plan ID.
plan_namestring
Plan name.
order_idstring | null
Your subscription ID from the create request.
customerobject
Customer: email, name, reference (your user ID). Invoices and reminders are sent to the email.
localestring
Language of emails and the subscription page: ru — Russian, anything else — English.
amountstring
Amount per period — locked at signup: changing the plan does not affect it.
currencystring
Currency of the amount.
intervalstring
Period unit: day, week, month, year.
interval_countinteger
Units per period.
trial_endstring | null
End of the trial period.
period_numberinteger
Number of the last paid period (0 — nothing paid yet).
current_period_startstring
Start of the current period (before the first payment — the signup date).
current_period_endstring
The subscription is paid up to this moment (or the end of the trial). Monthly periods are counted from the original day: January 31 → February 28 (29) → March 31.
next_payment_atstring | null
Next payment due date. null if renewal is cancelled or the subscription has ended.
cancel_at_period_endboolean
true — renewal is cancelled: no new invoices, and at the end of the period the status becomes cancelled.
cancelled_atstring | null
When cancellation was requested.
ended_atstring | null
When the subscription ended (cancelled or expired).
current_invoiceobject | null
Invoice for the next period: id, status (invoice status), period_number, amount, currency, due_at — due date, expires_at — end of the grace period, payment_url.
customer_urlstring
Subscription page for the customer: pay the invoice, view history, Telegram reminders, cancel renewal. The link is secret — share it only with the customer.
metadataobject | null
Your data passed at creation.
created_atstring
When the subscription was created.
Example
{
  "id": "b7e4c2a1-9d3f-4e8b-a5c6-0f1e2d3c4b5a",
  "status": "active",
  "plan_id": "5d0c1b8e-2f4a-4c3b-9e7d-1a2b3c4d5e6f",
  "plan_name": "Pro",
  "order_id": "user-42-pro",
  "customer": {
    "email": "anna@example.com",
    "name": "Anna",
    "reference": "user-42"
  },
  "locale": "ru",
  "amount": "29",
  "currency": "USD",
  "interval": "month",
  "interval_count": 1,
  "trial_end": "2026-11-27T09:00:00.000Z",
  "period_number": 1,
  "current_period_start": "2026-11-27T09:00:00.000Z",
  "current_period_end": "2026-12-27T09:00:00.000Z",
  "next_payment_at": "2026-12-27T09:00:00.000Z",
  "cancel_at_period_end": false,
  "cancelled_at": null,
  "ended_at": null,
  "current_invoice": {
    "id": "0e9f8a7b-6c5d-4e3f-8a1b-2c3d4e5f6a7b",
    "status": "pending",
    "period_number": 2,
    "amount": "29",
    "currency": "USD",
    "due_at": "2026-12-27T09:00:00.000Z",
    "expires_at": "2026-12-30T09:00:00.000Z",
    "payment_url": "https://paymeusd.com/pay/0e9f8a7b-6c5d-4e3f-8a1b-2c3d4e5f6a7b"
  },
  "customer_url": "https://paymeusd.com/s/Xq3v9Lr2Tn8Wk5Pz1Hc7Jm4Ba6Ds0Fe",
  "metadata": {
    "user_id": 42
  },
  "created_at": "2026-11-13T09:00:00.000Z"
}

Create a plan

POST/v1/plans

A plan defines the amount and the billing period. Subscriptions are created for a plan.

Request body

namestringrequired
Name (up to 120 characters).
amountstringrequired
Amount per period, e.g. "29".
currencystringrequired
Currency: USD, EUR, RUB, UAH, KZT, GBP, TRY or a coin ticker (USDT…).
intervalstringrequired
day, week, month or year.
interval_countinteger
Units per period, default 1. At most 365 days, 260 weeks, 60 months, 5 years.
trial_daysinteger
Trial period, days (0–365). Default 0.
grace_daysinteger
Grace period after the period ends, days (0–60). Default 3.
allowed_assetsstring[]
Restrict the payment coins, e.g. ["tron:USDT","bsc:USDT"].
descriptionstring
Description for the customer (up to 500 characters).

Response

Object Plan.

Errors

validation_error unsupported_currency invalid_interval unknown_asset

Request
curl -X POST "https://paymeusd.com/v1/plans" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Pro",
  "amount": "29",
  "currency": "USD",
  "interval": "month",
  "trial_days": 14,
  "description": "Up to 10 projects and priority support"
}'
const res = await fetch('https://paymeusd.com/v1/plans', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Pro",
    "amount": "29",
    "currency": "USD",
    "interval": "month",
    "trial_days": 14,
    "description": "Up to 10 projects and priority support"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/v1/plans');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
      'name' => "Pro",
      'amount' => "29",
      'currency' => "USD",
      'interval' => "month",
      'trial_days' => 14,
      'description' => "Up to 10 projects and priority support",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.post(
    "https://paymeusd.com/v1/plans",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
        "name": "Pro",
        "amount": "29",
        "currency": "USD",
        "interval": "month",
        "trial_days": 14,
        "description": "Up to 10 projects and priority support"
    },
)
res.raise_for_status()
data = res.json()
Response 201
{
  "id": "5d0c1b8e-2f4a-4c3b-9e7d-1a2b3c4d5e6f",
  "name": "Pro",
  "description": "Up to 10 projects and priority support",
  "amount": "29",
  "currency": "USD",
  "interval": "month",
  "interval_count": 1,
  "trial_days": 14,
  "grace_days": 3,
  "allowed_assets": null,
  "archived": false,
  "archived_at": null,
  "created_at": "2026-11-13T09:00:00.000Z"
}

List plans

GET/v1/plans

Plans, newest first; archived plans last.

Query parameters

include_archivedstring
true — include archived plans.
limitinteger
1 to 100, default 50.

Response

An object with an items list.

Request
curl "https://paymeusd.com/v1/plans" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch('https://paymeusd.com/v1/plans', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/v1/plans');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('API_KEY'),
  ],
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.get(
    "https://paymeusd.com/v1/plans",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
Response 200
{
  "items": [
    {
      "id": "5d0c1b8e-2f4a-4c3b-9e7d-1a2b3c4d5e6f",
      "name": "Pro",
      "description": "Up to 10 projects and priority support",
      "amount": "29",
      "currency": "USD",
      "interval": "month",
      "interval_count": 1,
      "trial_days": 14,
      "grace_days": 3,
      "allowed_assets": null,
      "archived": false,
      "archived_at": null,
      "created_at": "2026-11-13T09:00:00.000Z"
    }
  ]
}

Retrieve a plan

GET/v1/plans/{id}

Plan by ID.

Path parameters

idstringrequired
Plan ID.

Response

Object Plan.

Errors

not_found

Request
curl "https://paymeusd.com/v1/plans/6722fb9d-ed9e-4710-9f08-c9b63600b25a" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch('https://paymeusd.com/v1/plans/6722fb9d-ed9e-4710-9f08-c9b63600b25a', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/v1/plans/6722fb9d-ed9e-4710-9f08-c9b63600b25a');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('API_KEY'),
  ],
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.get(
    "https://paymeusd.com/v1/plans/6722fb9d-ed9e-4710-9f08-c9b63600b25a",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
Response 200
{
  "id": "5d0c1b8e-2f4a-4c3b-9e7d-1a2b3c4d5e6f",
  "name": "Pro",
  "description": "Up to 10 projects and priority support",
  "amount": "29",
  "currency": "USD",
  "interval": "month",
  "interval_count": 1,
  "trial_days": 14,
  "grace_days": 3,
  "allowed_assets": null,
  "archived": false,
  "archived_at": null,
  "created_at": "2026-11-13T09:00:00.000Z"
}

Archive a plan

POST/v1/plans/{id}/archive

No new subscriptions to the plan can be created. Existing subscriptions continue on the same terms.

Path parameters

idstringrequired
Plan ID.

Response

Object Plan.

Errors

not_found

Request
curl -X POST "https://paymeusd.com/v1/plans/6722fb9d-ed9e-4710-9f08-c9b63600b25a/archive" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch('https://paymeusd.com/v1/plans/6722fb9d-ed9e-4710-9f08-c9b63600b25a/archive', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/v1/plans/6722fb9d-ed9e-4710-9f08-c9b63600b25a/archive');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('API_KEY'),
  ],
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.post(
    "https://paymeusd.com/v1/plans/6722fb9d-ed9e-4710-9f08-c9b63600b25a/archive",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
Response 200
{
  "id": "5d0c1b8e-2f4a-4c3b-9e7d-1a2b3c4d5e6f",
  "name": "Pro",
  "description": "Up to 10 projects and priority support",
  "amount": "29",
  "currency": "USD",
  "interval": "month",
  "interval_count": 1,
  "trial_days": 14,
  "grace_days": 3,
  "allowed_assets": null,
  "archived": true,
  "archived_at": "2026-12-01T10:00:00.000Z",
  "created_at": "2026-11-13T09:00:00.000Z"
}

Create a subscription

POST/v1/subscriptions

Creates a subscription to a plan. Without a trial, the invoice for the first period is issued immediately — the payment link is in current_invoice.payment_url, and the customer also receives it by email. Repeating with the same order_id returns the existing subscription (response 200).

Request body

plan_idstringrequired
Plan ID.
customerobject
Customer: email — where invoices and reminders are sent, name, reference — your user ID.
order_idstring
Your unique subscription ID (up to 128 characters). Ensures idempotency.
localestring
Language of emails and the subscription page: ru (default) or en.
start_atstring
Subscription start in the future (ISO 8601), at most one year ahead. Defaults to now.
metadataobject
Arbitrary data — returned in responses and webhooks.

Response

Object Subscription.

Errors

validation_error plan_not_found plan_archived order_exists invalid_start

Request
curl -X POST "https://paymeusd.com/v1/subscriptions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "plan_id": "5d0c1b8e-2f4a-4c3b-9e7d-1a2b3c4d5e6f",
  "customer": {
    "email": "anna@example.com",
    "name": "Anna",
    "reference": "user-42"
  },
  "order_id": "user-42-pro",
  "metadata": {
    "user_id": 42
  }
}'
const res = await fetch('https://paymeusd.com/v1/subscriptions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "plan_id": "5d0c1b8e-2f4a-4c3b-9e7d-1a2b3c4d5e6f",
    "customer": {
      "email": "anna@example.com",
      "name": "Anna",
      "reference": "user-42"
    },
    "order_id": "user-42-pro",
    "metadata": {
      "user_id": 42
    }
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/v1/subscriptions');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
      'plan_id' => "5d0c1b8e-2f4a-4c3b-9e7d-1a2b3c4d5e6f",
      'customer' => ['email' => "anna@example.com", 'name' => "Anna", 'reference' => "user-42"],
      'order_id' => "user-42-pro",
      'metadata' => ['user_id' => 42],
  ]),
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.post(
    "https://paymeusd.com/v1/subscriptions",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
        "plan_id": "5d0c1b8e-2f4a-4c3b-9e7d-1a2b3c4d5e6f",
        "customer": {
            "email": "anna@example.com",
            "name": "Anna",
            "reference": "user-42"
        },
        "order_id": "user-42-pro",
        "metadata": {
            "user_id": 42
        }
    },
)
res.raise_for_status()
data = res.json()
Response 201
{
  "id": "b7e4c2a1-9d3f-4e8b-a5c6-0f1e2d3c4b5a",
  "status": "pending",
  "plan_id": "5d0c1b8e-2f4a-4c3b-9e7d-1a2b3c4d5e6f",
  "plan_name": "Pro",
  "order_id": "user-42-pro",
  "customer": {
    "email": "anna@example.com",
    "name": "Anna",
    "reference": "user-42"
  },
  "locale": "ru",
  "amount": "29",
  "currency": "USD",
  "interval": "month",
  "interval_count": 1,
  "trial_end": null,
  "period_number": 0,
  "current_period_start": "2026-11-13T09:00:00.000Z",
  "current_period_end": "2026-11-13T09:00:00.000Z",
  "next_payment_at": "2026-11-13T09:00:00.000Z",
  "cancel_at_period_end": false,
  "cancelled_at": null,
  "ended_at": null,
  "current_invoice": {
    "id": "0e9f8a7b-6c5d-4e3f-8a1b-2c3d4e5f6a7b",
    "status": "pending",
    "period_number": 1,
    "amount": "29",
    "currency": "USD",
    "due_at": "2026-11-13T09:00:00.000Z",
    "expires_at": "2026-11-16T09:00:00.000Z",
    "payment_url": "https://paymeusd.com/pay/0e9f8a7b-6c5d-4e3f-8a1b-2c3d4e5f6a7b"
  },
  "customer_url": "https://paymeusd.com/s/Xq3v9Lr2Tn8Wk5Pz1Hc7Jm4Ba6Ds0Fe",
  "metadata": {
    "user_id": 42
  },
  "created_at": "2026-11-13T09:00:00.000Z"
}

List subscriptions

GET/v1/subscriptions

Subscriptions, newest first.

Query parameters

statusstring
Filter by status.
plan_idstring
Subscriptions to one plan.
order_idstring
Find by your ID.
customer_emailstring
A customer’s subscriptions by email.
limitinteger
1 to 100, default 20.
offsetinteger
How many items to skip — for pagination.

Response

An object with an items list.

Request
curl "https://paymeusd.com/v1/subscriptions?customer_email=anna%40example.com" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch('https://paymeusd.com/v1/subscriptions?customer_email=anna%40example.com', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/v1/subscriptions?customer_email=anna%40example.com');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('API_KEY'),
  ],
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.get(
    "https://paymeusd.com/v1/subscriptions?customer_email=anna%40example.com",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
Response 200
{
  "items": [
    {
      "id": "b7e4c2a1-9d3f-4e8b-a5c6-0f1e2d3c4b5a",
      "status": "active",
      "plan_id": "5d0c1b8e-2f4a-4c3b-9e7d-1a2b3c4d5e6f",
      "plan_name": "Pro",
      "order_id": "user-42-pro",
      "customer": {
        "email": "anna@example.com",
        "name": "Anna",
        "reference": "user-42"
      },
      "locale": "ru",
      "amount": "29",
      "currency": "USD",
      "interval": "month",
      "interval_count": 1,
      "trial_end": "2026-11-27T09:00:00.000Z",
      "period_number": 1,
      "current_period_start": "2026-11-27T09:00:00.000Z",
      "current_period_end": "2026-12-27T09:00:00.000Z",
      "next_payment_at": "2026-12-27T09:00:00.000Z",
      "cancel_at_period_end": false,
      "cancelled_at": null,
      "ended_at": null,
      "current_invoice": {
        "id": "0e9f8a7b-6c5d-4e3f-8a1b-2c3d4e5f6a7b",
        "status": "pending",
        "period_number": 2,
        "amount": "29",
        "currency": "USD",
        "due_at": "2026-12-27T09:00:00.000Z",
        "expires_at": "2026-12-30T09:00:00.000Z",
        "payment_url": "https://paymeusd.com/pay/0e9f8a7b-6c5d-4e3f-8a1b-2c3d4e5f6a7b"
      },
      "customer_url": "https://paymeusd.com/s/Xq3v9Lr2Tn8Wk5Pz1Hc7Jm4Ba6Ds0Fe",
      "metadata": {
        "user_id": 42
      },
      "created_at": "2026-11-13T09:00:00.000Z"
    }
  ]
}

Retrieve a subscription

GET/v1/subscriptions/{id}

Current state of the subscription and the invoice for the next period.

Path parameters

idstringrequired
Subscription ID.

Response

Object Subscription.

Errors

not_found

Request
curl "https://paymeusd.com/v1/subscriptions/6722fb9d-ed9e-4710-9f08-c9b63600b25a" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch('https://paymeusd.com/v1/subscriptions/6722fb9d-ed9e-4710-9f08-c9b63600b25a', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/v1/subscriptions/6722fb9d-ed9e-4710-9f08-c9b63600b25a');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('API_KEY'),
  ],
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.get(
    "https://paymeusd.com/v1/subscriptions/6722fb9d-ed9e-4710-9f08-c9b63600b25a",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
Response 200
{
  "id": "b7e4c2a1-9d3f-4e8b-a5c6-0f1e2d3c4b5a",
  "status": "active",
  "plan_id": "5d0c1b8e-2f4a-4c3b-9e7d-1a2b3c4d5e6f",
  "plan_name": "Pro",
  "order_id": "user-42-pro",
  "customer": {
    "email": "anna@example.com",
    "name": "Anna",
    "reference": "user-42"
  },
  "locale": "ru",
  "amount": "29",
  "currency": "USD",
  "interval": "month",
  "interval_count": 1,
  "trial_end": "2026-11-27T09:00:00.000Z",
  "period_number": 1,
  "current_period_start": "2026-11-27T09:00:00.000Z",
  "current_period_end": "2026-12-27T09:00:00.000Z",
  "next_payment_at": "2026-12-27T09:00:00.000Z",
  "cancel_at_period_end": false,
  "cancelled_at": null,
  "ended_at": null,
  "current_invoice": {
    "id": "0e9f8a7b-6c5d-4e3f-8a1b-2c3d4e5f6a7b",
    "status": "pending",
    "period_number": 2,
    "amount": "29",
    "currency": "USD",
    "due_at": "2026-12-27T09:00:00.000Z",
    "expires_at": "2026-12-30T09:00:00.000Z",
    "payment_url": "https://paymeusd.com/pay/0e9f8a7b-6c5d-4e3f-8a1b-2c3d4e5f6a7b"
  },
  "customer_url": "https://paymeusd.com/s/Xq3v9Lr2Tn8Wk5Pz1Hc7Jm4Ba6Ds0Fe",
  "metadata": {
    "user_id": 42
  },
  "created_at": "2026-11-13T09:00:00.000Z"
}

Cancel a subscription

POST/v1/subscriptions/{id}/cancel

Immediately (default) or at the end of the paid period. An unpaid invoice for the next period is cancelled. A subscription without a paid period (pending, past_due) is cancelled immediately. Repeating the call changes nothing.

Path parameters

idstringrequired
Subscription ID.

Request body

at_period_endboolean
true — cancel renewal: the subscription stays active until current_period_end, then becomes cancelled.

Response

Object Subscription.

Errors

not_found

Request
curl -X POST "https://paymeusd.com/v1/subscriptions/6722fb9d-ed9e-4710-9f08-c9b63600b25a/cancel" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "at_period_end": true
}'
const res = await fetch('https://paymeusd.com/v1/subscriptions/6722fb9d-ed9e-4710-9f08-c9b63600b25a/cancel', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "at_period_end": true
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/v1/subscriptions/6722fb9d-ed9e-4710-9f08-c9b63600b25a/cancel');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
      'at_period_end' => true,
  ]),
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.post(
    "https://paymeusd.com/v1/subscriptions/6722fb9d-ed9e-4710-9f08-c9b63600b25a/cancel",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
        "at_period_end": True
    },
)
res.raise_for_status()
data = res.json()
Response 200
{
  "id": "b7e4c2a1-9d3f-4e8b-a5c6-0f1e2d3c4b5a",
  "status": "active",
  "plan_id": "5d0c1b8e-2f4a-4c3b-9e7d-1a2b3c4d5e6f",
  "plan_name": "Pro",
  "order_id": "user-42-pro",
  "customer": {
    "email": "anna@example.com",
    "name": "Anna",
    "reference": "user-42"
  },
  "locale": "ru",
  "amount": "29",
  "currency": "USD",
  "interval": "month",
  "interval_count": 1,
  "trial_end": "2026-11-27T09:00:00.000Z",
  "period_number": 1,
  "current_period_start": "2026-11-27T09:00:00.000Z",
  "current_period_end": "2026-12-27T09:00:00.000Z",
  "next_payment_at": null,
  "cancel_at_period_end": true,
  "cancelled_at": "2026-12-01T10:00:00.000Z",
  "ended_at": null,
  "current_invoice": null,
  "customer_url": "https://paymeusd.com/s/Xq3v9Lr2Tn8Wk5Pz1Hc7Jm4Ba6Ds0Fe",
  "metadata": {
    "user_id": 42
  },
  "created_at": "2026-11-13T09:00:00.000Z"
}

Bitcoin Lightning

Network lightning, coin BTC (asset lightning:BTC). Payments are credited within seconds, and the network fee for the customer is a fraction of a cent. The balance is shared with regular BTC: funds received via Lightning can be withdrawn on the Bitcoin network and vice versa.

Receiving

  • When the customer selects lightning:BTC (or you pass asset when creating the invoice), the gateway creates a Lightning invoice for pay_amount. In the invoice, address is the Lightning invoice itself (a BOLT11 string lnbc…, 200–400 characters), payment_uri is lightning:lnbc… for the QR code and the “Open in wallet” button, and memo is null.
  • The Lightning invoice is for the exact amount and is valid until the invoice expires: underpayment is impossible, and it cannot be paid after the deadline. If the customer switches to another coin and comes back to Lightning, a new Lightning invoice is created.
  • Payment is final immediately: required_confirmations = 1, and the invoice goes straight to paid. In the payment, tx_hash is the payment hash of the Lightning invoice, and explorer_url is empty (Lightning has no public explorer).
  • There are no static addresses in Lightning: POST /v1/static-wallets with network: "lightning" returns 400 not_supported.

Payouts

In POST /v1/payouts, set network: "lightning", currency: "BTC" and one of the following in address:

  • A Lightning Address like name@wallet.example — the most convenient option: the gateway requests an invoice for the right amount from the recipient’s wallet (LNURL-pay) and verifies it.
  • The recipient’s BOLT11 invoice. The amount in the invoice must exactly match amount; an invoice without an amount is paid for amount. An invoice can be paid only once, and a payout to an expired invoice fails.

If the invoice does not fit (wrong amount, expired, the recipient’s wallet did not respond) or the payment finds no route, the payout gets the failed status with the reason in error, and the amount and fee are returned to your balance. The payout’s tx_hash is the payment hash. The withdrawal fee is fixed — see payout_fee in GET /v1/assets; routing fees are paid by the gateway.

Payment buttons and widget

A payment button works like a Payment Link: create it in the dashboard (Payment buttons) and get a link https://paymeusd.com/b/CODE for social media and messengers, plus button code for any website. The amount is either fixed or entered by the customer (donations, top-ups, paying a bill) within a minimum and maximum. Every click creates a regular invoice with an order_id like btn-CODE-… — the payment shows up under “Invoices”, and your URL receives the same invoice.* webhooks. The customer’s email and comment are stored in the invoice metadata: {"button": "CODE", "email": "…", "comment": "…"}.

A button on your website — one line

<script src="https://paymeusd.com/widget.js" data-button="CODE" async></script>

The button appears where the tag is placed. For several buttons on one page, use the markup <div data-cp-button="CODE"></div> and a single <script src="https://paymeusd.com/widget.js" async></script> tag at the end of the page (buttons added later by the site’s scripts appear too).

AttributeValue
data-themelight (default) or dark — for dark websites
data-langru or en; defaults to the page language
data-labelCustom button text, e.g. “Support the project”
  • The button is rendered in Shadow DOM: the site’s styles do not break it, and its styles do not affect the site. It works under a strict site CSP as long as script-src and connect-src allow https://paymeusd.com.
  • On click, an invoice is created and the payment page opens in a new window on desktop and in a new tab on mobile. If pop-ups are blocked — in the same tab. The payment page cannot be embedded in an iframe.
  • For a “customer enters the amount” button, the /b/CODE page with an amount field opens.
  • Tilda: the “HTML code” block (T123). WordPress: the “Custom HTML” block.

Tilda — cart and automatic payment confirmation

Connected via Tilda’s “Universal payment system”: dashboard → “Payment buttons” → “Tilda” card → “Connect” — there you find the login, the secret and all values for “Advanced settings”. The customer checks out the cart and goes to the payment page; after payment the gateway sends Tilda a signed notification, and the order is marked as paid.

  • API URL: https://paymeusd.com/tilda/pay; the Tilda order number becomes the invoice order_id (resubmitting the form returns the same invoice).
  • Order signature — “Custom rules”: {{login}}:{{order_id}}:{{amount}}:{{currency}}:{{secret}}, SHA-256 (hex).
  • Notification signature: {{login}}:{{order_id}}:{{amount}}:{{paid}}:{{secret}}, SHA-256; payment flag paid = 1, transaction ID — transaction_id (the invoice ID), success response — OK. The notification is retried for up to 24 hours until Tilda responds with OK; the log is in the same dashboard card.

The methods below are called by the widget from the customer’s browser. No API key is needed or sent; responses are allowed for any website (CORS, no cookies). The general per-IP rate limits apply.

Button object (public)

What the customer sees: data for the button and the /b/CODE page.

codestring
Button code.
titlestring
Name — shown on the page and in the invoice description.
descriptionstring | null
Description for the customer.
amountstring | null
Fixed amount; null — the customer enters the amount.
currencystring
Currency of the amount: fiat (USD, RUB…) or a coin (USDT…).
custom_amountboolean
true — the customer enters the amount.
min_amountstring | null
Minimum amount (for custom_amount).
max_amountstring | null
Maximum amount (for custom_amount).
merchantobject
{ name } — store name.
urlstring
Button page /b/CODE — can be shared as a payment link.
Example
{
  "code": "7KQ2M9XHTA",
  "title": "1-hour consultation",
  "description": "Zoom call",
  "amount": "25",
  "currency": "USD",
  "custom_amount": false,
  "min_amount": null,
  "max_amount": null,
  "merchant": {
    "name": "Shop"
  },
  "url": "https://paymeusd.com/b/7KQ2M9XHTA"
}

Button data

GET/api/public/buttons/{code}

Public button data — no API key. A disabled or deleted button, or a button of an inactive store, returns 404.

Path parameters

codestringrequired
Button code from the dashboard (“Payment buttons” section), e.g. 7KQ2M9XHTA.

Response

Object Button.

Errors

not_found

Request
curl "https://paymeusd.com/api/public/buttons/k3x9qa7m" \
  
const res = await fetch('https://paymeusd.com/api/public/buttons/k3x9qa7m', {
  method: 'GET',
  headers: {
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/api/public/buttons/k3x9qa7m');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
  ],
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.get(
    "https://paymeusd.com/api/public/buttons/k3x9qa7m",
    
)
res.raise_for_status()
data = res.json()
Response 200
{
  "code": "7KQ2M9XHTA",
  "title": "1-hour consultation",
  "description": "Zoom call",
  "amount": "25",
  "currency": "USD",
  "custom_amount": false,
  "min_amount": null,
  "max_amount": null,
  "merchant": {
    "name": "Shop"
  },
  "url": "https://paymeusd.com/b/7KQ2M9XHTA"
}

Invoice from a button

POST/api/public/buttons/{code}/invoice

Creates a new invoice from a button (every call creates a new invoice) and returns the payment page link. No API key; called from the browser on any website.

Path parameters

codestringrequired
Button code from the dashboard (“Payment buttons” section), e.g. 7KQ2M9XHTA.

Request body

amountstring
Amount for a “customer enters the amount” button — required for it, within min_amount…max_amount. Ignored for fixed-amount buttons.
emailstring
Customer email — stored in the invoice metadata.email.
commentstring
Customer comment (up to 500 characters) — stored in metadata.comment.
return_urlstring
Where to send the customer if they leave without paying. Accepted only if it matches the site the request came from (the Origin header); otherwise the button page is used.
langstring
Payment page language, e.g. ru or en.

Response

JSON — see the example on the right.

Errors

not_found amount_required invalid_amount amount_too_small amount_too_large validation_error rate_limited

Request
curl -X POST "https://paymeusd.com/api/public/buttons/k3x9qa7m/invoice" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "buyer@example.com",
  "comment": "Please do not call"
}'
const res = await fetch('https://paymeusd.com/api/public/buttons/k3x9qa7m/invoice', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "email": "buyer@example.com",
    "comment": "Please do not call"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
<?php
$ch = curl_init('https://paymeusd.com/api/public/buttons/k3x9qa7m/invoice');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
      'email' => "buyer@example.com",
      'comment' => "Please do not call",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
import os, requests

res = requests.post(
    "https://paymeusd.com/api/public/buttons/k3x9qa7m/invoice",
    
    json={
        "email": "buyer@example.com",
        "comment": "Please do not call"
    },
)
res.raise_for_status()
data = res.json()
Response 201
{
  "id": "6722fb9d-ed9e-4710-9f08-c9b63600b25a",
  "payment_url": "https://paymeusd.com/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a"
}

Webhooks

When an invoice status changes, a payment arrives at a static address or a payout completes, we send a POST request to your URL (from the url_callback parameter or the dashboard settings).

POST /webhooks/crypto
Content-Type: application/json
X-Webhook-Id: 3f1c…            ← unique per delivery, use it for deduplication
X-Webhook-Event: invoice.paid
X-Webhook-Timestamp: 1794560245
X-Webhook-Signature: 5d2a9c…   ← HMAC-SHA256

{ "event": "invoice.paid", "created_at": "2026-11-13T09:05:28.502Z", "data": { …Invoice object… } }

Events

EventWhendata
invoice.confirmingPayment detected, waiting for confirmationsInvoice
invoice.partialPart of the amount receivedInvoice
invoice.paid, invoice.paid_overThe invoice is paid — fulfil the orderInvoice
invoice.underpaid, invoice.expired, invoice.cancelledThe invoice closed without full paymentInvoice
payment.detected, payment.confirmed, payment.failedA payment to a static address, a late payment or one in the “wrong” coinPayment + order_id
payout.queued, payout.pending_approval, payout.completed, payout.failed, payout.rejectedThe payout status changedPayout
refund.queued, refund.pending_approval, refund.completed, refund.failed, refund.rejectedThe status of a customer refund changedPayout with kind: "refund"
test.pingTest delivery from the dashboard—

Verifying the signature

The signature is hex(HMAC_SHA256(webhook_secret, timestamp + "." + raw_body)). The secret is in the dashboard, “Integration” section. Verify the signature against the raw request body before parsing the JSON, and reject requests older than 5 minutes.

Signature verification
import crypto from 'node:crypto';
import express from 'express';

const app = express();
// important: verify the signature against the RAW body
app.post('/webhooks/crypto', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.get('x-webhook-timestamp') ?? '';
  const sig = req.get('x-webhook-signature') ?? '';
  const expected = crypto.createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(`${ts}.${req.body}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  if (!fresh || sig.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body);
  if (event.event === 'invoice.paid' || event.event === 'invoice.paid_over') {
    // fulfil order event.data.order_id (idempotently!)
  }
  res.sendStatus(200);
});
<?php
$body = file_get_contents('php://input');
$ts   = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';
$sig  = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $ts . '.' . $body, getenv('WEBHOOK_SECRET'));

if (abs(time() - (int)$ts) > 300 || !hash_equals($expected, $sig)) {
    http_response_code(401);
    exit;
}
$event = json_decode($body, true);
if (in_array($event['event'], ['invoice.paid', 'invoice.paid_over'], true)) {
    // fulfil order $event['data']['order_id'] (idempotently!)
}
http_response_code(200);
import hmac, hashlib, os, time, json
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/webhooks/crypto")
def webhook():
    body = request.get_data()  # raw body
    ts = request.headers.get("X-Webhook-Timestamp", "")
    sig = request.headers.get("X-Webhook-Signature", "")
    expected = hmac.new(os.environ["WEBHOOK_SECRET"].encode(),
                        ts.encode() + b"." + body, hashlib.sha256).hexdigest()
    if abs(time.time() - int(ts or 0)) > 300 or not hmac.compare_digest(expected, sig):
        abort(401)
    event = json.loads(body)
    if event["event"] in ("invoice.paid", "invoice.paid_over"):
        pass  # fulfil order event["data"]["order_id"] (idempotently!)
    return "", 200

Retries and requirements

  • Respond with a 2xx code within 10 seconds — otherwise the delivery is retried after 1 min, 5 min, 15 min, 1 h, 3 h, 6 h, 12 h and 24 h.
  • The handler must be idempotent: the same event may arrive more than once — check X-Webhook-Id or the order status.
  • Redirects are not followed — specify the final URL.
  • The delivery log and a retry button are in the dashboard, “Integration” section.

Payment page

The customer opens payment_url — a separate page on our domain. There they choose a coin and network (with fee and timing hints) and see the amount, the address, a QR code and the confirmation status. The page is localized (see the lang parameter of the invoice), supports light and dark themes and works on mobile.

  • Redirect the customer to payment_url or open it in a new tab. Embedding it in an iframe is not allowed for security reasons.
  • asset at invoice creation skips the coin selection step, allowed_assets restricts the options.
  • After payment the customer sees a button back to url_success. But fulfil the order only on a webhook or an API response — following the link does not confirm payment.
  • From the payment page the customer can open the invoice and, once paid, the payment receipt, and save them as PDF (the links are in documents of the invoice object). These are payment documents of the service, not fiscal receipts.

Test mode

The service can run on test networks: Ethereum Sepolia, TRON Nile, Solana Devnet, BNB Smart Chain Testnet and others. Test-mode keys start with sk_test_, and the payment page shows a TESTNET label.

  • Test coins are available for free from the faucets of the respective networks.
  • All API methods, webhooks and payouts work the same as in live mode.
  • To go live, replace the key with sk_live_… — no code changes needed.