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` / `tracking`	object	Não	Parâmetros de rastreamento (UTM, src, sck). Aceita `tracking` (preferencial), `trace` ou campos soltos no body. Usado em integrações como Utmify.
`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
`split`	array	Não	Divisão de receita entre parceiros (até 3). Ver Split CashIn

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"
  },
  "tracking": {
    "utm_source": "facebook",
    "utm_medium": "cpc",
    "utm_campaign": "campanha01",
    "utm_content": "criativo03",
    "utm_term": "publico01",
    "src": "fb",
    "sck": "abc123"
  },
  "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"
}

Parâmetros de rastreamento

Todos os campos abaixo são opcionais. Payloads antigos sem tracking continuam funcionando. Os dados são salvos na transação e repassados a integrações externas (ex.: Utmify), quando configuradas na conta.

Campo	Descrição
`tracking.utm_source` / `trace.utm_source`	Origem (ex.: facebook, google)
`tracking.utm_medium`	Meio (ex.: cpc, email)
`tracking.utm_campaign`	Nome da campanha
`tracking.utm_content`	Criativo / variação
`tracking.utm_term`	Palavra-chave ou público
`tracking.src`	Fonte customizada
`tracking.sck`	Chave de rastreamento (tracker / checkout)

No link de pagamento, adicione os parâmetros na URL (o slug do produto não é tracking): /l/seu-slug?utm_source=facebook&utm_campaign=campanha01&src=fb&sck=abc123. O checkout captura automaticamente; o comprador não preenche UTMs.

Split de receita (CashIn)

O split reparte o valor bruto de uma cobrança PIX entre você (dono da cobrança — conta que autenticou na API) e até 3 parceiros cadastrados na BitFlow. A divisão é definida por percentuais no momento da criação; os créditos na carteira de cada beneficiário ocorrem quando o pagamento é confirmado (PAID).

Como definir o split

Forma	Quando usar
`split` no body do `POST /cashin/api`	Regra por cobrança (marketplace, afiliado, coprodutor). Tem prioridade sobre qualquer preset do painel.
Preset global (painel)	Em Integrações → Split CashIn, configure destinatários fixos. Se você não enviar `split` na API, o preset ativo é aplicado automaticamente em cada nova cobrança.

Conflito preset × payload: se existir preset ativo e você enviar split na mesma requisição, a API responde 409 Conflict. Desative o preset no painel ou remova o array split do body.

Campos de cada item em split

Campo	Tipo	Descrição
`userId`	number (inteiro)	ID do usuário BitFlow do parceiro. Não pode ser o dono da cobrança nem repetir outro item do array.
`percentage`	number	Percentual da cobrança (máx. 2 casas decimais, ex.: `12.5` = 12,5%). A soma de todos os itens deve ser menor que 100%; o restante fica com o dono.

Regras de validação

De 1 a 3 destinatários no array (além do dono, que não entra no array).
Cada parceiro precisa estar ACTIVE, com KYC APPROVED e e-mail verificado na BitFlow.
A taxa CashIn é cobrada apenas do dono da cobrança, com a taxa configurada na conta dele, sobre o valor integral da transação. Os parceiros do split recebem a fatia bruta sem desconto de taxa.
Os campos fee e netAmount na resposta de criação e no webhook de PAID referem-se ao dono da cobrança, não ao valor total repartido.
Centavos de arredondamento: cada fatia usa floor quando o percentual não fecha em centavo exato. A diferença (poucos centavos no total) é registrada em houseRemainderCents na resposta — não é creditada a parceiros nem ao dono.
Em MED/estorno após PAID, os débitos de reversão consideram todos os beneficiários que receberam crédito no split.

Exemplo com split (R$ 100,00 — 20% parceiro A, 10% parceiro B)

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": "Produto com parceiros",
      "quantity": 1,
      "unitPriceCents": 10000,
      "tangible": false
    }
  ],
  "split": [
    { "userId": 42, "percentage": 20 },
    { "userId": 57, "percentage": 10 }
  ]
}

Resposta 201 com split (trecho)

{
  "id": 99,
  "amountCents": 10000,
  "fee": 300,
  "netAmount": 6700,
  "status": "PENDING",
  "hasSplit": true,
  "houseRemainderCents": 0,
  "split": [
    {
      "userId": 42,
      "role": "RECIPIENT",
      "percentageBps": 2000,
      "grossAmountCents": 2000,
      "feeCents": 0,
      "netAmountCents": 2000
    },
    {
      "userId": 57,
      "role": "RECIPIENT",
      "percentageBps": 1000,
      "grossAmountCents": 1000,
      "feeCents": 0,
      "netAmountCents": 1000
    },
    {
      "userId": 1,
      "role": "OWNER",
      "percentageBps": 7000,
      "grossAmountCents": 7000,
      "feeCents": 300,
      "netAmountCents": 6700
    }
  ]
}

percentageBps usa base 10.000 (= 100,00%). Ex.: 2000 = 20%. O item com role: "OWNER" é o dono da cobrança. Valores em grossAmountCents, feeCents e netAmountCents são o plano calculado na criação; na liquidação (PAID), as carteiras são creditadas conforme esse snapshot.

Para consultar o split após a criação (incluindo data de liquidação), use GET /cashin/:id com o mesmo token JWT — o objeto split traz source (PAYLOAD ou PRESET), appliedAt e allocations com percentuais legíveis.

Erros frequentes

HTTP	Mensagem (resumo)	Causa usual
400	Soma dos percentuais deve ser menor que 100%	Percentuais somam 100% ou mais; o dono precisa de fatia > 0.
400	Destinatário inexistente ou com cadastro incompleto	Parceiro sem KYC, inativo ou e-mail não verificado.
400	Dono da cobrança não pode aparecer no array split	`userId` igual ao dono incluído em `split`.
409	Split no payload conflita com preset global ativo	Preset ligado no painel e `split` enviado na mesma requisição.

📤 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 (com split, cada beneficiário recebe sua fatia líquida).
`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"
  }
}

Em cobranças com split, fee e netAmount no webhook são do dono da cobrança. O detalhamento por parceiro está na resposta do POST /cashin/api (quando hasSplit: true) e em GET /cashin/:id.

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