BitFlow Pay — Gateway de Pagamentos PIX

Pesquisar na documentacao

👋 Introdução

Esta documentação cobre somente os endpoints de integração da API PIX da BitFlow Pay.

A autenticação da API pública utiliza JWT OAuth2 (client credentials) e API Key. O token deve ser enviado no header Authorization e a chave pública no header X-API-Key.

🔐 Autenticação

1. Gerar credenciais da API

Acesse o painel BitFlow Pay.
Vá em Integrações > API PIX > Cadastrar API Key.
Guarde os valores de client_id (public key), client_secret (secret key).

O header X-API-Key deve receber o valor do client_id (public key).

2. Obter Token JWT

POST

/auth/oauth2/token

Body da Requisição

POST /auth/oauth2/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "bf_abc123...",
  "client_secret": "bf_xyz789..."
}

Campo	Tipo	Obrigatório	Descrição
`grant_type`	string	Sim	Valor fixo: `client_credentials`
`client_id`	string	Sim	Public key da API
`client_secret`	string	Sim	Secret key da API

Resposta

{
  "access_token": "jwt_aqui",
  "token_type": "Bearer",
  "expires_in": 3600
}

Utilize os headers abaixo nos endpoints da API:

Headers de Autenticação

Authorization: Bearer {access_token}
X-API-Key: {public_key}

💼 Get Balance

Consultar saldo da carteira

GET

/wallet/me

Retorna os saldos da carteira em centavos.

Exemplo de Requisição

GET /wallet/me
Authorization: Bearer {access_token}
X-API-Key: {public_key}

Resposta

{
  "available": 50000,
  "blocked": 10000,
  "reserved": 5000,
  "internalReserve": 0,
  "totalReceived": 100000
}

📥 Pix In (CashIn)

Criar cobrança PIX (API pública)

POST

/cashin/api

Para API pública, o objeto customer é obrigatório.

Campos do corpo

Campo	Tipo	Obrigatório	Descrição
`amountCents`	number	Sim	Valor em centavos
`description`	string	Não	Descrição da cobrança
`customer`	object	Sim (na API)	Dados do pagador (nome, email, cpf, phone; `externaRef` opcional)
`customer.externaRef`	string	Não	Referência no seu sistema; se omitido, usamos o ID do usuário BitFlow
`customer.address`	object	Condicional	Obrigatório se algum item tiver `tangible=true`
`items`	array	Sim	Lista com pelo menos 1 item
`trace`	object	Não	Metadados UTM opcionais
`pix.expiresInDays`	number	Não	Prazo da cobrança em dias (default: 2)
`urlCallBack`	string (URL)	Não	URL do cliente para notificação de status

Exemplo mínimo

POST /cashin/api
Authorization: Bearer {access_token}
X-API-Key: {public_key}
Content-Type: application/json

{
  "amountCents": 10000,
  "customer": {
    "name": "Cliente Teste",
    "email": "[email protected]",
    "cpf": "12345678901",
    "phone": "11999999999"
  },
  "items": [
    {
      "title": "Pagamento",
      "quantity": 1,
      "unitPriceCents": 10000,
      "tangible": false
    }
  ]
}

Exemplo completo

POST /cashin/api
Authorization: Bearer {access_token}
X-API-Key: {public_key}
Content-Type: application/json

{
  "amountCents": 25990,
  "description": "Pedido #9876",
  "customer": {
    "name": "Joao da Silva",
    "email": "[email protected]",
    "cpf": "12345678901",
    "phone": "11988887777",
    "externaRef": "user-ext-42",
    "address": {
      "street": "Rua A",
      "streetNumber": "100",
      "complement": "Apto 101",
      "zipCode": "01001000",
      "neighborhood": "Centro",
      "city": "Sao Paulo",
      "state": "SP",
      "country": "br"
    }
  },
  "trace": {
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "black_friday"
  },
  "pix": {
    "expiresInDays": 3
  },
  "items": [
    {
      "title": "Produto A",
      "quantity": 1,
      "unitPriceCents": 19990,
      "tangible": true
    },
    {
      "title": "Servico B",
      "quantity": 1,
      "unitPriceCents": 6000,
      "tangible": false
    }
  ],
  "urlCallBack": "https://cliente.com/webhooks/bitflow/pix-in"
}

Resposta de sucesso (201)

{
  "id": 1,
  "amountCents": 10000,
  "fee": 0,
  "netAmount": 10000,
  "description": "Pedido #9876",
  "paymentCode": "000201010212...",
  "status": "PENDING",
  "providerTransactionId": "388544133",
  "expiresAt": "2026-03-22T18:30:00.000Z",
  "createdAt": "2026-03-19T18:30:00.000Z"
}

📤 Pix Out (CashOut)

Criar envio PIX (API pública)

POST

/cashout/api

Campos do corpo

Campo	Tipo	Obrigatório	Descrição
`amountCents`	number	Sim	Valor em centavos
`pixKeyType`	enum	Sim	CPF, CNPJ, EMAIL, PHONE ou RANDOM
`pixKey`	string	Sim	Chave Pix de destino
`beneficiaryName`	string	Sim	Nome do beneficiário
`beneficiaryDocument`	string	Condicional	Obrigatório para `EMAIL`, `PHONE` e `RANDOM`. Em `CPF/CNPJ`, o backend usa a própria chave.
`description`	string	Não	Descrição do pagamento
`externalReference`	string	Não	Identificador de idempotência por usuário
`urlCallback`	string (URL)	Não	URL do cliente para receber mudança de status

Exemplo mínimo

POST /cashout/api
Authorization: Bearer {access_token}
X-API-Key: {public_key}
Content-Type: application/json

{
  "amountCents": 10000,
  "pixKeyType": "CPF",
  "pixKey": "12345678901",
  "beneficiaryName": "Cliente Exemplo"
}

Exemplo completo

POST /cashout/api
Authorization: Bearer {access_token}
X-API-Key: {public_key}
Content-Type: application/json

{
  "amountCents": 15350,
  "pixKeyType": "EMAIL",
  "pixKey": "[email protected]",
  "beneficiaryName": "Empresa Favorecida LTDA",
  "beneficiaryDocument": "12345678000190",
  "description": "Repasse pedido #9001",
  "externalReference": "cashout-9001",
  "urlCallback": "https://cliente.com/webhooks/bitflow/pix-out"
}

Resposta de sucesso (201)

{
  "id": 10,
  "amountCents": 10000,
  "fee": 0,
  "netAmount": 10000,
  "pixKey": "12345678901",
  "pixKeyType": "CPF",
  "beneficiaryName": "Cliente Exemplo",
  "beneficiaryDocument": "12345678901",
  "description": "Repasse pedido #9001",
  "status": "PENDING",
  "provider": "hiconex",
  "providerTransactionId": null,
  "externalReference": "cashout-9001",
  "createdAt": "2026-03-19T18:40:00.000Z",
  "updatedAt": "2026-03-19T18:40:00.000Z"
}

🔔 Webhooks (exemplos de payload)

A BitFlow Pay envia notificações para as URLs configuradas em urlCallback dos CashIns e CashOuts. Abaixo estão exemplos de payloads para facilitar sua implementação.

Regra de prioridade (API pública):

1) Se enviar urlCallBack/urlCallback no body, ela será usada.
2) Se não enviar no body, a BitFlow Pay usa a URL fixa cadastrada para o evento.
3) Se não houver nenhuma URL, a API retorna erro de callback obrigatório.

Webhook de Pix In (Pagamento Recebido)

Status	Quando ocorre
`PAID`	Pagamento confirmado e crédito aplicado na carteira.
`EXPIRED`	Cobrança venceu sem pagamento.
`CANCELLED`	Cobrança cancelada.
`MED`	Transação marcada em análise/devolução (MED).
`REFUNDED`	Valor estornado/devolvido após crédito anterior.

Exemplo

POST https://seusistema.com/webhook/pix-in
Content-Type: application/json

{
  "event": "cashin.status_changed",
  "data": {
    "cashInId": 14,
    "status": "PAID",
    "amountCents": 500,
    "fee": 67,
    "netAmount": 433,
    "providerTransactionId": "5eb1ed6df54d0786f47d9ea8213d18",
    "externalReference": "pedido-1234",
    "paymentCode": "000201010212...",
    "e2e": "E339303682026031912161117192f1",
    "urlCallback": "https://cliente.com/webhooks/bitflow/pix-in",
    "paidAt": "2026-03-19T12:16:11.000Z"
  }
}

Webhook de Pix Out (Pagamento Enviado)

Status	Quando ocorre
`COMPLETED`	Pagamento enviado com sucesso.
`FAILED`	Falha no envio (inclui cancelamento/falha no provider).

Exemplo

POST https://seusistema.com/webhook/pix-out
Content-Type: application/json

{
  "event": "cashout.status_changed",
  "data": {
    "cashOutId": 7,
    "status": "COMPLETED",
    "amountCents": 200,
    "fee": 0,
    "netAmount": 200,
    "providerTransactionId": "f6e84056-1bbf-4b59-add1-313bfdf70fd3",
    "pixKey": "03439207196",
    "beneficiaryName": "Lucas Melo",
    "beneficiaryDocument": "03439207196",
    "e2e": "E33930368202603192154341017192f1",
    "processedAt": "2026-03-19T15:54:39.000Z"
  }
}

🤖 Integre com IA

Para acelerar integrações com agentes de IA (Cursor, Claude, etc.), disponibilizamos um contexto técnico único com regras, payloads e comportamento esperado da API.

Baixe o arquivo, copie todo o conteúdo e cole no seu agente de IA junto com o contexto do seu projeto.

DOWNLOAD