Skip to content
Hayonix

API reference · Billing

Get a payment (the console polls this after Checkout)

GET/v1/orgs/{org_id}/billing/payments/{payment_id}
API keybilling:readOrganization
TypeScript
client.billing.getPayment()
Python
client.billing.get_payment()
CLI
hayonix billing payment

Returns one payment. After the customer pays, poll this until status leaves pending: credit is added when the payment processor confirms the payment, not when the customer returns from the checkout page.

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/pay_01jc5zq4m8k3v6x9t2w7r0b1e4" \
  -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_

  • payment_idstringrequired

    ID of the payment

    ID with prefix pay_

Response

200 Payment — The payment

  • 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)

Example response
Example response
{
  "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"
}

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.
402insufficient_credit_errorThe organization is out of credit or over a spend limit.
404not_found_errorNo such resource in this project (an ID from another project is answered the same way).
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.