前提条件
创建付款之前，您需要：- 预存账户 — 通过
POST /api/v2/customers/pre-fund/create创建 - 足够的余额 — 通过
GET /api/v2/customers/balances验证 - 收款方详情 — 收款人的银行账户、钱包地址或支付别名
设置预存账户
还没有预存账户？从这里开始。
完整付款流程
1
检查可用余额
在提交付款前确认有足够资金。
GET /api/v2/customers/balances
响应
[
{
"id": "balance-id",
"currency": "COP",
"amount": "10000000.00",
"accountId": "prefund-account-id"
}
]
2
创建付款
提交包含预存账户、金额和收款方的付款请求。
POST /api/v2/payouts
3
跟踪状态
轮询付款或监听 webhooks，直到达到终态（
COMPLETED、FAILED、REJECTED、ERROR 或 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": "BANK",
"account": {
"firstName": "Maria",
"lastName": "Garcia",
"email": "[email protected]",
"phone": "3001234567",
"document": { "type": "CC", "number": "12345678" },
"accountNumber": "123456789",
"bankCode": "001",
"type": "savings",
"countryCode": "CO"
}
}
}'
const createPayout = async (preFundAccountId, amount, beneficiary) => {
const response = await fetch(
'https://sandbox.killb.app/api/v2/payouts',
{
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
preFundAccountId,
amount,
beneficiary
})
}
);
if (!response.ok) {
const error = await response.json();
throw new Error(`付款失败: ${JSON.stringify(error)}`);
}
return response.json();
};
// 示例：通过 Bank Transfer 发送 500,000 COP
const payout = await createPayout(
'prefund-account-id',
500000,
{
type: 'BANK',
account: {
firstName: 'Maria',
lastName: 'Garcia',
email: '[email protected]',
phone: '3001234567',
document: { type: 'CC', number: '12345678' },
accountNumber: '123456789',
bankCode: '001',
type: 'savings',
countryCode: 'CO'
}
}
);
console.log('付款 ID:', payout.id);
console.log('状态:', payout.status);
import requests
def create_payout(pre_fund_account_id, amount, beneficiary, access_token):
response = requests.post(
'https://sandbox.killb.app/api/v2/payouts',
headers={
'Authorization': f'Bearer {access_token}',
'Content-Type': 'application/json',
'Idempotency-Key': f'payout-{pre_fund_account_id}-{amount}'
},
json={
'preFundAccountId': pre_fund_account_id,
'amount': amount,
'beneficiary': beneficiary
}
)
response.raise_for_status()
return response.json()
# 示例：通过 Bank Transfer 发送 500,000 COP
payout = create_payout(
pre_fund_account_id='prefund-account-id',
amount=500000,
beneficiary={
'type': 'BANK',
'account': {
'firstName': 'Maria',
'lastName': 'Garcia',
'email': '[email protected]',
'phone': '3001234567',
'document': {'type': 'CC', 'number': '12345678'},
'accountNumber': '123456789',
'bankCode': '001',
'type': 'savings',
'countryCode': 'CO'
}
},
access_token=token
)
print(f"付款已创建: {payout['id']} — {payout['status']}")
{
"id": "payout-abc123",
"amount": 500000,
"currency": "COP",
"status": "PENDING",
"externalId": "payout-2024-001",
"beneficiary": {
"type": "BANK",
"account": { ... }
},
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z"
}
收款方类型
- Bank Transfer（哥伦比亚）
- BREB（哥伦比亚）
通过 Bank Transfer 系统进行标准哥伦比亚银行账户转账。必填字段：
{
"type": "BANK",
"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 监控付款
配置 Webhooks
配置 PAYOUT webhook 通知