Back to Details

billing-integration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Credyt Integrate

Credyt 集成

Help the user wire Credyt into their application code. This skill works with the user's actual codebase — reading their existing code and adding Credyt integration in the right places.
The full integration guide with code examples is at docs.credyt.ai/ai-integration.md. Fetch it for detailed patterns and examples when needed.
帮助用户将Credyt接入其应用代码。该技能可对接用户的实际代码库——读取现有代码并在合适的位置添加Credyt集成。
完整的集成指南及代码示例可查看docs.credyt.ai/ai-integration.md。必要时可获取该文档以参考详细的模式和示例。

Understand the codebase first

先了解代码库

Before writing any code, understand what the user has:
"Let me look at your project to understand your stack and where billing should plug in."
Check for:
  • Language and framework (Node/Express, Next.js, Python/FastAPI, etc.)
  • Authentication setup (how users sign up and log in)
  • Where the billable activities happen in their code
  • Existing environment variable patterns
在编写任何代码之前，先了解用户已有的资源：
"让我查看你的项目，了解你的技术栈以及计费功能应该接入的位置。"
检查以下内容：
  • 语言与框架（Node/Express、Next.js、Python/FastAPI等）
  • 认证设置（用户注册和登录的方式）
  • 代码中产生计费行为的位置
  • 现有的环境变量配置模式

Integration areas

集成模块

Walk through each area. Not all will apply to every user — ask which ones they need.
逐一完成以下模块的集成。并非所有模块都适用于每个用户——询问用户需要哪些功能。

1. API key setup

1. API密钥配置

The Credyt API key must be stored securely on the server side — never in code that runs in the browser.
Add 
CREDYT_API_KEY
to their environment variables alongside their other secrets. Show them how to create an API client or helper that attaches the key as an 
X-CREDYT-API-KEY
header.
Credyt API密钥必须安全存储在服务器端——绝不能放在浏览器端运行的代码中。
将
CREDYT_API_KEY
添加到环境变量中，与其他保密信息放在一起。向用户展示如何创建API客户端或辅助工具，将密钥作为
X-CREDYT-API-KEY
请求头附加到请求中。

2. Customer creation (registration flow)

2. 客户创建（注册流程）

When a new user signs up in their app, create a matching Credyt customer. Find their registration/signup handler and add customer creation after successful account creation.
Key points:
  • Use 
    external_id
    to link the Credyt customer to their app's user ID
  • Subscribe the customer to the relevant products during creation
  • Store the Credyt customer ID in their database alongside the user record
  • Handle the case where the customer already exists (409/422 — look up by external_id instead)
Recurring fixed fees — pending subscriptions
If the product uses a recurring fixed fee (e.g. $20/month), the customer must pay upfront before their subscription activates. In this case the API returns a 
pending
status rather than activating immediately.
When the response status is 
pending
:
  • Check the 
    required_actions
    array for an action with 
    type: "payment"
    and extract its 
    redirect_url
  • Redirect the customer to that URL so they can enter their card details — include a 
    return_url
    (where to send them on success) and a 
    failure_url
    (where to send them if payment fails)
  • Do not activate the user's account yet — store it as pending in your database until payment is confirmed
  • If the redirect link expires before the customer completes payment, fetch the customer by their Credyt ID to get a refreshed link
Once the customer pays, Credyt fires a 
subscription.activated
webhook. Listen for this event on your backend and use it to activate the user's account.
当用户在你的应用中完成新账号注册后，创建对应的Credyt客户。找到你的注册/ signup处理程序，在账号创建成功后添加客户创建逻辑。
核心要点：
  • 使用
    external_id
    将Credyt客户与应用内的用户ID关联
  • 在创建客户时为其订阅相关产品
  • 将Credyt客户ID存储在数据库的用户记录中
  • 处理客户已存在的情况（409/422错误——通过external_id查询现有客户）
定期固定费用——待激活订阅
如果产品采用定期固定费用模式（例如每月20美元），客户必须预先支付费用才能激活订阅。这种情况下，API会返回
pending
状态，而非立即激活。
当响应状态为
pending
时：
  • 检查
    required_actions
    数组中类型为
    payment
    的操作，提取其
    redirect_url
  • 将客户重定向到该URL以输入银行卡信息——需包含
    return_url
    （支付成功后的跳转地址）和
    failure_url
    （支付失败后的跳转地址）
  • 暂不激活用户账号——在数据库中将其标记为待激活状态，直到支付确认
  • 如果重定向链接在客户完成支付前过期，通过Credyt客户ID重新获取新的链接
客户完成支付后，Credyt会触发
subscription.activated
webhook。在后端监听该事件，并以此激活用户账号。

3. Usage event tracking

3. 使用事件追踪

Find where the billable activities happen in their code and add event submission after each one. Each event needs:
  • A unique ID (UUID) so the same event can't be billed twice
  • The correct 
    event_type
    matching the product configuration
  • A timestamp of when it happened
  • Any data fields needed for pricing (volume fields, dimensions)
For volume-based products, the event data must include the volume field (e.g., 
total_tokens: 1500
). For dimensional products, include the dimension values (e.g., 
model: "gpt-4"
).
找到代码中产生计费行为的位置，在每个行为完成后添加事件上报逻辑。每个事件需要包含：
  • 唯一ID（UUID），避免同一事件被重复计费
  • 与产品配置匹配的正确
    event_type
  • 事件发生的时间戳
  • 定价所需的所有数据字段（用量字段、维度信息）
对于基于用量的产品，事件数据必须包含用量字段（例如
total_tokens: 1500
）。 对于基于维度的产品，需包含维度值（例如
model: "gpt-4"
）。

4. Cost tracking (if they set up vendors)

4. 成本追踪（若已配置供应商）

If the user set up vendors in 
/credyt:billing-setup
, add cost data to usage events. Each event can include a 
costs
array with the vendor ID, the amount it cost, and the currency.
This is typically added right after the billable action completes, when the cost is known (e.g., after receiving the response from an AI API that includes token counts).
"Even if you're not charging users yet, attaching costs to every event lets Credyt calculate your unit economics so you can make pricing decisions based on real data."
如果用户已在/credyt:billing-setup中配置了供应商，需在使用事件中添加成本数据。每个事件可包含
costs
数组，其中包含供应商ID、成本金额和货币类型。
这一步通常在计费行为完成后立即执行，此时成本信息已确定（例如在收到包含token数量的AI API响应后）。
"即使你尚未向用户收费，为每个事件附加成本信息也能让Credyt计算你的单位经济效益，帮助你基于真实数据制定定价策略。"

5. Balance checks (pre-action gating)

5. 余额查询（操作前校验）

Before expensive operations, check the customer's wallet balance. If insufficient, block the action and prompt the user to top up.
Find where billable actions are initiated (API routes, button handlers, etc.) and add a balance check before the action runs. Return a clear message if the balance is too low.
Show them how to estimate the cost of the upcoming action and compare it against the available balance.
在执行高成本操作前，检查客户的钱包余额。如果余额不足，阻止操作并提示用户充值。
找到计费操作的发起位置（API路由、按钮处理程序等），在操作执行前添加余额校验逻辑。如果余额过低，返回清晰的提示信息。
向用户展示如何预估即将执行的操作成本，并与可用余额进行比较。

6. Billing portal / top-up UI

6. 计费门户/充值UI

Help users add funds through Credyt's billing portal. This is the simplest way to handle payments — Credyt hosts the page, handles Stripe, and redirects back to their app.
Add a "Billing" or "Add funds" link/button in their app's settings or account page. When clicked, the backend creates a billing portal session and redirects the user to the URL.
Key points:
  • Portal sessions expire after 10 minutes
  • Set a 
    return_url
    for where to send users after they're done
  • Set a 
    failure_url
    for payment failures
帮助用户通过Credyt的计费门户添加资金。这是处理支付的最简单方式——Credyt托管页面、对接Stripe，并在完成后重定向回应用。
在应用的设置页或账户页添加“计费”或“充值”链接/按钮。点击时，后端创建计费门户会话并将用户重定向到对应的URL。
核心要点：
  • 门户会话10分钟后过期
  • 设置
    return_url
    （用户完成操作后的跳转地址）
  • 设置
    failure_url
    （支付失败后的跳转地址）

7. Balance display

7. 余额展示

Show the user's current balance in the app UI. Fetch from the wallet endpoint and display the available amount.
Consider where this fits in their app — sidebar, header, account page — and add it there.
在应用UI中显示用户当前余额。从钱包接口获取数据并展示可用金额。
考虑在应用中的合适位置添加该功能——侧边栏、头部导航、账户页等。

Implementation approach

实施步骤

Don't dump all the code at once. Work through each area one at a time:
  1. Start with API key setup and customer creation — these are foundational
  2. Then add usage event tracking — this is the core billing integration
  3. Add balance checks to gate expensive operations
  4. Add billing portal and balance display for the user-facing pieces
  5. Add cost tracking last if applicable
After each piece, suggest they test it:
"Try creating a new account in your app and check the Credyt dashboard — you should see a new customer appear. Then we'll move on to usage tracking."
不要一次性提供所有代码。逐一完成每个模块的集成：
  1. 从API密钥配置和客户创建开始——这些是基础功能
  2. 然后添加使用事件追踪——这是计费集成的核心
  3. 添加余额校验逻辑，限制高成本操作
  4. 添加计费门户和余额展示功能，完善用户端体验
  5. 最后按需添加成本追踪功能
完成每个模块后，建议用户进行测试：
"尝试在你的应用中创建一个新账号，然后查看Credyt控制台——你应该能看到一个新客户。之后我们再进行使用追踪的集成。"

Reference

参考资源

For detailed code examples, error handling patterns, and advanced topics (hybrid billing, refunds, auto top-up), point the user to:
如需详细的代码示例、错误处理模式以及进阶主题（混合计费、退款、自动充值），可引导用户查看：