Crear Cobro

Visión General

El endpoint PUT /api/cob/:txid crea un cobro inmediato (cob) asociado al identificador de transacción (txid) informado. El payload sigue el formato de la API Pix del Banco Central y la respuesta trae el código PIX copia y pega (EMV) para generar el QR Code.

El txid lo genera su sistema y debe ser único por cuenta. Vuelve en el campo data.txId del webhook RECEIVE, lo que permite conciliar el pago con su pedido.

Endpoint

PUT https://api.fypay.me/api/cob/{txid}

Autenticación

stringobrigatorio

Token Bearer obtenido en POST https://api.fypay.me/api/auth/token. Esta ruta no usa certificado de cliente.

Ejemplo: Bearer eyJhbGciOiJSUzI1NiIs...

Parámetros de URL

txidstringobrigatorio

Identificador de la transacción. Hasta 50 caracteres y único por cuenta. Recomendamos seguir el estándar del Banco Central: de 26 a 35 caracteres alfanuméricos [a-zA-Z0-9].

Repetir un txid ya usado devuelve 400 con el código PIX_DUPLICATE_EXTERNAL_ID.

Ejemplo: 7978c0c97ea847e78e8849634473c1f1

Request Body

object

Información de control de tiempo del cobro. Si se omite, se aplica la expiración por defecto.

objectobrigatorio

Valores monetarios del cobro.

string

Clave PIX del receptor. Máximo 77 caracteres. Se acepta por compatibilidad y se devuelve en la respuesta; el cobro siempre se genera para la cuenta autenticada por el token.

string

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

array

Lista de información adicional del cobro. Hasta 10 ítems, con nome único en cada ítem.

El campo devedor del estándar del Banco Central no se acepta hoy. Enviar devedor con cpf/cnpj y nome hace que la API responda 400 (PUB_REQUEST_BODY_INVALID). No incluya ese campo en el cuerpo.

Request

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": "Servicio 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: 'Servicio realizado.',
      infoAdicionais: [
        { nome: 'Pedido', valor: '#12345' },
      ],
    }),
  }
);

const cobro = 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': 'Servicio realizado.',
        'infoAdicionais': [
            {'nome': 'Pedido', 'valor': '#12345'},
        ],
    }
)

cobro = response.json()

Response

{
  "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": "Servicio 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"
}

Los errores siguen el formato estándar de la API: statusCode, timestamp, path, method, code, message, userMessage, details (opcional) y errorId. Trátelos por el code, no por el texto de message.

Campos de la Respuesta

calendarioobject

txidstring

Identificador de la transacción informado en la URL.

revisaointeger

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

locobject

Información del payload PIX.

locationstring

Código PIX copia y pega (mismo valor de loc.location). A diferencia del estándar del Banco Central, aquí es el propio payload EMV, no una URL.

statusstring

Estado del cobro en el momento de la creación:

ATIVA: cobro creado, esperando el pago (caso normal)
CONCLUIDA: pago ya confirmado
REMOVIDA_PELO_PSP: el cobro falló en el proveedor

valorobject

Los valores enviados en la solicitud.

chavestring

La clave enviada en la solicitud, o string vacío si no se envió.

solicitacaoPagadorstring

El texto enviado en la solicitud, cuando exista.

infoAdicionaisarray

La lista enviada en la solicitud, cuando exista.

No hay endpoint de consulta de cobro en este formato. La confirmación del pago llega por el webhook RECEIVE.

Webhook de Pago

Cuando se confirma el pago, las URLs registradas para el evento cash_in con el formato PIX BACEN reciben un webhook del tipo RECEIVE (fragmento):

{
  "data": {
    "id": 12345,
    "txId": "7978c0c97ea847e78e8849634473c1f1",
    "status": "LIQUIDATED",
    "payment": {
      "amount": "123.45",
      "currency": "BRL"
    },
    "endToEndId": "E12345678202401151030abcdefghijk",
    "debtorAccount": {
      "name": "Carlos Oliveira",
      "document": "12345678909"
    }
  },
  "type": "RECEIVE"
}

Webhook RECEIVE

Vea la documentación completa del webhook RECEIVE

Errores Comunes

Código HTTP	`code`	Causa	Solución
400	`PUB_REQUEST_BODY_INVALID`	Cuerpo inválido (valor fuera de formato, campo desconocido como `devedor`, límite de tamaño)	Revise `details.violations`
400	`PIX_DUPLICATE_EXTERNAL_ID`	`txid` ya usado en esta cuenta	Use un `txid` nuevo
400	`PIX_KEY_NOT_FOUND`	La cuenta no tiene una clave PIX activa para recibir	Registre una clave PIX en la cuenta
400	`PROVIDER_EXPIRATION_BELOW_MINIMUM`	`expiracao` por debajo del mínimo del proveedor	Aumente `calendario.expiracao`
401		Token ausente, inválido o expirado	Genere un nuevo token

Crear Cobro

Visión General

Endpoint

Autenticación

Parámetros de URL

Request Body

Request

Response

Campos de la Respuesta

Webhook de Pago

Webhook RECEIVE

Errores Comunes

Próximos Pasos

Solicitar Devolución

Webhook RECEIVE

En esta página

Crear Cobro

Propiedades

Propiedades

Ítem

Propiedades

Propiedades

Webhook RECEIVE

Solicitar Devolución

Webhook RECEIVE

En esta página