Documentação da API

Recurso Exclusivo para Desenvolvedores

Prompt de Integração para Inteligência Artificial

Copie todo o texto da caixa abaixo e cole no seu assistente de IA favorito (ChatGPT, Claude, Cursor, Antigravity, etc.). A IA lerá toda a especificação técnica da API NovvPay e gerará o código pronto e testado para o seu site ou projeto em qualquer linguagem!

Você é um desenvolvedor sênior especialista em integração de APIs de pagamento.
Preciso integrar a API do Gateway de Pagamentos NovvPay no meu projeto.

Aqui estão todas as especificações técnicas da API NovvPay v1.0:

=======================================================
1. INFORMAÇÕES DA API NOVVPAY
=======================================================
- Base URL: https://novvpay.com/api/v1
- Formato dos Dados: JSON (Header Content-Type: application/json)
- Autenticação por Headers HTTP:
  x-public-key: SEU_TOKEN_CLIENT_ID
  x-secret-key: SEU_TOKEN_CLIENT_SECRET

=======================================================
2. ENDPOINT: CRIAR PAGAMENTO PIX (CASH-IN)
=======================================================
- Método: POST
- Rota: https://novvpay.com/api/v1/payments/pix
- Payload JSON Enviado:
{
  "amount": 150.00,                      // Valor float da cobrança
  "payer_name": "Nome do Cliente",       // Nome completo
  "payer_email": "cliente@email.com",    // E-mail válido
  "payer_cpf": "12345678901",            // CPF (apenas números)
  "description": "Pedido #10293",        // Descrição da compra
  "postback_url": "https://meusite.com/api/webhook/novvpay" // URL de notificação automática
}

- Resposta Sucesso (HTTP Status 200):
{
  "success": true,
  "transaction_id": 98401,
  "uuid": "06e3c2bc-63ef-478e-8ffb-1d2536568457",
  "status": "pending",
  "amount": 150.00,
  "qr_code": "00020126870014br.gov.bcb.pix...",      // Código Pix Copia e Cola
  "qr_code_base64": "data:image/png;base64,...",     // Imagem do QR Code em Base64
  "expires_at": "2026-07-20 23:59:59"
}

=======================================================
3. ENDPOINT: CONSULTAR STATUS DO PAGAMENTO
=======================================================
- Método: GET
- Rota: https://novvpay.com/api/v1/payments/{uuid_ou_transaction_id}
- Resposta Sucesso:
{
  "success": true,
  "status": "paid",  // Valores possíveis: "pending", "paid", "expired", "failed"
  "paid_at": "2026-07-20 18:05:00"
}

=======================================================
4. RECEBIMENTO DE WEBHOOK (NOTIFICAÇÃO AUTOMÁTICA)
=======================================================
- O servidor NovvPay enviará um POST HTTP para a sua 'postback_url' quando o PIX for pago.
- Payload recebido via Webhook:
{
  "event": "payment.approved",
  "transaction_id": 98401,
  "uuid": "06e3c2bc-63ef-478e-8ffb-1d2536568457",
  "status": "paid",
  "amount": 150.00,
  "paid_at": "2026-07-20 18:05:00"
}
- A sua aplicação DEVE retornar HTTP status 200 OK após receber a notificação.

=======================================================
INSTRUÇÕES PARA A IA:
=======================================================
Por favor, gere o código completo, limpo e pronto para produção para integrar a API NovvPay na tecnologia que vou especificar abaixo:

Linguagem / Framework: [MENCIONE AQUI SUA LINGUAGEM OU FRAMEWORK, Ex: PHP Puro, Node.js/Express, Python/Django, Laravel, React, Next.js, WordPress/WooCommerce]

O código que você gerar deve incluir:
1. Uma classe/serviço utilitário para realizar a chamada de criação do PIX.
2. Renderização do QR Code em imagem e o botão de 'Copiar Código PIX'.
3. O script/rota do Webhook para receber a notificação e atualizar o status do pedido para 'PAGO' automaticamente no meu banco de dados.

Introdução à API

A API RESTful do Novvpay permite processar recebimentos via PIX e realizar saques automatizados de forma escalável.

Alta Disponibilidade

Respostas em milissegundos com confirmação de PIX instantânea.

Segurança Total

Autenticação obrigatória com chaves de API restritas e HTTPS.

Credenciais & Autenticação

Todas as chamadas à API devem incluir suas chaves nos headers HTTP da requisição:

x-public-key: SEU_CLIENT_ID_AQUI

x-secret-key: SEU_CLIENT_SECRET_AQUI

Content-Type: application/json

Gerar minhas chaves de API no painel

Criar Cobrança PIX

POST /payments/pix

Campo	Tipo	Obrigatório	Descrição
amount	float	Sim	Valor da cobrança (ex: 150.00)
payer_name	string	Sim	Nome completo do pagador
payer_email	string	Sim	E-mail válido do pagador
payer_cpf	string	Sim	CPF (apenas 11 números)
postback_url	string	Opcional	URL do seu sistema para receber o webhook

Saque / Transferência PIX (Cashout)

POST /cashout

Envie saques e transferências automáticas via PIX diretamente para qualquer chave bancária.

Campo	Tipo	Obrigatório	Descrição
amount	float	Sim	Valor do saque (ex: 250.00)
pix_key_type	string	Sim	Tipo da chave: "cpf", "cnpj", "email", "phone", "random"
pix_key	string	Sim	Valor da chave PIX do destinatário
description	string	Opcional	Descrição do saque (ex: Saque de comissão)

// Resposta de Sucesso (200 OK)

{
  "success": true,
  "transaction_id": 98402,
  "status": "approved",
  "amount": 250.00,
  "pix_key": "12345678901",
  "transferred_at": "2026-07-20 18:10:00"
}

Consultar Status da Transação

GET /payments/{id}

Consulte o status atualizado de qualquer transação informando o transaction_id ou o uuid.

// Exemplo de Resposta (200 OK)

{
  "success": true,
  "transaction_id": 98401,
  "uuid": "06e3c2bc-63ef-478e-8ffb-1d2536568457",
  "status": "paid",  // "pending", "paid", "expired", "failed"
  "amount": 150.00,
  "payer_name": "João Silva",
  "created_at": "2026-07-20 18:00:00",
  "paid_at": "2026-07-20 18:05:00"
}

Notificações via Webhook

Quando uma cobrança PIX é paga, enviamos uma requisição POST HTTP para a sua postback_url.

// Payload Recebido no Webhook

{
  "event": "payment.approved",
  "transaction_id": 98401,
  "uuid": "06e3c2bc-63ef-478e-8ffb-1d2536568457",
  "status": "paid",
  "amount": 150.00,
  "paid_at": "2026-07-20 18:05:00"
}

Exemplo em PHP

<?php
$ch = curl_init('https://novvpay.com/api/v1/payments/pix');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'x-public-key: SEU_CLIENT_ID',
    'x-secret-key: SEU_CLIENT_SECRET',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'amount' => 150.00,
    'payer_name' => 'João Silva',
    'payer_email' => 'joao@email.com',
    'payer_cpf' => '12345678901'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo "QR Code: " . $response['qr_code'];
?>

Exemplo em Node.js (Axios)

const axios = require('axios');

async function createPixPayment() {
    try {
        const response = await axios.post('https://novvpay.com/api/v1/payments/pix', {
            amount: 150.00,
            payer_name: 'João Silva',
            payer_email: 'joao@email.com',
            payer_cpf: '12345678901'
        }, {
            headers: {
                'x-public-key': 'SEU_CLIENT_ID',
                'x-secret-key': 'SEU_CLIENT_SECRET',
                'Content-Type': 'application/json'
            }
        });

        console.log('Pix Copia e Cola:', response.data.qr_code);
    } catch (error) {
        console.error('Erro na requisição:', error.response?.data || error.message);
    }
}

createPixPayment();

Exemplo em Python (Requests)

import requests

url = "https://novvpay.com/api/v1/payments/pix"
headers = {
    "x-public-key": "SEU_CLIENT_ID",
    "x-secret-key": "SEU_CLIENT_SECRET",
    "Content-Type": "application/json"
}
payload = {
    "amount": 150.00,
    "payer_name": "João Silva",
    "payer_email": "joao@email.com",
    "payer_cpf": "12345678901"
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

print("PIX Copia e Cola:", data.get("qr_code"))

Exemplo cURL

curl -X POST "https://novvpay.com/api/v1/payments/pix" \
  -H "x-public-key: SEU_CLIENT_ID" \
  -H "x-secret-key: SEU_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150.00,
    "payer_name": "João Silva",
    "payer_email": "joao@email.com",
    "payer_cpf": "12345678901"
  }'

Documentação da API NovvPay