Account Center › API Reference › Merchant Account

Prepaid top-up records (on-chain receipts and offline settlement)

GET /v1/merchant/topups scope: merchant:read

Merchant account

channel has two values representing entirely different paths:

chain: funds sent to the allocated deposit address; see GET /v1/merchant/deposit-addresses. Receipt is an external fact, and we automatically create the order and post it; no declaration is needed from you.
fiat: bank transfer. A person enters amounts from the receipt, and dual approval is required before posting. Processing takes hours to days; this is the path where programmatic polling is most useful.

Five status values: pending (awaiting processing), confirming (visible on-chain but below the required confirmation count, not included in balance), approving (manual review in progress), credited (posted), and rejected. Display unknown values unchanged; do not use a default fallback.

⚠ amount_text is the declared/detected amount, not the credited amount. The posted amount is what we actually confirm received. To see the balance credited, query GET /v1/merchant/balances, the ledger source of truth.

tx_hash exists only for the on-chain path and can be used for your own chain verification. note may contain notes from us or you, including the receipt reference for offline declarations; see the POST endpoint.

Keyset pagination, strictly descending by (created_at, id).

Query Parameters

Field	Type	Required	Description
`limit`	integer	Optional	Defaults to 20, maximum 100.
`cursor`	string	Optional	The previous page's `next_cursor`, an opaque string.

Response

200OK

{
  "data": [
    {
      "id": "5d2c8a41-3f6b-4e0a-9c77-1b8e0d4f2a56",
      "asset": "USDT",
      "channel": "fiat",
      "amount_text": "50000.00",
      "status": "approving",
      "note": "回单号：TT20260813001 | 8 月备付金",
      "tx_hash": "",
      "created_at": "2026-08-13T01:02:03.400Z",
      "updated_at": "2026-08-13T01:40:12.880Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

403insufficient_scope: missing merchant:read.

Request

curl -X GET 'https://api.zinfra.vip/v1/merchant/topups' \
  -H 'x-auth-token: Bearer $TOKEN'

const res = await fetch("https://api.zinfra.vip/v1/merchant/topups", {
  method: "GET",
  headers: {
    "x-auth-token": "Bearer $TOKEN",
  },
});
// Keep monetary amounts as strings, never numbers.
const data = await res.json();

import requests

res = requests.get(
    "https://api.zinfra.vip/v1/merchant/topups",
    headers={
        "x-auth-token": "Bearer $TOKEN",
    },
)
# Use Decimal(str(...)) for amounts, not float.
data = res.json()

req, _ := http.NewRequest("GET", "https://api.zinfra.vip/v1/merchant/topups",
    nil)
req.Header.Set("x-auth-token", "Bearer $TOKEN")
res, err := http.DefaultClient.Do(req)
// Decode amount fields as string, not float64.

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.zinfra.vip/v1/merchant/topups"))
    .header("x-auth-token", "Bearer $TOKEN")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
// Use String / BigDecimal for amounts, not double.

$ch = curl_init('https://api.zinfra.vip/v1/merchant/topups');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'x-auth-token: Bearer $TOKEN',
  ],
]);
$res = curl_exec($ch);
// Use bcmath / strings for amounts, not floatval.

200

{
  "data": [
    {
      "id": "5d2c8a41-3f6b-4e0a-9c77-1b8e0d4f2a56",
      "asset": "USDT",
      "channel": "fiat",
      "amount_text": "50000.00",
      "status": "approving",
      "note": "回单号：TT20260813001 | 8 月备付金",
      "tx_hash": "",
      "created_at": "2026-08-13T01:02:03.400Z",
      "updated_at": "2026-08-13T01:40:12.880Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}