---
title: "Top up credit"
method: POST
path: "/v1/users/me/top-ups"
tags: ["Users"]
---

# Top up credit

`POST /v1/users/me/top-ups`

## Request

- Base URL: `https://api.naturali.ai`
- URL: `https://api.naturali.ai/v1/users/me/top-ups`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.naturali.ai/authorize`, token URL `https://api.naturali.ai/token`, scopes: `mcp:access`)

Buys model credit for the caller's account. Once the card is charged the full amount is added to `credit_balance_usd` as purchased credit, which never expires. The card fee is not deducted. `amount_usd` is what is credited; a card issued in Brazil is charged its equivalent in Brazilian reais at the Banco Central's latest closing PTAX selling rate, and a checkout shows reais to a payer in Brazil.

With `saved_card: true` the saved card is charged at once and the answer is `status: paid`. When the card needs authentication or is declined, nothing is charged and the answer falls back to a checkout.

A checkout (`status: checkout`) is a hosted page: send the caller to `checkout_url`. Creating it charges nothing, and one left unpaid lapses at `expires_at`. The card paid with there becomes the account's saved card, replacing any other. After paying, the browser returns to the console's billing page.

## Request body

- TopUpCreate
  - `amount_usd` number, required: US dollars to buy, in whole cents.
  - `saved_card` boolean: Charge the saved card now instead of opening a checkout.

## Response `201`

The paid top-up, or the checkout to send the caller to.

- TopUp
  - `id` string, required: The payment's or the checkout's ID at the payment provider.
  - `amount_usd` number, required: What is credited once paid: charged in US dollars, or its equivalent in reais.
  - `status` 'paid' | 'checkout', required: `paid`: the saved card was charged and the credit added. `checkout`: nothing is charged until the caller pays at `checkout_url`.
  - `checkout_url` string, uri, nullable, required: The hosted page that takes the card; `null` when paid.
  - `expires_at` string, date-time, nullable, required: When an unpaid checkout lapses; `null` when paid.

## Other responses

- `400`: The request was malformed or failed validation.
- `401`: Missing or invalid credentials.
- `409`: `saved_card` with no saved card (`payment_method_required`).
- `502`: The payment provider could not be reached (`payment_provider_error`). Nothing was charged.
- `503`: Card payments are not available on this deployment (`payments_not_configured`), or the exchange rate for a card charged in reais could not be read (`exchange_rate_unavailable`). Nothing was charged.

---

[API](https://skmtc.dev/naturali/apis/naturali-ai-api.md) · [All operations](https://skmtc.dev/naturali/apis/naturali-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/naturali/apis/naturali-ai-api/revisions/e4905b78f422?raw)