前提条件
创建付款之前，您需要：
- 预存账户 — 通过
POST /api/v2/customers/pre-fund/create 创建
- 足够的余额 — 通过
GET /api/v2/customers/balances 验证
- 收款方详情 — 收款人的银行账户、钱包地址或支付别名
完整付款流程
检查可用余额
在提交付款前确认有足够资金。GET /api/v2/customers/balances
[
{
"id": "balance-id",
"currency": "COP",
"amount": "10000000.00",
"accountId": "prefund-account-id"
}
]
跟踪状态
轮询付款或监听 webhooks，直到达到终态（COMPLETED、ERROR、FAILED、REJECTED 或 REFUNDED）。
实现示例
curl -X POST https://sandbox.killb.app/api/v2/payouts \
-H "Authorization: Bearer 您的TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: payout-2024-001" \
-d '{
"preFundAccountId": "prefund-account-id",
"amount": 500000,
"externalId": "payout-2024-001",
"beneficiary": {
"type": "PSE",
"account": {
"firstName": "Maria",
"lastName": "Garcia",
"email": "[email protected]",
"phone": "3001234567",
"document": { "type": "CC", "number": "12345678" },
"accountNumber": "123456789",
"bankCode": "001",
"type": "savings",
"countryCode": "CO"
}
}
}'
{
"id": "payout-abc123",
"amount": 500000,
"currency": "COP",
"status": "PENDING",
"externalId": "payout-2024-001",
"beneficiary": {
"type": "PSE",
"account": { ... }
},
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z"
}
收款方类型
通过 PSE 系统进行标准哥伦比亚银行账户转账。{
"type": "PSE",
"account": {
"firstName": "Maria",
"lastName": "Garcia",
"email": "[email protected]",
"phone": "3001234567",
"document": {
"type": "CC",
"number": "12345678"
},
"accountNumber": "123456789",
"bankCode": "001",
"type": "savings",
"countryCode": "CO"
}
}
firstName 或 companyName、lastName、email、phone、document、accountNumber、bankCode、type、countryCode使用 GET /api/v2/banks 查询有效的 bankCode 值。 通过已注册的别名（手机号、邮箱、身份证或 BREB 别名）付款。{
"type": "BREB",
"account": {
"firstName": "Carlos",
"lastName": "Lopez",
"email": "[email protected]",
"phone": "3109876543",
"document": {
"type": "CC",
"number": "87654321"
},
"aliasType": "PHONE",
"alias": "3109876543",
"countryCode": "CO"
}
}
NATIONAL_ID、PHONE、EMAIL、ALPHANUMERIC、BUSINESS_ID 付款前检查余额
在发送大额付款之前，始终验证可用余额：
const checkBalance = async (preFundAccountId, requiredAmount) => {
const balances = await fetch('/api/v2/customers/balances', {
headers: { 'Authorization': `Bearer ${token}` }
}).then(r => r.json());
const account = balances.find(b => b.accountId === preFundAccountId);
if (!account || parseFloat(account.amount) < requiredAmount) {
throw new Error(
`余额不足。可用: ${account?.amount ?? 0}，需要: ${requiredAmount}`
);
}
return account;
};
幂等性
为防止网络重试时产生重复付款，每次创建付款请求时请传入唯一的 Idempotency-Key 请求头。如果相同的 key 被接收两次，KillB 将返回原始付款而不是创建新记录。
Idempotency-Key: <您的唯一付款参考>
使用稳定唯一的标识符作为 key——您的内部付款 ID 或与业务交易绑定的 UUID 都是好的选择。
查询付款列表
使用可选筛选条件获取所有付款记录：
const listPayouts = async ({ status, externalId, page = 1, limit = 20 } = {}) => {
const params = new URLSearchParams({ page, limit });
if (status) params.set('status', status);
if (externalId) params.set('externalId', externalId);
const response = await fetch(
`https://sandbox.killb.app/api/v2/payouts?${params}`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
return response.json(); // { payouts: [...], totalPage: N }
};
// 获取所有待处理的付款
const pending = await listPayouts({ status: 'PENDING' });
下一步
配置 Webhooks
配置 PAYOUT webhook 通知
