{"openapi":"3.0.0","info":{"title":"PayFast4 API","version":"1.0.0","description":"API de integração do PayFast4 - Gateway de Pagamentos PIX e Criptomoedas. Permite criar cobranças PIX, saques, e aceitar pagamentos em criptomoedas (USDT BEP-20).","contact":{"name":"Suporte PayFast4","email":"suporte@payfast4.com","url":"https://payfast4.com"}},"servers":[{"url":"https://payfast4.com/api/v1","description":"Servidor de produção"}],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Chave pública da API (formato: PF4_pk_...)"},"ApiSecretAuth":{"type":"apiKey","in":"header","name":"X-API-Secret","description":"Chave secreta da API (formato: PF4_sk_...)"}},"schemas":{"Charge":{"type":"object","properties":{"id":{"type":"string","description":"ID único da cobrança"},"status":{"type":"string","enum":["pending","processing","completed","failed","cancelled","expired"]},"amount":{"type":"number","description":"Valor em centavos (ex: 1000 = R$ 10,00)"},"fee":{"type":"number","description":"Taxa cobrada em centavos"},"net_amount":{"type":"number","description":"Valor líquido após taxas"},"pix_code":{"type":"string","description":"Código PIX copia e cola (EMV)"},"qr_code":{"type":"string","description":"QR Code em base64 data URL"},"external_id":{"type":"string","description":"ID externo do cliente"},"description":{"type":"string","description":"Descrição da cobrança"},"payer_name":{"type":"string","description":"Nome do pagador"},"payer_document":{"type":"string","description":"CPF/CNPJ do pagador"},"payer_email":{"type":"string","description":"Email do pagador"},"expires_at":{"type":"string","format":"date-time","description":"Data de expiração"},"created_at":{"type":"string","format":"date-time"},"paid_at":{"type":"string","format":"date-time","nullable":true}}},"Withdrawal":{"type":"object","properties":{"id":{"type":"string","description":"ID único do saque"},"status":{"type":"string","enum":["pending","processing","completed","failed","cancelled"]},"amount":{"type":"integer","description":"Valor em centavos"},"fee":{"type":"integer","description":"Taxa do saque em centavos"},"net_amount":{"type":"integer","description":"Valor líquido enviado"},"pix_key":{"type":"string","description":"Chave PIX do destinatário"},"pix_key_type":{"type":"string","enum":["cpf","cnpj","email","phone","random"]},"recipient_name":{"type":"string","description":"Nome do destinatário"},"external_id":{"type":"string","description":"ID externo do cliente"},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true}}},"CryptoInvoice":{"type":"object","properties":{"id":{"type":"string","description":"ID único da fatura"},"status":{"type":"string","enum":["pending","completed","expired","cancelled"]},"currency":{"type":"string","enum":["USDT_BSC","BUSD_BSC","BNB_BSC"],"description":"Moeda BEP-20"},"amount":{"type":"string","description":"Valor em crypto"},"amount_brl":{"type":"number","description":"Valor equivalente em BRL"},"wallet_address":{"type":"string","description":"Endereço da carteira para depósito"},"external_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"}}},"WebhookPayload":{"type":"object","properties":{"event":{"type":"string","enum":["charge.completed","charge.failed","charge.expired","withdrawal.completed","withdrawal.failed","crypto.completed"]},"data":{"type":"object","description":"Dados do evento (Charge, Withdrawal, ou CryptoInvoice)"},"timestamp":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"string","description":"Mensagem de erro"}}}}},"paths":{"/charges":{"post":{"summary":"Criar cobrança PIX","description":"Cria uma nova cobrança PIX e retorna o QR Code e código copia e cola","tags":["PIX"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"integer","description":"Valor em centavos (mínimo 100 = R$ 1,00)","example":5000},"external_id":{"type":"string","description":"ID externo para identificar a cobrança no seu sistema","example":"pedido_123"},"description":{"type":"string","description":"Descrição da cobrança","example":"Pagamento do pedido #123"},"payer_name":{"type":"string","description":"Nome do pagador","example":"João Silva"},"payer_document":{"type":"string","description":"CPF ou CNPJ do pagador","example":"12345678900"},"payer_email":{"type":"string","description":"Email do pagador","example":"joao@email.com"},"expiration_minutes":{"type":"integer","description":"Minutos até expirar (padrão: 30)","example":60}}}}}},"responses":{"201":{"description":"Cobrança criada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Charge"}}}},"400":{"description":"Erro de validação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Não autorizado - credenciais inválidas"}}}},"/charges/{id}":{"get":{"summary":"Consultar cobrança","description":"Retorna os detalhes de uma cobrança específica","tags":["PIX"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"ID da cobrança"}],"responses":{"200":{"description":"Detalhes da cobrança","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Charge"}}}},"404":{"description":"Cobrança não encontrada"}}}},"/charges/{id}/cancel":{"post":{"summary":"Cancelar cobrança","description":"Cancela uma cobrança pendente","tags":["PIX"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cobrança cancelada"},"400":{"description":"Cobrança não pode ser cancelada"}}}},"/transactions":{"get":{"summary":"Listar transações","description":"Lista todas as transações (cobranças e saques)","tags":["Transações"],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending","processing","completed","failed","cancelled"]}},{"name":"type","in":"query","schema":{"type":"string","enum":["deposit","withdrawal"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Lista de transações","content":{"application/json":{"schema":{"type":"object","properties":{"transactions":{"type":"array","items":{"$ref":"#/components/schemas/Charge"}},"total":{"type":"integer"}}}}}}}}},"/balance":{"get":{"summary":"Consultar saldo","description":"Retorna o saldo disponível e pendente da conta","tags":["Conta"],"responses":{"200":{"description":"Saldo da conta","content":{"application/json":{"schema":{"type":"object","properties":{"available":{"type":"integer","description":"Saldo disponível em centavos"},"pending":{"type":"integer","description":"Saldo pendente em centavos"},"total":{"type":"integer","description":"Saldo total em centavos"}}}}}}}}},"/withdrawals":{"post":{"summary":"Criar saque PIX","description":"Solicita um saque PIX para uma chave PIX específica. Valor mínimo: R$ 10,00 (1000 centavos)","tags":["Saques"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","pix_key","pix_key_type"],"properties":{"amount":{"type":"integer","description":"Valor em centavos (mínimo 1000)","example":10000},"pix_key":{"type":"string","description":"Chave PIX do destinatário","example":"12345678900"},"pix_key_type":{"type":"string","enum":["cpf","cnpj","email","phone","random"],"example":"cpf"},"recipient_name":{"type":"string","description":"Nome do destinatário","example":"Maria Santos"},"external_id":{"type":"string","description":"ID externo","example":"saque_456"}}}}}},"responses":{"201":{"description":"Saque criado com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Withdrawal"}}}},"400":{"description":"Erro de validação ou saldo insuficiente"}}}},"/withdrawals/{id}":{"get":{"summary":"Consultar saque","description":"Retorna os detalhes de um saque específico","tags":["Saques"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Detalhes do saque","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Withdrawal"}}}},"404":{"description":"Saque não encontrado"}}}},"/crypto/invoice":{"post":{"summary":"Criar fatura crypto","description":"Cria uma fatura para pagamento em criptomoeda (BEP-20 apenas: USDT, BUSD, BNB)","tags":["Crypto"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"number","description":"Valor em BRL","example":100},"currency":{"type":"string","enum":["USDT_BSC","BUSD_BSC","BNB_BSC"],"description":"Moeda BEP-20","example":"USDT_BSC"},"external_id":{"type":"string","example":"crypto_123"}}}}}},"responses":{"201":{"description":"Fatura criada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CryptoInvoice"}}}}}}},"/crypto/balance":{"get":{"summary":"Consultar saldo crypto","description":"Retorna o saldo em criptomoedas","tags":["Crypto"],"responses":{"200":{"description":"Saldo crypto","content":{"application/json":{"schema":{"type":"object","properties":{"balances":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"string"},"amount_brl":{"type":"number"}}}}}}}}}}}}},"webhooks":{"description":"O PayFast4 envia notificações via webhook quando eventos ocorrem. Configure sua URL de webhook no painel do desenvolvedor.","events":[{"name":"charge.completed","description":"Cobrança PIX foi paga com sucesso"},{"name":"charge.failed","description":"Cobrança PIX falhou"},{"name":"charge.expired","description":"Cobrança PIX expirou"},{"name":"withdrawal.completed","description":"Saque PIX foi concluído"},{"name":"withdrawal.failed","description":"Saque PIX falhou"},{"name":"crypto.completed","description":"Pagamento crypto confirmado"}],"security":{"description":"Valide webhooks usando o código de segurança enviado no header X-Webhook-Code","header":"X-Webhook-Code"},"example":{"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"}}}