Criar Cobrança

Visão Geral

O endpoint PUT /api/cob/:txid cria uma cobrança imediata (cob) associada ao identificador de transação (txid) informado. O payload segue o formato da API Pix do Banco Central e a resposta traz o código PIX copia-e-cola (EMV) para gerar o QR Code.

O txid é gerado pelo seu sistema e precisa ser único por conta. Ele volta no campo data.txId do webhook RECEIVE, o que permite conciliar o pagamento com o seu pedido.

Endpoint

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

Autenticação

stringobrigatorio

Token Bearer obtido em POST https://api.fypay.me/api/auth/token. Esta rota não usa certificado de cliente.

Exemplo: Bearer eyJhbGciOiJSUzI1NiIs...

Parâmetros de URL

txidstringobrigatorio

Identificador da transação. Até 50 caracteres e único por conta. Recomendamos seguir o padrão do Banco Central: de 26 a 35 caracteres alfanuméricos [a-zA-Z0-9].

Repetir um txid já usado retorna 400 com o código PIX_DUPLICATE_EXTERNAL_ID.

Exemplo: 7978c0c97ea847e78e8849634473c1f1

Request Body

object

Informações de controle de tempo da cobrança. Se omitido, vale a expiração padrão.

objectobrigatorio

Valores monetários da cobrança.

string

Chave PIX do recebedor. Máximo 77 caracteres. Aceito por compatibilidade e devolvido na resposta; a cobrança é sempre gerada para a conta autenticada pelo token.

string

Texto livre para o pagador. Máximo 140 caracteres.

array

Lista de informações adicionais da cobrança. Até 10 itens, com nome único em cada item.

O campo devedor do padrão do Banco Central não é aceito hoje. Enviar devedor com cpf/cnpj e nome faz a API responder 400 (PUB_REQUEST_BODY_INVALID). Não inclua esse campo no corpo.

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": "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()

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

Os erros seguem o formato padrão da API: statusCode, timestamp, path, method, code, message, userMessage, details (opcional) e errorId. Trate pelo code, não pelo texto de message.

Campos da Resposta

calendarioobject

txidstring

Identificador da transação informado na URL.

revisaointeger

Número da revisão da cobrança. Sempre 0.

locobject

Informações do payload PIX.

locationstring

Código PIX copia-e-cola (mesmo valor de loc.location). Diferente do padrão do Banco Central, aqui é o próprio payload EMV, não uma URL.

statusstring

Status da cobrança no momento da criação:

ATIVA: cobrança criada, aguardando pagamento (caso normal)
CONCLUIDA: pagamento já confirmado
REMOVIDA_PELO_PSP: a cobrança falhou no provedor

valorobject

Os valores enviados na requisição.

chavestring

A chave enviada na requisição, ou string vazia se não foi enviada.

solicitacaoPagadorstring

O texto enviado na requisição, quando houver.

infoAdicionaisarray

A lista enviada na requisição, quando houver.

Não há endpoint de consulta de cobrança neste formato. A confirmação do pagamento chega pelo webhook RECEIVE.

Webhook de Pagamento

Quando o pagamento for confirmado, as URLs cadastradas para o evento cash_in com o formato PIX BACEN recebem um webhook do tipo RECEIVE (trecho):

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

Veja a documentação completa do webhook RECEIVE

Erros Comuns

Código HTTP	`code`	Causa	Solução
400	`PUB_REQUEST_BODY_INVALID`	Corpo inválido (valor fora do formato, campo desconhecido como `devedor`, limite de tamanho)	Confira `details.violations`
400	`PIX_DUPLICATE_EXTERNAL_ID`	`txid` já usado nesta conta	Use um `txid` novo
400	`PIX_KEY_NOT_FOUND`	A conta não possui chave PIX ativa para receber	Cadastre uma chave PIX na conta
400	`PROVIDER_EXPIRATION_BELOW_MINIMUM`	`expiracao` abaixo do mínimo do provedor	Aumente `calendario.expiracao`
401		Token ausente, inválido ou expirado	Gere um novo token

Criar Cobrança

Visão Geral

Endpoint

Autenticação

Parâmetros de URL

Request Body

Request

Response

Campos da Resposta

Webhook de Pagamento

Webhook RECEIVE

Erros Comuns

Próximos Passos

Solicitar Devolução

Webhook RECEIVE

Nesta página

Criar Cobrança

Propriedades

Propriedades

Item

Propriedades

Propriedades

Webhook RECEIVE

Solicitar Devolução

Webhook RECEIVE

Nesta página