Forgedocs
Endpoints

Crear Cobro

Descripción general

El endpoint PUT /cob/:txid crea un cobro inmediato (cob) asociado al identificador de transacción (txid) proporcionado. Este endpoint sigue la especificacion oficial del Banco Central de Brasil para cobros PIX.

El txid es un identificador único generado por su sistema. Debe tener entre 26 y 35 caracteres alfanumericos.

Endpoint

PUT /cob/{txid}

Autenticación

stringobrigatorio

Token Bearer obtenido via /oauth/token.

Ejemplo: Bearer eyJhbGciOiJSUzI1NiIs...

Parámetros de URL

txidstringobrigatorio

Identificador de la transacción. Debe ser único y contener entre 26 y 35 caracteres alfanumericos [a-zA-Z0-9].

Ejemplo: 7978c0c97ea847e78e8849634473c1f1

Cuerpo de la Solicitud

objectobrigatorio

Información de control temporal del cobro.

object

Datos del deudor (pagador). Puede ser una persona fisica (CPF) o juridica (CNPJ).

objectobrigatorio

Valores monetarios del cobro.

string

Clave PIX del receptor. Puede ser número de telefono, correo electrónico, CPF/CNPJ o EVP (clave aleatoria). Máximo 77 caracteres.

string

Texto libre para el pagador. Máximo 140 caracteres.

array

Lista de información adicional para el pagador.

Solicitud

curl -X PUT https://api.gateway.goforge.com.br/cob/7978c0c97ea847e78e8849634473c1f1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "calendario": {
      "expiracao": 3600
    },
    "devedor": {
      "cpf": "12345678909",
      "nome": "Carlos Oliveira"
    },
    "valor": {
      "original": "123.45",
      "modalidadeAlteracao": 0
    },
    "chave": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906",
    "solicitacaoPagador": "Servico 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: {
        expiracao: 3600,
      },
      devedor: {
        cpf: '12345678909',
        nome: 'Carlos Oliveira',
      },
      valor: {
        original: '123.45',
        modalidadeAlteracao: 0,
      },
      chave: '7d9f0335-8dcc-4054-9bf9-0dbd61d36906',
      solicitacaoPagador: 'Servico realizado.',
      infoAdicionais: [
        { nome: 'Pedido', valor: '#12345' },
      ],
    }),
  }
);

const cobranca = 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': {
            'expiracao': 3600,
        },
        'devedor': {
            'cpf': '12345678909',
            'nome': 'Carlos Oliveira',
        },
        'valor': {
            'original': '123.45',
            'modalidadeAlteracao': 0,
        },
        'chave': '7d9f0335-8dcc-4054-9bf9-0dbd61d36906',
        'solicitacaoPagador': 'Servico realizado.',
        'infoAdicionais': [
            {'nome': 'Pedido', 'valor': '#12345'},
        ],
    }
)

cobranca = response.json()

Respuesta

{
  "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",
  "devedor": {
    "cpf": "12345678909",
    "nome": "Carlos Oliveira"
  },
  "valor": {
    "original": "123.45",
    "modalidadeAlteracao": 0
  },
  "chave": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906",
  "solicitacaoPagador": "Servico realizado.",
  "infoAdicionais": [
    {
      "nome": "Pedido",
      "valor": "#12345"
    }
  ]
}
{
  "statusCode": 400,
  "message": "CPF deve conter exatamente 11 digitos numericos",
  "error": "Bad Request"
}
{
  "statusCode": 409,
  "message": "Cobranca com este txid ja existe",
  "error": "Conflict"
}

Campos de Respuesta

calendarioobject

txidstring

Identificador de transacción proporcionado en la solicitud.

revisaonumber

Número de revisión del cobro. Siempre 0 en la creación.

locobject

Información del payload PIX.

locationstring

Código PIX copia y pega (mismo valor que loc.location). Cadena en formato EMV que puede usarse para el pago.

statusstring

Estado del cobro:

  • ATIVA: Cobro activo, esperando pago
  • CONCLUIDA: Pago recibido
  • REMOVIDA_PELO_USUARIO_RECEBEDOR: Cancelado por el receptor
  • REMOVIDA_PELO_PSP: Removido por el PSP

Estado del Cobro

stateDiagram-v2
    [*] --> ATIVA: Cobro creado
    ATIVA --> CONCLUIDA: Pago recibido
    ATIVA --> REMOVIDA_PELO_USUARIO_RECEBEDOR: Cancelado
    ATIVA --> REMOVIDA_PELO_PSP: Expirado/Removido
    CONCLUIDA --> [*]
    REMOVIDA_PELO_USUARIO_RECEBEDOR --> [*]
    REMOVIDA_PELO_PSP --> [*]

Webhook de Pago

Cuando el pago es confirmado, recibira un webhook V2 de tipo RECEIVE:

{
  "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

Vea la documentación completa del webhook RECEIVE

Errores Comunes

CódigoErrorSolución
400txid no coincide con el patronUse entre 26-35 caracteres alfanumericos
400CPF/CNPJ invalidoVerifique el formato (solo números)
400Valor invalidoUse el formato "123.45" (string con 2 decimales)
401Token invalidoRenueve el token de acceso
409txid ya existeUse un txid diferente

Próximos Pasos

Solicitar Devolución

Devolver un PIX recibido

Webhook RECEIVE

Procesar notificaciones de pago

Activación

Como activar el modo PIX Bacen y los Webhooks V2 en su cuenta

Solicitar Devolución

Solicitar la devolución de un PIX recibido siguiendo la especificacion del BACEN

En esta página

Descripción generalEndpointAutenticaciónParámetros de URLCuerpo de la SolicitudSolicitudRespuestaCampos de RespuestaEstado del CobroWebhook de PagoErrores ComunesPróximos Pasos