Payments

The on-chain half of an invoice: the leased deposit address, the amount actually received, confirmation progress and the transaction hash. Filterable by status and blockchain.

3 endpoints

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.

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.

JSONResponse Example

{
  "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
  }
}

GET/api/v1/payments/{id}Core

Read one payment in full, together with a four-field stub of the invoice it settles. The lookup is keyed on id AND merchantPointId, so a payment owned by another merchant point returns 404 PAYMENT_NOT_FOUND rather than 403. The body is the same shape the list endpoint emits per item — the extra invoice columns loaded by the query are dropped before serialisation.

Request Parameters

Name	Type	Required	Description
`id`	string	Required	Path parameter — the payment CUID returned by checkout or carried on the payment.completed webhook. The human referenceId (PAY-260826-041C) is not accepted here.

JSONResponse Example

{
  "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"
  }
}

GET/api/v1/payments/{id}/statusCore

Confirmation-only projection of a payment: seven fields selected directly in the query, with no invoice join and no chain or address metadata. This is the cheap endpoint to poll while a transaction confirms — compare confirmations against requiredConfirmations, which is fixed per chain when the payment is created. Prefer the payment.completed webhook where you can; poll this only as a reconciliation backstop.

Request Parameters

Name	Type	Required	Description
`id`	string	Required	Path parameter — the payment CUID. Scoped to the merchant point behind the API key; an id outside that scope yields 404 PAYMENT_NOT_FOUND.

JSONResponse Example

{
  "id": "clx7k4m2s0007qz8fd5v3n8q1",
  "referenceId": "PAY-260826-052D",
  "status": "CONFIRMING",
  "confirmations": 46,
  "requiredConfirmations": 128,
  "expiresAt": "2026-08-26T11:02:18.000Z",
  "completedAt": null
}

Category Summary

Total Endpoints

Base Domain

api2.havala.io