> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixroute.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing and Auto-Recharge

> Create recharge links, redeem codes, query wallet activity, and configure automatic 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.

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

## Read recharge configuration

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

```bash theme={null}
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 |

```bash theme={null}
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.

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

## Redeem a recharge code

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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](/en/api-reference/system-api/authentication-and-quota).

## Read automatic-recharge status

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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

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