Payments API

Create a static wallet

A permanent address for an unlimited number of incoming payments.

POST https://api.speend.io/payment/createStaticWallet

When to use which

Parameter	Type	Required	DESCRIPTION
wallet_id	integer	yes	Wallet ID. An integer > 0
Currency	string	yes	Currency code
network	string	yes	Network code
url_callback	string	no	URL for webhook notifications sent after every top-up of the wallet. It must contain the merchant domain, otherwise you get 422 url_callback is not valid. If omitted, the url_callback from the merchant dashboard settings is used
customer_email	string	no	Customer e-mail (validated as an email, up to 255 characters)

{
  "wallet_id": 10,
  "currency": "USDT",
  "network": "SOL",
  "url_callback": "https://example.com/webhook"
}

{
  "uuid": "019f6990-18ac-70ab-9186-46601087c41d",
  "merchant_wallet_id": 10,
  "address": "5mzKDA******AvLADas",
  "currency": "USDT",
  "network": "SOL",
  "url": "https://example.com/webhook",
  "qr_base64_png": "iVBORw0KGgoAAAANS..."
}

Response fields

Parameter	DESCRIPTION
uuid	Wallet UUID in this network
merchant_wallet_id	Your wallet_id from the request — returned so you can match it
address	The wallet address in the chosen network — the customer sends the payment here
currency	Wallet currency
network	Wallet network
url	The url_callback from the request — returned so you can match it
qr_base64_png	A QR code of the address as a PNG, base64-encoded.

When to use which

Important — what currency does

The address belongs to a network only and physically accepts any token that network supports — a wallet is not tied to one currency. The currency field in the request does not set "which currency the accounting is kept in"; it serves one purpose only: checking that the coin you named is enabled for the merchant at all (otherwise you get the currency is disabled error).

So if you call the method again with the same wallet_id and the same network but a different currency (USDT first and then USDC on TRON, say), you get the same address back — it is physically the very same wallet.

When to use which

The threshold differs per currency. On an underpayment the transaction is visible in the blockchain, but:
no webhook is sent
the money is not credited to the merchant balance
the money physically stays on the address and is not lost

422 errors

Situation	Message
wallet_id is not a number	The wallet id must be an integer.
wallet_id is negative	The wallet id must be greater than 0.
The currency + network combination does not exist	The selected currency and network combination does not exist.
The currency is disabled for the merchant	The selected currency is disabled.
Invalid network	The selected network is invalid.
Invalid currency	The selected currency is invalid.

Create a payment (invoice)

A one-off bill for a specific order, with a ready-made payment page and support for partial payments.

POST https://api.speend.io/payment/createPayment

Request body fields

Parameter	Type	Required	DESCRIPTION
amount	number	yes	Amount in the currency given by currency. Up to 2 decimal places, 1 000 000 maximum
currency	string	yes	Invoice currency code, USD for example
order_id	integer	yes	An integer > 0. Must be unique
network / to_currency	string	no	If both are sent, the address is generated straight away. If not, the payer picks them on the payment page
url_callback	string	no	URL the payment-status webhooks will be sent to
url_return	string	no	Before paying, the user can press a button on the payment form and return to the store at this URL.
url_success	string	no	After a successful payment, the user can press a button on the payment form and return to this URL.
subtract	integer	no	The payment fee percentage (0–100) passed on to the customer on top of the invoice amount. 0 means the merchant pays the fee, 100 means the customer pays all of it
accuracy_payment_percent	number	no	The payment tolerance (0–5), up to 2 decimal places. If you send 5, for example, the invoice is marked as paid even when the customer has paid only 95% of the amount. The amount actually paid is what gets credited to the balance
additional_data	string	no	Extra information for you (not shown to the customer). 255 characters maximum
currencies	array of objects	no	The list of currencies allowed for payment. Useful when you want to narrow down the coins your customers may pay invoices with.
except_currencies	array of objects	no	The list of currencies excluded from payment.
lifetime	integer	no	Invoice lifetime in seconds: from 300 to 43200 (12 hours). 3600 by default
customer_email	integer	no	Customer e-mail (validated as an email, up to 255 characters)

{
  "amount": 2,
  "currency": "USD",
  "order_id": 1002,
  "to_currency": "TRX",
  "network": "TRON"
}

{
  "uuid": "019f8914-9a83-71d4-a318-dd20f108ebc3",
  "order_id": "3001",
  "amount": "2",
  "payment_amount": "0",
  "payer_amount": "6.07017118",
  "payer_amount_exchange_rate": "0.32948000",
  "payer_currency": "TRX",
  "currency": "USD",
  "merchant_amount": "0",
  "network": "TRON",
  "address": "TMpPCg*****yGYKMhPz",
  "address_qr_code": "iVBORw0KGgo...",
  "from": null,
  "txid": null,
  "status": "check",
  "is_final": false,
  "url": "https://pay.speend.io/pay/019f8914-9a83-71d4-a318-dd20f108ebc3",
  "expired_at": "2026-07-22 10:07:36",
  "additional_data": null,
  "created_at": "2026-07-22T09:07:36+00:00",
  "updated_at": "2026-07-22T09:07:36+00:00"
}

Response fields

Parameter	DESCRIPTION
uuid	Invoice UUID
order_id	Your order ID from the request — returned so you can match it
amount	Invoice amount in the currency given by currency
payment_amount	How much of the invoice has been paid already, in the currency given by currency (it grows as payments arrive, until amount is covered)
payer_amount	The exact amount to pay, in the currency the payer chose
payer_amount_exchange_rate	The currency → payer_currency conversion rate, fixed at the moment the invoice was created
payer_currency	The currency the payer actually sends the payment in
currency	The invoice currency set by the merchant at creation
merchant_amount	The amount credited to the merchant after the fee is withheld (in the currency given by currency)
network	The network chosen for payment
address	The payment address in the chosen network
address_qr_code	A QR code of the address as a PNG, base64-encoded
from	Always null in this method's response — it is filled in by payment/info only, once a payment has arrived
txid	Always null in this method's response — it is filled in by payment/info only, once a payment has arrived
status	The current invoice status — see the "Payment statuses" section
is_final	The final-status flag — if true, no further changes to the invoice are expected (see the note about refund_processing in the statuses section)
url	A link to the payment page you can redirect the customer to
expired_at	The date and time the invoice expires
additional_data	Your arbitrary data passed when the invoice was created
created_at	The date and time the invoice was created
updated_at	The date and time the invoice was last changed

Payment statuses

Status	Meaning
process	The invoice is created, no currency chosen yet
check	Currency and network are chosen, the address is generated, waiting for a transaction
wrong_amount_waiting	An insufficient amount arrived, waiting for the rest
wrong_amount	An insufficient amount arrived and the waiting window has expired — the rest is no longer accepted
paid	Paid in full
paid_over	Overpaid, credited automatically
cancel	The invoice was cancelled or the payment window expired (no transaction ever arrived)
locked	The transaction was blocked by an AML check (compliance scoring of the sender address)
refund_processing	A refund to the address the payment came from has been started. Processing is under way
refund_failed	The refund attempt failed
refund_success	The refund finished successfully, the customer has the money back

422 errors

Parameter	Type
amount is over 1 000 000	The amount must be less than or equal to 1000000.
The amount converted to USD is below 0.5 (this includes a negative amount)	minimum amount 0.5 USD.
order_id has been used already	order_id is not unique, try another.
order_id is negative	The order id must be greater than 0.
order_id is not a number	The order id must be an integer.
currency was found neither as a crypto nor as a fiat currency	currency is not available
network is not in the list of supported networks (a typo or a value that does not exist)	The selected network is invalid.
network is not available for accepting payments	network is not available
to_currency is not available for accepting payments	Currency is not available.
The network + to_currency combination does not exist	Currency with such network is not available
subtract is over 100	The subtract must not be greater than 100.
accuracy_payment_percent is over 5	The accuracy payment percent must not be greater than 5.
lifetime is below 300	The lifetime must be at least 300.
url_callback, url_return or url_success does not contain the merchant domain	url_callback is not valid / url_return is not valid / url_success is not valid

Payment details

Getting the current status and the full details of an invoice created earlier. By uuid or by order_id.

POST https://api.speend.io/payment/info

Parameter	Type	Required
order_id	string	Either one of the two fields, or both at once
uuid	string	—

{
  "uuid": "019f6af2-3ac1-73f5-a227-f216319ffad1"
}

{
  "order_id": "1012"
}

Response fields

The response schema is exactly the one createPayment returns (see the "Create a payment" section), plus 2 fields. On top of that, the fields that createPayment always leaves null are filled with real values here:

Parameter	Description
paid_amount_usd	The paid amount converted to USD at the rate of the moment of payment (it does not depend on the invoice currency)
convert	Details of the automatic conversion of the received funds into USDT/USDC — it appears when auto-conversion is enabled for the merchant in the dashboard. null when the option is off
from	The sender address of the latest deposit received — filled with a real value once a payment has arrived (always null in createPayment)
txid	The transaction hash of the latest deposit received — filled with a real value once a payment has arrived (always null in createPayment)

Conversion example

Parameter	Description
to_currency	The currency the funds were converted into (USDT or USDC)
commission	The conversion fee withheld during the exchange
rate	The exchange rate applied during the conversion
amount	The resulting amount after conversion into to_currency

"convert": {
  "to_currency": "USDT",
  "commission": "0.00000000",
  "rate": "44.49640000",
  "amount": "0.94872110"
}

422 errors

Situation	Message
No payment was found for the data you sent	Payment not found
Neither of the fields was sent	The order id field is required when uuid is not present. The uuid field is required when order id is not present.