Forgedocs
接口端点

创建收款

概述

PUT /cob/:txid 接口端点创建一个与所提供的交易标识符（txid）关联的即时收款（cob）。此端点遵循巴西中央银行关于 PIX 收款的官方规范。

txid 是由您的系统生成的唯一标识符。必须包含 26 到 35 个字母数字字符。

接口端点

PUT /cob/{txid}

身份认证

stringobrigatorio

通过 /oauth/token 获取的 Bearer 令牌。

示例：Bearer eyJhbGciOiJSUzI1NiIs...

URL 参数

txidstringobrigatorio

交易标识符。必须唯一，包含 26 到 35 个字母数字字符 [a-zA-Z0-9]。

示例：7978c0c97ea847e78e8849634473c1f1

请求体

objectobrigatorio

收款的时间控制信息。

object

付款人（债务人）数据。可以是个人（CPF）或法人实体（CNPJ）。

objectobrigatorio

收款的货币金额。

string

收款方的 PIX 密钥。可以是手机号、邮箱、CPF/CNPJ 或 EVP（随机密钥）。最长 77 个字符。

string

给付款人的自由文本。最长 140 个字符。

array

给付款人的附加信息列表。

请求

curl -X PUT https://api.gateway.goforge.com.br/cob/7978c0c97ea847e78e8849634473c1f1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "calendario": {
      "expiração": 3600
    },
    "devedor": {
      "cpf": "12345678909",
      "nome": "Carlos Oliveira"
    },
    "valor": {
      "original": "123.45",
      "modalidadeAlteração": 0
    },
    "chave": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906",
    "solicitaçãoPagador": "Serviço realizado.",
    "infoAdicionais": [
      {
        "nome": "Pedido",
        "valor": "#12345"
      }
    ]
  }'
const response = await fetch(
  'https://api.gateway.goforge.com.br/cob/7978c0c97ea847e78e8849634473c1f1',
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      calendario: {
        expiração: 3600,
      },
      devedor: {
        cpf: '12345678909',
        nome: 'Carlos Oliveira',
      },
      valor: {
        original: '123.45',
        modalidadeAlteração: 0,
      },
      chave: '7d9f0335-8dcc-4054-9bf9-0dbd61d36906',
      solicitaçãoPagador: 'Serviço realizado.',
      infoAdicionais: [
        { nome: 'Pedido', valor: '#12345' },
      ],
    }),
  }
);

const cobrança = await response.json();
import requests

response = requests.put(
    'https://api.gateway.goforge.com.br/cob/7978c0c97ea847e78e8849634473c1f1',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json',
    },
    json={
        'calendario': {
            'expiração': 3600,
        },
        'devedor': {
            'cpf': '12345678909',
            'nome': 'Carlos Oliveira',
        },
        'valor': {
            'original': '123.45',
            'modalidadeAlteração': 0,
        },
        'chave': '7d9f0335-8dcc-4054-9bf9-0dbd61d36906',
        'solicitaçãoPagador': 'Serviço realizado.',
        'infoAdicionais': [
            {'nome': 'Pedido', 'valor': '#12345'},
        ],
    }
)

cobrança = response.json()

响应

{
  "calendario": {
    "criação": "2024-01-15T10:30:00.358Z",
    "expiração": 3600
  },
  "txid": "7978c0c97ea847e78e8849634473c1f1",
  "revisão": 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",
  "devedor": {
    "cpf": "12345678909",
    "nome": "Carlos Oliveira"
  },
  "valor": {
    "original": "123.45",
    "modalidadeAlteração": 0
  },
  "chave": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906",
  "solicitaçãoPagador": "Serviço realizado.",
  "infoAdicionais": [
    {
      "nome": "Pedido",
      "valor": "#12345"
    }
  ]
}
{
  "statusCode": 400,
  "message": "CPF deve conter exatamente 11 dígitos numéricos",
  "error": "Bad Request"
}
{
  "statusCode": 409,
  "message": "Cobrança com este txid já existe",
  "error": "Conflict"
}

响应字段

calendarioobject

txidstring

请求中提供的交易标识符。

revisãonumber

收款修订号。创建时始终为 0。

locobject

PIX 负载信息。

locationstring

PIX 复制粘贴码（与 loc.location 值相同）。可用于支付的 EMV 格式字符串。

statusstring

收款状态：

  • ATIVA：活跃收款，等待付款
  • CONCLUIDA：已收到付款
  • REMOVIDA_PELO_USUARIO_RECEBEDOR：被收款方取消
  • REMOVIDA_PELO_PSP：被 PSP 移除

收款状态

stateDiagram-v2
    [*] --> ATIVA: Charge created
    ATIVA --> CONCLUIDA: Payment received
    ATIVA --> REMOVIDA_PELO_USUARIO_RECEBEDOR: Cancelled
    ATIVA --> REMOVIDA_PELO_PSP: Expired/Removed
    CONCLUIDA --> [*]
    REMOVIDA_PELO_USUARIO_RECEBEDOR --> [*]
    REMOVIDA_PELO_PSP --> [*]

付款 Webhook

当付款被确认时，您将收到一个类型为 RECEIVE 的 V2 Webhook：

{
  "type": "RECEIVE",
  "data": {
    "id": 123,
    "txId": "7978c0c97ea847e78e8849634473c1f1",
    "status": "LIQUIDATED",
    "payment": {
      "amount": "123.45",
      "currency": "BRL"
    },
    "endToEndId": "E12345678901234567890123456789012",
    "debtorAccount": {
      "name": "Carlos Oliveira",
      "document": "123.xxx.xxx-xx"
    }
  }
}

Webhooks V2

查看完整的 RECEIVE Webhook 文档

常见错误

状态码错误解决方案
400txid 不符合规则使用 26-35 个字母数字字符
400CPF/CNPJ 无效检查格式（仅限数字）
400金额无效使用格式 "123.45"（带 2 位小数的字符串）
401令牌无效续期访问令牌
409txid 已存在使用不同的 txid

后续步骤

申请退款

退还已收到的 PIX

RECEIVE Webhook

处理付款通知

功能激活

如何在您的账户上激活 PIX Bacen 模式和 V2 Webhooks

申请退款

按照 BACEN 规范申请退还已收到的 PIX

本页目录

概述接口端点身份认证URL 参数请求体请求响应响应字段收款状态付款 Webhook常见错误后续步骤