List payments

Overview

The service automatically finds all payments arriving at your crypto wallets, but only while there are invoices with an active search. The search runs while an invoice is unpaid and continues for one more hour after the payment deadline—to account for slow networks. If no such invoices exist, an incoming transaction does not enter the system.

Request

curl -X POST https://api.bitsby.app/payments/list \
  -H "Authorization: Token MSvL2ltaDZdWVjmZURURMVWhqSJLT2NURjhL2Fla1Z1T1IxQTltKs1T3Ay" \
	-F "startDate=2000-01-01" \
	-F "endDate=2030-01-01" \
	-F "offset=0" \
	-F "limit=10"

Request parameters

Parameter	Data type	Description	Example	Required?	Default
walletId	UUID	Wallet ID in UUID format	1c48b092-9878-48f5-b441-07a8a48e7b54	no
invoiceId	UUID	Invoice ID in UUID format	1c48b092-9878-48f5-b441-07a8a48e7b54	no
startDate	String	Start date of the on-chain transaction, in Y-m-d format	2000-01-01	no
endDate	String	End date of the on-chain transaction, in Y-m-d format	2030-01-01	no
offset	Integer	Index of the first record to return	0	no	0
limit	Integer	Number of records you want to receive	50	no	10

Response example

A payment already matched to an invoice:

{
   "result":"success",
   "data":[
      {
         "id":"f986ad8d-2298-473d-982a-efbc817b975d",
         "amount":12,
         "hash":"f09352627039c088688806821b864895ff237558612d834861621fc026de5f68",
         "transactionDatetime":"2024-02-27 21:05:36",
         "invoice":{
            "id":"f31c61f6-407f-4999-95cf-56477eff06d4",
            "uid":"riUZBnNvd2rX",
            "projectId":"9deea1e2-0c08-41a3-bdc2-a34eada3892d",
            "createDatetime":"2024-02-27 20:57:23",
            "timeToPayDatetime":"2024-02-28 08:57:23",
            "commissionFiatUSD":0.12,
            "amountFiatUSD":12,
            "amountFiat":12,
            "currencyFiat":"USD",
            "description":null,
            "serviceData":"orderId:2444",
            "views":1,
            "status":"paid"
         },
         "wallet":{
            "id":"47aa71e2-07a0-482e-9172-7114d7376ba0",
            "name":"usdt-tron",
            "blockchain":"tron",
            "cryptocurrency":"usdt",
            "address":"TKbstUwMzLrfTAGL4erYb7gc7ghmHQ9zG7"
         }
      },
      {
         "id":"f3195184-9a6f-4c82-928b-d7fe7c015b7b",
         "amount":5.02,
         "hash":"74763b65e43bcc9492a6ce9a7f26fbfdbd7635aecd3454420b5e9534cba50ee6",
         "transactionDatetime":"2024-02-26 13:32:57",
         "invoice":{
            "id":"fac8ef03-2c41-4ce0-a432-7c33b928f16f",
            "uid":"AFhygKX21ecd",
            "projectId":"9deea1e2-0c08-41a3-bdc2-a34eada3892d",
            "createDatetime":"2024-02-26 13:29:24",
            "timeToPayDatetime":"2024-02-27 01:29:24",
            "commissionFiatUSD":0.05,
            "amountFiatUSD":5.02, 
            "amountFiat":5,
            "currencyFiat":"USD",
            "description":null,
            "serviceData":"orderId:3419",
            "views":3,
            "status":"paid"
         },
         "wallet":{
            "id":"47aa71e2-07a0-482e-9172-7114d7376ba0",
            "name":"usdt-tron",
            "blockchain":"tron",
            "cryptocurrency":"usdt",
            "address":"TKbstUwMzLrfTAGL4erYb7gc7ghmHQ9zG7"
         }
      }
   ]
}

A payment the service has found but not yet matched to an invoice comes without the invoice block. These payments are the candidates for manual matching:

{
   "result":"success",
   "data":[
      {
         "id":"c1d0f4a2-93b7-4f61-8c25-1a6f0e2b7d94",
         "amount":9.87,
         "hash":"5b1e4b1cf0a4c3d2e9f6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192",
         "transactionDatetime":"2024-02-28 09:14:02",
         "wallet":{
            "id":"47aa71e2-07a0-482e-9172-7114d7376ba0",
            "name":"usdt-tron",
            "blockchain":"tron",
            "cryptocurrency":"usdt",
            "address":"TKbstUwMzLrfTAGL4erYb7gc7ghmHQ9zG7"
         }
      }
   ]
}

Response parameters

Parameter	Description
id	Payment ID in UUID format
amount	Payment amount in cryptocurrency
hash	The on-chain transaction hash
transactionDatetime	Date and time of the on-chain transaction (UTC)
invoice	Block with the invoice parameters. Present if an invoice is matched to the payment
invoice.id	Invoice ID in UUID format
invoice.uid	Invoice ID (for the customer)
invoice.projectId	Project ID in UUID format
invoice.createDatetime	Invoice creation date and time (UTC)
invoice.timeToPayDatetime	Date and time until which the invoice is valid (UTC)
invoice.commissionFiatUSD	Service fee amount. Calculated from the invoice.amountFiatUSD amount
invoice.amountFiatUSD	The invoice amount converted to USD. At invoice creation it is calculated from invoice.amountFiat at the current exchange rate. At the moment of payment it is overwritten with the amount actually received, converted to USD at the rate at that moment. The fee in invoice.commissionFiatUSD is recalculated from it as well
invoice.amountFiat	The original invoice amount in fiat currency. Does not change
invoice.currencyFiat	Fiat currency
invoice.description	The description set at invoice creation
invoice.serviceData	The service data set at invoice creation
invoice.views	Number of payment page views
invoice.status	Invoice status
wallet	Block with the wallet parameters
wallet.id	Wallet ID in UUID format
wallet.name	Wallet name
wallet.blockchain	The crypto wallet's blockchain
wallet.cryptocurrency	The wallet's cryptocurrency
wallet.address	The crypto wallet's address