Listing invoices

GET /api/public/v1/invoices

This endpoint returns a list of invoices with pagination.

Headers

NameValue

Content-Type

application/vnd.api+json

Authorization

Bearer <api_key>

Query Parameters

NameTypeDescription

order

string

Order in which the list of invoices should be returned. Can be created_at.

order_type

string

Order type. Can be either asc or desc.

page

number

Page for which you want to return invoices.

per_page

number

Number of invoices per page to return.

reference

number

Invoice reference.

Response Body

NameTypeDescription

data.id

string

Invoice ID.

data.type

string

Entity type returned. Always invoices.

data.attributes

object

Set of invoice attributes.

data.attributes.amountBilled

string

Invoice amount to display to end users. Determines the amount due after conversion.

data.attributes.amountCharged

string

Amount due. Determines the amount of cryptucurrency the end-user is required to pay.

data.attributes.billedCurrency

string

Invoice currency to display to end users. Determines the currency due after conversion. Refer to supported currencies.

data.attributes.chargedCurrency

string

Crypto currency that customer must pay in. Refer to supported currencies.

data.attributes.reference

string

The custom reference ID to tie the invoice to end-user who pays. This can be anything you choose.

data.attributes.statusContext

string

Invoice status context. Refer to Invoice status flow.

data.attributes.network

string

Network code. Refer to Supported currencies.

data.attributes.networkName

string

Network name to display.

data.attributes.status

string

Invoice status. Refer to Invoice status flow.

data.attributes.successRedirectUrl

string

URL your customer will be redirected from our hosted page to if the invoice completes.

data.attributes.unsuccessRedirectUrl

string

URL your customer will be redirected from our hosted page to if the invoice gets expired, cancelled or rejected.

data.attributes.paymentStatus

string

Invoice payment status. Refer to Invoice status flow.

data.attributes.exchangeRate

string

Invoice exchange rate valid for 20 minutes.

data.attributes.expiresAt

string

Invoice expiry date and time.

data.attributes.createdAt

string

Date and time invoice was created at.

data.attributes.hostedPageUrl

string

Invoice hosted page.

included.type(addresses).attributes

object

Invocie receiving address. This is the address the end-user must send their crytpocurrency payment to.

included.type(invoiceTransactions).attributes

object

Invoice processing fee. This is how much Txn will debit from the finalized invoice payment before crediting funds to the merchant's account on the Txn platform - transactionFee.

included.type(coinDeposits).attributes

object

Data related to cryptocurrency payment/s made by the end-user. In this object you will find a transaction hash txHash, transaction amount amount and transaction timestamp createdAt.

included.type(transactions).attributes

object

Data related to invoice entries on the merchant's currency account on Txn. Efectively, this will be the amount credited to your account on the Txn platform after the invoice processing fees - amount. The amount currency code does always correspond with the billedCurrency code.

included.type(exchangeQuotes).attributes

object

This is the amount that the invoice payment resulted in before the invoice processing fee - amountReceived. This is how much you will usually want to credit to the end-user's balance on your end. The exchangeRate value supplied in this object is always the effective exchange rate at which the end-user's cryptocurrency transaction was converted to billedCurrency. >>> Normally, it matches the value of data.attributes.exchangeRate. However, if the invoice was underpaid, paid late, or overpaid, Txn applies the spot exchange rate, which will be reflected in this object. <<<

Response

{
  "data": [
    {
      "id": "55f7832f-9745-4553-8548-1a06e30fb251",
      "type": "invoices",
      "attributes": {
        "amountBilled": "1000.00",
        "amountCharged": "1011.233592",
        "billedCurrency": "usd",
        "chargedCurrency": "usdt",
        "reference": "9556e207-b785-4faf-9486-8e79fb442e76",
        "statusContext": "full",
        "network": "ttrx:usdt",
        "networkName": "Tron (TRC20)",
        "status": "completed",
        "successRedirectUrl": "https://example.com/success",
        "unsuccessRedirectUrl": "https://example.com/fail",
        "paymentStatus": "on_time",
        "exchangeRate": "0.98889",
        "expiresAt": "2024-06-14T12:50:53.637Z",
        "createdAt": "2024-06-14T12:30:53.693Z",
        "hostedPageUrl": "https://sandbox.txn.pro/redirect?invoice_id=55f7832f-9745-4553-8548-1a06e30fb251\u0026request_type=invoice_hosted_page"
      },
      "relationships": {
        "address": {
          "data": {
            "type": "addresses",
            "id": "b5c97775-1378-4170-a7f0-78c2c5d60720"
          }
        },
        "invoiceTransactions": {
          "data": [
            {
              "type": "invoiceTransactions",
              "id": "00312f1a-4f9d-499f-abaa-1919e6e03e63"
            }
          ]
        },
        "coinDeposits": {
          "data": [
            {
              "type": "coinDeposits",
              "id": "ddd289d9-41c8-4d60-8d8a-6c50d2fb21b1"
            }
          ]
        }
      }
    }
  ],
  "included": [
    {
      "id": "b5c97775-1378-4170-a7f0-78c2c5d60720",
      "type": "addresses",
      "attributes": {
        "label": "USDT TTRX",
        "value": "TBq5k63KV9q4reE6JEF9e7wTYGo3RUkMQU",
        "createdAt": "2024-06-14T12:18:47.095Z"
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        },
        "network": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "00312f1a-4f9d-499f-abaa-1919e6e03e63",
      "type": "invoiceTransactions",
      "attributes": {
        "transactionFee": "10.0",
        "transactionFeeCurrency": "USD"
      },
      "relationships": {
        "txn": {
          "data": {
            "type": "transactions",
            "id": "00312f1a-4f9d-499f-abaa-1919e6e03e63"
          }
        },
        "exchangeQuote": {
          "data": {
            "type": "exchangeQuotes",
            "id": "45a4789f-497d-4cbc-a9d3-92685b53e657"
          }
        }
      }
    },
    {
      "id": "ddd289d9-41c8-4d60-8d8a-6c50d2fb21b1",
      "type": "coinDeposits",
      "attributes": {
        "txHash": "2cdde6dbe7669dbe933956cd28c7728e7ceb450804287149f3a8e59ee5bb344a",
        "currencyCode": "USDT",
        "createdAt": "2024-06-14T12:32:19.097Z",
        "amount": "1011.233592",
        "riskScore": "4.0"
      },
      "relationships": {
        "network": {
          "meta": {
            "included": false
          }
        },
        "address": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "00312f1a-4f9d-499f-abaa-1919e6e03e63",
      "type": "transactions",
      "attributes": {
        "createdAt": "2024-06-14T12:34:39.530Z",
        "simplifiedState": "completed",
        "transactionType": "InvoiceTransaction",
        "amount": "990.00"
      },
      "relationships": {
        "account": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "45a4789f-497d-4cbc-a9d3-92685b53e657",
      "type": "exchangeQuotes",
      "attributes": {
        "expiresAt": "2024-06-14T12:35:09.402Z",
        "amountCharged": "1011.233592",
        "amountReceived": "1000.0",
        "rate": "0.98889",
        "exchangeFee": "0.00",
        "exchangeFeeCurrency": "USD",
        "rateCurrency": "USD"
      },
      "relationships": {
        "accountCharged": {
          "meta": {
            "included": false
          }
        },
        "accountReceived": {
          "meta": {
            "included": false
          }
        },
        "exchangeOrder": {
          "meta": {
            "included": false
          }
        }
      }
    }
  ],
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}

Last updated