API reference

Billing API

What this covers#

A prepaid USD wallet per account. Read the balance and the rate, list transactions and invoices, and open a checkout to top up. Console door only — a project key does not move money.

Every example below runs as written once these are exported:

bash

export DVAARIK_TOKEN="<account access token>"   # console session, from POST /console/auth/login
export INVOICE_ID="<uuid>"

A <value> inside a JSON body is a value you supply. Responses are JSON; every error body is { "detail": … }. Each schema is expanded once per page, where it first appears.

Account door errors#

Status	Cause
`401`	No account session was presented, or it is invalid or expired. Refresh once, then re-authenticate.
`403`	The account is suspended or its email is not verified.

Operations — account session#

The same resource through the console door. These are what the web console calls; both doors return the same shapes.

GET `/console/v2/billing/invoices`#

Receipts for paid top-ups.

Detail	Value
Door	Account session — `Authorization: Bearer $DVAARIK_TOKEN`
Operation	`consoleListBillingInvoices`
Success	`200` `V2InvoiceInfo[]`

Parameter	In	Type	Required	Notes
`limit`	query	integer	no
`offset`	query	integer	no

`V2InvoiceInfo`#

Field	Type	Required
`amount_minor`	integer or null	no
`credits_nano_usd`	string or null	no
`currency`	string	yes
`id`	uuid	yes
`issued_at`	date-time	yes
`number`	string	yes
`project_id`	uuid or null	yes

Error	When
`401`	No account session was presented, or it is invalid or expired.
`403`	The account is suspended or its email is not verified.
`404`	The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.

Plus the account-door errors above. Full list on the errors page.

bash

curl -sS -X GET "https://api.developers.dvaarik.com/console/v2/billing/invoices?limit=20" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"

GET `/console/v2/billing/invoices/{invoice_id}.pdf`#

Download one receipt as a PDF.

Detail	Value
Door	Account session — `Authorization: Bearer $DVAARIK_TOKEN`
Operation	`consoleDownloadBillingInvoicePdf`
Success	`200` `application/pdf`

Parameter	In	Type	Required	Notes
`invoice_id`	path	uuid	yes

Error	When
`401`	No account session was presented, or it is invalid or expired.
`403`	The account is suspended or its email is not verified.
`404`	The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.

Plus the account-door errors above. Full list on the errors page.

bash

curl -sS -X GET "https://api.developers.dvaarik.com/console/v2/billing/invoices/$INVOICE_ID.pdf" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"

GET `/console/v2/billing/quote`#

What a top-up buys, before you start it. No fee and no markup: one cent is exactly 10,000,000 nano-USD.

Detail	Value
Door	Account session — `Authorization: Bearer $DVAARIK_TOKEN`
Operation	`consoleGetTopupQuote`
Success	`200` `V2TopupQuote`

Parameter	In	Type	Required	Notes
`amount_usd_cents`	query	integer	yes

`V2TopupQuote`#

Field	Type	Required	Notes
`amount_usd_cents`	integer	yes
`credits_nano_usd`	string	yes
`currency`	string	no	default "USD"
`money_scale`	integer	yes

Error	When
`401`	No account session was presented, or it is invalid or expired.
`403`	The account is suspended or its email is not verified.
`404`	The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.

Plus the account-door errors above. Full list on the errors page.

bash

curl -sS -X GET "https://api.developers.dvaarik.com/console/v2/billing/quote?amount_usd_cents=<amount_usd_cents>" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"

GET `/console/v2/billing/rate`#

The connected-minute rate on its own, with its metering basis and rate version.

Detail	Value
Door	Account session — `Authorization: Bearer $DVAARIK_TOKEN`
Operation	`consoleGetVoiceRate`
Success	`200` `VoiceRateResponse`

`VoiceRateResponse`#

Field	Type	Required	Notes
`voice_rate`	VoiceRateContract	yes	The one price this product charges.

`VoiceRateContract`#

What one connected minute costs, in both forms the console needs.

Field	Type	Required	Notes
`currency`	string	no	default "USD"
`metering_basis`	string	no	default "connected_minute_rounded_up"
`money_scale`	integer	no	default 1000000000
`rate_display`	string	yes
`rate_nano_usd_per_minute`	string	yes
`rate_version`	string	yes

Error	When
`401`	No account session was presented, or it is invalid or expired.
`403`	The account is suspended or its email is not verified.

Plus the account-door errors above. Full list on the errors page.

bash

curl -sS -X GET "https://api.developers.dvaarik.com/console/v2/billing/rate" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"

GET `/console/v2/billing/summary`#

The account wallet — balance, held, spendable, lifetime top-up, low-balance flag — with the rate and this project's limits.

Detail	Value
Door	Account session — `Authorization: Bearer $DVAARIK_TOKEN`
Operation	`consoleGetBillingSummary`
Success	`200` `V2BillingSummary`

Parameter	In	Type	Required	Notes
`project_id`	query	uuid or null	no

`V2BillingSummary`#

Field	Type	Required	Notes
`api_requests_per_minute`	integer	yes
`balance_nano_usd`	string	yes
`currency`	string	no	default "USD"
`held_nano_usd`	string	yes
`lifetime_topup_nano_usd`	string	yes
`low_balance`	boolean	yes
`low_balance_threshold_nano_usd`	string	yes
`max_voice_session_seconds`	integer	yes
`money_scale`	integer	no	default 1000000000
`project_id`	uuid	yes
`spendable_nano_usd`	string	yes
`usd_state`	string	yes
`voice_concurrency`	integer	yes
`voice_rate`	VoiceRateContract	yes

Error	When
`401`	No account session was presented, or it is invalid or expired.
`403`	The account is suspended or its email is not verified.
`404`	The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.

Plus the account-door errors above. Full list on the errors page.

bash

curl -sS -X GET "https://api.developers.dvaarik.com/console/v2/billing/summary" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"

POST `/console/v2/billing/topup`#

Record a top-up order and open a Razorpay USD checkout. The wallet is credited by the payment webhook, never by a successful checkout alone.

Detail	Value
Door	Account session — `Authorization: Bearer $DVAARIK_TOKEN`
Operation	`consoleStartTopup`
Success	`200` `V2TopupOrderResponse`

Request body: V2TopupRequest.

`V2TopupRequest`#

Field	Type	Required	Notes
`amount_usd_cents`	integer	yes
`project_id`	uuid or null	no

`V2TopupOrderResponse`#

Field	Type	Required	Notes
`amount_usd_cents`	integer	yes
`credits_nano_usd`	string	yes
`currency`	string	no	default "USD"
`money_scale`	integer	yes
`order_id`	string	yes
`project_id`	uuid	yes
`razorpay_key_id`	string	yes

Error	When
`401`	No account session was presented, or it is invalid or expired.
`403`	The account is suspended or its email is not verified.
`404`	The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
`409`	The project or resource is in a state that refuses this change.
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.
`502`	The payment gateway did not create an order.
`503`	The order could not be recorded locally, so no checkout was returned.

Plus the account-door errors above. Full list on the errors page.

bash

curl -sS -X POST "https://api.developers.dvaarik.com/console/v2/billing/topup" \
  -H "Authorization: Bearer $DVAARIK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_usd_cents": 2500
  }'

GET `/console/v2/billing/transactions`#

The ledger, newest first.

Detail	Value
Door	Account session — `Authorization: Bearer $DVAARIK_TOKEN`
Operation	`consoleListBillingTransactions`
Success	`200` `V2TransactionInfo[]`

Parameter	In	Type	Required	Notes
`limit`	query	integer	no
`offset`	query	integer	no

`V2TransactionInfo`#

One canonical USD ledger row. A row from before the USD cutover has no USD amount and is deliberately NOT rendered as a zero: amount_nano_usd is null and the caller can tell "nothing" from "nothing yet converted". The archival paise figures stay on the legacy route.

Field	Type	Required
`amount_nano_usd`	string or null	no
`balance_after_nano_usd`	string or null	no
`created_at`	date-time	yes
`currency`	string	yes
`description`	string or null	no
`id`	uuid	yes
`money_scale`	integer	yes
`project_id`	uuid or null	yes
`reference`	string or null	no
`type`	string	yes

Error	When
`401`	No account session was presented, or it is invalid or expired.
`403`	The account is suspended or its email is not verified.
`404`	The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.

Plus the account-door errors above. Full list on the errors page.

bash

curl -sS -X GET "https://api.developers.dvaarik.com/console/v2/billing/transactions?limit=20" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"

Try it without a key in the browser

The playground opens a real voice session with your account session, so a project key never reaches a browser. Machine calls belong on your own server.

Open the playground Quickstart

Billing API

What this covers#

Account door errors#

Operations — account session#

GET /console/v2/billing/invoices#

V2InvoiceInfo#

GET /console/v2/billing/invoices/{invoice_id}.pdf#

GET /console/v2/billing/quote#

V2TopupQuote#

GET /console/v2/billing/rate#

VoiceRateResponse#

VoiceRateContract#

GET /console/v2/billing/summary#

V2BillingSummary#

POST /console/v2/billing/topup#

V2TopupRequest#

V2TopupOrderResponse#

GET /console/v2/billing/transactions#

V2TransactionInfo#

GET `/console/v2/billing/invoices`#

`V2InvoiceInfo`#

GET `/console/v2/billing/invoices/{invoice_id}.pdf`#

GET `/console/v2/billing/quote`#

`V2TopupQuote`#

GET `/console/v2/billing/rate`#

`VoiceRateResponse`#

`VoiceRateContract`#

GET `/console/v2/billing/summary`#

`V2BillingSummary`#

POST `/console/v2/billing/topup`#

`V2TopupRequest`#

`V2TopupOrderResponse`#

GET `/console/v2/billing/transactions`#

`V2TransactionInfo`#