> ## Documentation Index
> Fetch the complete documentation index at: https://docs.safefypay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Objeto Saque

> Estrutura e atributos do objeto Saque na API Safefy

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

```json theme={null}
{
  "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

<ParamField body="id" type="string" required>
  Identificador único do saque no formato UUID v4. Gerado automaticamente pela API.
</ParamField>

<ParamField body="crypto" type="object">
  Destino de saques cripto via XGate. É preenchido apenas quando o saque foi criado com `cryptoPayoutAccountId`; o endereço da carteira é sempre mascarado.

  <Expandable title="Atributos da carteira cripto">
    <ParamField body="crypto.walletAddress" type="string" required>
      Endereço da carteira mascarado.
    </ParamField>

    <ParamField body="crypto.networkSymbol" type="string" required>
      Rede blockchain utilizada, por exemplo `BEP-20`.
    </ParamField>

    <ParamField body="crypto.cryptoSymbol" type="string" required>
      Criptomoeda liquidada, por exemplo `USDT`.
    </ParamField>

    <ParamField body="crypto.transactionId" type="string">
      Identificador da transação retornado pela XGate, quando disponível.
    </ParamField>
  </Expandable>
</ParamField>

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

<ParamField body="externalId" type="string">
  Identificador externo do saque no seu sistema. Útil para vincular o saque da Safefy com registros do seu banco de dados.
</ParamField>

<ParamField body="amount" type="integer" required>
  Valor bruto do saque em centavos. Por exemplo, R\$ 500,00 = `50000`.
</ParamField>

<ParamField body="fee" type="integer" required>
  Taxa cobrada pelo saque em centavos.
</ParamField>

<ParamField body="netAmount" type="integer" required>
  Valor líquido transferido para a conta de destino em centavos. Calculado como `amount - fee`.
</ParamField>

<ParamField body="currency" type="string" required>
  Moeda do saque. Atualmente apenas `BRL` (Real Brasileiro) é suportado.
</ParamField>

<ParamField body="status" type="string" required>
  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
</ParamField>

<ParamField body="environment" type="string" required>
  Ambiente do saque:

  * `Sandbox` - Ambiente de testes
  * `Production` - Ambiente de produção
</ParamField>

<ParamField body="pix" type="object" required>
  Dados da transferência PIX.

  <Expandable title="Atributos do PIX">
    <ParamField body="pix.pixKeyType" type="string" required>
      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
    </ParamField>

    <ParamField body="pix.pixKey" type="string" required>
      Valor da chave PIX do destinatário.
    </ParamField>

    <ParamField body="pix.endToEndId" type="string">
      Identificador fim-a-fim da transação PIX no Banco Central. Preenchido após o processamento.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="requestedAt" type="string" required>
  Data e hora em que o saque foi solicitado no formato ISO 8601.
</ParamField>

<ParamField body="processedAt" type="string">
  Data e hora em que o saque começou a ser processado no formato ISO 8601.
</ParamField>

<ParamField body="completedAt" type="string">
  Data e hora em que o saque foi concluído no formato ISO 8601.
</ParamField>

<ParamField body="failureReason" type="string">
  Motivo da falha ou rejeição do saque. Preenchido apenas quando `status` é `Failed` ou `Rejected`.
</ParamField>

<ParamField body="createdAt" type="string" required>
  Data e hora de criação do registro no formato ISO 8601.
</ParamField>

## 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

| 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](/api-reference/cashouts/create)                      |
| `POST` | `/v1/cashout-accounts`     | [Cadastrar conta de saque](/api-reference/cashouts/create-account) |
| `GET`  | `/v1/cashouts`             | [Listar saques](/api-reference/cashouts/list)                      |
| `GET`  | `/v1/cashouts/{id}`        | [Buscar saque](/api-reference/cashouts/get)                        |
| `POST` | `/v1/cashouts/{id}/cancel` | [Cancelar saque](/api-reference/cashouts/cancel)                   |
| `POST` | `/v1/cashouts/simulate`    | [Simular saque (Sandbox)](/api-reference/cashouts/simulate)        |