Billing and Auto-Recharge

Overview

Wallet endpoints let an authenticated user inspect recharge configuration, create a payment link, redeem a code, review recharge history, and manage automatic recharge.

Payment and auto-recharge endpoints create financial operations. Call them only from a trusted backend after explicit user confirmation.

Read recharge configuration

Always read the current configuration before presenting amounts or payment options:

topup_info=$(curl -fsS "$BASE_URL/api/user/topup/info" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID")

jq '.data' <<< "$topup_info"

Important fields can include:

Field	Meaning
`amount_options`	Suggested recharge amounts
`min_topup`	General minimum amount
`stripe_min_topup`	Stripe-specific minimum
`pay_methods`	Enabled payment processors and their limits
`daily_recharge_tiers`	Amount ranges and bonus rates
`enable_stripe_topup`	Whether Stripe recharge is enabled
`enable_redotpay_topup`	Whether the corresponding crypto payment flow is enabled

These values are deployment and campaign configuration. Validate the selected amount immediately before creating a payment link.

Create a payment link

The current wallet flow accepts an integer USD amount and one of the payment methods shown below:

`payment_method`	Flow
`credit_card`	Card checkout
`usdt`	USDT checkout

payment=$(curl -fsS -X POST "$BASE_URL/api/user/topup/pay" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50,
    "payment_method": "credit_card"
  }')

pay_link=$(jq -er '
  select(.success == true or .message == "success")
  | .data.pay_link
' <<< "$payment")

Redirect the user to pay_link in a browser. Receiving a link does not mean the wallet has been credited; credit is applied after the payment provider confirms completion.

Do not embed the system access token in the redirect URL or send it to the payment provider.

Redeem a recharge code

curl -fsS -X POST "$BASE_URL/api/user/topup" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{"key":"YOUR_REDEMPTION_CODE"}' | jq

Redemption codes are single-use. Do not log them or retry a successful redemption.

Recharge history

curl -fsS --get "$BASE_URL/api/user/topup/self" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  --data-urlencode "p=1" \
  --data-urlencode "page_size=20" \
  --data-urlencode "keyword=" | jq

The response uses items, page, page_size, and total. After the checkout completes, refresh both recharge history and account balance:

curl -fsS "$BASE_URL/api/user/self" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" | jq '.data.quota'

Account quota is in internal units. Convert it using quota_per_unit as described in Authentication and quota.

Read automatic-recharge status

curl -fsS "$BASE_URL/api/user/auto-recharge" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" | jq

The response reports:

bound: whether a reusable payment method is bound
card_last4: masked card identifier
enabled: whether automatic recharge is active
threshold: wallet balance in USD that triggers a recharge
amount: USD amount charged on each trigger
stripe_ready: whether automatic recharge can be configured

Bind a payment method

When no payment method is bound, start the setup flow:

setup=$(curl -fsS -X POST "$BASE_URL/api/user/auto-recharge/setup" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "threshold": 10,
    "amount": 50
  }')

setup_link=$(jq -er '.data.pay_link' <<< "$setup")

Redirect the user to setup_link. Wait for the provider callback, then call GET /api/user/auto-recharge again and confirm bound: true before enabling the feature.

Configure automatic recharge

After binding, update all three settings together:

curl -fsS -X PUT "$BASE_URL/api/user/auto-recharge" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "threshold": 10,
    "amount": 50
  }' | jq

threshold must be non-negative. The current console requires a recharge amount of at least USD 10, but clients should also honor current server and payment-provider limits. Disable automatic recharge without removing the bound method by sending the same payload with enabled: false.

Remove the binding

curl -fsS -X DELETE "$BASE_URL/api/user/auto-recharge/binding" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" | jq

Removing the binding also disables automatic recharge and removes the saved card reference. Require explicit confirmation before calling this endpoint.

Recommended payment flow

Read /api/user/topup/info and validate the amount and method.
Create the payment or binding link once.
Redirect the user to the returned link.
Treat the provider redirect as pending, not final proof of credit.
Refresh /api/user/topup/self, /api/user/self, or /api/user/auto-recharge until the expected state appears.
Make retries idempotent in your application and avoid creating multiple checkout links for the same user action.

Popular Models

OpenAI SDK Usage

System API

Text Series

Embedding Series

Image Series

Video Series

Others

Billing and Auto-Recharge

Overview

Read recharge configuration

Create a payment link

Redeem a recharge code

Recharge history

Read automatic-recharge status

Bind a payment method

Configure automatic recharge

Remove the binding

Recommended payment flow

​Overview

​Read recharge configuration

​Create a payment link

​Redeem a recharge code

​Recharge history

​Read automatic-recharge status

​Bind a payment method

​Configure automatic recharge

​Remove the binding

​Recommended payment flow

Overview

Read recharge configuration

Create a payment link

Redeem a recharge code

Recharge history

Read automatic-recharge status

Bind a payment method

Configure automatic recharge

Remove the binding

Recommended payment flow