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

# 付款

> 从预存余额直接向收款方发送资金

## 什么是付款？

付款是出站付款功能，允许您将 KillB 预存余额中的资金发送给任何收款方——银行账户、加密货币钱包或本地支付别名。这是大规模分发资金最简单的方式：无需报价步骤，无需支付 URL，无需等待最终用户操作。您持有余额；KillB 将其路由到目的地。

<Info>
  付款是 B2B 功能，专为需要向多个收款方发送资金的企业设计（工资发放、供应商付款、平台结算、加密货币分发等）。
</Info>

## 付款 vs. Ramps

付款和 ramps 都能转移资金，但用途不同：

|             | 付款         | Off-Ramps     |
| ----------- | ---------- | ------------- |
| **方向**      | 预存账户 → 收款方 | 加密货币钱包 → 法币账户 |
| **发起方**     | 您的后端       | 您的终端用户        |
| **需要报价？**   | 否          | 是             |
| **支付 URL？** | 否          | 是             |
| **使用场景**    | 批量付款、工资、结算 | 用户提现          |
| **资金来源**    | 预存账户       | 用户的加密货币钱包     |

## 工作原理

```mermaid theme={null}
sequenceDiagram
    participant You as 您的后端
    participant KillB
    participant Bank as 银行 / 钱包

    You->>KillB: POST /api/v2/payouts
    Note over KillB: 扣减预存余额
    KillB-->>You: { id, status: "CREATED" }
    KillB->>Bank: 通过流程路由付款
    Bank-->>KillB: 确认
    KillB-->>You: Webhook: payout.completed
```

## 前提条件

每笔付款需要：

1. **活跃的预存账户** — 持有待发放的余额
2. **足够的余额** — 等于或大于付款金额
3. **有效的收款方信息** — 与所选付款通道要求的字段匹配

<Card title="设置预存账户" icon="vault" href="/zh/guides/pre-fund/pre-fund-accounts">
  了解如何创建和充值预存账户
</Card>

## 付款生命周期

```mermaid theme={null}
graph LR
    CREATED --> CashIn[收款阶段]
    CashIn --> KYTOut[KYT 出账]
    KYTOut --> CashOut[出款阶段]
    CashOut --> COMPLETED

    KYTOut -.-> REVIEW_NEEDED
    REVIEW_NEEDED -.-> REJECTED

    KYTOut -.-> FAILED
    KYTOut -.-> ERROR
    CashOut -.-> FAILED
    CashOut -.-> ERROR
    FAILED --> REFUNDED
    ERROR --> REFUNDED
    REJECTED --> REFUNDED

    CashIn -.->|"终态"| FAILED
    CashIn -.->|"终态"| ERROR

    style COMPLETED fill:#22c55e,color:#fff
    style REJECTED fill:#f97316,color:#fff
    style FAILED fill:#ef4444,color:#fff
    style ERROR fill:#ef4444,color:#fff
    style REFUNDED fill:#6366f1,color:#fff
    style REVIEW_NEEDED fill:#eab308,color:#000
```

<Warning>
  \*\*收款（Cash In）\*\*阶段的 `FAILED` 和 `ERROR` 是终态——未收集到任何资金，不会发起退款。所有后续阶段（KYT 出账、出款）发生这些状态时，将触发退款流程。`REJECTED` 也会触发退款流程，因为它仅在收款阶段之后发生。
</Warning>

### 状态

| 状态                    | 阶段     | 含义                                 |
| --------------------- | ------ | ---------------------------------- |
| `CREATED`             | 初始     | 付款已接收并持久化，等待进入处理队列                 |
| `CASH_IN_PENDING`     | 收款     | 入账资金收集已入队                          |
| `CASH_IN_PROCESSING`  | 收款     | 正在从预存余额收集资金                        |
| `CASH_IN_COMPLETED`   | 收款     | 资金已成功收集                            |
| `KYT_OUT_PENDING`     | KYT 出账 | 出账交易已入队等待合规检查                      |
| `KYT_OUT_PROCESSING`  | KYT 出账 | 出账合规审查进行中                          |
| `KYT_OUT_COMPLETED`   | KYT 出账 | 出账合规检查通过                           |
| `CASH_OUT_PENDING`    | 出款     | 向收款方的付款已入队                         |
| `CASH_OUT_PROCESSING` | 出款     | 资金已提交至支付服务商                        |
| `CASH_OUT_COMPLETED`  | 出款     | 支付服务商已确认交付                         |
| `COMPLETED`           | 终态     | 付款已完全结算                            |
| `REVIEW_NEEDED`       | 审查     | 交易已标记为需要人工合规审查                     |
| `FAILED`              | 错误状态   | 操作失败。收款阶段为终态；后续阶段触发退款流程。           |
| `REJECTED`            | 错误状态   | 付款因合规审查被拦截。始终触发退款流程，因为它仅在收款阶段之后发生。 |
| `ERROR`               | 错误状态   | 内部系统错误。收款阶段为终态；后续阶段触发退款流程。         |
| `REFUND_PENDING`      | 退款     | 退回预存余额的退款已入队                       |
| `REFUND_PROCESSING`   | 退款     | 退款进行中                              |
| `REFUNDED`            | 终态     | 资金已退回预存余额                          |

## 支持的收款方类型

| 类型     | 地区   | 说明                        |
| ------ | ---- | ------------------------- |
| `BANK` | 哥伦比亚 | 通过 Bank Transfer 进行银行账户转账 |
| `BREB` | 哥伦比亚 | 已注册别名（手机号、邮箱、身份证）         |

## 幂等性

为防止网络重试时产生重复付款，每次创建付款请求时请传入唯一的 `Idempotency-Key` 请求头。如果相同的 key 被接收两次，KillB 将返回原始付款而不是创建新记录。

```bash theme={null}
Idempotency-Key: <您的唯一付款参考>
```

## 常见问题

<AccordionGroup>
  <Accordion title="付款失败后我的余额会怎样？" icon="circle-question">
    取决于失败发生在哪个阶段：

    * **收款阶段** — 未收集到任何资金，不会从预存余额中扣款。
    * **收款阶段之后**（KYT 出账、出款）— 资金已收集。付款将转入退款流程（`REFUND_PENDING` → `REFUND_PROCESSING` → `REFUNDED`），资金将退回您的预存余额。
  </Accordion>

  <Accordion title="ERROR、FAILED 和 REJECTED 有什么区别？" icon="circle-question">
    每种状态反映不同的失败来源：

    * **`ERROR`** — KillB 内部系统错误，未进行任何付款。
    * **`FAILED`** — 因发送方提供的收款方账户信息无效或不正确，银行拒绝了转账。
    * **`REJECTED`** — 付款因 KillB 的合规审查被拦截。资金将通过退款流程退回您的预存余额。
  </Accordion>

  <Accordion title="什么是 REVIEW_NEEDED？" icon="circle-question">
    当 KYT（了解您的交易）合规检查标记某笔交易需要人工审查时，付款进入 `REVIEW_NEEDED` 状态。您无需采取任何行动——审查完成后付款将自动恢复，或者在被拦截时转为 `REJECTED`。
  </Accordion>

  <Accordion title="什么时候会出现 REFUNDED 状态？" icon="circle-question">
    当 `FAILED` 或 `ERROR` 发生在收款阶段之后（KYT 出账或出款），或付款被 `REJECTED` 时，付款状态变为 `REFUNDED`。由于资金已收集，付款自动经过 `REFUND_PENDING` → `REFUND_PROCESSING` → `REFUNDED`。

    如果 `FAILED` 或 `ERROR` 发生在收款阶段，未收集到任何资金，不会发起退款。
  </Accordion>

  <Accordion title="付款需要多长时间？" icon="circle-question">
    Bank Transfer 和 BREB 转账通常在几分钟到几个工作小时内结算，具体取决于银行和截止时间。
  </Accordion>

  <Accordion title="幂等性如何工作？" icon="circle-question">
    在付款创建请求中传入唯一的 `Idempotency-Key` 请求头。如果相同的 key 被接收两次（例如重试时），KillB 将返回原始付款而不是创建重复付款。
  </Accordion>
</AccordionGroup>

## 最佳实践

* **先检查余额** — 创建付款前始终调用 `GET /api/v2/customers/balances`，避免因余额不足导致失败
* **使用 `Idempotency-Key`** — 每笔付款始终传入唯一 key，安全重试不产生重复
* **订阅 webhooks** — 配置 `PAYOUT` 事件 webhooks，实时获取状态更新
* **监控 REJECTED 付款** — 拒绝时记录完整收款方数据，以便识别和修正无效账户信息
* **每日对账** — 获取前一天的所有付款，与内部账本核对

## 相关指南

<CardGroup cols={2}>
  <Card title="创建付款" icon="paper-plane" href="/zh/guides/payouts/create-payout">
    分步实现指南
  </Card>

  <Card title="状态跟踪" icon="chart-line" href="/zh/guides/payouts/payout-status">
    通过 webhooks 和轮询监控付款
  </Card>

  <Card title="预存账户" icon="vault" href="/zh/guides/pre-fund/pre-fund-accounts">
    充值预存账户
  </Card>

  <Card title="Webhooks" icon="bell" href="/zh/concepts/webhooks">
    实时事件通知
  </Card>
</CardGroup>