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.
https://paymway.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
- Get an API key. Sign up and create a key in the dashboard: Integration → API keys.
- Create an invoice with
POST /v1/invoicesand redirect the customer topayment_url. - Handle the webhook. Accept
invoice.paidat yoururl_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.
message 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.| HTTP | Code | When |
|---|---|---|
| 400 | validation_error | Invalid request parameters |
| 400 | unsupported_currency, unknown_asset, asset_not_allowed | The currency or asset is not supported |
| 400 | invalid_address, amount_too_small, insufficient_balance | Payout errors |
| 401 | unauthorized | The key is missing, invalid or revoked, or the account is not active |
| 404 | not_found | The object does not exist or belongs to another account |
| 400 | invalid_idempotency_key | The Idempotency-Key header is empty, longer than 255 characters or contains non-printable or non-ASCII characters |
| 409 | order_exists | This order_id already exists with different parameters |
| 409 | idempotency_in_progress | A request with this Idempotency-Key is still in progress — retry in a few seconds |
| 422 | idempotency_key_mismatch | This Idempotency-Key has already been used with a different request — use a new key |
| 409 | invoice_locked | The invoice can no longer be changed or cancelled |
| 409 | nothing_to_refund | Nothing to refund for this invoice: no payments, or everything has already been refunded |
| 400 | refund_too_large | The refund amount exceeds the amount received for the invoice |
| 400 | batch_invalid | The batch payout was not created: invalid rows or insufficient balance — see details |
| 403 | address_not_whitelisted, address_not_active_yet | The payout address whitelist is on: the address is not on the list or is not active yet (new addresses become active after 24 h) |
| 403 | refund_requires_cabinet | With the whitelist on, refunds can only be made from the dashboard |
| 429 | rate_limited | Too many requests — retry after the time given in the message |
| 500 | internal_error | Failure on the service side — retry later; if it persists, contact support |
| 503 | rate_unavailable, network_unavailable | The 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: trueheader — 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.GETrequests 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.
| Status | Meaning |
|---|---|
pending | Awaiting payment |
confirming | Payment detected, waiting for network confirmations |
partial | Part of the amount received; the customer can pay the rest before the invoice expires |
paid / paid_over | Paid in full / overpaid — you can fulfil the order |
underpaid | Expired with only part of the amount received |
expired | Expired without payment |
cancelled | Cancelled 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_finalbooleantrue— 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.nulluntil 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…nullfor 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 arenull).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 (nulluntil 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:
ruorglobal.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_offbooleantrue— crypto payment is turned off for this invoice (crypto: falsewas passed at creation).themestring | null- Payment page theme, if set at creation:
lightordark.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".
{
"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://paymway.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://paymway.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://paymway.com/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a/invoice",
"receipt_url": "https://paymway.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
/v1/invoicesCreates 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,TRYor 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 thelanglanguage). Withoutemail, the payment page asks the buyer for it before they choose a payment method and saves it tocustomer.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 (convertby default). If there are no such methods in the invoice currency,convertapplies. cryptobooleanfalse— no crypto payment: only the additional payment methods, if enabled (otherwise theno_payment_methodserror). Default:true.themestring- Payment page theme:
lightordark. 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
curl -X POST "https://paymway.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://paymway.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://paymway.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://paymway.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()
{
"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://paymway.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://paymway.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://paymway.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
/v1/invoices/{id}Current state of the invoice with all its payments.
Path parameters
idstringrequired- Invoice ID.
Response
Object Invoice.
Errors
not_found
curl "https://paymway.com/v1/invoices/6722fb9d-ed9e-4710-9f08-c9b63600b25a" \
-H "Authorization: Bearer $API_KEY"const res = await fetch('https://paymway.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://paymway.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://paymway.com/v1/invoices/6722fb9d-ed9e-4710-9f08-c9b63600b25a",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
{
"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://paymway.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://paymway.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://paymway.com/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a/invoice",
"receipt_url": "https://paymway.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
/v1/invoicesInvoices, 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.
curl "https://paymway.com/v1/invoices?order_id=1001" \
-H "Authorization: Bearer $API_KEY"const res = await fetch('https://paymway.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://paymway.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://paymway.com/v1/invoices?order_id=1001",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
{
"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://paymway.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://paymway.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://paymway.com/pay/6722fb9d-ed9e-4710-9f08-c9b63600b25a/invoice",
"receipt_url": "https://paymway.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
/v1/invoices/{id}/cancelCancels a pending invoice that has not received any payments yet.
Path parameters
idstringrequired- Invoice ID.
Response
Object Invoice.
Errors
not_found invoice_locked
curl -X POST "https://paymway.com/v1/invoices/6722fb9d-ed9e-4710-9f08-c9b63600b25a/cancel" \
-H "Authorization: Bearer $API_KEY"const res = await fetch('https://paymway.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://paymway.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://paymway.com/v1/invoices/6722fb9d-ed9e-4710-9f08-c9b63600b25a/cancel",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
{
"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://paymway.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://paymway.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://paymway.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
/v1/invoices/{id}/refundCreates 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
curl -X POST "https://paymway.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://paymway.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://paymway.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://paymway.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()
{
"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.
{
"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
/v1/static-walletsReturns 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
curl -X POST "https://paymway.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://paymway.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://paymway.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://paymway.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()
{
"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.
statusstringpending— waiting for confirmations,confirmed— credited,failed— reverted or dropped from the chain.kindstringinvoice— 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.
{
"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
/v1/paymentsPayments, 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.
curl "https://paymway.com/v1/payments" \
-H "Authorization: Bearer $API_KEY"const res = await fetch('https://paymway.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://paymway.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://paymway.com/v1/payments",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
{
"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
/v1/balancesAmounts available for withdrawal, per coin.
Response
An object with an items list.
curl "https://paymway.com/v1/balances" \
-H "Authorization: Bearer $API_KEY"const res = await fetch('https://paymway.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://paymway.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://paymway.com/v1/balances",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
{
"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.
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.
kindstringpayout— 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).
statusstringpending_approval→queued→processing→completed; alsofailedandrejected(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.
{
"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
/v1/payoutsQueues 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
curl -X POST "https://paymway.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://paymway.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://paymway.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://paymway.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()
{
"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
/v1/payouts/batchUp 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, optionallymemoandorder_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
curl -X POST "https://paymway.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://paymway.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://paymway.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://paymway.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()
{
"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
/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
curl "https://paymway.com/v1/payouts/batch/6722fb9d-ed9e-4710-9f08-c9b63600b25a" \
-H "Authorization: Bearer $API_KEY"const res = await fetch('https://paymway.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://paymway.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://paymway.com/v1/payouts/batch/6722fb9d-ed9e-4710-9f08-c9b63600b25a",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
{
"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
/v1/payouts/{id}Current payout status and transaction hash.
Path parameters
idstringrequired- Payout ID.
Response
Object Payout.
Errors
not_found
curl "https://paymway.com/v1/payouts/6722fb9d-ed9e-4710-9f08-c9b63600b25a" \
-H "Authorization: Bearer $API_KEY"const res = await fetch('https://paymway.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://paymway.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://paymway.com/v1/payouts/6722fb9d-ed9e-4710-9f08-c9b63600b25a",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
{
"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
/v1/payoutsPayouts, 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.
curl "https://paymway.com/v1/payouts" \
-H "Authorization: Bearer $API_KEY"const res = await fetch('https://paymway.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://paymway.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://paymway.com/v1/payouts",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
{
"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 ID | Network | Decimals | Confs | ≈ Settlement | Min. payment | Payout fee |
|---|---|---|---|---|---|---|
bitcoin:BTC | Bitcoin | 8 | 2 | 20 min | 0.00001 | 0.0002 |
ethereum:ETH | Ethereum | 18 | 12 | 2 min | 0.00001 | 0.0005 |
ethereum:USDT | Ethereum ERC-20 | 6 | 12 | 2 min | 0.01 | 5 |
ethereum:USDC | Ethereum ERC-20 | 6 | 12 | 2 min | 0.01 | 5 |
bsc:BNB | BNB Smart Chain | 18 | 15 | 10 sec | 0.0001 | 0.0005 |
bsc:USDT | BNB Smart Chain BEP-20 | 18 | 15 | 10 sec | 0.01 | 0.5 |
bsc:USDC | BNB Smart Chain BEP-20 | 18 | 15 | 10 sec | 0.01 | 0.5 |
polygon:POL | Polygon | 18 | 32 | 1 min | 0.01 | 0.5 |
polygon:USDT | Polygon ERC-20 | 6 | 32 | 1 min | 0.01 | 0.5 |
polygon:USDC | Polygon ERC-20 | 6 | 32 | 1 min | 0.01 | 0.5 |
arbitrum:ETH | Arbitrum One | 18 | 20 | 5 sec | 0.00001 | 0.0005 |
arbitrum:USDT | Arbitrum One ERC-20 | 6 | 20 | 5 sec | 0.01 | 0.5 |
arbitrum:USDC | Arbitrum One ERC-20 | 6 | 20 | 5 sec | 0.01 | 0.5 |
optimism:ETH | Optimism | 18 | 20 | 40 sec | 0.00001 | 0.0005 |
optimism:USDT | Optimism ERC-20 | 6 | 20 | 40 sec | 0.01 | 0.5 |
optimism:USDC | Optimism ERC-20 | 6 | 20 | 40 sec | 0.01 | 0.5 |
base:ETH | Base | 18 | 20 | 40 sec | 0.00001 | 0.0005 |
base:USDC | Base ERC-20 | 6 | 20 | 40 sec | 0.01 | 0.5 |
avalanche:AVAX | Avalanche C-Chain | 18 | 3 | 5 sec | 0.001 | 0.02 |
avalanche:USDT | Avalanche C-Chain ERC-20 | 6 | 3 | 5 sec | 0.01 | 0.5 |
avalanche:USDC | Avalanche C-Chain ERC-20 | 6 | 3 | 5 sec | 0.01 | 0.5 |
plasma:XPL | Plasma | 18 | 10 | 10 sec | 0.01 | 0.5 |
plasma:USDT | Plasma ERC-20 | 6 | 10 | 10 sec | 0.01 | 0.5 |
kaia:KAIA | Kaia | 18 | 3 | 5 sec | 0.1 | 1 |
kaia:USDT | Kaia ERC-20 | 6 | 3 | 5 sec | 0.01 | 0.5 |
celo:CELO | Celo | 18 | 10 | 10 sec | 0.1 | 0.5 |
celo:USDT | Celo ERC-20 | 6 | 10 | 10 sec | 0.01 | 0.5 |
celo:USDC | Celo ERC-20 | 6 | 10 | 10 sec | 0.01 | 0.5 |
kava:KAVA | Kava | 18 | 3 | 20 sec | 0.1 | 0.5 |
kava:USDT | Kava ERC-20 | 6 | 3 | 20 sec | 0.01 | 0.5 |
mantle:MNT | Mantle | 18 | 20 | 40 sec | 0.1 | 0.5 |
mantle:USDT | Mantle ERC-20 | 6 | 20 | 40 sec | 0.01 | 0.5 |
tron:TRX | TRON | 6 | 19 | 55 sec | 1 | 1 |
tron:USDT | TRON TRC-20 | 6 | 19 | 55 sec | 0.01 | 2 |
solana:SOL | Solana | 9 | 32 | 15 sec | 0.0001 | 0.005 |
solana:USDT | Solana SPL | 6 | 32 | 15 sec | 0.01 | 1 |
solana:USDC | Solana SPL | 6 | 32 | 15 sec | 0.01 | 1 |
ton:TON | TON | 9 | 1 | 5 sec | 0.01 | 0.05 |
ton:USDT | TON | 6 | 1 | 5 sec | 0.01 | 1 |
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.
{
"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
/v1/assetsAll assets currently available for payments and withdrawals.
Response
An object with an items list.
curl "https://paymway.com/v1/assets" \
-H "Authorization: Bearer $API_KEY"const res = await fetch('https://paymway.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://paymway.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://paymway.com/v1/assets",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
{
"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
/v1/domainsThe 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.
curl "https://paymway.com/v1/domains" \
const res = await fetch('https://paymway.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://paymway.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://paymway.com/v1/domains",
)
res.raise_for_status()
data = res.json()
{
"regions": {
"ru": {
"active": "https://pay-shop.ru"
},
"global": {
"active": "https://paymway.com"
}
},
"fallback": "https://paymway.com"
}Service status
/v1/statusWhether 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.
curl "https://paymway.com/v1/status" \
const res = await fetch('https://paymway.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://paymway.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://paymway.com/v1/status",
)
res.raise_for_status()
data = res.json()
{
"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
/v1/currenciesCurrencies 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.
curl "https://paymway.com/v1/currencies" \
-H "Authorization: Bearer $API_KEY"const res = await fetch('https://paymway.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://paymway.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://paymway.com/v1/currencies",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
{
"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.
- Create a plan —
POST /v1/plans: amount and period, optionally a trial. - Create a subscription —
POST /v1/subscriptionswith the customer’s email. Without a trial, the invoice for the first period is issued immediately: send the customer tocurrent_invoice.payment_url. - 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.renewedwebhook.
| Status | Meaning |
|---|---|
pending | Awaiting the first payment. If none arrives before the grace period ends — expired |
trialing | Trial period; the invoice for the first period arrives before it ends |
active | Paid until current_period_end — provide the service |
past_due | The 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 |
cancelled | Cancelled: by you, by the customer on the subscription page, or at the end of the period after renewal was cancelled |
expired | Not paid before the grace period ended |
- A subscription invoice is a regular invoice: its
order_idlooks likesub-<subscription id>-<period number>, it carriesmetadata.billing_subscription_id, and it triggers the usualinvoice.*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).
| Event | When |
|---|---|
subscription.created | Subscription created |
subscription.invoice_created | Invoice for the next period issued (+ invoice) |
subscription.renewed | Invoice paid, period extended (+ invoice) |
subscription.past_due | The period has ended, the invoice is unpaid |
subscription.cancel_scheduled, subscription.resumed | Renewal cancelled / resumed (the subscription stays active until the end of the period) |
subscription.cancelled | Subscription cancelled |
subscription.expired | Not 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. archivedbooleantrue— 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.
{
"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).
statusstringpending,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.
nullif renewal is cancelled or the subscription has ended. cancel_at_period_endbooleantrue— renewal is cancelled: no new invoices, and at the end of the period the status becomescancelled.cancelled_atstring | null- When cancellation was requested.
ended_atstring | null- When the subscription ended (
cancelledorexpired). 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.
{
"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://paymway.com/pay/0e9f8a7b-6c5d-4e3f-8a1b-2c3d4e5f6a7b"
},
"customer_url": "https://paymway.com/s/Xq3v9Lr2Tn8Wk5Pz1Hc7Jm4Ba6Ds0Fe",
"metadata": {
"user_id": 42
},
"created_at": "2026-11-13T09:00:00.000Z"
}Create a plan
/v1/plansA 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,TRYor a coin ticker (USDT…). intervalstringrequiredday,week,monthoryear.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
curl -X POST "https://paymway.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://paymway.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://paymway.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://paymway.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()
{
"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
/v1/plansPlans, newest first; archived plans last.
Query parameters
include_archivedstringtrue— include archived plans.limitinteger- 1 to 100, default 50.
Response
An object with an items list.
curl "https://paymway.com/v1/plans" \
-H "Authorization: Bearer $API_KEY"const res = await fetch('https://paymway.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://paymway.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://paymway.com/v1/plans",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
{
"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
/v1/plans/{id}Plan by ID.
Path parameters
idstringrequired- Plan ID.
Response
Object Plan.
Errors
not_found
curl "https://paymway.com/v1/plans/6722fb9d-ed9e-4710-9f08-c9b63600b25a" \
-H "Authorization: Bearer $API_KEY"const res = await fetch('https://paymway.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://paymway.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://paymway.com/v1/plans/6722fb9d-ed9e-4710-9f08-c9b63600b25a",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
{
"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
/v1/plans/{id}/archiveNo 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
curl -X POST "https://paymway.com/v1/plans/6722fb9d-ed9e-4710-9f08-c9b63600b25a/archive" \
-H "Authorization: Bearer $API_KEY"const res = await fetch('https://paymway.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://paymway.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://paymway.com/v1/plans/6722fb9d-ed9e-4710-9f08-c9b63600b25a/archive",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
{
"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
/v1/subscriptionsCreates 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) oren. 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
curl -X POST "https://paymway.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://paymway.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://paymway.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://paymway.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()
{
"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://paymway.com/pay/0e9f8a7b-6c5d-4e3f-8a1b-2c3d4e5f6a7b"
},
"customer_url": "https://paymway.com/s/Xq3v9Lr2Tn8Wk5Pz1Hc7Jm4Ba6Ds0Fe",
"metadata": {
"user_id": 42
},
"created_at": "2026-11-13T09:00:00.000Z"
}List subscriptions
/v1/subscriptionsSubscriptions, 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.
curl "https://paymway.com/v1/subscriptions?customer_email=anna%40example.com" \
-H "Authorization: Bearer $API_KEY"const res = await fetch('https://paymway.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://paymway.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://paymway.com/v1/subscriptions?customer_email=anna%40example.com",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
{
"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://paymway.com/pay/0e9f8a7b-6c5d-4e3f-8a1b-2c3d4e5f6a7b"
},
"customer_url": "https://paymway.com/s/Xq3v9Lr2Tn8Wk5Pz1Hc7Jm4Ba6Ds0Fe",
"metadata": {
"user_id": 42
},
"created_at": "2026-11-13T09:00:00.000Z"
}
]
}Retrieve a subscription
/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
curl "https://paymway.com/v1/subscriptions/6722fb9d-ed9e-4710-9f08-c9b63600b25a" \
-H "Authorization: Bearer $API_KEY"const res = await fetch('https://paymway.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://paymway.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://paymway.com/v1/subscriptions/6722fb9d-ed9e-4710-9f08-c9b63600b25a",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
res.raise_for_status()
data = res.json()
{
"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://paymway.com/pay/0e9f8a7b-6c5d-4e3f-8a1b-2c3d4e5f6a7b"
},
"customer_url": "https://paymway.com/s/Xq3v9Lr2Tn8Wk5Pz1Hc7Jm4Ba6Ds0Fe",
"metadata": {
"user_id": 42
},
"created_at": "2026-11-13T09:00:00.000Z"
}Cancel a subscription
/v1/subscriptions/{id}/cancelImmediately (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_endbooleantrue— cancel renewal: the subscription stays active untilcurrent_period_end, then becomescancelled.
Response
Object Subscription.
Errors
not_found
curl -X POST "https://paymway.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://paymway.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://paymway.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://paymway.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()
{
"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://paymway.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 passassetwhen creating the invoice), the gateway creates a Lightning invoice forpay_amount. In the invoice,addressis the Lightning invoice itself (a BOLT11 stringlnbc…, 200–400 characters),payment_uriislightning:lnbc…for the QR code and the “Open in wallet” button, andmemoisnull. - 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 topaid. In the payment,tx_hashis the payment hash of the Lightning invoice, andexplorer_urlis empty (Lightning has no public explorer). - There are no static addresses in Lightning:
POST /v1/static-walletswithnetwork: "lightning"returns400 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 foramount. 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://paymway.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://paymway.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://paymway.com/widget.js" async></script> tag at the end of the page (buttons added later by the site’s scripts appear too).
| Attribute | Value |
|---|---|
data-theme | light (default) or dark — for dark websites |
data-lang | ru or en; defaults to the page language |
data-label | Custom 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-srcandconnect-srcallowhttps://paymway.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/CODEpage 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://paymway.com/tilda/pay; the Tilda order number becomes the invoiceorder_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 flagpaid = 1, transaction ID —transaction_id(the invoice ID), success response —OK. The notification is retried for up to 24 hours until Tilda responds withOK; 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_amountbooleantrue— 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.
{
"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://paymway.com/b/7KQ2M9XHTA"
}Button data
/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
curl "https://paymway.com/api/public/buttons/k3x9qa7m" \
const res = await fetch('https://paymway.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://paymway.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://paymway.com/api/public/buttons/k3x9qa7m",
)
res.raise_for_status()
data = res.json()
{
"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://paymway.com/b/7KQ2M9XHTA"
}Invoice from a button
/api/public/buttons/{code}/invoiceCreates 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
Originheader); otherwise the button page is used. langstring- Payment page language, e.g.
ruoren.
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
curl -X POST "https://paymway.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://paymway.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://paymway.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://paymway.com/api/public/buttons/k3x9qa7m/invoice",
json={
"email": "buyer@example.com",
"comment": "Please do not call"
},
)
res.raise_for_status()
data = res.json()
{
"id": "6722fb9d-ed9e-4710-9f08-c9b63600b25a",
"payment_url": "https://paymway.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
| Event | When | data |
|---|---|---|
invoice.confirming | Payment detected, waiting for confirmations | Invoice |
invoice.partial | Part of the amount received | Invoice |
invoice.paid, invoice.paid_over | The invoice is paid — fulfil the order | Invoice |
invoice.underpaid, invoice.expired, invoice.cancelled | The invoice closed without full payment | Invoice |
payment.detected, payment.confirmed, payment.failed | A payment to a static address, a late payment or one in the “wrong” coin | Payment + order_id |
payout.queued, payout.pending_approval, payout.completed, payout.failed, payout.rejected | The payout status changed | Payout |
refund.queued, refund.pending_approval, refund.completed, refund.failed, refund.rejected | The status of a customer refund changed | Payout with kind: "refund" |
test.ping | Test 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.
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
2xxcode 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-Idor 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_urlor open it in a new tab. Embedding it in aniframeis not allowed for security reasons. assetat invoice creation skips the coin selection step,allowed_assetsrestricts 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
documentsof 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.