Club Wallet Activity

Overview

Authentication

X-API-Key header

Format

JSON, read-only

Rate limit

120 requests per minute per IP address

Sort order

Newest payment first

The API key is provided by the Helping With Flags team. Keep it on your server. Never put it in a browser, mobile app or code repository. If the key may have leaked, contact us and we will replace it.

curl -G "https://www.helpingwithflags.com/api/v1/club-wallet/activity" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  --data-urlencode "club_slug=SpringfieldRotary" \
  --data-urlencode "date_type=custom" \
  --data-urlencode "payments_for=03-01-2026 / 03-31-2026" \
  --data-urlencode "per_page=50"

Parameters

Send as query parameters. Only club_slug is required; with no filters you get the current calendar year, all payment types and all statuses, 10 rows per page.

Date ranges use MM-DD-YYYY / MM-DD-YYYY (space, slash, space), US Central time, both days included. URL-encode the value.

Response

{
  "type": "success",
  "code": 200,
  "message": "Payment activity retrieved successfully.",
  "data": {
    "club": { "id": 123, "slug": "SpringfieldRotary", "name": "Springfield Rotary Club" },
    "gateway": "stripe",
    "filters": {
      "date_type": "custom", "date_from": "2026-03-01", "date_to": "2026-03-31", "subscription_year": null,
      "payment_types": ["CARD", "STORED_CARD", "CASH", "CHECK", "E_CHECK"],
      "payment_status": ["paid", "refund", "processing"],
      "filter_name": null, "filter_product": null, "filter_account": null
    },
    "payments": [
      {
        "payment_id": 82601,
        "payment_date": "2026-03-14T10:22:05-05:00",
        "full_name": "Jane Smith",
        "payment_type": "CARD",
        "payment_status": "paid",
        "gateway": "stripe",
        "flags": 2,
        "flag_amount": 100.00,
        "processing_fee": 3.20,
        "gateway_fee": 3.29,
        "total": 99.91
      }
    ],
    "totals": {
      "flags": 2, "flag_amount": 100.00, "processing_fee": 3.20,
      "sub_total": 103.20, "gateway_fee": 3.29, "total": 99.91
    },
    "pagination": { "current_page": 1, "per_page": 50, "total": 1, "last_page": 1 }
  }
}

Payment fields

Other fields

Amounts are in US dollars, rounded to 2 decimals (sent as JSON numbers, so 50 means 50.00). Payment row amounts are always positive; refunds are identified by payment_status: "refund".

Calculations

Amounts follow the same rules as the Club Wallet Activity page, so both always match.

With filter_product, each payment is split into one row per matching product line (same payment_id). The amount, fees and flags are shared out by that line's part of the payment, donations excluded, and cash and check rows add the processing fee to total. Totals cover that product across all pages, except totals.flags, which counts every flag on the matching payments.

totals.gateway_fee counts card fees only, and is 0 when card payments are excluded or payment_status=refund. Unpaid "pay later" requests and payments imported from other systems are never listed.

Errors

Errors return type: "error" with code equal to the HTTP status. Validation errors also list each problem by parameter.

{
  "type": "error",
  "code": 422,
  "message": "The request has some problems. Please check the errors list.",
  "errors": { "payments_for": ["Use the format MM-DD-YYYY / MM-DD-YYYY with real dates, for example 03-01-2026 / 03-31-2026."] }
}

No matching payments is not an error: you get 200 with an empty payments list.