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

# POST /api/billing/payments — start a wallet top-up

> Create a wallet top-up order with Stripe, WeChat Pay, or Alipay. Returns a redirect URL or QR code for the payer to complete the payment.

Create a wallet top-up order with a supported provider. Response includes a redirect URL (Stripe Checkout) or a QR code URL (WeChat Pay, Alipay) that the payer uses to complete the payment.

**Method:** `POST` **Path:** `/api/billing/payments` **Auth:** Session Bearer

## Request

<ParamField body="provider" type="string" required>
  `stripe` (international, USD), `wechat` (China, CNY), or `alipay` (China, CNY). Must be enabled: check `GET /api/payments/providers`.
</ParamField>

<ParamField body="amount" type="number" required>
  Top-up amount in major units of `currency` (for example `20` for \$20).
</ParamField>

<ParamField body="currency" type="string" required>
  `USD` on the international site, `CNY` on the China site.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Payment identifier.
</ResponseField>

<ResponseField name="provider" type="string">
  Selected provider.
</ResponseField>

<ResponseField name="status" type="string">
  Initial status, typically `pending`.
</ResponseField>

<ResponseField name="redirect_url" type="string">
  Stripe Checkout URL (Stripe only).
</ResponseField>

<ResponseField name="qr_code_url" type="string">
  QR code URL to render for WeChat Pay or Alipay.
</ResponseField>

<ResponseField name="expires_at" type="string">
  ISO 8601 expiry timestamp.
</ResponseField>

## Example

```bash theme={null}
curl -X POST https://ariacompute.com/api/billing/payments \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{"provider": "stripe", "amount": 20, "currency": "USD"}'
```

```json theme={null}
{
  "id": "pay_01H...",
  "provider": "stripe",
  "status": "pending",
  "redirect_url": "https://checkout.stripe.com/c/pay/...",
  "expires_at": "2026-09-23T11:00:00Z"
}
```

## Errors

| Status | Meaning                                                     |
| ------ | ----------------------------------------------------------- |
| `400`  | Missing field or unsupported provider/currency combination. |
| `401`  | Missing or invalid session token.                           |
| `409`  | Provider not enabled.                                       |


## Related topics

- [GET /api/billing/payments — list wallet top-ups](/api-reference/billing/payments-list.md)
- [Prepaid wallet, top-ups, and usage billing](/concepts/wallet-billing.md)
- [Top up your wallet with Stripe, WeChat Pay, or Alipay](/guides/top-up-wallet.md)
- [GET /api/billing/payments/{id} — get payment status](/api-reference/billing/payments-get.md)
- [Download invoices and receipts for your payments](/guides/invoices-receipts.md)