Pular para o conteúdo principal
O objeto Saque (Cashout ou Payout) representa uma transferência de fundos da sua conta Safefy para uma conta bancária externa via PIX. Os saques são processados utilizando chaves PIX.

​
Estrutura

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "saque_001",
  "amount": 50000,
  "fee": 100,
  "netAmount": 49900,
  "currency": "BRL",
  "status": "Completed",
  "environment": "Production",
  "pix": {
    "pixKeyType": "CPF",
    "pixKey": "12345678901",
    "endToEndId": "E12345678202401151234567890123456"
  },
  "requestedAt": "2024-01-15T10:30:00Z",
  "processedAt": "2024-01-15T10:31:00Z",
  "completedAt": "2024-01-15T10:31:30Z",
  "failureReason": null,
  "createdAt": "2024-01-15T10:30:00Z"
}

​
Atributos

​
id
string
obrigatório
Identificador único do saque no formato UUID v4. Gerado automaticamente pela API.
​
externalId
string
Identificador externo do saque no seu sistema. Útil para vincular o saque da Safefy com registros do seu banco de dados.
​
amount
integer
obrigatório
Valor bruto do saque em centavos. Por exemplo, R$ 500,00 = 50000.
​
fee
integer
obrigatório
Taxa cobrada pelo saque em centavos.
​
netAmount
integer
obrigatório
Valor líquido transferido para a conta de destino em centavos. Calculado como amount - fee.
​
currency
string
obrigatório
Moeda do saque. Atualmente apenas BRL (Real Brasileiro) é suportado.
​
status
string
obrigatório
Status atual do saque. Valores possíveis:
  • Pending - Saque solicitado, aguardando processamento
  • Processing - Saque sendo processado
  • Completed - Saque concluído com sucesso
  • Failed - Falha no processamento do saque
  • Rejected - Saque rejeitado (dados inválidos, etc)
  • Cancelled - Saque cancelado pelo usuário
​
environment
string
obrigatório
Ambiente do saque:
  • Sandbox - Ambiente de testes
  • Production - Ambiente de produção
​
pix
object
obrigatório
Dados da transferência PIX.
​
requestedAt
string
obrigatório
Data e hora em que o saque foi solicitado no formato ISO 8601.
​
processedAt
string
Data e hora em que o saque começou a ser processado no formato ISO 8601.
​
completedAt
string
Data e hora em que o saque foi concluído no formato ISO 8601.
​
failureReason
string
Motivo da falha ou rejeição do saque. Preenchido apenas quando status é Failed ou Rejected.
​
createdAt
string
obrigatório
Data e hora de criação do registro no formato ISO 8601.

​
Ciclo de Vida do Saque

Pending → Processing → Completed
    ↓         ↓
Cancelled  Failed
              ↓
          Rejected
  1. Pending: Saque solicitado, aguardando processamento
  2. Processing: Saque em andamento
  3. Completed: Transferência concluída com sucesso
  4. Cancelled: Cancelado antes de iniciar o processamento
  5. Failed: Falha durante o processamento
  6. Rejected: Rejeitado (chave PIX inválida, conta inexistente, etc)

​
Tipos de Chave PIX

TipoFormatoExemplo
CPF11 dígitos numéricos12345678901
CNPJ14 dígitos numéricos12345678000199
EmailEmail válidoexemplo@email.com
Phone+55 + DDD + número+5511999999999
Random32 caracteres alfanuméricosa1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6

​
Endpoints

MétodoEndpointDescrição
POST/v1/cashoutsCriar saque
GET/v1/cashoutsListar saques
GET/v1/cashouts/{id}Buscar saque
POST/v1/cashouts/{id}/cancelCancelar saque
POST/v1/cashouts/simulateSimular saque (Sandbox)