> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spacepay.solutions/llms.txt
> Use this file to discover all available pages before exploring further.

# List payments

> List and filter your merchant's payments with pagination, using secret key authentication

# List payments

Returns a paginated list of payments for the merchant tied to your secret key. You can filter by `type` (`payment` or `deposit`), `status`, free-text `search`, and control sort order.

<RequestExample>
  ```bash cURL theme={null}
    curl -X GET \
    "https://api.spacepay.solutions/v1/external/secretkey-auth/payments?type=payment&status=completed&limit=50&offset=0"
    \ -H "X-SpacePay-Secret-Key: sk_test_your_secret_key"
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response (200) theme={null}
  {
    "data": [
      {
        "id": "4291f98b-d68c-4eb0-883e-6bc790a41c96",
        "merchantId": "4e29f55d-d6a8-42d7-8230-cb8efeded39e",
        "merchantShortName": "Copycat Creations",
        "type": "payment",
        "amountInCents": 250,
        "currency": "USD",
        "status": "completed",
        "depositAddress": {
          "id": "6c1c95e1-04f1-4881-b7cc-c2a529fbde76",
          "paymentId": "4291f98b-d68c-4eb0-883e-6bc790a41c96",
          "type": "EVM",
          "address": "0xa35e74109b7040d0ee74cb7cb71bae35a2981254",
          "createdAt": "2025-10-10T21:44:06.749Z"
        },
        "quotes": [
          {
            "id": "eb0e59b9-14d5-4324-a056-e87b74aa954f",
            "paymentId": "4291f98b-d68c-4eb0-883e-6bc790a41c96",
            "token": {
              "id": "f9d14525-367d-4e16-b247-8d4ed23f1413",
              "symbol": "ETH",
              "decimals": 18,
              "contractAddress": "0x0000000000000000000000000000000000000000",
              "type": "volatile",
              "assetType": "native",
              "status": "active"
            },
            "chainId": 84532,
            "expectedAmountAsset": "668082370801162",
            "rateUsdAsset": "3742.05353900",
            "expiresAt": "2025-10-10T21:54:06.796Z",
            "status": "active",
            "createdAt": "2025-10-10T21:44:06.794Z"
          }
        ],
        "receipt": {
          "transactionHash": "0x1234567890abcdef1234567890abcdef12345678",
          "blockNumber": 18500000,
          "confirmations": 12,
          "requiredConfirmations": 12,
          "completedAt": "2025-10-10T21:45:00.000Z"
        },
        "orderId": "order_123",
        "redirectUrl": "https://merchant.example.com/checkout/success",
        "createdAt": "2025-10-10T21:44:06.733Z"
      }
    ],
    "pagination": {
      "total": 84,
      "limit": 50,
      "offset": 0,
      "hasMore": true,
      "totalPages": 2,
      "currentPage": 1
    }
  }
  ```
</ResponseExample>

## Query Parameters

<ParamField query="type" type="string">
  Filter by payment type. Possible values: `payment`, `deposit`.
</ParamField>

<ParamField query="status" type="string">
  Filter by payment status. Possible values: `pending`, `processing`,
  `completed`, `failed`, `expired`, `cancelled`.
</ParamField>

<ParamField query="search" type="string">
  Free-text search across payment ID, deposit wallet address, merchant short
  name, receipt transaction hash, and receipt sender address.
</ParamField>

<ParamField query="sortBy" type="string" default="createdAt">
  Field to sort results by. Possible values: `createdAt`, `amountInCents`.
</ParamField>

<ParamField query="sortOrder" type="string" default="DESC">
  Sort direction. Possible values: `ASC`, `DESC`.
</ParamField>

<ParamField query="limit" type="number" default="100">
  Number of payments to return. Minimum: **1**, maximum: **1000**.
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of payments to skip for pagination.
</ParamField>

## Response Fields

<ResponseField name="data" type="array" required>
  Array of payment objects.

  <Expandable title="Payment properties">
    <ResponseField name="id" type="string">
      Unique payment identifier.
    </ResponseField>

    <ResponseField name="merchantId" type="string">
      ID of the merchant who created the payment.
    </ResponseField>

    <ResponseField name="merchantShortName" type="string">
      Short name of the merchant for display purposes.
    </ResponseField>

    <ResponseField name="type" type="string">
      `payment` (fixed amount) or `deposit` (variable on-chain amount).
    </ResponseField>

    <ResponseField name="amountInCents" type="number">
      Payment amount in cents.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Payment currency.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current payment status: `pending`, `processing`, `completed`, `failed`,
      `expired`, or `cancelled`.
    </ResponseField>

    <ResponseField name="depositAddress" type="object">
      Cryptocurrency deposit address for the payment.

      <Expandable title="Deposit address properties">
        <ResponseField name="address" type="string">
          The cryptocurrency address where customers send payment.
        </ResponseField>

        <ResponseField name="type" type="string">
          Address type (for example, `EVM` for Ethereum-compatible chains).
        </ResponseField>

        <ResponseField name="createdAt" type="string">
          Timestamp when the deposit address was created.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="quotes" type="array">
      Available cryptocurrency quotes for the payment.

      <Expandable title="Quote properties">
        <ResponseField name="token" type="object">
          Token information including symbol, decimals, and contract address.
        </ResponseField>

        <ResponseField name="expectedAmountAsset" type="string">
          Expected amount to send in the smallest token unit.
        </ResponseField>

        <ResponseField name="rateUsdAsset" type="string">
          Exchange rate from token to USD.
        </ResponseField>

        <ResponseField name="expiresAt" type="string">
          Quote expiration timestamp.
        </ResponseField>

        <ResponseField name="status" type="string">
          Quote status (`active`, `expired`, etc.).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="receipt" type="object">
      Transaction receipt. Only present for `completed` payments.

      <Expandable title="Receipt properties">
        <ResponseField name="transactionHash" type="string">
          Blockchain transaction hash.
        </ResponseField>

        <ResponseField name="blockNumber" type="integer">
          Block number where the transaction was confirmed.
        </ResponseField>

        <ResponseField name="confirmations" type="integer">
          Number of confirmations received.
        </ResponseField>

        <ResponseField name="requiredConfirmations" type="integer">
          Required number of confirmations for completion.
        </ResponseField>

        <ResponseField name="completedAt" type="string">
          Timestamp when the payment was completed.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="orderId" type="string">
      Merchant's order identifier.
    </ResponseField>

    <ResponseField name="redirectUrl" type="string">
      URL to redirect the customer after payment completion.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      Timestamp when the payment was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object" required>
  Pagination metadata.

  <Expandable title="Pagination properties">
    <ResponseField name="total" type="number">
      Total number of payments matching the filter.
    </ResponseField>

    <ResponseField name="limit" type="number">
      Number of items requested per page.
    </ResponseField>

    <ResponseField name="offset" type="number">
      Number of items skipped.
    </ResponseField>

    <ResponseField name="hasMore" type="boolean">
      Whether there are more pages after this one.
    </ResponseField>

    <ResponseField name="totalPages" type="number">
      Total number of pages.
    </ResponseField>

    <ResponseField name="currentPage" type="number">
      Current page number.
    </ResponseField>
  </Expandable>
</ResponseField>

## Error Responses

<ResponseExample>
  ```json Error Response (401) theme={null}
  {
    "error": {
      "type": "authentication_error",
      "message": "Invalid or missing X-SpacePay-Secret-Key header",
      "code": "invalid_api_key"
    }
  }
  ```
</ResponseExample>