Documentação da API

Integre o Avg Pix Digital ao seu sistema de forma simples e rápida

Navegação

Base URL da API (prefixo Laravel /api/v1): https://avgpix.pro/api/v1

Substitua pelo domínio da sua instalação (ex.: https://seudominio.com/api/v1). Todas as rotas abaixo são relativas a essa base. Valores monetários são em reais (decimal, ex.: 10.50).

Introdução

A API do Avg Pix Digital permite que você integre pagamentos PIX e Cartão de Crédito ao seu sistema de forma simples e segura.

Características

  • API RESTful completa
  • Autenticação via Token Bearer
  • Webhooks em tempo real
  • Respostas em JSON

Obter Credenciais de API

Para usar a API, você precisa gerar uma chave de API no painel do sistema.

Passo 1: Acesse a página de Chaves de API

No painel do sistema, acesse a seção "Chave API" no menu lateral.

Ir para Chaves de API →

Passo 2: Gere uma nova chave

Clique em "Gerar Nova Chave" e dê um nome descritivo (ex: "Site Principal", "App Mobile").

⚠️ Importante: Copie e guarde o token imediatamente, pois ele só será exibido uma vez!

Passo 3: Configure no seu sistema

Na criação da chave, o painel exibe dois dados: Client ID e Token (secret). Você deve enviar os dois nas requisições (Bearer + cabeçalho X-Client-ID). O token costuma parecer:

nxp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Algumas integrações legadas funcionam apenas com o token no Authorization; o uso do par Client ID + Token é o método recomendado.

Autenticação HTTP

Todas as rotas sob https://avgpix.pro/api/v1 exigem o middleware de token da API (exceto webhooks públicos próprios do gateway na raiz /api/...).

Cabeçalho Obrigatório Descrição
Authorization Sim Bearer SEU_TOKEN
X-Client-ID Recomendado Mesmo valor de Client ID gerado junto com a chave na área logada.
Accept Recomendado application/json
Content-Type Em POST/PUT application/json

Lista de IPs (saque automático)

Se você cadastrar IPs permitidos na chave de API, apenas essas origens conseguirão usar a credencial — útil contra vazamento de token. Para saques automáticos via API, o IP da sua hospedagem precisa estar na lista e o modo de saque da chave em Automático.

Integração PIX

Crie pagamentos PIX e receba notificações em tempo real quando o pagamento for confirmado.

Endpoint

POST https://avgpix.pro/api/v1/payments/pix

Parâmetros

Campo Tipo Obrigatório Descrição
amount float Sim Valor do pagamento (mínimo: R$ 0,01)
payer_name string Sim Nome completo do pagador
payer_email string Sim Email do pagador
payer_cpf string Sim CPF do pagador (apenas números)
description string Não Descrição do pagamento
external_reference string Não Identificador do seu pedido (até 191 caracteres). Devolvido no callback de confirmação.
callback_url string (URL) Não URL pública HTTPS que recebe POST application/json quando o PIX for pago. Deve responder 200 OK após processar.

O servidor normaliza payer_cpf para 11 dígitos. Em caso de taxa alta em valores muito baixos, a taxa é limitada para que amount_net não fique negativo. Se o provedor PIX não devolver código copia-e-cola (EMV), a API retorna erro 500 com mensagem explicativa.

Resposta de Sucesso (201)

{
  "success": true,
  "data": {
    "transaction_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "external_reference": "PEDIDO_12345",
    "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:00.000000Z",
    "expires_in_seconds": 300
  }
}

Cash-in rápido (alternativo)

Fluxo opcional quando você não precisa informar dados do pagador linha a linha — o sistema monta nome/e-mail/documento a partir do perfil da conta da chave API.

Endpoint

POST https://avgpix.pro/api/v1/cashin/pix
Campo Obrigatório Notas
amount Sim Valor mínimo atual da rota cashin/pix: R$ 1,00.
payer_name Não Quando omitido, usa o nome cadastrado no usuário titular da chave.

Exemplo simplificado da resposta (estrutura real pode incluir outros campos):

{
  "success": true,
  "transaction": { "uuid": "...", "amount_gross": 100.0, "status": "pending" },
  "qr_code": "00020126...",
  "qr_code_image_url": "https://..."
}

Cashout - Saques via PIX

Crie saques via PIX para transferir saldo da conta do usuário para uma chave PIX.

Importante: Para saques automáticos funcionarem, você precisa: 1. Configurar o modo de saque como "Automático" ao criar a credencial de API 2. Adicionar o IP do seu servidor nas configurações da API 3. O usuário precisa estar aprovado (KYC) e com saques desbloqueados

Endpoint

POST https://avgpix.pro/api/v1/cashout/pix

Parâmetros

Campo Tipo Obrigatório Descrição
amount float Sim Valor líquido desejado (mínimo: R$ 10,00). O sistema calcula automaticamente o valor bruto incluindo taxas.
pix_key string Sim Chave PIX de destino (CPF, Email, Telefone ou Chave Aleatória)

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 Transações

Liste e filtre as transações da sua conta ou busque uma transação específica.

Listar Transações

GET https://avgpix.pro/api/v1/transactions

Detalhar uma Transação

GET https://avgpix.pro/api/v1/transactions/{uuid}

Substitua {uuid} pelo transaction_uuid retornado na criação do PIX.

Consultar Cobrança (pagamento PIX)

GET https://avgpix.pro/api/v1/payments/{uuid}

Equivalente ligado ao fluxo POST /payments/pix; mesmo identificador uuid da transação.

Parâmetros (Query — GET /transactions)

Campo Tipo Descrição
status string Filtrar por status (pending, paid, completed, failed, conforme ciclo da transação)
type string Tipo da transação (ex.: pix)
start_date data (YYYY-MM-DD) Início do intervalo (created_at)
end_date data Fim do intervalo
page integer Página atual (paginação Laravel)
per_page integer Itens por página — padrão 20

A lista retorna objeto pagination (current_page, last_page, per_page, total).

Webhooks (Notificações)

Receba notificações automáticas em seu sistema sempre que o status de uma transação mudar.

Callback HTTP para o seu site (integrações)

Ao criar cobrança com POST /payments/pix, você pode incluir callback_url — uma URL HTTPS acessível publicamente onde seu próprio servidor recebe confirmação de pagamento. Isso é independente dos webhooks configurados ao adquirente (BsPay/Venit, etc.) dentro do painel.

O envio só funciona quando a instância gravou corretamente a URL/referência no banco (colunas opcionais merchant_callback_url / merchant_external_reference). Use JSON external_reference no mesmo POST para correlacionar com seu pedido.

Eventos (visão integrador)

Evento Descrição
payment.paid POST para o seu callback_url quando o PIX é confirmado. Corpo atual documentado ao lado.
Notificações do adquirente O gateway interno também recebe postbacks (/api/webhooks/bspay, Venit etc.) configurados pela equipe técnica — não é esse o endpoint da sua integração.

Corpo típico: payment.paid → seu callback_url

Payload enviado em POST application/json (implementação atual do servidor).

{
  "event": "payment.paid",
  "data": {
    "transaction_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "external_reference": "PEDIDO_123",
    "status": "paid",
    "amount": 150.00,
    "amount_net": 145.50,
    "paid_at": "2024-01-20T10:35:00+00:00"
  }
}

external_reference pode vir null se não foi enviado na criação. Trate sempre transaction_uuid como referência oficial.

Resposta Esperada

Seu endpoint deve responder HTTP 200 OK com corpo opcionalmente JSON ({\"status\":\"success\"}). Se retornar HTTP 500 após falha interna, o lado integrador deve reaproveitar a lógica de retry própria; valide duplicidade por transaction_uuid.

Exemplo em PHP

Exemplo de criação de pagamento PIX usando Guzzle.

<?php

$client = new \GuzzleHttp\Client();

$response = $client->post('https://avgpix.pro/api/v1/payments/pix', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'X-Client-ID' => 'SEU_CLIENT_ID',
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'amount' => 100.00,
        'payer_name' => 'João Silva',
        'payer_email' => 'joao@email.com',
        'payer_cpf' => '12345678900',
        'description' => 'Pagamento de Teste',
        'external_reference' => 'PEDIDO_12345',
        'callback_url' => 'https://seudominio.com/seu-webhook-pix.php'
    ]
]);

$body = json_decode($response->getBody(), true);
print_r($body);

Exemplo em Python

Exemplo usando a biblioteca requests.

import requests

url = "https://avgpix.pro/api/v1/payments/pix"

payload = {
    "amount": 100.00,
    "payer_name": "João Silva",
    "payer_email": "joao@email.com",
    "payer_cpf": "12345678900",
    "description": "Pagamento de Teste",
    "external_reference": "PEDIDO_12345",
    "callback_url": "https://seudominio.com/seu-webhook-pix.php"
}

headers = {
    "Authorization": "Bearer SEU_TOKEN",
    "X-Client-ID": "SEU_CLIENT_ID",
    "Accept": "application/json",
    "Content-Type": "application/json"
}

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

print(response.json())

Exemplo em JavaScript

Exemplo usando fetch API.

const url = "https://avgpix.pro/api/v1/payments/pix";

const payload = {
    amount: 100.00,
    payer_name: "João Silva",
    payer_email: "joao@email.com",
    payer_cpf: "12345678900",
    description: "Pagamento de Teste",
    external_reference: "PEDIDO_12345",
    callback_url: "https://seudominio.com/seu-webhook-pix.php"
};

const headers = {
    "Authorization": "Bearer SEU_TOKEN",
    "X-Client-ID": "SEU_CLIENT_ID",
    "Accept": "application/json",
    "Content-Type": "application/json"
};

fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error("Error:", error));

Exemplo cURL

curl -X POST "https://avgpix.pro/api/v1/payments/pix" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "X-Client-ID: SEU_CLIENT_ID" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "payer_name": "João Silva",
    "payer_email": "joao@email.com",
    "payer_cpf": "12345678900",
    "description": "Pagamento de Teste",
    "external_reference": "PEDIDO_12345",
    "callback_url": "https://seudominio.com/seu-webhook-pix.php"
  }'

Códigos de Erro

Lista de possíveis códigos de status HTTP retornados pela API.

Código Significado Descrição
200 OK Requisição processada com sucesso.
201 Created Recurso criado com sucesso (ex: novo pagamento).
400 Bad Request Dados inválidos enviados na requisição. Verifique os campos.
401 Unauthorized Token inválido ou não fornecido.
403 Forbidden Acesso negado ao recurso solicitado.
404 Not Found Recurso não encontrado (ex: transação inexistente).
422 Unprocessable Entity Erro de validação (ex: email inválido, saldo insuficiente).
500 Internal Server Error Erro interno do servidor. Tente novamente mais tarde.