List Payments

HTTP Method: GET
Endpoint URL: /payment
Description: Retrieves a list of payments with detailed information, filtered by query parameters.
Security: Requires the API-KEY header.

Query Parameters

Filtering

statuses (string): Comma-separated display statuses (NEW, OPEN, COMPLETED, EXPIRED, OVERPAID, UNDERPAID, AML_CHECK_DANGER)
method (string): Filter by asset and network in format {asset}_{network} (e.g. USDT_tron, USDC_ethereum)
search (string): Search across: addressFrom, addressTo, clientId, txnId, invoice (partial match), id (exact match)
txnIds (string): Comma-separated transaction IDs
ids (string): Comma-separated payment UUIDs
invoices (string): Comma-separated invoice identifiers

Sorting

sortField (string): Column to sort by (e.g. created_at, amount, status)
sortOrder (string): Sort direction — asc or desc

Pagination

page (number ≥ 1): Page number (default: 1)
limit (number 1–100): Items per page (default: 20)

Request Headers

API-KEY: your_account_api_key

Example cURL

curl "https://api.alppay.io/v2/payment?statuses=OPEN&page=1&limit=20" \
  -H "API-KEY: ak_live_1234567890abcdef"

Example with Sorting and Method Filter

curl "https://api.alppay.io/v2/payment?method=USDT_tron&sortField=created_at&sortOrder=desc&page=1&limit=50" \
  -H "API-KEY: ak_live_1234567890abcdef"

Example with Search

curl "https://api.alppay.io/v2/payment?search=INV-001&page=1&limit=20" \
  -H "API-KEY: ak_live_1234567890abcdef"

Successful Response (200 OK)

{
  "results": [
    {
      "id": "285d8dce-7663-4580-ba7f-8afb2f2d3292",
      "transactions": [
        {
          "paymentId": "285d8dce-7663-4580-ba7f-8afb2f2d3292",
          "txnId": "0xe7238caa68382485141be0443d6ba7efd0bd9f6bac5a624bd059acc53af1bf1d19",
          "receivedAmount": "20.00",
          "asset": {
            "short": "USDT",
            "name": "Tether",
            "logoUrl": "https://cryptologos.cc/logos/tether-usdt-logo.png",
            "network": "tron"
          },
          "destTag": null,
          "addressFrom": "0x5D8D9C7f68A46634BCEaD2a6FF166A0BdFb08540",
          "addressTo": "0x5D8D9C7f68A46634BCEaD2a6FF166A0BdFb08540",
          "date": "2025-05-20T12:34:56Z"
        }
      ],
      "amount": "1000.00",
      "totalReceivedAmount": "20.00",
      "asset": {
        "short": "USDT",
        "name": "Tether",
        "logoUrl": "https://cryptologos.cc/logos/tether-usdt-logo.png",
        "network": "tron"
      },      "addressTo": "0x5D8D9C7f68A46634BCEaD2a6FF166A0BdFb08540",
      "confirmsNeeded": 30,
      "timeout": 9000,
      "checkoutUrl": "https://your-shop.com/orders/40113049",
      "status": "OPEN",
      "displayStatus": "OPEN",
      "customer": {
        "id": 12312312,
        "name": "John",
        "email": "[email protected]"
      },
      "merchant": {
        "id": "285d8dce-7663-4580-ba7f-8afb2f2d3292",
        "name": "Your Company",
        "siteUrl": "https://your-shop.com",
        "logoUrl": "https://your-shop.com/logo.svg",
        "email": "[email protected]"
      },
      "invoice": "INV-001",
      "paymentRedirectUrl": "https://a-pay-system.com/en/invoice?id=285d8dce-7663-4580-ba7f-8afb2f2d3292",
      "createdAt": "2025-05-20T12:34:56Z",
      "updatedAt": "2025-05-20T12:34:56Z"
    },
    {
      "id": "a7c3f2b1-1234-5678-9abc-def012345678",
      "transactions": [],
      "amount": "250.00",
      "totalReceivedAmount": "0.00",
      "asset": {
        "short": "BTC",
        "name": "Bitcoin",
        "logoUrl": "https://cryptologos.cc/logos/bitcoin-btc-logo.png",
        "network": "bitcoin"
      },      "addressTo": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
      "confirmsNeeded": 2,
      "timeout": 7200,
      "checkoutUrl": "https://your-shop.com/orders/40113050",
      "status": "EXPIRED",
      "displayStatus": "OPEN",
      "customer": {
        "id": 12312313,
        "name": "Jane",
        "email": "[email protected]"
      },
      "merchant": {
        "id": "285d8dce-7663-4580-ba7f-8afb2f2d3292",
        "name": "Your Company",
        "siteUrl": "https://your-shop.com",
        "logoUrl": "https://your-shop.com/logo.svg",
        "email": "[email protected]"
      },
      "invoice": "INV-002",
      "paymentRedirectUrl": "https://a-pay-system.com/en/invoice?id=a7c3f2b1-1234-5678-9abc-def012345678",
      "createdAt": "2025-05-19T09:15:00Z",
      "updatedAt": "2025-05-19T11:15:00Z"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 42
}

Response Fields

Pagination Info

results: Array of payment objects
page: Current page number
limit: Number of items per page
total: Total number of payments matching the filters

Payment Object Fields

id: Unique payment identifier
transactions: Array of associated blockchain transactions
amount: Requested payment amount
totalReceivedAmount: Actual amount received so far
asset: Cryptocurrency details (short name, full name, logo, network)
addressTo: Receiving cryptocurrency address
confirmsNeeded: Required blockchain confirmations
timeout: Payment expiration time in seconds
checkoutUrl: Merchant's checkout/return URL
status: Current payment status
displayStatus: Detailed status for UI and merchant logic. Use this field to display payment state to users
customer: Customer information (id, name, email)
merchant: Merchant details
invoice: Merchant's invoice reference
paymentRedirectUrl: ALPPAY payment page URL
createdAt: Payment creation timestamp
updatedAt: Last update timestamp

Display Status Values

The statuses query parameter filters by displayStatus, not status. The underlying status field has only three values: OPEN, EXPIRED, COMPLETED.

OPEN — Payment is active and awaiting funds
COMPLETED — Full payment amount received
EXPIRED — Payment window has expired
OVERPAID — Received amount exceeds the requested amount
UNDERPAID — Received amount is less than the requested amount
AML_CHECK_DANGER — Payment flagged by anti-money laundering check

Error Responses

401 Unauthorized: Invalid or missing API key
400 Bad Request: Invalid query parameters
429 Too Many Requests: Rate limit exceeded