跳转到主要内容

​
什么是账户？

KillB 中的账户代表 ramp 交易中资金的目的地或来源。账户可以是银行账户、加密货币钱包或托管账户。
用户可以拥有多个不同类型的账户。每个账户都链接到特定用户。

​
账户类型

用于接收本地货币的传统法币银行账户类型：
  • PSE - 哥伦比亚银行账户
  • SPEI - 墨西哥银行账户（CLABE）
  • ACH - 美国银行账户
  • WIRE - 国际电汇
  • TRANSFIYA - 哥伦比亚移动钱包
用例：
  • Off-ramp 目的地（加密货币 → 法币）
  • 接收本地货币
  • 银行提款

​
账户状态

状态描述可以交易？
ACTIVE账户已验证并准备就绪✅ 是
PENDING等待验证❌ 否
REJECTED验证失败❌ 否
INACTIVE由用户/管理员禁用❌ 否

​
创建账户

​
PSE 账户（哥伦比亚）

用于接收 COP 的哥伦比亚银行账户： 
{
  "type": "PSE",
  "userId": "user-id-here",
  "externalId": "account-123",
  "data": {
    "firstName": "Juan",
    "lastName": "García",
    "email": "[email protected]",
    "phone": "+573001234567",
    "accountNumber": "1234567890",
    "bankCode": "0001",
    "type": "savings",
    "countryCode": "CO",
    "document": {
      "type": "NUIP",
      "number": "1234567890",
      "issuedCountryCode": "CO"
    }
  }
}

​
SPEI 账户（墨西哥）

使用 CLABE 的墨西哥银行账户： 
{
  "type": "SPEI",
  "userId": "user-id-here",
  "externalId": "account-456",
  "data": {
    "firstName": "María",
    "lastName": "López",
    "email": "[email protected]",
    "phone": "+525512345678",
    "clabe": "012345678901234567",
    "clabeType": "CLABE",
    "countryCode": "MX",
    "document": {
      "type": "RFC",
      "number": "LOMM900515ABC",
      "issuedCountryCode": "MX"
    }
  }
}
SPEI 支持三种 CLABE 类型：标准 18 位 CLABE、16 位 DEBIT_CARD 或 10 位 PHONE_NUMBER

​
钱包账户

用于接收 USDC/USDT 的加密货币钱包： 
{
  "type": "WALLET",
  "userId": "user-id-here",
  "externalId": "wallet-789",
  "data": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "phone": "+573001234567",
    "currency": "USDC",
    "network": "POLYGON",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "countryCode": "CO",
    "document": {
      "type": "PASSPORT",
      "number": "AB123456",
      "issuedCountryCode": "CO"
    }
  }
}

​
ACH 账户（美国）

用于 USD 的美国银行账户： 
{
  "type": "ACH",
  "userId": "user-id-here",
  "externalId": "ach-001",
  "data": {
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "[email protected]",
    "phone": "+12125551234",
    "bankName": "Chase Bank",
    "routingNumber": "021000021",
    "accountNumber": "123456789",
    "type": "checking",
    "countryCode": "US",
    "document": {
      "type": "SSN",
      "number": "123-45-6789",
      "issuedCountryCode": "US"
    }
  }
}

​
账户验证

KillB 在允许交易之前验证账户：

​
银行账户验证

  • 银行代码存在于支持的银行中
  • 账户号码格式正确
  • 路由号码有效（对于 ACH/Wire）
  • CLABE 是有效的 18 位格式（对于 SPEI）
  • 账户持有人姓名与用户匹配

​
钱包验证

  • 地址对指定网络有效
  • 地址校验和正确（对于 EVM 链）
  • 网络支持该货币
  • 地址不是智能合约（除非允许）

​
查询账户

​
获取所有用户账户

GET /api/v2/accounts/userId/{userId}

​
搜索账户

GET /api/v2/accounts?type=WALLET&userId=user-id
过滤选项：
  • ids - 特定账户 ID
  • userId - 按用户过滤
  • type - 账户类型
  • accountNumber - 银行账户号码
  • address - 钱包地址

​
更新账户

更新账户信息（有限字段）： 
PATCH /api/v2/accounts/{accountId}
可更新字段：
  • 文档信息
  • CLABE 号码（SPEI）
  • 钱包地址
  • 账户号码
  • 银行代码
某些更新可能需要重新验证，并暂时将账户状态设置为 PENDING。

​
删除账户

DELETE /api/v2/accounts/{accountId}
在待处理或处理中的 ramps 中使用的账户无法删除，直到这些交易完成。

​
最佳实践

  • 使用 /api/v2/banks 端点验证银行代码
  • 在客户端检查钱包地址格式
  • 确认用户拥有该账户
  • 首先测试小额交易
  • 为每个账户提供唯一的 externalId
  • 使用您的内部账户标识符
  • 实现轻松账户查找
  • 防止重复账户
  • 允许用户保存多个账户
  • 让用户设置默认/首选账户
  • 支持账户切换
  • 显示账户验证状态
  • 永远不要存储敏感的银行详情
  • 在您的数据库中使用 KillB 账户 ID
  • 实现账户所有权检查
  • 每次使用时验证账户访问

​
下一步

账户管理指南

管理账户的完整指南

银行账户设置

为不同国家配置银行账户

加密货币钱包

设置加密货币钱包账户

预充值账户

了解使用预存流动性的即时执行

API 参考

查看账户 API 文档