# PayFast4 API - Documentação de Integração

## Visão Geral
PayFast4 é um gateway de pagamentos que permite aceitar PIX e criptomoedas (USDT BEP-20).

Base URL: https://payfast4.com/api/v1

## Autenticação
Todas as requisições devem incluir os headers:
- X-API-Key: Sua chave pública (PF4_pk_...)
- X-API-Secret: Sua chave secreta (PF4_sk_...)

Obtenha suas credenciais no painel: https://payfast4.com/merchant/developer

## Endpoints

### PIX - Criar Cobrança
POST /api/v1/charges
Content-Type: application/json

Request:
{
  "amount": 5000,           // Valor em centavos (R$ 50,00)
  "external_id": "pedido_123",
  "description": "Pagamento do pedido #123",
  "payer_name": "João Silva",
  "payer_document": "12345678900",
  "payer_email": "joao@email.com",
  "expiration_minutes": 30
}

Response:
{
  "id": "txn_abc123",
  "status": "pending",
  "amount": 5000,
  "fee": 150,
  "net_amount": 4850,
  "pix_code": "00020126580014br.gov.bcb.pix...",
  "qr_code": "data:image/png;base64,...",
  "external_id": "pedido_123",
  "expires_at": "2024-01-15T11:00:00Z"
}

### PIX - Consultar Cobrança
GET /api/v1/charges/{id}

### PIX - Cancelar Cobrança
POST /api/v1/charges/{id}/cancel

### PIX - Criar Saque
POST /api/v1/withdrawals
Valor mínimo: R$ 10,00 (1000 centavos)

Request:
{
  "amount": 10000,          // Valor em centavos (R$ 100,00)
  "pix_key": "12345678900",
  "pix_key_type": "cpf",    // cpf, cnpj, email, phone, random
  "recipient_name": "Maria Santos",
  "external_id": "saque_456"
}

Response:
{
  "id": "wth_xyz789",
  "status": "pending",
  "amount": 10000,
  "fee": 200,
  "net_amount": 9800,
  "pix_key": "12345678900",
  "pix_key_type": "cpf",
  "recipient_name": "Maria Santos"
}

### PIX - Consultar Saque
GET /api/v1/withdrawals/{id}

### Listar Transações
GET /api/v1/transactions?status=completed&type=deposit&limit=50

### Consultar Saldo
GET /api/v1/balance

Response:
{
  "available": 500000,  // R$ 5.000,00
  "pending": 50000,     // R$ 500,00
  "total": 550000       // R$ 5.500,00
}

### Crypto - Criar Fatura
POST /api/v1/crypto/invoice

Request:
{
  "amount": 100.00,         // Valor em BRL
  "currency": "USDT_BSC",   // USDT_BSC, BUSD_BSC, BNB_BSC
  "external_id": "crypto_123"
}

Response:
{
  "id": "inv_crypto123",
  "status": "pending",
  "currency": "USDT_BSC",
  "amount": "18.50",        // Valor em USDT
  "amount_brl": 100.00,
  "wallet_address": "0x1234...",
  "expires_at": "2024-01-15T12:00:00Z"
}

### Crypto - Consultar Saldo
GET /api/v1/crypto/balance

## Webhooks

Configure sua URL no painel do desenvolvedor. Receba notificações em tempo real.

### Eventos
- charge.completed: Cobrança PIX paga
- charge.failed: Cobrança PIX falhou
- charge.expired: Cobrança PIX expirou
- withdrawal.completed: Saque PIX concluído
- withdrawal.failed: Saque PIX falhou
- crypto.completed: Pagamento crypto confirmado

### Validação
Valide usando o header X-Webhook-Code com seu código de segurança do painel.

### Exemplo de Payload
{
  "event": "charge.completed",
  "data": {
    "id": "txn_abc123",
    "status": "completed",
    "amount": 5000,
    "fee": 150,
    "net_amount": 4850,
    "external_id": "pedido_123",
    "paid_at": "2024-01-15T10:30:00Z"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

## Códigos de Status HTTP
- 200: Sucesso
- 201: Criado com sucesso
- 400: Erro de validação
- 401: Não autorizado
- 404: Não encontrado
- 500: Erro interno

## Suporte
Email: suporte@payfast4.com
Site: https://payfast4.com