Top-up & Billing Guide: One-Stop Reference for Stripe Payments, CNY, Refunds, and Invoices

Top-up & Billing Guide

TL;DR: CodeGateway bills per token. $2 starting credit, balances never expire, self-funded balance is refundable any time, and the markup automatically drops with your 90-day rolling spend (1.5× → 1.2×).

CodeGateway uses pay-as-you-go billing — there's no monthly subscription. This article walks through every billing-related topic in one place: top-up flow, pricing mechanics, refund policy, getting an invoice, and more.

1. The top-up flow

1. Open the top-up page

Log in to the Dashboard → Billing page → click Top up.

2. Pick a top-up amount

Preset amounts: $10 / $20 / $50 / $100. You can also enter a custom amount (minimum $5, maximum $10,000).

3. Pay through Stripe

Click Pay and you'll be redirected to Stripe's official checkout. Stripe is a globally compliant payment processor — users in China can pay with:

• Visa / Mastercard / American Express credit cards
• UnionPay credit cards (some issuers)
• Alipay bridging (in some cases)

Note: CodeGateway prices are denominated in USD. Stripe's checkout will automatically convert at the day's exchange rate to your card's local currency (CNY) and charge that amount, including Stripe's processing fee (typically 3.9% + $0.30). The final charge shown by Stripe is the source of truth.

4. Automatic credit

Once the payment succeeds, Stripe notifies CodeGateway via webhook, and your balance is usually credited within 30 seconds.

If it hasn't shown up after 5 minutes, check the status in Dashboard → Billing → Payment history:

• pending — Stripe has received the payment, the webhook is still syncing
• succeeded — your balance has been credited
• failed — the payment failed; the funds will be returned via the original payment method (1-7 business days)

Verify the top-up landed (optional)

If the dashboard hasn't refreshed yet, you can pull the live balance directly from the API:

# replace $CG_API_KEY with one of your API keys (Dashboard → API Keys)
curl -sS https://api.codegateway.dev/v1/billing/balance \
  -H "x-api-key: $CG_API_KEY" \
  | jq '.'
# Returns:
# {
#   "balance_cents": 200,        // self top-up balance in cents
#   "gifted_cents": 100,         // signup bonus + invite rewards (non-refundable)
#   "tier": "tier1",
#   "current_markup": 1.5
# }

If balance_cents hasn't moved 5 minutes after Stripe confirmed the payment, open Dashboard → Billing → Payment History and check the row's status — failed payments roll back automatically (1–7 business days), succeeded payments without credit usually mean the webhook hasn't reached the worker yet (rare; refresh after a few seconds).

2. How pricing works

CodeGateway adds a tiered markup on top of Anthropic's official pricing:

Markup tiers:

• New users start at 1.5x
• 90-day spend ≥ $10 → 1.4x
• 90-day spend ≥ $50 → 1.3x
• 90-day spend ≥ $200 → 1.25x
• 90-day spend ≥ $500 → 1.2x (hard floor)

Full details in Tiered Markups Explained.

3. Cache discounts

Claude Sonnet/Opus support prompt caching: for the same system prompt + few-shot examples, every call after the first is billed at the cached rate (just 10% of full price).

CodeGateway fully supports cache billing:

• Cache write: 1.25x of the regular price (for the first write)
• Cache hit: 0.1x of the regular price (90% discount)

Used wisely, prompt caching can save 80%+ of cost in scenarios dominated by a large system prompt. See the Anthropic Prompt Caching docs for details.

4. Refund Policy

We support refunds for any unused balance. Rules:

Eligibility

• Only self-funded top-ups are refundable (gifted balances like the $1 signup bonus are not)
• Refund amount ≤ current balance minus gifted portion (refund up to whatever's left of self-funded top-up; one refund per top-up)
• At most 1 refund per month (CMS-configurable)
• No API call in the 5 minutes preceding the refund request (prevents in-flight billing conflicts; exact window is set by refundIdleSeconds)

Process

Dashboard → Billing → Refund button → enter a reason → submit.

Stripe refunds the original card in 1-3 business days (the exact timing depends on your issuing bank).

Or if you'd rather skip the dashboard, hit the refund API directly:

# 1) list your top-ups to find the payment_id
curl -sS https://api.codegateway.dev/v1/billing/payments \
  -H "x-api-key: $CG_API_KEY"

# 2) request a refund (amount in cents — must be ≤ self-funded balance)
curl -sS -X POST https://api.codegateway.dev/v1/billing/refund \
  -H "x-api-key: $CG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payment_id": "pay_xxx", "amount_cents": 500, "reason": "no longer needed"}'

The same eligibility rules apply: the API enforces refundIdleSeconds (no API call within the last ~5 minutes), monthly cap, and gifted-balance exclusion.

Non-refundable scenarios

• Gifted balance (signup bonus, invite rewards) is not refundable — only self-funded top-ups are
• Amounts that have been written off via invoicing are not refundable (to avoid tax complexity)
• If the Stripe refund itself fails (e.g. issuer declined), the balance is automatically rolled back, and you can re-submit

5. Invoices

CodeGateway issues official invoices directly through Stripe, so accounting in your company is straightforward.

Automatic receipts

After every successful top-up, Stripe sends a payment receipt email to the email address on your account. That receipt works as a proof of payment for accounting.

What's on the invoice

Invoice item: software / information technology service fee.

The invoice is issued in the company name you submit (individuals can also use a personal name).

6. Balance alerts

A low balance can break your service continuity. We provide two layers of alerts:

Dashboard alert

When your balance falls below $2, a red banner appears at the top of the Dashboard.

Email alert

When your balance falls below $5, we send a daily email to your registered address (rate-limited to one email per day to avoid spam).

Coming soon: auto top-up (Auto Top-Up) — when the balance drops below your threshold, $X is automatically charged to your linked card to refill it, avoiding any service interruption. You can subscribe to a launch notification through the feedback widget.

7. FAQ

Q: Can I pay in CNY?

A: CodeGateway prices are in USD, but Stripe checkout supports automatic conversion to CNY. If your card is a CNY card, the charge will be in CNY, calculated at the day's exchange rate plus Stripe's processing fee. We don't charge CNY directly — the page displays the USD equivalent.

Q: Does the balance expire?

A: No. The balance from a top-up is valid forever, until you spend it.

Q: Does rotating an API key affect the balance?

A: No. The balance belongs to the account, not to a specific key. Multiple keys on one account share the same balance.

Q: I forgot to track how much I've used. How do I reconcile?

A: Dashboard → Request logs has every call recorded with full detail: model, token count, cache hits, the markup at the time, and the amount charged. You can filter by time range, or export to CSV.

Q: What happens to the next call when my balance hits 0?

A: You'll get a 403 insufficient balance error (see the Error Troubleshooting Guide for details). Your account isn't disabled — service resumes immediately after a top-up.

Related docs

• Tiered Markups Explained — the 90-day rolling markup
• Error Troubleshooting Guide — 401 / 403 / 429 / 500
• API Key Security Best Practices — key management

References

• Stripe Payments docs
• Anthropic API pricing
• Anthropic Prompt Caching docs