API reference · Billing
Get a payment (the console polls this after Checkout)
/v1/orgs/{org_id}/billing/payments/{payment_id}- 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
| Header | Required | Description |
|---|---|---|
Authorization | yes | Bearer and your API key. The key implies its project. |
Path parameters
org_idstringYour organization. The SDKs and the CLI fill it in from the API key.
ID with prefix org_
payment_idstringrequiredID of the payment
ID with prefix pay_
Response
200 Payment — The payment
objectstringrequiredAlways `payment`: the type of this object
One of
paymentidstringrequiredUnique ID (`pay_…`)
ID with prefix pay_
org_idstringrequiredOrganization it belongs to
ID with prefix org_
driverstringrequired`development` payments are test credit granted without taking money
One of
stripedevelopmentdevelopmentbooleanrequiredTrue for test credit granted without taking money
purposestringrequired`top_up` (started by you) or `auto_recharge` (charged automatically)
One of
top_upauto_rechargestatusstringrequired`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 of
pendingrequires_actionsucceededfailedcanceledneeds_reviewamountstringrequiredCredit added (excludes tax)
pattern ^-?[0-9]+$
taxstringrequiredInteger nano-USD as a decimal string
pattern ^-?[0-9]+$
refundedstringrequiredAmount refunded to the card (credit and tax)
pattern ^-?[0-9]+$
currencystringrequiredAlways `usd`
One of
usdcheckout_urlstring | nullrequiredWhere to send the customer to pay (pending top-ups)
receipt_urlstring | nullrequiredReceipt from the payment processor; null until one exists
cardobject | nullrequiredThe card charged; null until it is known
ShowHide 2 fields of
cardbrandstring | nullrequiredCard brand, for example `visa`; null when unknown
last4string | nullrequiredLast four digits of the card; null when unknown
three_d_secureobjectrequiredCard authentication (3-D Secure) for this payment
ShowHide 2 fields of
three_d_securerequestedbooleanrequiredWhether card authentication (3-D Secure) was asked for
resultstring | nullrequiredOutcome of card authentication as reported by the payment processor; null when none took place
failure_codestring | nullrequiredMachine-readable reason the payment did not succeed or needs review; null otherwise
failure_messagestring | nullrequiredThe same reason, for people; null otherwise
created_atstring (date-time)requiredWhen it was created (ISO 8601, UTC)
succeeded_atstring (date-time) | nullrequiredTime succeeded (ISO 8601, UTC)
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:
| Status | Type | When |
|---|---|---|
400 | invalid_request_error | A parameter or body field is missing or not allowed; param names it. |
401 | authentication_error | The key or session is missing, revoked or expired. |
403 | permission_error | The credential lacks the permission this needs, or the organization is suspended. |
402 | insufficient_credit_error | The organization is out of credit or over a spend limit. |
404 | not_found_error | No such resource in this project (an ID from another project is answered the same way). |
429 | rate_limit_error rate_limited | Too many requests; retry after retry-after seconds. |