HAT PAY — Documentação completa da API Gerado em: 2026-10-28 10:32 Site: https://hatpay.online Base URL: https://hatpay.online/api/v1 Versão: v1 Este arquivo é a documentação oficial em texto corrido para integrar a API do HAT PAY em sistemas e IAs. Use placeholders SEU_TOKEN e SEU_CLIENT_ID. Nunca envie tokens reais para modelos públicos. ============================================================================== 1. AUTENTICAÇÃO ============================================================================== Todas as rotas de /api/v1 exigem: Authorization: Bearer SEU_TOKEN X-Client-ID: SEU_CLIENT_ID Accept: application/json Content-Type: application/json O token e o Client ID são gerados no painel, em Chave API. O token tem o formato nxp_ + 64 caracteres. Não envie o token na query string (?api_token=). Use apenas headers. Rate limit da API: 60 requisições por minuto. ============================================================================== 2. CHECKLIST DE PRODUÇÃO ============================================================================== - Envie Bearer + X-Client-ID em todas as chamadas. - Saque automático exige IP permitido na credencial. Curingas * e 0.0.0.0 não são aceitos. - Configure a Webhook URL na credencial. - Valide X-Webhook-Signature com HMAC-SHA256 do corpo JSON cru, usando o token da API como segredo. - Processe eventos de forma idempotente (não credite duas vezes o mesmo transaction_id). - Responda o webhook com HTTP 200. ============================================================================== 3. ENDPOINTS ============================================================================== POST https://hatpay.online/api/v1/payments/pix POST https://hatpay.online/api/v1/payments/credit-card GET https://hatpay.online/api/v1/payments/{uuid} POST https://hatpay.online/api/v1/cashin/pix POST https://hatpay.online/api/v1/cashout/pix GET https://hatpay.online/api/v1/cashout/pix/{id} GET https://hatpay.online/api/v1/balance GET https://hatpay.online/api/v1/transactions GET https://hatpay.online/api/v1/transactions/{uuid} ============================================================================== 4. CRIAR PAGAMENTO PIX ============================================================================== POST https://hatpay.online/api/v1/payments/pix Body JSON: amount number obrigatório Valor do pagamento. Mínimo 0.01 payer_name string obrigatório Nome do pagador payer_email string obrigatório Email do pagador payer_cpf string obrigatório CPF ou CNPJ (máx. 18) description string opcional Descrição (máx. 500) Resposta 201: { "success": true, "data": { "transaction_uuid": "550e8400-e29b-41d4-a716-446655440000", "amount": 100.00, "fee": 4.00, "amount_net": 96.00, "status": "pending", "qr_code": "00020126580014BR.GOV.BCB.PIX...", "pix_code": "00020126580014BR.GOV.BCB.PIX...", "pix_key": "00020126580014BR.GOV.BCB.PIX...", "expires_at": "2024-11-26T12:30:00Z", "expires_in_seconds": 1800 } } Exiba pix_code / qr_code para o cliente pagar. Quando o PIX for confirmado, o status muda para completed e o webhook transaction.completed é enviado. ============================================================================== 5. CRIAR PAGAMENTO CARTÃO ============================================================================== POST https://hatpay.online/api/v1/payments/credit-card Body JSON: amount number obrigatório card_number string obrigatório card_cvv string obrigatório card_expiry string obrigatório card_holder string obrigatório payer_name string obrigatório payer_email string obrigatório payer_cpf string obrigatório installments integer opcional 1 a 12 description string opcional ============================================================================== 6. CONSULTAR PAGAMENTO ============================================================================== GET https://hatpay.online/api/v1/payments/{uuid} O uuid é o transaction_uuid retornado na criação. ============================================================================== 7. CASHIN PIX (DEPÓSITO NA CONTA) ============================================================================== POST https://hatpay.online/api/v1/cashin/pix Body JSON: amount number obrigatório Mínimo 1.00 payer_name string opcional Gera um PIX para creditar saldo na conta do dono da credencial. ============================================================================== 8. CASHOUT PIX (SAQUE) ============================================================================== POST https://hatpay.online/api/v1/cashout/pix Body JSON: amount number obrigatório Valor líquido. Mínimo padrão 10.00 pix_key string obrigatório CPF, e-mail, telefone ou chave aleatória (mín. 10) Requisitos para saque automático: 1. Credencial com modo automático 2. IP do servidor liberado na credencial 3. Conta não bloqueada e saques liberados Resposta de sucesso: { "success": true, "message": "Saque criado e processado automaticamente.", "withdrawal": { "id": 123, "amount": 95.00, "amount_gross": 100.00, "fee": 5.00, "status": "processing", "pix_key": "12345678900" } } Consultar saque: GET https://hatpay.online/api/v1/cashout/pix/{id} ============================================================================== 9. SALDO ============================================================================== GET https://hatpay.online/api/v1/balance Retorna o saldo disponível da conta autenticada pela credencial. ============================================================================== 10. TRANSAÇÕES ============================================================================== GET https://hatpay.online/api/v1/transactions Query opcional: status pending, completed, failed type pix, credit, withdrawal start_date YYYY-MM-DD end_date YYYY-MM-DD per_page padrão 20 Resposta: { "success": true, "data": [ { "uuid": "550e8400-e29b-41d4-a716-446655440000", "amount_gross": 100.00, "amount_net": 96.00, "fee": 4.00, "type": "pix", "status": "completed", "gateway_provider": "pluggou", "external_id": "TXN_123456789", "description": "Depósito via PIX - API", "created_at": "2024-01-20T10:30:00Z", "updated_at": "2024-01-20T10:35:00Z" } ], "pagination": { "current_page": 1, "last_page": 5, "per_page": 20, "total": 100 } } GET https://hatpay.online/api/v1/transactions/{uuid} ============================================================================== 11. WEBHOOKS ============================================================================== Configure a URL na Chave de API. O HAT PAY envia POST JSON quando o status muda. Eventos: transaction.completed Pagamento confirmado e saldo creditado transaction.failed Pagamento falhou, expirou ou foi cancelado withdrawal.completed Saque concluído Payload: { "event": "transaction.completed", "created_at": "2024-01-20T10:30:00Z", "data": { "transaction_id": "550e8400-e29b-41d4-a716-446655440000", "external_id": "TXN_123456789", "amount_gross": 150.00, "amount_net": 145.50, "fee": 4.50, "status": "completed", "gateway_provider": "pluggou", "paid_at": "2024-01-20T10:35:00Z" } } Campos: event nome do evento created_at ISO 8601 data.transaction_id UUID no HAT PAY data.external_id ID no adquirente data.amount_gross valor bruto data.amount_net valor líquido data.fee taxa data.status completed, failed, etc data.gateway_provider pluggou, misticpay, sharkhub, cajupay, nexuspag, trimpag data.paid_at confirmação do pagamento Validação da assinatura (PHP): $signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? ''; $raw = file_get_contents('php://input'); $expected = hash_hmac('sha256', $raw, 'SEU_TOKEN'); if (!hash_equals($expected, preg_replace('/^sha256=/i', '', $signature))) { http_response_code(401); exit; } Responda 200 OK. Sem 200, o envio pode ser repetido. Use transaction_id para idempotência. ============================================================================== 12. EXEMPLOS ============================================================================== PHP (Guzzle): $client = new \GuzzleHttp\Client(); $response = $client->post('https://hatpay.online/api/v1/payments/pix', [ 'headers' => [ 'Authorization' => 'Bearer SEU_TOKEN', 'X-Client-ID' => 'SEU_CLIENT_ID', 'Accept' => 'application/json', ], 'json' => [ 'amount' => 100.00, 'payer_name' => 'Joao Silva', 'payer_email' => 'joao@email.com', 'payer_cpf' => '12345678900', 'description' => 'Pagamento de teste' ] ]); print_r(json_decode($response->getBody(), true)); Python (requests): import requests r = requests.post( "https://hatpay.online/api/v1/payments/pix", json={ "amount": 100.00, "payer_name": "Joao Silva", "payer_email": "joao@email.com", "payer_cpf": "12345678900", "description": "Pagamento de teste", }, headers={ "Authorization": "Bearer SEU_TOKEN", "X-Client-ID": "SEU_CLIENT_ID", "Content-Type": "application/json", }, ) print(r.json()) JavaScript (fetch): fetch("https://hatpay.online/api/v1/payments/pix", { method: "POST", headers: { "Authorization": "Bearer SEU_TOKEN", "X-Client-ID": "SEU_CLIENT_ID", "Content-Type": "application/json" }, body: JSON.stringify({ amount: 100.00, payer_name: "Joao Silva", payer_email: "joao@email.com", payer_cpf: "12345678900", description: "Pagamento de teste" }) }).then(r => r.json()).then(console.log); cURL: curl -X POST "https://hatpay.online/api/v1/payments/pix" \ -H "Authorization: Bearer SEU_TOKEN" \ -H "X-Client-ID: SEU_CLIENT_ID" \ -H "Content-Type: application/json" \ -d "{\"amount\":100.00,\"payer_name\":\"Joao Silva\",\"payer_email\":\"joao@email.com\",\"payer_cpf\":\"12345678900\",\"description\":\"Pagamento de teste\"}" ============================================================================== 13. CÓDIGOS HTTP ============================================================================== 200 OK Sucesso 201 Created Recurso criado (pagamento) 400 Bad Request Dados inválidos ou gateway indisponível 401 Unauthorized Token ausente ou inválido 403 Forbidden IP não autorizado, conta bloqueada ou saque negado 404 Not Found Recurso inexistente 422 Unprocessable Entity Validação ou saldo insuficiente 429 Too Many Requests Rate limit 500 Internal Server Error Erro interno 503 Service Unavailable Webhook/gateway sem configuração ============================================================================== 14. STATUS DE TRANSAÇÃO ============================================================================== pending Aguardando pagamento completed Confirmado failed Falhou / expirou / cancelado processing Saque em processamento ============================================================================== 15. PAINEL ============================================================================== Documentação web: https://hatpay.online/documentacao Documentação no painel: https://hatpay.online/documentation Chaves de API: https://hatpay.online/api (após login) Fim da documentação.