Regular Invoices

Regular invoices have a fixed amount defined by the merchant. The client pays the exact specified amount.

Create New Regular Invoice

This endpoint creates a new invoice under merchant's account.

POST /api/invoices/v1/regular

Headers

Header	Value
`Authorization`	`Bearer YOUR_PUBLIC_TOKEN`
`Content-Type`	`application/json`

Request Body

Field	Type	Required	Description
`invoiceCurrency`	string	Yes	Invoice items price currency. Can be `eur`, `usd`, or one of crypto assets (`usdt`, `usdc`, `btc`, `eth`, `ton`, `sol`, `bnb`, `bch`, `ltc`, `trx`)
`items`	array	Yes	List of invoice items. Each item should contain `name` and `price`. Can contain as many items as needed
`items[].name`	string	Yes	Any desirable item name
`items[].price`	number	Yes	Item price in `invoiceCurrency`. Can be zero or negative if total price of all items is greater than 0. Precision is rounded per currency (see below)
`isMerchantPaysFee`	boolean	No	`false` — client pays total + fees, merchant receives full amount. `true` — client pays total only, merchant receives total minus fees
`paymentCurrency`	string	No	Crypto asset the merchant wants to receive. If not provided or `null`, the client chooses
`redirectURL`	string	No	URL to redirect after invoice reaches "Done" status. If `null` or absent, the default from Settings/Payment is used

Price Precision by Currency

Currency	Decimal places
usd, eur, usdt, usdc	2
sol, ton	4
btc, eth	6
bnb, bch, ltc, trx	8

cURL

curl --location 'https://my.paidlys.com/api/invoices/v1/regular' \
  --header 'Authorization: Bearer YOUR_PUBLIC_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '<body>'

Body:

{
    "invoiceCurrency": "eur",
    "items": [
        {
            "name": "Coffee",
            "price": 10.99
        },
        {
            "name": "Sugar",
            "price": 1
        },
        {
            "name": "Regular client discount",
            "price": -3
        },
        {
            "name": "Coffee gift (1+1 promo)",
            "price": 0
        }
    ],
    "isMerchantPaysFee": false,
    "paymentCurrency": "usdc",
    "redirectURL": "https://myshop.com/payment-success"
}

Response

View response body

{
    "id": "invoice_id",
    "status": "created",
    "createdAt": "YYYY-MM-DDTHH:MM:SS.000Z",
    "company": {
        "name": "%company_name",
        "logoUrl": "%logo_url%",
        "assets": [
            { "asset": "btc", "isAllowed": false },
            { "asset": "eth", "isAllowed": false },
            { "asset": "usdt", "isAllowed": false },
            { "asset": "sol", "isAllowed": false },
            { "asset": "ton", "isAllowed": false },
            { "asset": "usdc", "isAllowed": false },
            { "asset": "bnb", "isAllowed": false },
            { "asset": "ltc", "isAllowed": false },
            { "asset": "near", "isAllowed": false },
            { "asset": "trx", "isAllowed": false },
            { "asset": "bch", "isAllowed": false }
        ]
    },
    "invoiceContent": {
        "invoiceCurrency": "eur",
        "items": [
            { "name": "Coffee", "price": "10" },
            { "name": "Sugar", "price": "1" },
            { "name": "Regular client discount", "price": "-3" }
        ],
        "paymentCurrency": "usdc",
        "isMerchantPaysFee": false,
        "redirectURL": "https://myshop.com/payment-success"
    }
}

Response Fields

Field	Description
`id`	Invoice identifier. Open on frontend: `https://pay.paidlys.com/%invoice_id%`
`status`	Current invoice state (see Invoice Statuses)
`createdAt`	Invoice creation date and time
`company`	Merchant's company information: `name`, `logoUrl`, `assets` (list of accepted assets with `isAllowed` flag)
`invoiceContent`	Primary invoice info: items list, prices, `invoiceCurrency`, `paymentCurrency`, `isMerchantPaysFee`
`redirectURL`	URL for redirect after "Done" status. `null` means no redirect

Fill Invoice with Client Info

This endpoint fills a regular invoice with client's info — email address and payment asset (if not pre-defined by merchant during creation).

POST /api/invoices/v1/regular/%invoice_id%/proceed

Headers

Header	Value
`Content-Type`	`application/json`
`Authorization`	`Bearer YOUR_PUBLIC_TOKEN` (optional)

Authorization is not required as the invoice is provided to a non-registered client and uses their email to identify the person as an invoice payee.

Request Body

Field	Type	Required	Description
`clientEmail`	string	Yes	Client's email. Should meet standard email format
`paymentCurrency`	string	Yes	Asset name + network the client wants to pay with. Values: `btc`, `eth`, `trc20usdt`, `usdterc20`, `sol`, `ton`, `usdc`, `bnb`, `ltc`, `trx`, `bch`. Ignored if `paymentCurrency` was previously provided during invoice creation or its value was `null`

cURL

curl --location 'https://my.paidlys.com/api/invoices/v1/regular/%invoice_id%/proceed' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_PUBLIC_TOKEN' \
  --data '<body>'

Body:

{
    "paymentCurrency": "sol",
    "clientEmail": "client@example.com"
}

Response

View response body

{
    "id": "%invoice_id%",
    "status": "%invoice_status%",
    "createdAt": "YYYY-MM-DDTHH:MM:SS.000Z",
    "company": {
        "name": "%company_name%",
        "logoUrl": "%logo_url%",
        "assets": [
            { "asset": "btc", "isAllowed": true },
            { "asset": "eth", "isAllowed": false },
            { "asset": "usdt", "isAllowed": true },
            { "asset": "sol", "isAllowed": false },
            { "asset": "ton", "isAllowed": false },
            { "asset": "usdc", "isAllowed": false },
            { "asset": "bnb", "isAllowed": false },
            { "asset": "ltc", "isAllowed": false },
            { "asset": "near", "isAllowed": false },
            { "asset": "trx", "isAllowed": false },
            { "asset": "bch", "isAllowed": false }
        ]
    },
    "invoiceContent": {
        "invoiceCurrency": "eur",
        "items": [
            { "name": "Coffee", "price": "1000" },
            { "name": "Sugar", "price": "1" },
            { "name": "Regular client discount", "price": "-3" }
        ],
        "paymentCurrency": "trc20usdt",
        "isMerchantPaysFee": false
    },
    "redirectURL": "%url_for_DONE_statused_invoices_redirection%",
    "clientEmail": "client_mail@service.domain",
    "address": {
        "id": "%payment_address_id%",
        "address": "%payment_address%",
        "tag": null,
        "asset": "trc20usdt"
    },
    "paymentDetails": {
        "rate": "1.16843920",
        "invoiceFee": "12.728032"
    },
    "expiredAt": "YYYY-MM-DDTHH:MM:SS.000Z"
}

Additional Response Fields

Fields available after the invoice is filled (not available for "Created" status):

Field	Description
`clientEmail`	Client's email
`address`	Payment address: `id`, `address`, `tag` (null if not TON), `asset`
`paymentDetails.rate`	invoiceCurrency → paymentCurrency exchange rate
`paymentDetails.invoiceFee`	Fees in paymentCurrency
`expiredAt`	Invoice expiration time. 30 min for all assets, 120 min for BTC

Get Invoice Info

This endpoint allows to receive invoice info. For clients it's necessary to see their invoice. For merchants it's necessary to have invoice info on the "Invoices" page.

GET /api/invoices/v1/regular/%invoice_id%

Headers

Header	Value
`Content-Type`	`application/json`

Authorization is not required.

cURL

curl --location 'https://my.paidlys.com/api/invoices/v1/regular/%invoice_id%' \
  --header 'Content-Type: application/json'

Response

Response will differ depending on the invoice's status and its corresponding content.

View full response body

{
    "id": "%invoice_id%",
    "status": "%invoice_status%",
    "createdAt": "YYYY-MM-DDTHH:MM:SS.000Z",
    "company": {
        "name": "%company_name%",
        "logoUrl": "%logo_url%",
        "assets": [
            { "asset": "btc", "isAllowed": true },
            { "asset": "eth", "isAllowed": false },
            { "asset": "usdt", "isAllowed": true },
            { "asset": "sol", "isAllowed": false },
            { "asset": "ton", "isAllowed": false },
            { "asset": "usdc", "isAllowed": false },
            { "asset": "bnb", "isAllowed": false },
            { "asset": "ltc", "isAllowed": false },
            { "asset": "near", "isAllowed": false },
            { "asset": "trx", "isAllowed": false },
            { "asset": "bch", "isAllowed": false }
        ]
    },
    "invoiceContent": {
        "invoiceCurrency": "eur",
        "items": [
            { "name": "Coffee", "price": "1000" },
            { "name": "Sugar", "price": "1" },
            { "name": "Regular client discount", "price": "-3" }
        ],
        "paymentCurrency": "trc20usdt",
        "isMerchantPaysFee": false
    },
    "redirectURL": "%url_for_DONE_statused_invoices_redirection%",
    "clientEmail": "client_mail@service.domain",
    "address": {
        "id": "%payment_address_id%",
        "address": "%payment_address%",
        "tag": null,
        "asset": "trc20usdt"
    },
    "paymentDetails": {
        "rate": "1.16843920",
        "invoiceFee": "12.728032"
    },
    "invoiceTransactions": [
        {
            "id": "%transaction_id%",
            "amount": "34.1054",
            "from": "usdt",
            "txHash": "https://tronscan.org/#/transaction/%tx_id%",
            "companyId": "%company_id%",
            "invoiceId": "%invoice_id%",
            "addressId": "%payment_address_id%",
            "createdAt": "YYYY-MM-DDTHH:MM:SS.000Z"
        }
    ],
    "expiredAt": "YYYY-MM-DDTHH:MM:SS.000Z"
}

Additional Response Fields (vs Fill Invoice)

Field	Description
`invoiceTransactions`	List of invoice transactions (deposits, autoswaps). Unavailable until at least one transaction has occurred. Content is dynamically added as new transactions are created

Create New Regular Invoice​

Headers​

Request Body​

Price Precision by Currency​

cURL​

Response​

Response Fields​

Fill Invoice with Client Info​

Headers​

Request Body​

cURL​

Response​

Additional Response Fields​

Get Invoice Info​

Headers​

cURL​

Response​

Additional Response Fields (vs Fill Invoice)​

Create New Regular Invoice

Headers

Request Body

Price Precision by Currency

cURL

Response

Response Fields

Fill Invoice with Client Info

Headers

Request Body

cURL

Response

Additional Response Fields

Get Invoice Info

Headers

cURL

Response

Additional Response Fields (vs Fill Invoice)