Objeto Saque

O objeto Saque (Cashout ou Payout) representa uma transferência de fundos da sua conta Safefy para uma chave PIX ou uma carteira blockchain externa. Saques para carteira são processados via XGate usando uma carteira previamente verificada.

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"
  },
  "crypto": null,
  "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

string

obrigatório

Identificador único do saque no formato UUID v4. Gerado automaticamente pela API.

object

Destino de saques cripto via XGate. É preenchido apenas quando o saque foi criado com cryptoPayoutAccountId; o endereço da carteira é sempre mascarado.

Mostrar Atributos da carteira cripto

string

obrigatório

Endereço da carteira mascarado.

string

obrigatório

Rede blockchain utilizada, por exemplo BEP-20.

string

obrigatório

Criptomoeda liquidada, por exemplo USDT.

string

Identificador da transação retornado pela XGate, quando disponível.

Para criar um saque cripto, envie cryptoPayoutAccountId em POST /v1/cashouts. O token identifica o merchant e a XGate ativa é escolhida automaticamente.

string

Identificador externo do saque no seu sistema. Útil para vincular o saque da Safefy com registros do seu banco de dados.

integer

obrigatório

Valor bruto do saque em centavos. Por exemplo, R$ 500,00 = 50000.

integer

obrigatório

Taxa cobrada pelo saque em centavos.

integer

obrigatório

Valor líquido transferido para a conta de destino em centavos. Calculado como amount - fee.

string

obrigatório

Moeda do saque. Atualmente apenas BRL (Real Brasileiro) é suportado.

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

string

obrigatório

Ambiente do saque:

Sandbox - Ambiente de testes
Production - Ambiente de produção

object

obrigatório

Dados da transferência PIX.

Mostrar Atributos do PIX

string

obrigatório

Tipo da chave PIX. Valores possíveis:

CPF - CPF do destinatário
CNPJ - CNPJ do destinatário
Email - Email cadastrado como chave PIX
Phone - Telefone cadastrado como chave PIX
Random - Chave aleatória

string

obrigatório

Valor da chave PIX do destinatário.

string

Identificador fim-a-fim da transação PIX no Banco Central. Preenchido após o processamento.

string

obrigatório

Data e hora em que o saque foi solicitado no formato ISO 8601.

string

Data e hora em que o saque começou a ser processado no formato ISO 8601.

string

Data e hora em que o saque foi concluído no formato ISO 8601.

string

Motivo da falha ou rejeição do saque. Preenchido apenas quando status é Failed ou Rejected.

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

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

Tipos de Chave PIX

Tipo	Formato	Exemplo
`CPF`	11 dígitos numéricos	`12345678901`
`CNPJ`	14 dígitos numéricos	`12345678000199`
`Email`	Email válido	`exemplo@email.com`
`Phone`	+55 + DDD + número	`+5511999999999`
`Random`	32 caracteres alfanuméricos	`a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6`

Endpoints

Método	Endpoint	Descrição
`POST`	`/v1/cashouts`	Criar saque
`POST`	`/v1/cashout-accounts`	Cadastrar conta de saque
`GET`	`/v1/cashouts`	Listar saques
`GET`	`/v1/cashouts/{id}`	Buscar saque
`POST`	`/v1/cashouts/{id}/cancel`	Cancelar saque
`POST`	`/v1/cashouts/simulate`	Simular saque (Sandbox)

Autenticação

Clientes

Transações

Saldo

Disputas

Saques

Estrutura

Atributos

Ciclo de Vida do Saque

Tipos de Chave PIX

Endpoints

​Estrutura

​Atributos

​Ciclo de Vida do Saque

​Tipos de Chave PIX

​Endpoints

Estrutura

Atributos

Ciclo de Vida do Saque

Tipos de Chave PIX

Endpoints