内容
# Chia
非洲支付提供商的统一TypeScript工具。Chia在一个类型安全的接口后面封装了PayChangu、PawaPay和OneKhusa。
**文档：[docs.usechia.com](https://docs.usechia.com)**
## 工具列表
| 工具 | 描述 | 文档 |
|---------|-------------|------|
| **[@chiahq/sdk](./packages/sdk)** | 用于直接提供商API访问的TypeScript SDK | [SDK文档](https://docs.usechia.com/docs/sdk/overview) |
| **[@chiahq/widget](./packages/widget)** | 可嵌入的订阅小部件 - 一个脚本标签，无需后端 | [小部件文档](https://docs.usechia.com/docs/widget/overview) |
| **[@chiahq/mcp](./packages/mcp)** | MCP服务器，向AI助手公开支付操作 | [MCP文档](https://docs.usechia.com/docs/mcp/overview) |
## 快速入门
```bash
npm install @chiahq/sdk
# 或
pnpm add @chiahq/sdk
# 或
yarn add @chiahq/sdk
```
```typescript
import { ChiaSDK } from "@chiahq/sdk";
const sdk = ChiaSDK.initialize({
paychangu: {
secretKey: process.env.PAYCHANGU_SECRET_KEY,
environment: "DEVELOPMENT",
},
pawapay: {
jwt: process.env.PAWAPAY_JWT,
environment: "DEVELOPMENT",
},
onekhusa: {
apiKey: process.env.ONEKHUSA_API_KEY,
apiSecret: process.env.ONEKHUSA_API_SECRET,
organisationId: process.env.ONEKHUSA_ORGANISATION_ID,
environment: "DEVELOPMENT",
},
});
// 统一 - 跨配置的提供商路由支付
const payment = await sdk.payments.initiate({
reference: "order-123",
amount: "50.00",
currency: "ZMW",
msisdn: "260971234567",
country: "ZMB",
});
payment.provider // "pawapay" - 由国家和货币路由
payment.status // "pending"
payment.nextAction // { type: "pin_prompt" }
```
`sdk.payments` 和 `sdk.payouts` 是推荐的收款和付款方式 - 它们会路由到可以处理请求的已配置提供商。参见 [统一支付](https://docs.usechia.com/docs/sdk/unified-payments) 以了解路由、故障转移和错误处理。
直接提供商访问（`sdk.pawapay.*`、`sdk.paychangu.*`、`sdk.onekhusa.*`）仍然可用于统一API未涵盖的提供商特定功能：
```typescript
// PayChangu - 启动托管结账
const checkout = await sdk.paychangu.initiatePayment({
amount: "1000",
currency: "MWK",
tx_ref: "order-123",
callback_url: "https://your-app.com/webhook",
return_url: "https://your-app.com/success",
email: "customer@example.com",
});
// PawaPay - 请求移动货币存款
const deposit = await sdk.pawapay.deposits.sendDeposit({
depositId: "unique-deposit-id",
amount: "100.00",
currency: "ZMW",
payer: {
type: "MMO",
accountDetails: {
phoneNumber: "260971234567",
provider: "MTN_MOMO_ZMB",
},
},
});
// OneKhusa - 启动收款
const collection = await sdk.onekhusa.collections.initiateRequestToPay({
amount: 500,
currency: "MWK",
phone: "+265991234567",
paymentMethod: "MOBILE_MONEY",
});
```
您需要提供自己的提供商凭证。有关所有支持的选项，请参见 [配置](https://docs.usechia.com/docs/sdk/configuration)。
> 永远不要将生产API密钥提交到版本控制中。使用环境变量或机密管理器。
## 支持的提供商
- **PayChangu** - 覆盖马拉维最广泛的支付网关（直接收费、移动货币、银行转账）
- **PawaPay** - 跨20多个非洲国家的移动货币支付（存款、付款、退款）
- **OneKhusa** - 关注马拉维和南部非洲的收款和付款
## SDK功能
**PayChangu** - 直接收费支付、移动货币收款和付款、银行转账、交易验证、运营商列表
**PawaPay** - 存款请求、单次和批量付款、退款、钱包余额、网络配置和可用性检查、提供商预测
**OneKhusa** - 请求付款收款、单次和批量付款、审批工作流（批准、审查、拒绝）、资金转账、交易列表（带筛选器）
## 小部件
使用单个脚本标签将订阅流程嵌入任何站点：
```html
<div id="subscribe-widget"></div>
<script src="https://cdn.jsdelivr.net/npm/@chiahq/widget/dist/chia-widget.min.js"></script>
<script>
Chia.init({
publishableKey: "pk_live_your_key_here",
container: "#subscribe-widget",
planId: "your-plan-id",
});
</script>
```
参见 [小部件快速入门](https://docs.usechia.com/docs/widget/quick-start) 以了解配置和事件。
## MCP服务器
```bash
npm install -g @chiahq/mcp
# 或使用npx直接运行
npx @chiahq/mcp
```
参见 [MCP文档](https://docs.usechia.com/docs/mcp/overview) 以了解与Claude Desktop和其他AI助手进行配置。
## 类型导入
所有类型都从包根重新导出 - 无需深入导入：
```typescript
import type {
PayChanguOperatorsResponse,
PawaPayTypes,
OneKhusaTypes,
} from "@chiahq/sdk";
```
完整引用： [类型定义](https://docs.usechia.com/docs/sdk/types)。
## 项目结构
```
packages/sdk/ TypeScript SDK
packages/widget/ 可嵌入的订阅小部件
packages/mcp/ 用于AI助手的MCP服务器
docs/ 文档站点（docs.usechia.com）
website/ 营销站点
examples/ 用例
.github/workflows/ CI/CD和发布自动化
```
## 开发
```bash
# 安装依赖
pnpm install
# 构建SDK
pnpm --filter @chiahq/sdk build
# 构建小部件
pnpm --filter @chiahq/widget build
# 构建MCP服务器（首先构建SDK）
pnpm --filter @chiahq/sdk build && pnpm --filter @chiahq/mcp build
# 运行SDK测试
pnpm --filter @chiahq/sdk test
# 校验和格式化（SDK）
pnpm --filter @chiahq/sdk lint
pnpm --filter @chiahq/sdk format
```
## 发布
该项目使用GitHub Actions进行自动化发布。每个包都有自己的工作流：
| 包 | 工作流 | 标签格式 | npm包 |
|---------|----------|------------|-------------|
| SDK | `release-sdk.yml` | `v{version}` | `@chiahq/sdk` |
| 小部件 | `release-widget.yml` | `widget-v{version}` | `@chiahq/widget` |
| MCP | `release-mcp.yml` | `mcp-v{version}` | `@chiahq/mcp` |
发布类型：`patch`（错误修复）、`minor`（新功能）、`major`（重大更改）、`beta`（预发布）。
文档站点通过 `release-docs.yml` 部署。
## 文档
- [文档站点](https://docs.usechia.com) - SDK、小部件和MCP服务器的完整参考
- [SDK README](./packages/sdk/README.md) - SDK概述和API参考
- [小部件 README](./packages/widget/README.md) - 小部件设置和配置
- [MCP README](./packages/mcp/README.md) - MCP服务器设置和使用
- [MCP安装指南](./packages/mcp/INSTALLATION.md) - 详细的MCP设置
- [示例](./examples/) - 工作代码示例
- [变更日志](./CHANGELOG.md) - 版本历史
## 贡献
欢迎贡献。请在提交拉取请求之前阅读 [贡献指南](./CONTRIBUTING.md)。
参与该项目，您同意遵守 [行为准则](./CODE_OF_CONDUCT.md)。
## 安全
如果您发现安全漏洞，请负责任地报告。有关详细信息，请参见 [安全策略](./SECURITY.md)。
## 许可证
该项目根据MIT许可证授权。有关完整文本，请参见 [LICENSE](./LICENSE)。
