创建收款
概述
PUT /api/cob/:txid 端点创建一笔与所提供的交易标识符（txid）关联的即时收款（cob）。请求体遵循巴西央行 Pix API 的格式，响应中包含用于生成二维码的 PIX 复制粘贴码（EMV）。
txid 由您的系统生成，且必须在账户内唯一。它会在 RECEIVE Webhook 的 data.txId 字段中返回，便于您将付款与订单对账。
端点
PUT https://api.fypay.me/api/cob/{txid}认证
通过 POST https://api.fypay.me/api/auth/token 获取的 Bearer 令牌。此路由不使用客户端证书。
示例：Bearer eyJhbGciOiJSUzI1NiIs...
URL 参数
txidstringobrigatorio交易标识符。最多 50 个字符，且在账户内唯一。建议遵循巴西央行标准：26 到 35 个字母数字字符 [a-zA-Z0-9]。
重复使用已用过的 txid 会返回 400，错误码为 PIX_DUPLICATE_EXTERNAL_ID。
示例：7978c0c97ea847e78e8849634473c1f1
请求体
收款的时间控制信息。省略时使用默认过期时间。
收款金额信息。
收款方的 PIX 密钥。最多 77 个字符。为兼容而接受并在响应中返回；收款始终为令牌所认证的账户生成。
给付款人的自由文本。最多 140 个字符。
收款的附加信息列表。最多 10 项，每项的 nome 必须唯一。
巴西央行标准中的 devedor 字段目前不被接受。发送包含 cpf/cnpj 和 nome 的 devedor 会使 API 返回 400（PUB_REQUEST_BODY_INVALID）。请不要在请求体中包含该字段。
请求
curl -X PUT https://api.fypay.me/api/cob/7978c0c97ea847e78e8849634473c1f1 \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"calendario": {
"expiracao": 3600
},
"valor": {
"original": "123.45"
},
"solicitacaoPagador": "Serviço realizado.",
"infoAdicionais": [
{
"nome": "Pedido",
"valor": "#12345"
}
]
}'const response = await fetch(
'https://api.fypay.me/api/cob/7978c0c97ea847e78e8849634473c1f1',
{
method: 'PUT',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
calendario: {
expiracao: 3600,
},
valor: {
original: '123.45',
},
solicitacaoPagador: 'Serviço realizado.',
infoAdicionais: [
{ nome: 'Pedido', valor: '#12345' },
],
}),
}
);
const cobranca = await response.json();import requests
response = requests.put(
'https://api.fypay.me/api/cob/7978c0c97ea847e78e8849634473c1f1',
headers={
'Authorization': f'Bearer {token}',
'Content-Type': 'application/json',
},
json={
'calendario': {
'expiracao': 3600,
},
'valor': {
'original': '123.45',
},
'solicitacaoPagador': 'Serviço realizado.',
'infoAdicionais': [
{'nome': 'Pedido', 'valor': '#12345'},
],
}
)
cobranca = response.json()响应
{
"calendario": {
"criacao": "2024-01-15T10:30:00.358Z",
"expiracao": 3600
},
"txid": "7978c0c97ea847e78e8849634473c1f1",
"revisao": 0,
"loc": {
"id": 12345,
"location": "00020126580014br.gov.bcb.pix0136a629532e-7693-4846-852d-1bbff817b5a8520400005303986540512.345802BR5916Tech Solutions Ltda6009Sao Paulo62070503***6304ABCD",
"tipoCob": "cob"
},
"location": "00020126580014br.gov.bcb.pix0136a629532e-7693-4846-852d-1bbff817b5a8520400005303986540512.345802BR5916Tech Solutions Ltda6009Sao Paulo62070503***6304ABCD",
"status": "ATIVA",
"valor": {
"original": "123.45"
},
"chave": "",
"solicitacaoPagador": "Serviço realizado.",
"infoAdicionais": [
{
"nome": "Pedido",
"valor": "#12345"
}
]
}{
"statusCode": 400,
"timestamp": "2024-01-15T10:30:00.000Z",
"path": "/api/cob/7978c0c97ea847e78e8849634473c1f1",
"method": "PUT",
"code": "PUB_REQUEST_BODY_INVALID",
"message": "Request body validation failed: valor: invalid",
"userMessage": "Request body is invalid.",
"details": {
"violations": {
"valor": "invalid"
}
},
"errorId": "c0a8012e-7b1f-4c55-9d1e-2f9a8c3b4d5e"
}{
"statusCode": 400,
"code": "PIX_DUPLICATE_EXTERNAL_ID",
"userMessage": "Esta transação já existe no sistema.",
"details": {
"externalId": "7978c0c97ea847e78e8849634473c1f1",
"existingTransactionId": 12345
},
"errorId": "c0a8012e-7b1f-4c55-9d1e-2f9a8c3b4d5e"
}错误遵循 API 的标准格式：statusCode、timestamp、path、method、code、message、userMessage、details（可选）和 errorId。请根据 code 处理，而不是 message 的文本。
响应字段
calendarioobjecttxidstringURL 中提供的交易标识符。
revisaointeger收款的修订号。始终为 0。
locobjectPIX 载荷信息。
locationstringPIX 复制粘贴码（与 loc.location 相同）。与巴西央行标准不同，这里是 EMV 载荷本身，而不是 URL。
statusstring创建时的收款状态：
ATIVA：收款已创建，等待付款（正常情况）CONCLUIDA：付款已确认REMOVIDA_PELO_PSP：收款在提供商处失败
valorobject请求中发送的金额信息。
chavestring请求中发送的密钥；未发送时为空字符串。
solicitacaoPagadorstring请求中发送的文本（如有）。
infoAdicionaisarray请求中发送的列表（如有）。
此格式下没有查询收款的端点。付款确认通过 RECEIVE Webhook 送达。
付款 Webhook
付款确认后，在 cash_in 事件下以 PIX BACEN 格式登记的 URL 会收到 RECEIVE 类型的 Webhook（节选）：
{
"data": {
"id": 12345,
"txId": "7978c0c97ea847e78e8849634473c1f1",
"status": "LIQUIDATED",
"payment": {
"amount": "123.45",
"currency": "BRL"
},
"endToEndId": "E12345678202401151030abcdefghijk",
"debtorAccount": {
"name": "Carlos Oliveira",
"document": "12345678909"
}
},
"type": "RECEIVE"
}RECEIVE Webhook
查看 RECEIVE Webhook 的完整文档
常见错误
| HTTP 状态码 | code | 原因 | 解决方法 |
|---|---|---|---|
| 400 | PUB_REQUEST_BODY_INVALID | 请求体无效（金额格式错误、出现 devedor 等未知字段、超出长度限制） | 查看 details.violations |
| 400 | PIX_DUPLICATE_EXTERNAL_ID | 该账户已使用过此 txid | 使用新的 txid |
| 400 | PIX_KEY_NOT_FOUND | 账户没有可用于收款的有效 PIX 密钥 | 为账户登记 PIX 密钥 |
| 400 | PROVIDER_EXPIRATION_BELOW_MINIMUM | expiracao 低于提供商的最小值 | 增大 calendario.expiracao |
| 401 | 令牌缺失、无效或已过期 | 生成新令牌 |