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.

PUT `/console/v2/billing/currency`#

Choose which currency calls spend. Refused while any call holds money; money is never converted, each currency keeps its own balance. The one exception is an untouched dollar welcome credit, which the first switch to rupees moves (the rupee welcome amount, never a conversion).

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

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

Request body: V2CurrencyRequest.

`V2CurrencyRequest`#

Field	Type	Required	Notes
`currency`	"USD" or "INR"	yes

`V2BillingSummary`#

Field	Type	Required	Notes
`api_requests_per_minute`	integer	yes
`balance_minor`	string	yes
`balance_nano_usd`	string	yes
`can_switch_currency`	boolean	yes
`currency`	string	no	default "USD"
`held_minor`	string	yes
`held_nano_usd`	string	yes
`lifetime_topup_minor`	string	yes
`lifetime_topup_nano_usd`	string	yes
`low_balance`	boolean	yes
`low_balance_threshold_minor`	string	yes
`low_balance_threshold_nano_usd`	string	yes
`max_voice_session_seconds`	integer	yes
`money_scale`	integer	no	default 1000000000
`other_currency`	string	yes
`other_currency_balance_minor`	string	yes
`project_id`	uuid	yes
`spendable_minor`	string	yes
`spendable_nano_usd`	string	yes
`topup_fee_bps`	integer	yes
`topup_max_minor`	integer	yes
`topup_min_minor`	integer	yes
`usd_state`	string	yes
`voice_concurrency`	integer	yes
`voice_rate`	VoiceRateContract	yes

`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 or null	yes
`rate_per_minute_minor`	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.
`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`	A call or a chat reply is in progress (money is held); switch after it ends.
`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 PUT "https://api.developers.dvaarik.com/console/v2/billing/currency" \
  -H "Authorization: Bearer $DVAARIK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD"
  }'

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_minor`	integer or null	no
`credits_nano_usd`	string or null	no
`currency`	string	yes
`fee_minor`	integer or null	no
`id`	uuid	yes
`issued_at`	date-time	yes
`number`	string	yes
`project_id`	uuid or null	yes
`total_minor`	integer or null	no

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_minor`	query	integer or null	no
`amount_usd_cents`	query	integer or null	no

`V2TopupQuote`#

What a top-up credits and what the gateway charges, in the wallet's currency.

Field	Type	Required	Notes
`amount_minor`	integer	yes
`amount_usd_cents`	integer or null	no
`credits_minor`	string	yes
`credits_nano_usd`	string or null	no
`currency`	string	no	default "USD"
`fee_bps`	integer	yes
`fee_minor`	integer	yes
`money_scale`	integer	yes
`total_minor`	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" \
  -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.

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

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
`amount_minor`	integer or null	no
`amount_usd_cents`	integer or null	no
`project_id`	uuid or null	no

`V2TopupOrderResponse`#

Field	Type	Required	Notes
`amount_minor`	integer	yes
`amount_usd_cents`	integer or null	no
`credits_minor`	string	yes
`credits_nano_usd`	string or null	no
`currency`	string	no	default "USD"
`fee_bps`	integer	yes
`fee_minor`	integer	yes
`money_scale`	integer	yes
`order_id`	string	yes
`project_id`	uuid	yes
`razorpay_key_id`	string	yes
`total_minor`	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.
`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"

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_minor`	string or null	no
`amount_nano_usd`	string or null	no
`balance_after_minor`	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
`label`	string or null	no
`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#

PUT /console/v2/billing/currency#

V2CurrencyRequest#

V2BillingSummary#

VoiceRateContract#

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#

GET /console/v2/billing/summary#

POST /console/v2/billing/topup#

V2TopupRequest#

V2TopupOrderResponse#

GET /console/v2/billing/transactions#

V2TransactionInfo#

PUT `/console/v2/billing/currency`#

`V2CurrencyRequest`#

`V2BillingSummary`#

`VoiceRateContract`#

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`#

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

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

`V2TopupRequest`#

`V2TopupOrderResponse`#

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

`V2TransactionInfo`#