# 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 | Notes |
| --- | --- | --- | --- |
| `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](/docs/errors).

```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](/docs/errors).

```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](/docs/errors).

```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](/docs/errors).

```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](/docs/errors).

```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](/docs/errors).

```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 | Notes |
| --- | --- | --- | --- |
| `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](/docs/errors).

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

---

Source: https://developers.dvaarik.com/docs/api/billing · every page as one file: https://developers.dvaarik.com/docs.md