Cash Out - Saques e Transferências PIX

Visão Geral

O endpoint de Cash Out permite realizar transferências PIX para qualquer chave PIX cadastrada no sistema. Esta funcionalidade é essencial para operações de saque, pagamento a fornecedores, transferências entre contas e outras operações financeiras.

Pré-requisitos

Antes de realizar operações de Cash Out, você precisa garantir que:

• Credenciais de API ativas: Possuir Client ID, Client Secret e API Key válidos
• Token de acesso válido: Obter um token OAuth através do endpoint /api/v1/oauth
• Saldo suficiente: Ter saldo disponível na carteira para cobrir o valor da transferência + taxas
• Conta ativa: Sua conta deve estar ativa e sem restrições

O que é Necessário

Para realizar uma transferência PIX, você precisa fornecer as seguintes informações:

O que é Importante para o Funcionamento

Como Utilizar o Endpoint

Authorization: Bearer <seu-access-token>
Content-Type: application/json

{
  "name": "Maria Santos",
  "pix_key": "12345678900",
  "pix_key_type": 1,
  "beneficiary_type": 1,
  "account_type": 1,
  "amount": "100.50",
  "cpf": "12345678900",
  "description": "Transferência para cliente",
  "favorite": false
}

{
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PROCESSING",
  "amount": 100.50,
  "fee": 2.50,
  "totalDebited": 103.00,
  "createdAt": "2024-01-15T17:30:00.000Z",
  "beneficiary": {
    "name": "Maria Santos",
    "pixKey": "12345678900",
    "pixKeyType": "CPF"
  }
}

Exemplo Completo de Requisição

Abaixo está um exemplo completo em JavaScript/Node.js de como realizar uma transferência PIX:

// Exemplo de transferência PIX (Cash Out)
const axios = require('axios');

const BASE_URL = 'https://api.vexapagamentos.com.br/api/v1';
const ACCESS_TOKEN = 'seu-access-token-aqui';

async function realizarTransferenciaPIX() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/cash-out`,
      {
        name: "Maria Santos",
        pix_key: "12345678900",
        pix_key_type: 1, // CPF
        beneficiary_type: 1, // Pessoa Física
        account_type: 1, // Conta Corrente
        amount: "100.50",
        cpf: "12345678900",
        description: "Transferência para cliente",
        favorite: false
      },
      {
        headers: {
          'Authorization': `Bearer ${ACCESS_TOKEN}`,
          'Content-Type': 'application/json'
        }
      }
    );
    
    return response.data;
  } catch (error: any) {
    console.error('Erro ao realizar transferência:', error.message);
    throw error;
  }
}

// Executar transferência
realizarTransferenciaPIX();

Exemplo com cURL

curl -X POST https://api.vexapagamentos.com.br/api/v1/cash-out \
  -H "Authorization: Bearer seu-access-token-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Santos",
    "pix_key": "12345678900",
    "pix_key_type": 1,
    "beneficiary_type": 1,
    "account_type": 1,
    "amount": "100.50",
    "cpf": "12345678900",
    "description": "Transferência para cliente",
    "favorite": false
  }'

Possíveis Erros

{
    "message": [
        "pix_key must be a valid PIX key",
        "amount must be a valid number"
    ],
    "error": "Bad Request",
    "statusCode": 400
}

{
    "message": "Unauthorized",
    "statusCode": 401
}

{
    "message": "Saldo insuficiente para realizar a transferência",
    "error": "Payment Required",
    "statusCode": 402
}

{
    "message": "Credenciais não encontradas",
    "error": "Not Found",
    "statusCode": 404
}

{
    "message": "Internal server error",
    "error": "Internal Server Error",
    "statusCode": 500
}

Boas Práticas e Recomendações

• Validação prévia: Sempre valide os dados antes de enviar a requisição (formato do CPF, chave PIX, valor mínimo/máximo)
• Verificação de saldo: Consulte o saldo disponível antes de realizar transferências para evitar erros
• Logs e auditoria: Mantenha logs de todas as transferências realizadas para auditoria e rastreabilidade
• Webhooks: Configure webhooks para receber notificações em tempo real sobre o status das transferências
• Validação de chave PIX: Valide o formato da chave PIX antes de enviar, conforme o tipo especificado
• Limites de transação: Respeite os limites de transação configurados na plataforma
• Idempotência: Use identificadores únicos para evitar transferências duplicadas

Validações Importantes

Integração com Webhooks

Para receber notificações em tempo real sobre o status das transferências, configure webhooks. Isso permite que sua aplicação seja notificada automaticamente quando uma transferência for concluída, falhar ou mudar de status.

Suporte e Recursos Adicionais

Para mais informações sobre outros endpoints e funcionalidades:

• Cash In: Documentação sobre geração de QR Codes PIX para recebimento
• Extrato: Como consultar histórico de transações e status de transferências
• Saldo: Como consultar saldo disponível antes de realizar transferências
• Webhooks: Configuração de notificações em tempo real
• Autenticação: Guia completo sobre OAuth e geração de tokens