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.
# 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.
{
"api_key": "revox_live_xxxxxxxxxxxxxxxxxxxxx",
"amount": 100.00,
"requestNumber": "pedido_001"
}
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.
| Status | Código de Erro | Definição |
|---|---|---|
| 200 OK | — | Sucesso. Transação criada ou processada. |
| 400 | invalid_json | O corpo da requisição não é um JSON válido. |
| 400 | insufficient_balance | Saldo insuficiente para o saque. |
| 400 | invalid_amount | Valor abaixo do mínimo (R$1,00) ou inválido. |
| 401 | auth_failed | API Key errada, inativa ou sem permissão. |
| 403 | unauthorized_ip | Requisição bloqueada por segurança (IP não autorizado). |
{
"status": "error",
"message": "Saldo insuficiente para esta operação",
"error_code": "insufficient_balance",
"current_balance": 15.50
}
{
"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
| Atributo | Tipo | Descrição |
|---|---|---|
| api_keySim | string | Sua chave secreta da RevoxPay. |
| amountSim | float | Valor em reais (ex: 20.00). Mínimo: R$ 1,00. |
| requestNumberSim | string | Seu ID único para a transação. Retornado no webhook como correlationID. |
| postback_urlNão | string | Sua URL de Webhook para receber o aviso quando o PIX for pago. |
| payer.nameRec. | string | Nome completo do pagador. |
| payer.documentRec. | string | CPF ou CNPJ (somente números). |
| payer.emailNão | string | Email do pagador. |
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"
}
}'
{
"status": "success",
"paymentCode": "00020126...",
"idTransaction": "ORD_998",
"amount": 150.00
}
<?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
| Status | Descrição |
|---|---|
| PAID | Pagamento confirmado. Libere o crédito/produto no seu sistema. |
| WAITING_FOR_PAYMENT | PIX gerado, aguardando pagamento do cliente. |
| EXPIRED | O tempo de validade expirou sem pagamento. |
{
"event": "PAYMENT_CONFIRMED",
"status": "PAID",
"correlationID": "pedido_042",
"value": 15000,
"paidAt": "2026-03-04T14:30:00Z"
}
<?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";
}
?>
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)
| Atributo | Tipo | Definição |
|---|---|---|
| api_keySim | string | Sua chave de API. |
| requestNumberSim | string | O mesmo ID que você enviou ao gerar o PIX. |
curl -X GET \
"https://revoxpay.com/api/status/index.php\
?api_key=revox_live_...&requestNumber=pedido_042"
{
"status": "success",
"type": "PIX_CASHIN",
"transaction_status": "PAID_OUT",
"amount": 150.00,
"external_id": "pedido_042",
"date": "2026-03-04 14:30:00"
}
<?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_type | Formato |
|---|---|
| CPF | Apenas números do CPF (11 dígitos). |
| CNPJ | Apenas números do CNPJ (14 dígitos). |
| Email válido do recebedor. | |
| PHONE | Formato Internacional: +5511999998888 |
| EVP | Chave aleatória (UUID). |
Parâmetros da Requisição
| Atributo | Tipo | Descrição |
|---|---|---|
| api_keySim | string | Sua chave secreta. |
| amountSim | float | Valor em reais a transferir. |
| pix_keySim | string | A chave PIX do destinatário. |
| pix_key_typeSim | string | Tipo da chave: CPF, CNPJ, EMAIL, PHONE ou EVP. |
{
"api_key": "revox_live_sua_chave",
"amount": 50.00,
"pix_key": "12345678901",
"pix_key_type": "CPF"
}
{
"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"
}
{
"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
}
<?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
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.
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ática | Detalhes |
|---|---|
| Idempotência | Use UUID v4 como requestNumber para evitar duplicatas em retentativas. |
| Variáveis de Ambiente | Nunca hardcode a api_key. Use os.environ.get("REVOXPAY_KEY"). |
| Retry com Backoff | Em falha de rede: aguarde 1s, depois 2s, 4s antes de tentar novamente. |
| Reconciliação | Verifique transações pendentes via consulta de status a cada 30 segundos. |
| Logs | Registre cada chamada com timestamp, requestNumber e resposta para auditoria. |
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)