Transferência via Chave PIX

Visão Geral

Realize transferências PIX (cash out) enviando valores da sua conta FireBanking para chaves PIX conhecidas (CPF, CNPJ, email, telefone ou chave aleatória). As transferências são processadas instantaneamente e funcionam 24/7.

Para pagamentos via QR Code dinâmico ou código Copia e Cola, utilize o endpoint /payment/withdraw/qrcode.

Certifique-se de ter saldo suficiente na sua conta antes de realizar a transferência.

Exemplo de Requisição

curl -X POST "https://api-gateway.firebanking.com.br/pix/v2/payment/withdraw" \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "PIX",
    "value": 15,
    "details": {
      "key": "12312312387",
      "keyType": "DOCUMENT",
      "name": "John Marvin",
      "document": "12312312387"
    },
    "externalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }'

Exemplo de Resposta

{
  "transactionId": "75906707-8c31-479c-b354-aa805c4cefbc",
  "status": "WAITING_CONFIRMATION"
}

Campos de Resposta

transactionId

string

ID único da transferência no FireBanking

status

string

Status da transferência:

WAITING_CONFIRMATION - Aguardando confirmação/processamento
WITHDRAW_PAID - Transferência realizada com sucesso
ERROR - Erro no processamento

Fluxo de Processamento

1. Validação Inicial

Verificação de saldo disponível
Validação da chave PIX do beneficiário
Confirmação dos dados do beneficiário

2. Processamento

Débito do valor na sua conta
Envio da transferência PIX
Confirmação pelo Sistema de Pagamentos Instantâneos (SPI)

3. Confirmação

Webhook enviado com status final
Valor disponível na conta do beneficiário
Comprovante gerado

Estados da Transferência

WAITING_CONFIRMATION

Descrição: Transferência criada, aguardando processamento
Duração típica: Alguns segundos
Ação: Sistema está validando e processando
Próximo status: WITHDRAW_PAID ou ERROR

WITHDRAW_PAID

Descrição: Transferência realizada com sucesso
Valor: Debitado da sua conta e creditado no destino
Dados extras: Informações do banco beneficiário
Status final: Transferência concluída

ERROR

Descrição: Erro no processamento da transferência
Possíveis causas: Chave inválida, saldo insuficiente, dados incorretos
Valor: Não foi debitado (ou estornado automaticamente)
Ação: Verificar erro e tentar novamente

Validações e Limites

Limites Operacionais

Valor mínimo: R$ 0,01
Valor máximo diurno: R$ 20.000,00 (6h às 20h)
Valor máximo noturno: R$ 1.000,00 (20h às 6h)
Limite mensal: Configurável por conta

Validações Automáticas

Saldo disponível: Verificação em tempo real
Chave PIX válida: Validação no DICT (Diretório de Identificadores)
Dados do beneficiário: Confirmação nome/documento
Limites de horário: Conformidade com regulamentação

Tipos de Chave PIX

CPF/CNPJ (DOCUMENT)

{
  "key": "12345678901",
  "keyType": "DOCUMENT"
}

CPF: 11 dígitos (sem formatação)
CNPJ: 14 dígitos (sem formatação)
Validação: Dígitos verificadores e registro PIX

Email (EMAIL)

{
  "key": "[email protected]",
  "keyType": "EMAIL"
}

Formato: Endereço de email válido
Case-sensitive: Não (convertido automaticamente)
Validação: Formato e registro no PIX

Telefone (PHONE)

{
  "key": "+5511999999999",
  "keyType": "PHONE"
}

Formato: +55 + DDD + número (ou sem +55)
Padronização: Automática para formato brasileiro
Validação: Formato e registro PIX

Chave Aleatória (RANDOM_KEY)

{
  "key": "123e4567-e89b-12d3-a456-426614174000",
  "keyType": "RANDOM_KEY"
}

Formato: UUID v4 (36 caracteres com hífens)
Segurança: Maior privacidade (não expõe dados pessoais)
Validação: Formato UUID e registro PIX

Códigos de Erro

Código	Descrição
`INSUFFICIENT_BALANCE`	Saldo insuficiente na conta
`INVALID_PIX_KEY`	Chave PIX inválida ou não encontrada
`INVALID_KEY_TYPE`	Tipo de chave não corresponde ao formato
`INVALID_BENEFICIARY_DATA`	Dados do beneficiário inconsistentes
`LIMIT_EXCEEDED`	Limite de transferência excedido
`INVALID_AMOUNT`	Valor inválido (fora dos limites permitidos)
`EXTERNAL_ID_EXISTS`	ExternalId já utilizado
`PIX_UNAVAILABLE`	Sistema PIX temporariamente indisponível

Boas Práticas

Segurança

Validação prévia: Sempre validar chaves PIX antes de transferir
Confirmação dupla: Implementar confirmação para valores altos
Log detalhado: Registrar todas as tentativas de transferência
Rate limiting: Limitar número de transferências por minuto

Experiência do Usuário

Validação em tempo real: Verificar chaves durante digitação
Feedback claro: Mostrar progresso da transferência
Comprovante imediato: Exibir dados da transferência confirmada
Histórico acessível: Manter registro das transferências

Performance

Cache de validações: Para chaves PIX frequentes
Timeout apropriado: 30 segundos para transferências
Retry inteligente: Retentar apenas em casos específicos
Webhook prioritário: Use webhook ao invés de polling

Webhook de Confirmação

Após o processamento, você receberá um webhook:

{
  "event": "pix.withdraw_completed",
  "transaction_id": "withdraw_987654321012345",
  "external_id": "transfer-789012",
  "timestamp": "2024-01-15T15:30:15Z",
  "data": {
    "status": "WITHDRAW_PAID",
    "value": 25050,
    "beneficiary": {
      "name": "Ana Silva Santos",
      "key": "[email protected]",
      "bank": "Banco Inter"
    },
    "fees": {
      "total": 0
    }
  }
}

Próximos Passos

Webhooks Cash Out

Configure notificações de transferência

Verificar Saldo

Consulte saldo disponível para transferências

Authorizations

x-api-key

string

header

required

Chave de API para autenticação

Body

application/json

type

enum<string>

required

Tipo da operação: sempre PIX

Opções disponíveis:

PIX

value

number

required

Valor da transferência em reais

Intervalo obrigatório: x >= 0.01

Example:

15

details

object

required

Mostrar atributos filhos

details.key

string

required

Chave PIX do beneficiário

Example:

"12312312387"

details.keyType

enum<string>

required

Tipo da chave PIX

Opções disponíveis:

DOCUMENT,

EMAIL,

PHONE,

RANDOM

details.name

string

required

Nome completo do beneficiário

Example:

"John Marvin"

details.document

string

required

CPF ou CNPJ do beneficiário (apenas números)

Example:

"12312312387"

externalId

string

Identificador único da transferência em seu sistema

Example:

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

Response

Transferência PIX criada com sucesso

transactionId

string

required

ID único da transferência no FireBanking

Example:

"75906707-8c31-479c-b354-aa805c4cefbc"

status

enum<string>

required

Status da transferência

Opções disponíveis:

WAITING_CONFIRMATION,

WITHDRAW_PAID,

ERROR

Example:

"WAITING_CONFIRMATION"

Visão Geral

Fluxo de Integração

PIX Cobrança (Cash In)

PIX Saque (Cash Out)

Operações

Gestão

Webhooks

Visão Geral

Exemplo de Requisição

Exemplo de Resposta

Campos de Resposta

Fluxo de Processamento

1. Validação Inicial

2. Processamento

3. Confirmação

Estados da Transferência

Validações e Limites

Limites Operacionais

Validações Automáticas

Tipos de Chave PIX

Códigos de Erro

Boas Práticas

Segurança

Experiência do Usuário

Performance

Webhook de Confirmação

Próximos Passos

Webhooks Cash Out

Verificar Saldo

Authorizations

Body

Response

Visão Geral

Fluxo de Integração

PIX Cobrança (Cash In)

PIX Saque (Cash Out)

Operações

Gestão

Webhooks

​Visão Geral

​Exemplo de Requisição

​Exemplo de Resposta

​Campos de Resposta

​Fluxo de Processamento

​1. Validação Inicial

​2. Processamento

​3. Confirmação

​Estados da Transferência

​Validações e Limites

​Limites Operacionais

​Validações Automáticas

​Tipos de Chave PIX

​Códigos de Erro

​Boas Práticas

​Segurança

​Experiência do Usuário

​Performance

​Webhook de Confirmação

​Próximos Passos

Webhooks Cash Out

Verificar Saldo

Authorizations

Body

Response

Visão Geral

Exemplo de Requisição

Exemplo de Resposta

Campos de Resposta

Fluxo de Processamento

1. Validação Inicial

2. Processamento

3. Confirmação

Estados da Transferência

Validações e Limites

Limites Operacionais

Validações Automáticas

Tipos de Chave PIX

Códigos de Erro

Boas Práticas

Segurança

Experiência do Usuário

Performance

Webhook de Confirmação

Próximos Passos