Pular para o conteúdo principal

​
Visão Geral

Realiza o pagamento de um boleto bancário. O sistema irá:
  1. Validar o código de barras
  2. Bloquear o saldo necessário
  3. Autorizar e executar o pagamento no provedor
  4. Processar confirmação via webhook
Atenção: Este endpoint debita o saldo da conta. Certifique-se de ter saldo suficiente antes de executar.

​
Fluxo de Pagamento

1. Cliente chama POST /withdraw
   ↓
2. Sistema valida saldo disponível
   ↓
3. Autoriza pagamento no provedor
   ↓
4. Bloqueia saldo necessário
   ↓
5. Executa pagamento no provedor
   ↓
6. Retorna ID do pagamento (status: PENDING)
   ↓
7. Webhook confirma (status: PAID ou CANCELED)
Validação de Saldo: O sistema verifica se há saldo disponível ANTES de bloquear e processar o pagamento. O saldo disponível é calculado como: saldo total - saldo bloqueado.

​
Parâmetros da Requisição

​
barcode
string
required
Código de barras ou linha digitável do boleto (apenas números)Formatos aceitos:
  • Código de barras: 44 dígitos
  • Linha digitável: 47 dígitos
Exemplo: 34191091000000150001234567880000012345678901
​
externalId
string
Identificador único da transação em seu sistema (máximo 100 caracteres)Importante: Se fornecido, não é possível criar dois pagamentos com o mesmo externalId para a mesma conta.

​
Resposta de Sucesso

​
id
string
ID único do pagamento (UUID)Use este ID para consultar o status do pagamento posteriormente.

​
Exemplo de Requisição

cURL
curl -X POST https://api-gateway.firebanking.com.br/bank-slip/v1/payment/withdraw \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "barcode": "34191091000000150001234567880000012345678901",
    "externalId": "PAY-2024-001"
  }'
JavaScript
const response = await fetch('https://api-gateway.firebanking.com.br/bank-slip/v1/payment/withdraw', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    barcode: '34191091000000150001234567880000012345678901',
    externalId: 'PAY-2024-001'
  })
});

const data = await response.json();
Python
import requests

response = requests.post(
    'https://api-gateway.firebanking.com.br/bank-slip/v1/payment/withdraw',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
    },
    json={
        'barcode': '34191091000000150001234567880000012345678901',
        'externalId': 'PAY-2024-001'
    }
)

data = response.json()

​
Exemplo de Resposta

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

​
Códigos de Resposta

​
200
success
Pagamento iniciado com sucessoO pagamento está sendo processado. Use o ID retornado para consultar o status.
​
400
error
Requisição inválidaPossíveis causas:
  • Código de barras inválido
  • Boleto já foi pago
  • Saldo insuficiente
  • ExternalId duplicado
​
401
error
API key inválida ou ausente
​
409
error
Conflito - pagamento com mesmo externalId já existe
​
500
error
Erro interno do servidor

​
Erros Comuns

{
  "statusCode": 400,
  "message": "Insufficient balance. Available: R$ 100.00, Required: R$ 150.50",
  "error": "Bad Request"
}
A conta não possui saldo disponível suficiente para o pagamento. A mensagem indica o saldo disponível e o valor necessário.
{
  "statusCode": 409,
  "message": "Payment with externalId PAY-2024-001 already exists",
  "error": "Conflict"
}
Já existe um pagamento com o mesmo externalId para esta conta.
{
  "statusCode": 400,
  "message": "Bank slip has already been paid",
  "error": "Bad Request"
}
O boleto já foi quitado anteriormente (pela Fire Banking ou outro meio).
{
  "statusCode": 400,
  "message": "Invalid barcode format",
  "error": "Bad Request"
}
O código de barras fornecido não possui o formato correto.

​
Gestão de Saldo

O pagamento de boleto segue o seguinte fluxo de saldo:

​
Fluxo Normal (Sucesso)

  1. Validação: Sistema verifica se saldo disponível >= valor total
    • Saldo disponível = saldo total - saldo bloqueado
    • Se insuficiente, retorna erro 400
  2. Bloqueio: Saldo é bloqueado (não disponível para outras operações)
  3. Execução: Pagamento é processado no provedor
  4. Confirmação (webhook billpayment):
    • Saldo bloqueado é desbloqueado
    • Valor é debitado do saldo real
    • Status muda para PAID

​
Fluxo de Erro

Erro Imediato (falha no provedor):
  • Sistema faz rollback automático
  • Saldo bloqueado é devolvido imediatamente
  • Erro retornado ao cliente
Erro via Webhook (billpayment-occurrence):
  • Saldo bloqueado é devolvido
  • Nada é debitado
  • Status muda para CANCELED

​
Webhooks

Após a criação do pagamento, você receberá webhooks para atualização de status:
  • billpayment: Quando o pagamento é confirmado com sucesso
  • billpayment-occurrence: Quando ocorre erro no pagamento
Saiba mais sobre Webhooks de Pagamento

​
Status do Pagamento

Após criar o pagamento, ele passará pelos seguintes status:
StatusDescrição
PENDINGPagamento em processamento no provedor
PAIDPagamento confirmado com sucesso
CANCELEDPagamento falhou ou foi cancelado
REFUND_OCCURRENCEOcorrência de estorno/devolução

​
Próximos Passos

Após criar o pagamento, você pode:
  1. Consultar status em tempo real: Use Consultar Status
  2. Listar pagamentos: Veja o histórico com Listar Pagamentos
  3. Receber webhooks: Configure webhooks para receber atualizações automáticas
Dica: Sempre verifique os dados do boleto com Verificar Dados antes de criar o pagamento, para mostrar o valor atualizado ao usuário final.
Pagamento Parcial: Atualmente não é suportado. O boleto sempre será pago pelo valor total retornado pela autorização.