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

# 打款 Webhooks

> 当打款创建或状态发生变化时，发送到您的 webhook endpoint 的 payload。使用这些事件在您的会计系统中对账。

> [!NOTE]
>
> 打款 webhook 会在您自己的资金从 Dodo Payments 转入您的银行账户时通知您。使用它们在您的会计系统中对账打款，无需轮询 [List Payouts](https://docs.dodopayments.com/api-reference/payouts/get-payouts.md) endpoint。

## 打款 Webhook 事件

打款会在其生命周期的每个阶段触发一个事件。这些阶段与您的 dashboard 中显示的 [打款状态](https://docs.dodopayments.com/features/payouts/payout-structure.md)一致。

| 事件 | 触发时机 | 通常含义 |
| - | - | - |
| `payout.created` | 通过自动打款周期或非周期流程创建打款时 | 打款已存在，但尚未开始转移 |
| `payout.in_progress` | 打款到期日到达且处理开始时 | 资金正在转入您的银行账户 |
| `payout.on_hold` | 打款暂停或进入审核时 | 您可能需要提供其他信息 |
| `payout.success` | 转入您银行账户的打款完成结算时 | 资金应已可在您的账户中使用 |
| `payout.failed` | 打款失败时 | 金额和费用会退回您的 wallet |

> [!NOTE]
>
> `payout.created` 之前以 `payout.not_initiated` 的形式发送。如果现有 endpoint 按 `payout.not_initiated` 进行过滤，请将过滤条件更新为 `payout.created`，以便继续匹配。此阶段，payload 上的 `status` 字段仍会报告 `not_initiated`。

## 处理打款事件

打款涉及的是您自己的资金，而不是客户的资金，因此这些事件通常用于记账和内部告警，而不是面向客户的流程。

```javascript Handling payout events expandable theme={null}
app.post('/webhooks/dodo', async (req, res) => {
  // Verify the signature first. See /developer-resources/webhooks#verifying-signatures.
  // With express.raw(), req.body is a Buffer, so parse it after verification.
  const event = JSON.parse(req.body);

  switch (event.type) {
    case 'payout.created': {
      const payout = event.data;
      // Record the expected payout so finance can reconcile it later
      await recordPayout(payout.payout_id, payout.amount, payout.currency);
      break;
    }
    case 'payout.success': {
      // Funds settled — mark the payout as received
      await markPayoutSettled(event.data.payout_id, event.data.updated_at);
      break;
    }
    case 'payout.failed': {
      // Funds and fees are credited back to your wallet — alert finance
      await alertPayoutFailed(event.data.payout_id, event.data.remarks);
      break;
    }
    case 'payout.on_hold': {
      // Review may be required before the payout can continue
      await alertPayoutOnHold(event.data.payout_id, event.data.remarks);
      break;
    }
  }

  res.json({ received: true });
});
```

> [!TIP]
>
> 在处理之前，务必验证 webhook 签名 — 有关设置，请参阅 [Webhooks guide](https://docs.dodopayments.com/developer-resources/webhooks.md)。为简洁起见，上面的处理程序省略了验证步骤。

> [!WARNING]
>
> 打款事件既不是终态事件，也不严格按顺序排列。当银行退回转账时，`payout.failed` 可能会在 `payout.success` 之后到达；而当失败的打款随后恢复时，`payout.success` 也可能会在 `payout.failed` 之后到达。payload 中的 `status` 始终与事件类型匹配，即使事件延迟交付也是如此。因此，请将每个事件顶层的 `timestamp` 与您为该笔打款处理的上一个值进行比较，而不要假定最后收到的事件就是最终事件。

## 打款状态

打款对象通过单个字段报告其进度：

| 字段 | 值 |
| - | - |
| `status` | `not_initiated`、`in_progress`、`on_hold`、`success`、`failed` |

> [!NOTE]
>
> payload 上的 `refunds`、`chargebacks` 和 `tax` 已弃用。请改用 [打款拆分 endpoint](https://docs.dodopayments.com/api-reference/payouts/retrieve-breakup.md) 获取详细明细。

## 相关内容

> **[Payout Structure](https://docs.dodopayments.com/features/payouts/payout-structure.md)**
>
> 打款如何安排和计算，以及每种打款状态的含义。

> **[Balances & Wallets](https://docs.dodopayments.com/features/account-summary-payout-wallet.md)**
>
> 跟踪 wallet 余额以及每笔打款背后的 ledger。

## Webhook Payload Schema


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.