Users

Top up credit

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.

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)

Request body

amount_usdnumber required

US dollars to buy, in whole cents.

saved_cardboolean

Charge the saved card now instead of opening a checkout.

Example request

{
  "amount_usd": 50
}

Response

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

idstring required

The payment's or the checkout's ID at the payment provider.

amount_usdnumber 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_urlstring uri nullable required

The hosted page that takes the card; null when paid.

expires_atstring date-time nullable required

When an unpaid checkout lapses; null when paid.

Example response

{
  "id": "cs_test_a1b2c3",
  "amount_usd": 50,
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3"
}

Changes

No recorded changes to this operation across all 1 revision of this API.