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

# 子账户事件

> 与子账户状态变更相关的实时通知。

Webhook 允许您的应用程序在 Bullring 账户中发生事件时接收实时通知。我们会向您配置的 URL 发送 HTTP POST 请求，而无需轮询 API。

### 子账户已创建

```json theme={null}
{
  "event": "subaccount.status.created",
  "data": {
    "id": "7625a677-44e1-4b96-b0d0-ba86af1b93cc",
    "email": "user@example.com",
    "status": "created"
  }
}
```

### 子账户审核中

```json theme={null}
{
  "event": "subaccount.status.review",
  "data": {
    "id": "7625a677-44e1-4b96-b0d0-ba86af1b93cc",
    "email": "user@example.com",
    "status": "review"
  }
}
```

### 子账户已批准

当子账户获得批准时，webhook 包含一个详细的 `capabilities` 对象，显示解锁了哪些货币、支付渠道和加密资产。

<CodeGroup>
  ```json 初始批准（基础验证） theme={null}
  {
    "event": "subaccount.status.approved",
    "data": {
      "id": "b6fe2299-ffaf-4468-bffe-415e22038921",
      "email": "contact@acmetech.com",
      "status": "approved",
      "capabilities": {
        "kyc": {
          "profiles": [
            {
              "country": "NG",
              "status": "approved"
            },
            {
              "country": "GH",
              "status": "approved"
            },
            {
              "country": "ZM",
              "status": "approved"
            }
          ]
        },
        "capabilities": {
          "currencies": {
            "NGN": {
              "status": "approved",
              "canOnramp": true,
              "canOfframp": true,
              "canDeposit": true,
              "canWithdraw": true,
              "rails": {
                "banktransfer": true
              }
            },
            "GHS": {
              "status": "approved",
              "canOnramp": true,
              "canOfframp": true,
              "canDeposit": true,
              "canWithdraw": true,
              "rails": {
                "momo": true
              }
            },
            "ZMW": {
              "status": "approved",
              "canOnramp": true,
              "canOfframp": true,
              "canDeposit": true,
              "canWithdraw": true,
              "rails": {
                "momo": true
              }
            },
            "USD": {
              "status": "locked",
              "canOnramp": false,
              "canOfframp": false,
              "canDeposit": false,
              "canWithdraw": false,
              "requiredKyc": "Additional Verification required for USD operations",
              "rails": {
                "wire": false,
                "ach": false,
                "swift": false
              }
            }
          },
          "assets": {
            "USDT": {
              "networks": ["ETH-SEPOLIA", "SOL-DEVNET", "CELO-SEPOLIA"]
            },
            "USDC": {
              "networks": ["ETH-SEPOLIA", "SOL-DEVNET", "CELO-SEPOLIA", "POLY-AMOY"]
            },
            "EURC": {
              "networks": ["ETH-SEPOLIA", "SOL-DEVNET", "CELO-SEPOLIA"]
            },
            "BTC": {
              "networks": ["LIGHTNING"]
            }
          }
        }
      }
    }
  }
  ```

  ```json 增强批准（额外验证） theme={null}
  {
    "event": "subaccount.status.approved",
    "data": {
      "id": "ac5ee406-3d18-4dd7-9e68-f3e06c6f906a",
      "email": "customer@example.com",
      "status": "approved",
      "capabilities": {
        "kyc": {
          "profiles": [
            {
              "country": "US",
              "status": "approved"
            },
            {
              "country": "EU",
              "status": "approved"
            },
            {
              "country": "GH",
              "status": "approved"
            },
            {
              "country": "ZM",
              "status": "approved"
            }
          ]
        },
        "capabilities": {
          "currencies": {
            "USD": {
              "status": "partial",
              "canOnramp": false,
              "canOfframp": true,
              "canDeposit": true,
              "canWithdraw": true,
              "rails": {
                "wire": true,
                "ach": false,
                "swift": false
              }
            },
            "EUR": {
              "status": "partial",
              "canOnramp": false,
              "canOfframp": true,
              "canDeposit": true,
              "canWithdraw": true,
              "rails": {
                "sepa": true
              }
            },
            "GHS": {
              "status": "approved",
              "canOnramp": true,
              "canOfframp": true,
              "canDeposit": true,
              "canWithdraw": true,
              "rails": {
                "momo": true
              }
            },
            "ZMW": {
              "status": "approved",
              "canOnramp": true,
              "canOfframp": true,
              "canDeposit": true,
              "canWithdraw": true,
              "rails": {
                "momo": true
              }
            },
            "NGN": {
              "status": "locked",
              "canOnramp": false,
              "canOfframp": false,
              "canDeposit": false,
              "canWithdraw": false,
              "requiredKyc": "Additional Verification required for NGN operations",
              "rails": {
                "banktransfer": false
              }
            }
          },
          "assets": {
            "USDT": {
              "networks": ["ETH-SEPOLIA", "SOL-DEVNET", "CELO-SEPOLIA"]
            },
            "USDC": {
              "networks": ["ETH-SEPOLIA", "SOL-DEVNET", "CELO-SEPOLIA", "POLY-AMOY"]
            },
            "EURC": {
              "networks": ["ETH-SEPOLIA", "SOL-DEVNET", "CELO-SEPOLIA"]
            },
            "BTC": {
              "networks": ["LIGHTNING"]
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**货币状态值：**

* **`approved`**：完全访问 - 所有操作已启用
* **`locked`**：无访问权限 - 需要额外验证
* **`partial`**：有限访问 - 某些操作/渠道已启用

### 子账户已拒绝

当子账户申请被拒绝时，payload 将包含 `failure_reason`（拒绝原因）以及一个布尔值 `can_resubmit`，表示是否允许用户重新提交。

<CodeGroup>
  ```json 可以重新提交 theme={null}
  {
    "event": "subaccount.status.declined",
    "data": {
      "id": "7ae50606-4422-4b8d-8604-543686e4472d",
      "email": "user@example.com",
      "status": "declined",
      "failure_reason": "BAD_PROOF_OF_ADDRESS",
      "can_resubmit": true
    }
  }
  ```

  ```json 不可重新提交 theme={null}
  {
    "event": "subaccount.status.declined",
    "data": {
      "id": "7ae50606-4422-4b8d-8604-543686e4472d",
      "email": "user@example.com",
      "status": "declined",
      "failure_reason": "FORGERY",
      "can_resubmit": false
    }
  }
  ```
</CodeGroup>