Create an invoice

Creates an invoice payable in the chosen coin and network.

POST/invoices

System information

API key: Required
Rate limit: 20 requests per minute

Body parameters

Parameter	Type	Required	Description
coinCode	string	Yes	Cryptocurrency code, for example `USDT`.
networkCode	string	Yes	Blockchain network code, for example `tron`.
amount	string	Yes	Fiat payment amount. At most 2 decimals.
currency	string	No	Fiat currency of the amount: `USD`, `EUR`, `RUB`. Default `USD`.
orderId	string	No	Your order ID. Used for idempotency within the project.
description	string	No	Payment description.

curl -X POST "https://api.atomic.wallet/api/v1/invoices" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "coinCode": "USDT",
  "networkCode": "tron",
  "amount": "100.00",
  "currency": "USD",
  "orderId": "order-1001",
  "description": "Order payment"
}'

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "projectUuid": "73e68013-32f0-4248-95ac-46aed61e59b0",
  "coinCode": "USDT",
  "networkCode": "tron",
  "coinName": "Tether USD",
  "networkName": "TRON",
  "networkPrefix": "TRC-20",
  "amount": "100.000000",
  "sourceAmount": "100.00",
  "sourceCurrency": "USD",
  "sourceRate": "1.000000",
  "status": "pending",
  "confirmedAmount": "0.000000",
  "unconfirmedAmount": "0.000000",
  "remainingAmount": "100.000000",
  "overpaidAmount": "0.000000"
}

Response fields

Parameter	Type	Description
uuid	string	Invoice UUID.
projectUuid	string	Project UUID.
coinCode	string	Cryptocurrency code.
networkCode	string	Blockchain network code.
coinName	string	Cryptocurrency name.
networkName	string	Network name.
networkPrefix	string	Token standard in the network, for example `TRC-20`.
amount	string	Amount to pay in cryptocurrency.
sourceAmount	string	Invoice amount in the source currency.
sourceCurrency	string	Invoice source currency.
sourceRate	string	Conversion rate from the source currency to cryptocurrency.
status	string	Invoice status, see “Statuses”.
confirmedAmount	string	Paid and confirmed amount.
unconfirmedAmount	string	Received but not yet confirmed amount.
remainingAmount	string	Amount left to pay.
overpaidAmount	string	Overpaid amount.

Idempotency

Situation	Result
Same `orderId` and same payload	The existing invoice is returned.
Same `orderId`, different payload	`409 INVOICE_EXTERNAL_ID_CONFLICT`
No `orderId`	Every `POST` creates a new invoice.
`429 INVOICE_CREATION_RATE_LIMITED`	Limit: 20 invoices per 60 seconds per project.
`500` or timeout	The outcome is unknown: retry only with the same `orderId` and keep the `requestId`.

Possible errors

HTTP	Code	Description
400	`INVOICE_COIN_UNAVAILABLE`	The coin is not available for invoices.
400	`INVOICE_AMOUNT_INVALID`	Invalid invoice amount.
400	`INVOICE_AMOUNT_BELOW_MINIMUM`	The amount is below the minimum.
400	`INVOICE_AMOUNT_ABOVE_MAXIMUM`	The amount is above the maximum.
400	`INVOICE_DESCRIPTION_INVALID`	Invalid invoice description.
400	`INVOICE_RATE_UNAVAILABLE`	No rate available for the coin.
400	`INVOICE_ADDRESS_GENERATION_FAILED`	Failed to generate the invoice address.
400	`VALIDATION_FAILED`	Request parameters failed validation.
409	`INVOICE_EXTERNAL_ID_CONFLICT`	`orderId` is already used with different invoice parameters.
429	`INVOICE_CREATION_RATE_LIMITED`	Invoice creation rate limit exceeded.

← PreviousOverview Next →List invoices