Skip to content
Hayonix

API reference · Billing

Start a top-up: returns a payment with the checkout URL to send the customer to

POST/v1/orgs/{org_id}/billing/top-ups
Console sessionbilling:manageOrganizationIdempotency-Key

Credit is added only when the payment processor confirms the payment (webhook), never by the return page. With the development driver, credit is added at once and the payment is marked development.

Console session only: no API key can be granted the billing:manage permission it needs. Requires the billing:manage permission (a key's scope, or a role that includes it).

Request

Headers
HeaderRequiredDescription
Idempotency-KeynoMakes a retry safe: the same key and request within 24 hours return the original response (see Idempotency). The SDKs send one for you.

Path parameters

  • org_idstring

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

    ID with prefix org_

Body

JSON (application/json): CreateTopUpRequest.

  • amountstringrequired

    Credit to buy, nano-USD; a whole number of cents

    pattern ^[1-9][0-9]{0,18}$

  • save_payment_methodboolean

    Save the card for auto-recharge

Response

201 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.
409conflict_error idempotency_in_progressA request with the same Idempotency-Key is still running.
422idempotency_error idempotency_key_reusedThe Idempotency-Key was used with a different request.
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.