Client API: Billing

Invoices, credit balance, top-ups, and hourly billing controls.

Base URL: https://api.coritan.com/api/v1. Paths below are complete.

To try these requests in the browser, open the interactive Client API reference.

GET /api/v1/billing/credit

Authentication: an access token, sent as Authorization: Bearer <token>.

Fields of a 200 response:

GET /api/v1/billing/crypto/address

This user's permanent deposit address for the network's chain family.

Uses the write session because a first call issues an address. Repeat calls return the same one.

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/billing/crypto/assets

Assets we can accept right now.

Excludes anything enabled but unpriced, since a deposit to it would be held rather than credited.

Authentication: an access token, sent as Authorization: Bearer <token>.

POST /api/v1/billing/crypto/check

Look for this customer's payment now, and say where it stands.

What the refresh button calls, and what the wallet and invoice panels poll while they are open. Before this the panels could only re-read the database and wait for the background scan to notice. A customer who had just paid had no way to ask, and the honest answer to "is it there yet" was "wait".

Rate limited because it reads the chain, which is spending money on the customer's behalf. The chain read is separately throttled inside, so several tabs polling on their own timers cost one read rather than one each; below that threshold this still answers with current deposit state, which is what was actually being asked for.

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json

Type: object or null.

GET /api/v1/billing/crypto/deposits

Deposit history, including transfers still confirming.

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/billing/crypto/deposits/{deposit_id}

One deposit, for polling while it confirms.

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/billing/crypto/plan

Every way to pay this amount in crypto, cheapest first.

Answers the question a customer has ("how much do I send to end up with $X?") instead of showing a rate and a spread and leaving the arithmetic to them. Each option states what it credits, which is never below the target, and says outright when a chain's fee would eat the deposit.

invoice_id targets the invoice's outstanding balance instead of a bare amount, so the figure shown is the one that settles it.

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/billing/crypto/quote

How much to send for a target USD credit, itemised.

Quoting records an intent, which is what lets the deposit be credited at the rate shown here and applied to invoice_id when it lands, instead of arriving as a balance the customer then has to spend by hand.

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/billing/hourly-eligibility

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/billing/invoices

Newest first, ties by id so a page boundary never repeats or skips a row.

The bare list is the answer every existing caller reads; with_total wraps the same page in InvoicePage.

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/billing/invoices/{invoice_id}

Authentication: an access token, sent as Authorization: Bearer <token>.

Fields of a 200 response:

POST /api/v1/billing/invoices/{invoice_id}/apply-credit

Apply account credit to an unpaid invoice (unlocks provision / plan change when paid).

Authentication: an access token, sent as Authorization: Bearer <token>.

POST /api/v1/billing/topup/checkout

Hosted checkout to buy USD account credit without a saved payment method.

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

GET /api/v1/billing/topup/config

Authentication: an access token, sent as Authorization: Bearer <token>.

Fields of a 200 response:

PUT /api/v1/billing/topup/config

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

POST /api/v1/billing/topup/confirm-payment

Finalize a top-up PaymentIntent after SCA and credit the user balance.

USD credit comes from PaymentIntent metadata base_amount (set at checkout/charge). Optional client amount may assert within $0.02.

Authentication: an access token, sent as Authorization: Bearer <token>.

POST /api/v1/billing/topup/manual

Manually top up credit balance by charging a payment method.

data.amount is always USD. The gateway is charged in the user's preferred pay currency via admin FX rates (same path as auto-topup).

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

POST /api/v1/billing/topup/pay-intent

Create an in-page Stripe Payment Element intent for a credit top-up.

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

POST /api/v1/billing/topup/paypal-capture

Capture an approved PayPal order and credit the platform user balance.

USD credit is derived from the order (custom_id=topup:<usd>), not the client amount alone. Optional amount may assert within $0.02.

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/billing/transactions

As list_invoices: newest first, ties by id, with_total for a TransactionPage. type_filter=credit is credit added or used.

Authentication: an access token, sent as Authorization: Bearer <token>.