List Payments

GET/api/v1/paymentsRecommended

Page through the payments recorded against the merchant point behind the API key, ordered createdAt descending. status and blockchain are applied as exact-match filters straight onto the stored columns, and take is clamped to 100 with a default of 20. pagination.page is computed as floor(skip / take) + 1 and hasMore as skip + take < total, so both only read correctly when skip advances in whole multiples of take.

Authentication

Signature Pattern

HMAC-SHA256(apiSecret, "{t}\nGET\n/api/v1/payments\n{sha256(\"\")}")

Header	Value	Description
`X-API-Key`	7f3b9c1e4a26d508bf71ac93e2d64f08	Merchant point API key, issued in the merchant dashboard. Treat it as opaque — depending on how the point was created it is 32 or 64 hex characters, so never validate on length. Identifies the point whose payments you can reach.
`X-Signature`	t=1787739243,v1=9c4f2ab7e1d6538042bfa9c7e31d685f0a2c94b7e6d813fa50c9b2e74a1d6f38	Literal form t={unix_seconds},v1={hex_hmac_sha256}; t must sit within ±300s of server time or the guard raises SIGNATURE_EXPIRED
`Content-Type`	application/json	Always application/json. These reads carry no body, so the body hash in the canonical string is sha256 of the empty string.

Request Parameters

Name	Type	Required	Description
`status`	string	Optional	Query parameter — exact PaymentStatus literal: PENDING, PROCESSING, CONFIRMING, COMPLETED, FAILED, EXPIRED or REFUNDED. Passed through to the enum column verbatim, so it is case-sensitive and an unrecognised value is not silently ignored.
`blockchain`	string	Optional	Query parameter — exact lowercase chain slug: ethereum, polygon, bsc, arbitrum, optimism, base, avalanche, bitcoin, tron, solana, ton. Not the uppercase enum form.
`skip`	integer	Optional	Query parameter — row offset, parsed with parseInt; defaults to 0.
`take`	integer	Optional	Query parameter — page size; defaults to 20 and is hard-clamped to a maximum of 100.

Response Parameters

Field	Type	Example
`items`	array	[…]
`items[].id`	string	"clx7k3r4d0004qz8f7t1m5x2p"
`items[].referenceId`	string	"PAY-260826-047C"
`items[].status`	string	"PENDING"
`items[].blockchain`	string	"tron"
`items[].network`	string	"MAINNET"
`items[].isTestnet`	boolean	false
`items[].cryptoCurrency`	string	"USDT"
`items[].amount`	string	"82.00"
`items[].expectedAmount`	string	"82.00"
`items[].receivedAmount`	string	"0"
`items[].address`	string	"TXk9m4Qp2vR7hLZc3nB6dF8sJyW1eA5tGu"
`items[].confirmations`	integer	0
`items[].requiredConfirmations`	integer	19
`items[].transactionHash`	null	null
`items[].expiresAt`	string	"2026-08-26T11:09:31.000Z"
`items[].createdAt`	string	"2026-08-26T10:39:31.000Z"
`items[].completedAt`	null	null
`items[].invoice`	object	{…}
`items[].invoice.id`	string	"clx7k3r3b0003qz8f9h4c8k7v"
`items[].invoice.referenceId`	string	"INV-260826-046C"
`items[].invoice.orderId`	string	"ORDER-2026-04431"
`items[].invoice.status`	string	"PAYMENT_PENDING"
`pagination`	object	{…}
`pagination.total`	integer	2
`pagination.page`	integer	1
`pagination.limit`	integer	20
`pagination.hasMore`	boolean	false

Response Example

JSONResponse

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "clx7k3r4d0004qz8f7t1m5x2p",
        "referenceId": "PAY-260826-047C",
        "status": "PENDING",
        "blockchain": "tron",
        "network": "MAINNET",
        "isTestnet": false,
        "cryptoCurrency": "USDT",
        "amount": "82.00",
        "expectedAmount": "82.00",
        "receivedAmount": "0",
        "address": "TXk9m4Qp2vR7hLZc3nB6dF8sJyW1eA5tGu",
        "confirmations": 0,
        "requiredConfirmations": 19,
        "transactionHash": null,
        "expiresAt": "2026-08-26T11:09:31.000Z",
        "createdAt": "2026-08-26T10:39:31.000Z",
        "completedAt": null,
        "invoice": {
          "id": "clx7k3r3b0003qz8f9h4c8k7v",
          "referenceId": "INV-260826-046C",
          "orderId": "ORDER-2026-04431",
          "status": "PAYMENT_PENDING"
        }
      },
      {
        "id": "clx7k2p9a0001qz8fh3n2v4m6",
        "referenceId": "PAY-260826-041C",
        "status": "COMPLETED",
        "blockchain": "ethereum",
        "network": "MAINNET",
        "isTestnet": false,
        "cryptoCurrency": "USDT",
        "amount": "149.50",
        "expectedAmount": "149.50",
        "receivedAmount": "149.50",
        "address": "0x5c9E7A1fD2B84c0d3aE617F9b8cB2fA0d431ecB7",
        "confirmations": 12,
        "requiredConfirmations": 12,
        "transactionHash": "0x3f7d1c9a48b2e05f6d1a7c94e2b83f05c1d6a94b72e83f01c5a9d6b47e2f08a1",
        "expiresAt": "2026-08-26T10:44:03.000Z",
        "createdAt": "2026-08-26T10:14:03.000Z",
        "completedAt": "2026-08-26T10:21:47.000Z",
        "invoice": {
          "id": "clx7k2p8v0000qz8f2r6b1w9d",
          "referenceId": "INV-260826-039C",
          "orderId": "ORDER-2026-04417",
          "status": "PAID"
        }
      }
    ],
    "pagination": {
      "total": 2,
      "page": 1,
      "limit": 20,
      "hasMore": false
    }
  },
  "timestamp": "2026-08-26T13:41:02.477Z",
  "requestId": "req_V1StGXR8_Z5j"
}

Error shape

JSONError

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  },
  "timestamp": "2026-08-26T13:41:02.477Z",
  "requestId": "req_V1StGXR8_Z5j"
}

Status Codes

200Success

201Created

400Bad Request

401Unauthorized

404Not Found

429Rate Limited

Try itMockapi2.havala.io

GEThttps://api2.havala.io

Get Payment→