Suporte Dashboard

Começando

A API RevoxPay permite que você integre pagamentos PIX e processamento de saques de forma instantânea em seu sistema. Utilizamos JSON em todas as comunicações.

URL de Produção — PIX (Cash-In)

https://revoxpay.com/api/pix/index.php

URL de Produção — Saque (Cash-Out)

https://revoxpay.com/api/index.php

URL de Produção — Consultar Status

https://revoxpay.com/api/status/index.php

Checklist de Integração

1. Obtenha sua API Key no painel administrativo.
2. Realize uma chamada POST para gerar um QRCode PIX.
3. Configure sua URL de Webhook para receber confirmações de pagamento.

URLs de Produção
# PIX (Cash-In) — Gerar cobrança
POST https://revoxpay.com/api/pix/index.php

# Saques (Cash-Out) — Enviar PIX
POST https://revoxpay.com/api/index.php

# Consultar Status da Transação
GET https://revoxpay.com/api/status/index.php

Autenticação

Nossa autenticação é simplificada. Todas as requisições devem incluir o campo api_key no corpo (body) enviado via JSON.

Mantenha sua chave segura

Nunca exponha sua API Key em código front-end (JavaScript). Todas as chamadas devem ser feitas a partir do seu Servidor (Backend).

Formato da API Key

Sua chave segue o formato: revox_live_XXXXXXXXXXXXXXXXXXXX

Você encontra sua API Key no painel RevoxPay em Configurações → API.

Autenticação (JSON)
{
  "api_key": "revox_live_xxxxxxxxxxxxxxxxxxxxx",
  "amount": 100.00,
  "requestNumber": "pedido_001"
}
Exemplo — cURL com autenticação
curl -X POST https://revoxpay.com/api/pix/index.php \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "revox_live_sua_chave_aqui",
    "amount": 50.00,
    "requestNumber": "PEDIDO-001"
  }'

Respostas HTTP

Nossa API utiliza códigos de status padrão HTTP. Abaixo, os erros mais comuns que você deve tratar no seu sistema.

StatusCódigo de ErroDefinição
200 OKSucesso. Transação criada ou processada.
400invalid_jsonO corpo da requisição não é um JSON válido.
400insufficient_balanceSaldo insuficiente para o saque.
400invalid_amountValor abaixo do mínimo (R$1,00) ou inválido.
401auth_failedAPI Key errada, inativa ou sem permissão.
403unauthorized_ipRequisição bloqueada por segurança (IP não autorizado).
Resposta de Erro (JSON)
{
  "status": "error",
  "message": "Saldo insuficiente para esta operação",
  "error_code": "insufficient_balance",
  "current_balance": 15.50
}
Resposta de Sucesso (JSON)
{
  "status": "success",
  "paymentCode": "00020126...",
  "idTransaction": "ORD_998",
  "amount": 150.00
}

Gerar QRCode PIX

Cria uma cobrança PIX dinâmica. Por padrão, todos os QRCodes gerados têm validade de 24 horas.

Dica

Envie o objeto payer para melhorar a rastreabilidade e facilitar a identificação do cliente no painel.

Parâmetros da Requisição

AtributoTipoDescrição
api_keySimstringSua chave secreta da RevoxPay.
amountSimfloatValor em reais (ex: 20.00). Mínimo: R$ 1,00.
requestNumberSimstringSeu ID único para a transação. Retornado no webhook como correlationID.
postback_urlNãostringSua URL de Webhook para receber o aviso quando o PIX for pago.
payer.nameRec.stringNome completo do pagador.
payer.documentRec.stringCPF ou CNPJ (somente números).
payer.emailNãostringEmail do pagador.
PIX Cash-In — Request (cURL)
curl -X POST https://revoxpay.com/api/pix/index.php \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "revox_live_sua_chave",
    "amount": 150.00,
    "requestNumber": "pedido_042",
    "postback_url": "https://seusite.com/callback.php",
    "payer": {
      "name": "João Silva",
      "document": "12345678900",
      "email": "joao@email.com"
    }
  }'
Response (JSON)
{
  "status": "success",
  "paymentCode": "00020126...",
  "idTransaction": "ORD_998",
  "amount": 150.00
}
Exemplo em PHP
<?php
$dados = [
    'api_key'       => 'revox_live_sua_chave',
    'amount'        => 150.00,
    'requestNumber' => 'pedido_042',
    'postback_url'  => 'https://seusite.com/callback.php',
    'payer'         => [
        'name'     => 'João Silva',
        'document' => '12345678900',
        'email'    => 'joao@email.com',
    ],
];

$ch = curl_init('https://revoxpay.com/api/pix/index.php');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($dados));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

// Use $response['paymentCode'] para exibir o QR Code
?>

Notificações (Webhook)

O Webhook é o coração da integração. Nosso servidor notificará sua URL assim que o status do PIX mudar.

Segurança — Como Validar o Webhook

Ao receber o webhook, nunca credite o valor baseado apenas no campo status. Siga esta sequência obrigatória:

1. Receba o POST no seu postback_url.
2. Leia o campo correlationID — ele é o mesmo requestNumber que você enviou ao gerar o PIX.
3. Busque esse ID no seu banco de dados e confirme que o valor (value) bate com o esperado.
4. Somente então libere o crédito/produto no seu sistema.

Responda sempre com HTTP 200 em até 5 segundos. Respostas lentas causam retentativas.

Status Possíveis

StatusDescrição
PAIDPagamento confirmado. Libere o crédito/produto no seu sistema.
WAITING_FOR_PAYMENTPIX gerado, aguardando pagamento do cliente.
EXPIREDO tempo de validade expirou sem pagamento.
Webhook Payload (JSON recebido)
{
  "event": "PAYMENT_CONFIRMED",
  "status": "PAID",
  "correlationID": "pedido_042",
  "value": 15000,
  "paidAt": "2026-03-04T14:30:00Z"
}
Webhook Handler — callback.php
<?php
// Seu arquivo callback.php (postback URL)
$body = file_get_contents('php://input');
$data = json_decode($body, true);

if ($data['status'] === 'PAID') {
    $ref = $data['correlationID'];
    // ✅ Credite o usuário no seu sistema
    // Ex: atualize o banco de dados, libere o produto

    http_response_code(200);
    echo "OK";
}
?>
Webhook Handler — Node.js
app.post('/callback', (req, res) => {
  const { status, correlationID, value } = req.body;

  if (status === 'PAID') {
    // Credite o usuário
    console.log(`Pago: ${correlationID} - R$${value/100}`);
  }

  res.status(200).send('OK');
});

Consultar Status

Verifique manualmente o status de uma transação (Polling) caso o Webhook não chegue. Aceita tanto GET (query string) quanto POST (body JSON).

Boas Práticas

Recomendamos verificar a cada 30 segundos por no máximo 24 horas. Prefira sempre o Webhook para não sobrecarregar a API.

PAID vs PAID_OUT

No Webhook você recebe status: "PAID" quando o PIX é confirmado.
Na Consulta de Status a transação paga retorna transaction_status: "PAID_OUT". São campos diferentes — não confunda!

Parâmetros (Query String ou JSON)

AtributoTipoDefinição
api_keySimstringSua chave de API.
requestNumberSimstringO mesmo ID que você enviou ao gerar o PIX.
Status Check (cURL)
curl -X GET \
  "https://revoxpay.com/api/status/index.php\
?api_key=revox_live_...&requestNumber=pedido_042"
Status Response (JSON)
{
  "status": "success",
  "type": "PIX_CASHIN",
  "transaction_status": "PAID_OUT",
  "amount": 150.00,
  "external_id": "pedido_042",
  "date": "2026-03-04 14:30:00"
}
Polling em PHP
<?php
function consultarStatus($apiKey, $requestNumber) {
    $url = "https://revoxpay.com/api/status/index.php"
         . "?api_key={$apiKey}&requestNumber={$requestNumber}";

    $res = json_decode(file_get_contents($url), true);

    if ($res['transaction_status'] === 'PAID_OUT') {
        return 'PAGO';
    }
    return $res['transaction_status'];
}
?>

Realizar Saque (Cashout)

Envie pagamentos PIX para seus clientes de forma automatizada e instantânea.

TAXAS

Consulte sua taxa de saque no menu Configurações do painel RevoxPay.

Dicionário de Tipos de Chave PIX

pix_key_typeFormato
CPFApenas números do CPF (11 dígitos).
CNPJApenas números do CNPJ (14 dígitos).
EMAILEmail válido do recebedor.
PHONEFormato Internacional: +5511999998888
EVPChave aleatória (UUID).

Parâmetros da Requisição

AtributoTipoDescrição
api_keySimstringSua chave secreta.
amountSimfloatValor em reais a transferir.
pix_keySimstringA chave PIX do destinatário.
pix_key_typeSimstringTipo da chave: CPF, CNPJ, EMAIL, PHONE ou EVP.
Cashout Request (JSON)
{
  "api_key": "revox_live_sua_chave",
  "amount": 50.00,
  "pix_key": "12345678901",
  "pix_key_type": "CPF"
}
Cashout Response — Sucesso (JSON)
{
  "status": "success",
  "message": "Withdrawal requested successfully",
  "withdrawal_id": 9942,
  "amount_to_player": 50.00,
  "fee_deducted": 1.50,
  "total_balance_deduction": 51.50,
  "status_code": "PENDING"
}
Cashout Response — Saldo Insuficiente (JSON)
{
  "error": "Insufficient balance for amount + fees",
  "requested_amount": 50.00,
  "breakdown": {
    "percent_fee": 2.50,
    "fixed_fee": 1.50,
    "acquirer_fee": 0,
    "total_fee": 4.00
  },
  "total_required": 54.00,
  "current_balance": 30.00
}
Exemplo — PHP
<?php
$saque = [
    'api_key'      => 'revox_live_sua_chave',
    'amount'       => 50.00,
    'pix_key'      => '12345678901',
    'pix_key_type' => 'CPF',
];

$ch = curl_init('https://revoxpay.com/api/index.php');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($saque));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($res['status'] === 'success') {
    echo "Saque enviado! ID: " . $res['withdrawal_id'];
}
?>

Integração com IA

A API RevoxPay é 100% compatível com agentes de IA. Use o prompt abaixo como System Prompt no ChatGPT, Claude ou Gemini para que a IA entenda toda a integração automaticamente.

O que você pode automatizar

Gerar cobranças PIX ao criar pedidos · Processar saques em lote · Monitorar pagamentos via webhook · Reconciliar transações · Criar assistentes financeiros personalizados.

System Prompt — Cole no seu agente de IA

System Prompt — RevoxPay API
Você é um assistente especializado na API RevoxPay, gateway de pagamentos brasileiro. # AUTENTICAÇÃO - Toda requisição usa "api_key" no body JSON - Nunca exponha a api_key em logs ou respostas - Formato: revox_live_XXXXXXXXXXXX # ENDPOINTS PIX Cash-In (cobrança): POST https://revoxpay.com/api/pix/index.php Saque (Cash-Out): POST https://revoxpay.com/api/index.php Consulta de Status: GET https://revoxpay.com/api/status/index.php # GERAR COBRANÇA PIX { "api_key": "revox_live_...", "amount": 100.00, "requestNumber": "ID_UNICO", "postback_url": "https://seusite.com/webhook", "payer": { "name": "Nome do Cliente", "document": "CPF_SEM_PONTOS", "email": "email@exemplo.com" } } # REALIZAR SAQUE PIX { "api_key": "revox_live_...", "amount": 50.00, "pix_key": "12345678901", "pix_key_type": "CPF" } Tipos de chave: CPF, CNPJ, EMAIL, PHONE, EVP # WEBHOOK RECEBIDO (status PAID = pago) { "event": "PAYMENT_CONFIRMED", "status": "PAID", "correlationID": "ID_QUE_VOCE_ENVIOU", "value": 10000, "paidAt": "2026-01-01T12:00:00Z" } # REGRAS 1. Sempre use HTTPS 2. requestNumber deve ser único por transação 3. Responda ao webhook com HTTP 200 em até 5 segundos 4. Valor mínimo: R$ 1,00 5. Valide sempre o correlationID antes de creditar # ERROS COMUNS - auth_failed: API Key inválida - insufficient_balance: Saldo insuficiente - invalid_amount: Valor abaixo do mínimo - invalid_json: Body malformado

Como usar

ChatGPT: Vá em Personalizar ChatGPT → Instruções → Cole o prompt acima.

Claude: Use no início de qualquer conversa como contexto do sistema.

Gemini: Use como System Instruction no AI Studio.

Python — OpenAI Function Calling
import openai, requests, json

client = openai.OpenAI(api_key="sk-...")

tools = [{
  "type": "function",
  "function": {
    "name": "gerar_pix",
    "description": "Gera cobrança PIX na RevoxPay",
    "parameters": {
      "type": "object",
      "properties": {
        "amount": {"type": "number"},
        "payer_name": {"type": "string"},
        "payer_cpf": {"type": "string"}
      },
      "required": ["amount","payer_name","payer_cpf"]
    }
  }
}]

def gerar_pix(amount, payer_name, payer_cpf):
    r = requests.post(
        "https://revoxpay.com/api/pix/index.php",
        json={
            "api_key": "revox_live_...",
            "amount": amount,
            "requestNumber": f"ped_{payer_cpf[:4]}_{int(amount)}",
            "payer": {"name": payer_name, "document": payer_cpf}
        }
    )
    return r.json()

msgs = [{"role":"user","content":"Cobre R$150 do João, CPF 12345678900"}]
res = client.chat.completions.create(model="gpt-4",messages=msgs,tools=tools)

if res.choices[0].finish_reason == "tool_calls":
    args = json.loads(res.choices[0].message.tool_calls[0].function.arguments)
    resultado = gerar_pix(**args)
    print("QR gerado:", resultado['paymentCode'][:30])

Agentes Autônomos

Configure agentes de IA para operar a API RevoxPay de forma totalmente autônoma, 24/7, sem intervenção humana.

Casos de uso

Sistemas de e-commerce que geram cobranças automaticamente · Plataformas que processam saques em lote · Bots de atendimento que consultam status de pagamentos.

Boas Práticas para Agentes

PráticaDetalhes
IdempotênciaUse UUID v4 como requestNumber para evitar duplicatas em retentativas.
Variáveis de AmbienteNunca hardcode a api_key. Use os.environ.get("REVOXPAY_KEY").
Retry com BackoffEm falha de rede: aguarde 1s, depois 2s, 4s antes de tentar novamente.
ReconciliaçãoVerifique transações pendentes via consulta de status a cada 30 segundos.
LogsRegistre cada chamada com timestamp, requestNumber e resposta para auditoria.
Agente Autônomo — Python
import os, uuid, requests, time

API_KEY = os.environ.get("REVOXPAY_API_KEY")

def criar_cobranca(valor, nome, cpf, webhook):
    req_id = str(uuid.uuid4())  # ID único garantido
    payload = {
        "api_key": API_KEY,
        "amount": valor,
        "requestNumber": req_id,
        "postback_url": webhook,
        "payer": {"name": nome, "document": cpf}
    }
    for tentativa in range(3):
        try:
            r = requests.post(
                "https://revoxpay.com/api/pix/index.php",
                json=payload, timeout=10
            )
            return r.json()
        except Exception:
            time.sleep(2 ** tentativa)  # backoff
    return None

def verificar_status(req_id):
    r = requests.get(
        "https://revoxpay.com/api/status/index.php",
        params={"api_key": API_KEY, "requestNumber": req_id}
    )
    return r.json().get("transaction_status")

# Uso:
result = criar_cobranca(99.90, "Maria Silva", "98765432100",
                        "https://meusite.com/webhook")
print(f"PIX: {result['paymentCode'][:20]}...")

# Polling até confirmar
while True:
    st = verificar_status(result['idTransaction'])
    if st == "PAID_OUT": print("Pago!"); break
    time.sleep(30)