Skip to main content

​
List Payments

GET /payments Returns a list of payments processed by your merchants, with pagination and filtering options.

​
Query Parameters

ParameterTypeDefaultDescription
limitnumber50Number of results per page (min 1, max 100).
offsetnumber0Number of results to skip.
statusstring-Filter by lifecycle status: PENDING, CONFIRMED, FAILED.

​
Example Request

curl "https://api.taprails.com/api/v1/management/payments?status=CONFIRMED&limit=2" \
  -H "x-api-key: sk_live_your_key"

​
Response

The response is a JSON object with a list of payments and pagination metadata.
FieldTypeDescription
paymentsarrayA list of recent payments.
paginationobjectMetadata for traversing results.

​
Payment Object

FieldTypeDescription
payment_idstringUnique identifier for the payment request (e.g., pay_abcd123).
statusstringCurrent status: PENDING, CONFIRMED, or FAILED.
amountstringPayment amount in USDC decimal string.
currencystringAlways USDC.
merchantobjectReference to the merchant receiving the payment.
merchant.idstringThe merchant’s unique ID.
merchant.namestringDisplay name of the merchant.
tx_hashstringOn-chain transaction hash on Base (once confirmed).
created_atstringISO 8601 timestamp of payment creation.
expires_atstringTime until the payment request expires.
confirmed_atstringTime of on-chain confirmation (if confirmed).

​
Sample Response

{
  "payments": [
    {
      "payment_id": "pay_xyz789",
      "status": "CONFIRMED",
      "amount": "12.50",
      "currency": "USDC",
      "merchant": {
        "id": "mch_abc123",
        "name": "Coffee Haven"
      },
      "tx_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef12345678",
      "created_at": "2026-03-28T21:00:00Z",
      "expires_at": "2026-03-28T22:00:00Z",
      "confirmed_at": "2026-03-28T21:05:00Z"
    },
    {
      "payment_id": "pay_ghi456",
      "status": "PENDING",
      "amount": "5.00",
      "currency": "USDC",
      "merchant": {
        "id": "mch_abc123",
        "name": "Coffee Haven"
      },
      "tx_hash": null,
      "created_at": "2026-03-31T01:45:00Z",
      "expires_at": "2026-03-31T02:45:00Z",
      "confirmed_at": null
    }
  ],
  "pagination": {
    "limit": 100,
    "has_more": false
  }
}