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

txnIds (string[]): Filter by one or more transaction IDs
ids (string[]): Filter by one or more payment IDs
invoices (string[]): Filter by one or more invoice identifiers
statuses (string[]): Filter by payment status (OPEN, EXPIRED, COMPLETED, CANCELLED, AML_CHECK_FAILED)
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 Multiple Filters

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

Successful Response (200 OK)

{
  "data": [
    {
      "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": 10,
      "timeout": 9000,
      "checkoutUrl": "https://your-shop.com/orders/40113049",
      "status": "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": 3,
      "timeout": 7200,
      "checkoutUrl": "https://your-shop.com/orders/40113050",
      "status": "EXPIRED",
      "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

data: 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
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

Status Values

OPEN: Payment is active and awaiting funds
COMPLETED: Payment successfully completed
EXPIRED: Payment window has expired
CANCELLED: Payment was cancelled
AML_CHECK_FAILED: Payment failed anti-money laundering compliance check

Error Responses

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