Documentação da API
Bem-vindo à documentação técnica da API REST do AvanPay Gateway. Aqui você encontra tudo que precisa para integrar pagamentos PIX, consultar transações, gerenciar saques e configurar webhooks.
Base URL:
https://api.avanpay.com.br/apiSuporte: suporte@avanpay.com.br
Visão Geral
A API do AvanPay é um gateway de pagamento completo que permite processar pagamentos via PIX, Boleto e Cartão de Crédito de forma simples e segura.
Características
Autenticação
A API do AvanPay suporta dois métodos de autenticação: JWT Token (Bearer Token) para aplicações web e frontend, e API Keys para integrações server-to-server.
JWT Token (Bearer Token)
O método de autenticação via JWT Token é recomendado para aplicações web e frontend. O token deve ser incluído no header Authorization de todas as requisições autenticadas.
Authorization: Bearer {seu_token_jwt}
Obtenção do Token
Para obter um token JWT, realize uma requisição de autenticação no endpoint /api/auth/login com suas credenciais. O processo consiste em:
- Realizar requisição POST para
/api/auth/logincom email e senha - Receber
accessTokenerefreshTokenna resposta - Utilizar o
accessTokenno headerAuthorizationde requisições subsequentes - Utilizar o
refreshTokenpara renovar o token quando necessário
Autentica usuário e retorna tokens JWT para acesso à API.
Request Body
{
"email": "empresa@exemplo.com",
"password": "senhaSegura123"
}
Response (200 OK)
{
"success": true,
"data": {
"user": {
"id": 1,
"name": "Nome da Empresa",
"email": "empresa@exemplo.com"
},
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
}
API Keys
O método de autenticação via API Keys é recomendado para integrações server-to-server. As chaves devem ser incluídas nos headers de todas as requisições.
X-API-Public-Key: {sua_public_key}
X-API-Secret-Key: {sua_secret_key}
Pagamento PIX
O endpoint de pagamento PIX permite criar transações de pagamento instantâneo via PIX. Os pagamentos PIX são processados em tempo real e oferecem confirmação imediata após a realização do pagamento.
Headers
| Header | Tipo | Descrição |
|---|---|---|
Authorization |
string | Token JWT ou API Keys * |
Idempotency-Key |
string | Chave única para garantir idempotência (opcional) |
Content-Type |
string | application/json * |
Request:
POST /api/payments/pix
Authorization: Bearer {token}
Content-Type: application/json
{
"amount": 10000,
"sellerExternalRef": "PEDIDO-123",
"customer": {
"name": "João Silva",
"email": "joao@example.com",
"phone": "11999999999",
"documentType": "CPF",
"document": "12345678900"
},
"items": [
{
"title": "Produto Exemplo",
"quantity": 1,
"amount": 10000,
"tangible": true
}
],
"postbackUrl": "https://seu-site.com/api/webhooks/provider/AvanPay",
"metadata": {
"orderId": "12345",
"customField": "valor"
}
}
Parâmetros Comuns
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
amount |
integer | * | Valor em centavos (ex: 10000 = R$ 100,00) |
sellerExternalRef |
string | * | Referência externa do pedido |
customer |
object | * | Dados do cliente |
customer.name |
string | * | Nome completo |
customer.email |
string | * | E-mail válido |
customer.phone |
string | * | Telefone (apenas números) |
customer.documentType |
string | * | CPF ou CNPJ |
customer.document |
string | * | CPF/CNPJ (apenas números) |
items |
array | * | Array de itens |
items[].title |
string | * | Nome do item |
items[].quantity |
integer | * | Quantidade |
items[].amount |
integer | * | Valor unitário em centavos |
items[].tangible |
boolean | * | Se é produto físico |
postbackUrl |
string | - | URL para receber webhooks (ex: https://seu-site.com/api/webhooks/provider/AvanPay). Deve ser a mesma URL cadastrada no painel. |
metadata |
object | - | Dados adicionais (JSON) |
preferredProvider |
string | - | Provider preferido (starkpay, witetec) |
Response (201 Created):
{
"success": true,
"data": {
"id": "tx_abc123",
"status": "WAITING_PAYMENT",
"amount": 10000,
"pix": {
"qrcode": "data:image/png;base64,iVBORw0KGgo...",
"copyPaste": "00020126360014BR.GOV.BCB.PIX...",
"expirationDate": "2024-12-03T10:00:00Z"
},
"createdAt": "2024-12-02T10:00:00Z"
}
}
Status da Transação
WAITING_PAYMENT- Aguardando pagamento pelo clientePAID- Pagamento confirmado e processadoEXPIRED- Prazo de pagamento expiradoCANCELLED- Transação canceladaFAILED- Falha no processamento
Transações
Os endpoints de transações permitem consultar e gerenciar todas as transações realizadas através da API. É possível listar transações com filtros e paginação, além de consultar detalhes de transações específicas.
Lista todas as transações com suporte a filtros e paginação.
Query Parameters
| Parâmetro | Tipo | Descrição |
|---|---|---|
page |
number | Número da página (padrão: 1) |
limit |
number | Itens por página (padrão: 20, máximo: 100) |
status |
string | Filtrar por status da transação |
type |
string | Filtrar por tipo (PIX, BOLETO, CARD) |
startDate |
string | Data inicial no formato ISO 8601 |
endDate |
string | Data final no formato ISO 8601 |
Consultar Transação
Response:
{
"success": true,
"data": {
"id": "tx_abc123",
"status": "PAID",
"amount": 10000,
"paymentMethod": "PIX",
"customer": { ... },
"items": [ ... ],
"pix": { ... },
"createdAt": "2024-12-02T10:00:00Z",
"paidAt": "2024-12-02T10:05:00Z"
}
}
Listar Transações
Query Parameters: page, limit, status, type, startDate, endDate
Saldo
O endpoint de saldo permite consultar o saldo disponível, pendente e bloqueado da conta.
Response (200 OK)
{
"success": true,
"data": {
"available": 5000.00,
"pending": 1000.00,
"blocked": 500.00,
"currency": "BRL"
}
}
Saques
O endpoint de saques permite criar solicitações de saque para contas bancárias cadastradas. Os saques são processados conforme a política de liquidação configurada.
Criar Saque
Request:
POST /api/payments/cash-out
Authorization: Bearer {token}
Content-Type: application/json
{
"amount": 5000,
"pixKey": "11999999999",
"pixKeyType": "PHONE",
"method": "PIX",
"sellerExternalRef": "SAQUE-001"
}
Tipos de Chave PIX:
CPF: CPF (11 dígitos)CNPJ: CNPJ (14 dígitos)EMAIL: E-mail válidoPHONE: Telefone (+5511999999999)EVP: Chave aleatória (UUID)
Response:
{
"success": true,
"data": {
"id": "cashout_abc123",
"status": "PENDING",
"amount": 5000,
"pixKey": "11999999999",
"pixKeyType": "PHONE",
"createdAt": "2024-12-02T10:00:00Z"
}
}
Consultar Saque
Listar Saques
Webhooks
Os webhooks permitem receber notificações em tempo real sobre eventos de pagamento e transações. A AvanPay enviará uma requisição HTTP POST para a URL cadastrada sempre que um evento relevante ocorrer.
1. Cadastrar URL do Webhook
Cadastre a URL do webhook no Painel AvanPay (Configurações → Webhooks). A URL deve seguir o padrão:
https://seu-site.com/api/webhooks/provider/AvanPay
postbackUrl ao criar pagamentos. Exemplo: se você cadastrou https://seu-site.com/api/webhooks/provider/AvanPay, use essa mesma URL no postbackUrl.
2. Enviar postbackUrl ao Criar Pagamento
Ao criar um pagamento PIX, inclua o campo postbackUrl com a mesma URL cadastrada no painel:
{
"amount": 10000,
"postbackUrl": "https://seu-site.com/api/webhooks/provider/AvanPay",
"customer": { ... },
"items": [ ... ]
}
3. Payload Recebido
Quando um evento ocorrer, a AvanPay enviará um POST para sua URL com o seguinte payload normalizado:
{
"id": 1053,
"transactionId": 1053,
"event": "pix.confirmed",
"provider": "avanpay",
"status": "PAID",
"amount": 10000,
"amount_brl": 100.00,
"createdAt": "2026-02-10T17:30:44.000Z",
"updatedAt": "2026-02-10T17:31:02.000Z",
"paidAt": "2026-02-10T17:31:02.000Z",
"customer": {
"name": "João Silva",
"email": "joao@example.com",
"phone": "11999999999",
"document": { "type": "CPF", "number": "123.456.789-00" }
},
"items": [
{ "title": "Produto", "quantity": 1, "amount": 10000 }
],
"metadata": {
"externalRef": "PEDIDO-123",
"paymentType": "PIX",
"paymentMethod": "PIX",
"postbackUrl": "https://seu-site.com/api/webhooks/provider/AvanPay"
}
}
Campos do Payload
| Campo | Tipo | Descrição |
|---|---|---|
id / transactionId |
integer | ID interno da transação na AvanPay |
event |
string | Tipo do evento (ex: pix.confirmed, cashout.completed) |
provider |
string | Sempre "avanpay" |
status |
string | Status da transação: PENDING, PAID, EXPIRED, CANCELLED, FAILED |
amount |
integer | Valor em centavos (ex: 10000 = R$ 100,00) |
amount_brl |
float | Valor em reais (ex: 100.00) |
paidAt |
string | Data/hora do pagamento (ISO 8601) |
customer |
object | Dados do cliente (nome, email, telefone, documento) |
metadata |
object | Dados adicionais, incluindo externalRef (sua referência do pedido) |
4. Headers da Requisição
A AvanPay inclui headers de segurança em cada webhook enviado:
| Header | Descrição |
|---|---|
X-Webhook-Signature |
Assinatura HMAC-SHA256 do payload (v1=abc123...) |
X-Webhook-Timestamp |
Timestamp Unix da assinatura |
X-Webhook-Id |
ID único da entrega (UUID) |
X-Webhook-Event |
Tipo do evento (ex: pix.confirmed) |
Content-Type |
application/json |
5. Validação de Assinatura
Valide a assinatura HMAC-SHA256 para garantir que o webhook é legítimo:
// Node.js
const crypto = require('crypto');
function validateWebhook(payload, signature, secret, timestamp) {
const message = `${timestamp}.${JSON.stringify(payload)}`;
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(message)
.digest('hex');
return `v1=${expectedSignature}` === signature;
}
// PHP
function validateWebhook($payload, $signature, $secret, $timestamp) {
$message = $timestamp . '.' . json_encode($payload);
$expectedSignature = 'v1=' . hash_hmac('sha256', $message, $secret);
return hash_equals($expectedSignature, $signature);
}
6. Exemplo de Recebimento
PHP (Laravel / Vanilla)
<?php
// Rota: POST /api/webhooks/provider/AvanPay
$payload = json_decode(file_get_contents('php://input'), true);
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';
$event = $_SERVER['HTTP_X_WEBHOOK_EVENT'] ?? '';
// Validar assinatura (opcional mas recomendado)
$secret = 'SUA_SECRET_KEY'; // Obtida no painel AvanPay
$message = $timestamp . '.' . json_encode($payload);
$expectedSig = 'v1=' . hash_hmac('sha256', $message, $secret);
if (!hash_equals($expectedSig, $signature)) {
http_response_code(401);
echo json_encode(['error' => 'Assinatura inválida']);
exit;
}
// Processar o evento
$transactionId = $payload['transactionId'];
$status = $payload['status'];
$amount = $payload['amount_brl'];
$eventType = $payload['event'];
switch ($eventType) {
case 'pix.confirmed':
// Pagamento PIX confirmado - creditar saldo do usuário
// $amount contém o valor em reais
break;
case 'pix.expired':
// PIX expirado - cancelar pedido
break;
case 'cashout.completed':
// Saque processado com sucesso
break;
case 'cashout.failed':
// Saque falhou - reverter
break;
}
// IMPORTANTE: Sempre retornar 200
http_response_code(200);
echo json_encode(['received' => true]);
?>
Node.js (Express)
const express = require('express');
const crypto = require('crypto');
const app = express();
app.use(express.json());
// Rota: POST /api/webhooks/provider/AvanPay
app.post('/api/webhooks/provider/AvanPay', (req, res) => {
const payload = req.body;
const signature = req.headers['x-webhook-signature'];
const timestamp = req.headers['x-webhook-timestamp'];
// Processar evento
const { transactionId, event, status, amount_brl } = payload;
console.log(`Evento: ${event}, Tx: ${transactionId}, Status: ${status}, Valor: R$${amount_brl}`);
switch (event) {
case 'pix.confirmed':
// Pagamento confirmado
break;
case 'cashout.completed':
// Saque processado
break;
}
// IMPORTANTE: Sempre retornar 200
res.status(200).json({ received: true });
});
Python (Flask)
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/api/webhooks/provider/AvanPay', methods=['POST'])
def webhook_AvanPay():
payload = request.get_json()
event = payload.get('event')
status = payload.get('status')
transaction_id = payload.get('transactionId')
amount = payload.get('amount_brl')
if event == 'pix.confirmed':
# Pagamento confirmado
print(f'PIX confirmado: Tx {transaction_id}, R${amount}')
elif event == 'cashout.completed':
# Saque processado
print(f'Saque processado: Tx {transaction_id}')
# IMPORTANTE: Sempre retornar 200
return jsonify({'received': True}), 200
200 OK em até 5 segundos. Se não responder 200, o webhook será reenviado até 5 vezes com backoff exponencial (30s, 60s, 120s, 240s).
postbackUrl enviada na criação do pagamento devem ser idênticas. Se forem diferentes, o webhook não será entregue.
Eventos de Webhook
Lista completa de eventos disponíveis para configuração de webhooks.
Eventos Enviados
| Evento | Descrição | Quando é Enviado |
|---|---|---|
pix.received |
PIX criado | Quando o QR Code é gerado |
pix.confirmed |
PIX pago | Quando o pagamento é confirmado |
pix.expired |
PIX expirado | Quando o QR Code expira |
pix.cancelled |
PIX cancelado | Quando é cancelado |
card.authorized |
Cartão autorizado | Quando a autorização é aprovada |
card.paid |
Cartão pago | Quando o pagamento é capturado |
card.refused |
Cartão recusado | Quando é recusado |
boleto.created |
Boleto criado | Quando o boleto é gerado |
boleto.paid |
Boleto pago | Quando é pago |
cashout.created |
Saque criado | Quando o saque é solicitado |
cashout.completed |
Saque concluído | Quando é processado |
cashout.failed |
Saque falhou | Quando falha |
Códigos de Status
Status de Transação
| Status | Descrição |
|---|---|
WAITING_PAYMENT |
Aguardando pagamento |
PAID |
Pago com sucesso |
REJECTED |
Recusado |
CANCELLED |
Cancelado |
REFUNDED |
Estornado |
EXPIRED |
Expirado |
FAILED |
Falhou |
PENDING |
Em análise |
Status de Saque
| Status | Descrição |
|---|---|
PENDING |
Aguardando aprovação |
APPROVED |
Aprovado |
PROCESSING |
Em processamento |
COMPLETED |
Concluído |
FAILED |
Falhou |
REJECTED |
Rejeitado |
CANCELLED |
Cancelado |
Tratamento de Erros
Códigos HTTP
| Código | Descrição |
|---|---|
200 |
Sucesso |
201 |
Criado com sucesso |
400 |
Requisição inválida |
401 |
Não autorizado |
403 |
Proibido |
404 |
Não encontrado |
429 |
Rate limit excedido |
500 |
Erro interno do servidor |
Formato de Erro
{
"success": false,
"message": "Descrição do erro",
"error": {
"code": "ERROR_CODE",
"details": "Detalhes adicionais"
}
}
Erros Comuns
| Código | Descrição | Solução |
|---|---|---|
UNAUTHORIZED |
Token inválido ou expirado | Renovar token |
INVALID_AMOUNT |
Valor inválido | Verificar valor mínimo (R$ 1,00) |
INVALID_DOCUMENT |
CPF/CNPJ inválido | Verificar formato |
INSUFFICIENT_BALANCE |
Saldo insuficiente | Verificar saldo |
RATE_LIMIT_EXCEEDED |
Muitas requisições | Aguardar ou aumentar limite |
Exemplos de Integração
Esta seção contém exemplos práticos de integração em diferentes linguagens de programação. Utilize estes exemplos como base para implementar sua integração.
JavaScript / Node.js - Autenticação via JWT Token
const axios = require('axios');
// Usando JWT Token
const api = axios.create({
baseURL: 'https://api.avanpay.com.br/api',
headers: {
'Authorization': `Bearer ${process.env.JWT_TOKEN}`,
'Content-Type': 'application/json'
}
});
// Criar pagamento PIX
async function createPixPayment() {
try {
const response = await api.post('/payments/pix', {
amount: 10000,
sellerExternalRef: 'PEDIDO-123',
customer: {
name: 'João Silva',
email: 'joao@example.com',
phone: '11999999999',
documentType: 'CPF',
document: '12345678900'
},
items: [{
title: 'Produto',
quantity: 1,
amount: 10000,
tangible: true
}],
postbackUrl: 'https://seu-site.com/api/webhooks/provider/AvanPay'
});
console.log('Pagamento criado:', response.data);
return response.data;
} catch (error) {
console.error('Erro:', error.response?.data || error.message);
throw error;
}
}
JavaScript / Node.js - Autenticação via API Keys
const axios = require('axios');
// Usando API Keys
const api = axios.create({
baseURL: 'https://api.avanpay.com.br/api',
headers: {
'X-API-Public-Key': process.env.API_PUBLIC_KEY,
'X-API-Secret-Key': process.env.API_SECRET_KEY,
'Content-Type': 'application/json'
}
});
// Criar pagamento PIX
async function createPixPayment() {
try {
const response = await api.post('/payments/pix', {
amount: 10000,
sellerExternalRef: 'PEDIDO-123',
customer: {
name: 'João Silva',
email: 'joao@example.com',
phone: '11999999999',
documentType: 'CPF',
document: '12345678900'
},
items: [{
title: 'Produto',
quantity: 1,
amount: 10000,
tangible: true
}],
postbackUrl: 'https://seu-site.com/api/webhooks/provider/AvanPay'
});
console.log('Pagamento criado:', response.data);
return response.data;
} catch (error) {
console.error('Erro:', error.response?.data || error.message);
throw error;
}
}
Python - Autenticação via JWT Token
import requests
# Usando JWT Token
url = 'https://api.avanpay.com.br/api/payments/pix'
headers = {
'Authorization': f'Bearer {JWT_TOKEN}',
'Content-Type': 'application/json'
}
data = {
'amount': 10000,
'sellerExternalRef': 'PEDIDO-123',
'customer': {
'name': 'João Silva',
'email': 'joao@example.com',
'phone': '11999999999',
'documentType': 'CPF',
'document': '12345678900'
},
'items': [{
'title': 'Produto',
'quantity': 1,
'amount': 10000,
'tangible': True
}]
}
response = requests.post(url, json=data, headers=headers)
if response.status_code == 201:
print('Pagamento criado:', response.json())
else:
print('Erro:', response.json())
Python - Autenticação via API Keys
import requests
# Usando API Keys
url = 'https://api.avanpay.com.br/api/payments/pix'
headers = {
'X-API-Public-Key': 'pk_1234567890abcdef',
'X-API-Secret-Key': 'sk_abcdef1234567890',
'Content-Type': 'application/json'
}
data = {
'amount': 10000,
'sellerExternalRef': 'PEDIDO-123',
'customer': {
'name': 'João Silva',
'email': 'joao@example.com',
'phone': '11999999999',
'documentType': 'CPF',
'document': '12345678900'
},
'items': [{
'title': 'Produto',
'quantity': 1,
'amount': 10000,
'tangible': True
}]
}
response = requests.post(url, json=data, headers=headers)
if response.status_code == 201:
print('Pagamento criado:', response.json())
else:
print('Erro:', response.json())
PHP - Autenticação via JWT Token
<?php
// Usando JWT Token
$jwtToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
$url = 'https://api.avanpay.com.br/api/payments/pix';
$data = [
'amount' => 10000,
'sellerExternalRef' => 'PEDIDO-123',
'customer' => [
'name' => 'João Silva',
'email' => 'joao@example.com',
'phone' => '11999999999',
'documentType' => 'CPF',
'document' => '12345678900'
],
'items' => [[
'title' => 'Produto',
'quantity' => 1,
'amount' => 10000,
'tangible' => true
]]
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer ' . $jwtToken,
'Content-Type: application/json'
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode === 201) {
$result = json_decode($response, true);
echo "Pagamento criado: " . $result['data']['id'];
} else {
echo "Erro: " . $response;
}
?>
PHP - Autenticação via API Keys
<?php
// Usando API Keys
$publicKey = 'pk_1234567890abcdef';
$secretKey = 'sk_abcdef1234567890';
$url = 'https://api.avanpay.com.br/api/payments/pix';
$data = [
'amount' => 10000,
'sellerExternalRef' => 'PEDIDO-123',
'customer' => [
'name' => 'João Silva',
'email' => 'joao@example.com',
'phone' => '11999999999',
'documentType' => 'CPF',
'document' => '12345678900'
],
'items' => [[
'title' => 'Produto',
'quantity' => 1,
'amount' => 10000,
'tangible' => true
]]
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'X-API-Public-Key: ' . $publicKey,
'X-API-Secret-Key: ' . $secretKey,
'Content-Type: application/json'
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode === 201) {
$result = json_decode($response, true);
echo "Pagamento criado: " . $result['data']['id'];
} else {
echo "Erro: " . $response;
}
?>
cURL - Autenticação via JWT Token
curl -X POST https://api.avanpay.com.br/api/payments/pix \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json" \
-d '{
"amount": 10000,
"sellerExternalRef": "PEDIDO-123",
"customer": {
"name": "João Silva",
"email": "joao@example.com",
"phone": "11999999999",
"documentType": "CPF",
"document": "12345678900"
},
"items": [
{
"title": "Produto",
"quantity": 1,
"amount": 10000,
"tangible": true
}
],
"postbackUrl": "https://seu-site.com/api/webhooks/provider/AvanPay"
}'
cURL - Autenticação via API Keys
curl -X POST https://api.avanpay.com.br/api/payments/pix \
-H "X-API-Public-Key: pk_1234567890abcdef" \
-H "X-API-Secret-Key: sk_abcdef1234567890" \
-H "Content-Type: application/json" \
-d '{
"amount": 10000,
"sellerExternalRef": "PEDIDO-123",
"customer": {
"name": "João Silva",
"email": "joao@example.com",
"phone": "11999999999",
"documentType": "CPF",
"document": "12345678900"
},
"items": [
{
"title": "Produto",
"quantity": 1,
"amount": 10000,
"tangible": true
}
],
"postbackUrl": "https://seu-site.com/api/webhooks/provider/AvanPay"
}'
Suporte
- E-mail: suporte@avanpay.com.br
- Documentação: https://doc.avanpay.com.br
- Status: https://status.avanpay.com.br
Última atualização: Fevereiro 2026