Skip to content
Hayonix

API reference · Billing

Payment history (top-ups and auto-recharges) with receipt links

GET/v1/orgs/{org_id}/billing/payments
API keybilling:readOrganizationPaginated
TypeScript
client.billing.listPayments()
Python
client.billing.list_payments()
CLI
hayonix billing payments

Returns every payment in any state, newest first.

Project API key (Authorization: Bearer sk_…), or a console session. Requires the billing:read permission (a key's scope, or a role that includes it).

Examples

The samples read API_KEY and API_BASE_URL from the environment (see Setup). Values are examples.

# The org of your key: GET /v1/caller
ORG_ID=$(curl -sS "$API_BASE_URL/caller" -H "Authorization: Bearer $API_KEY" | jq -r .org_id)

curl -sS "$API_BASE_URL/orgs/$ORG_ID/billing/payments" \
  -H "Authorization: Bearer $API_KEY"

Request

Headers
HeaderRequiredDescription
AuthorizationyesBearer and your API key. The key implies its project.

Path parameters

  • org_idstring

    Your organization. The SDKs and the CLI fill it in from the API key.

    ID with prefix org_

Query parameters

  • limitinteger

    1–200, default 50

    1–200

  • cursorstring

    `next_cursor` of the previous page

    up to 200 characters

Response

200 a page of results — A page of payments, newest first

  • dataarray of Paymentrequired

    The items of this page.

    Show 19 fields of data
    • objectstringrequired

      Always `payment`: the type of this object

      One ofpayment

    • idstringrequired

      Unique ID (`pay_…`)

      ID with prefix pay_

    • org_idstringrequired

      Organization it belongs to

      ID with prefix org_

    • driverstringrequired

      `development` payments are test credit granted without taking money

      One ofstripedevelopment

    • developmentbooleanrequired

      True for test credit granted without taking money

    • purposestringrequired

      `top_up` (started by you) or `auto_recharge` (charged automatically)

      One oftop_upauto_recharge

    • statusstringrequired

      `pending` (waiting for payment), `requires_action` (the card holder must authenticate), `succeeded` (credit added), `failed`, `canceled`, or `needs_review` (the amount received did not match; held for review, no credit added yet)

      One ofpendingrequires_actionsucceededfailedcanceledneeds_review

    • amountstringrequired

      Credit added (excludes tax)

      pattern ^-?[0-9]+$

    • taxstringrequired

      Integer nano-USD as a decimal string

      pattern ^-?[0-9]+$

    • refundedstringrequired

      Amount refunded to the card (credit and tax)

      pattern ^-?[0-9]+$

    • currencystringrequired

      Always `usd`

      One ofusd

    • checkout_urlstring | nullrequired

      Where to send the customer to pay (pending top-ups)

    • receipt_urlstring | nullrequired

      Receipt from the payment processor; null until one exists

    • cardobject | nullrequired

      The card charged; null until it is known

      Show 2 fields of card
      • brandstring | nullrequired

        Card brand, for example `visa`; null when unknown

      • last4string | nullrequired

        Last four digits of the card; null when unknown

    • three_d_secureobjectrequired

      Card authentication (3-D Secure) for this payment

      Show 2 fields of three_d_secure
      • requestedbooleanrequired

        Whether card authentication (3-D Secure) was asked for

      • resultstring | nullrequired

        Outcome of card authentication as reported by the payment processor; null when none took place

    • failure_codestring | nullrequired

      Machine-readable reason the payment did not succeed or needs review; null otherwise

    • failure_messagestring | nullrequired

      The same reason, for people; null otherwise

    • created_atstring (date-time)required

      When it was created (ISO 8601, UTC)

    • succeeded_atstring (date-time) | nullrequired

      Time succeeded (ISO 8601, UTC)

  • next_cursorstring | nullrequired

    Pass as `cursor` for the next page; null on the last page.

Example response
Example response
{
  "data": [
    {
      "object": "payment",
      "id": "pay_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "org_id": "org_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "driver": "stripe",
      "development": true,
      "purpose": "top_up",
      "status": "pending",
      "amount": "1500000000",
      "tax": "1500000000",
      "refunded": "1500000000",
      "currency": "usd",
      "checkout_url": "string",
      "receipt_url": "string",
      "card": {
        "brand": "string",
        "last4": "string"
      },
      "three_d_secure": {
        "requested": true,
        "result": "string"
      },
      "failure_code": "string",
      "failure_message": "string",
      "created_at": "2026-01-01T00:00:00.000Z",
      "succeeded_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "next_cursor": "string"
}

Errors

Errors use the standard envelope. What this operation can answer:

Errors
StatusTypeWhen
400invalid_request_errorA parameter or body field is missing or not allowed; param names it.
401authentication_errorThe key or session is missing, revoked or expired.
403permission_errorThe credential lacks the permission this needs, or the organization is suspended.
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.