Visão geral
A API REST da AveroPay recebe e paga por PIX: cobranças com checkout hospedado, links de pagamento, pagamentos para chaves PIX, devoluções e a defesa de MED. JSON nos dois sentidos, valores em texto decimal com a moeda ao lado e um webhook assinado para cada mudança.
Endereço e autenticação
Todas as rotas ficam em https://api.averopay.io/v1 (o endereço dos exemplos). Cada chamada leva a sua chave em Authorization: Bearer sk_…; o prefixo da chave decide o ambiente: sk_test_ no teste, sk_live_ em produção. Tudo o que a API devolve é da empresa e do ambiente da chave: uma chave de teste nunca vê dado de produção.
GET /v1/account não exige escopo e responde com a empresa, o ambiente e os escopos da chave: é o jeito mais rápido de conferir a integração. Mais em Chaves de API e escopos.
Convenções
- Valores em texto decimal com ponto, na escala da moeda (
"150.00"em BRL), sempre comcurrencyao lado. Moedas nunca são somadas nem convertidas. - Datas em ISO 8601, em UTC na resposta (
"2026-11-03T14:32:08.512Z"). - Ids com prefixo:
ch_cobrança,plk_link de pagamento,po_pagamento,re_devolução,dsp_disputa,evt_evento. Guarde como texto, sem supor tamanho nem formato. - Campo desconhecido no corpo é recusado com
VALIDATION_ERROR. Já nas respostas e nos webhooks, campos novos podem aparecer: ignore o que o seu código não conhece. - Criar cobrança, devolução, pagamento, link de pagamento e evidência de MED exige Idempotency-Key.
Envelope de resposta
Toda resposta vem no mesmo envelope: success, message (em português, para pessoas), statusCode (igual ao status HTTP) e data. No erro, data dá lugar a error.code, em inglês e estável, e error.details quando houver. Veja Formato de erro.
{
"success": true,
"message": "Cobrança",
"statusCode": 200,
"data": { "id": "ch_7Hq2Kd8Wf91a", "object": "charge", … }
}Paginação
As listas (GET /v1/charges, /v1/payment-links, /v1/payouts, /v1/disputes, /v1/beneficiaries e /v1/events) vêm da mais recente para a mais antiga, em data.items, com data.nextCursor. Para a próxima página, mande ?cursor= com esse valor; null é o fim. limit vai de 1 a 100 (padrão 20). O cursor é opaco: não monte nem altere.
As listas de uma cobrança (/refunds e /disputes) e as contas de saque vêm inteiras, sem cursor. /v1/customers pagina por número (?page=, 20 por página, com total): a ordem muda a cada pagamento. Exemplo completo em Listar cobranças.
Limite de requisições
Cada chave faz até 1.200 requisições por minuto. Passou disso, a resposta é 429 RATE_LIMITED, com os segundos até a janela abrir de novo em error.details.retryAfterSeconds.
HTTP/1.1 429 Too Many Requests
{
"success": false,
"message": "Muitas requisições. Tente novamente em instantes",
"statusCode": 429,
"error": { "code": "RATE_LIMITED", "details": { "retryAfterSeconds": 23 } }
}X-Request-Id
Toda resposta traz X-Request-Id. Se você mandar o seu (de 8 a 64 caracteres: letras, números, _ e -), ele volta igual; senão vem um req_…. Guarde nos seus logs e mande junto quando falar com o suporte. As chamadas a /v1 também aparecem no painel, em Desenvolvedores › Logs de requisições.
Rotas
| Método | Rota | Escopo | O que faz |
|---|---|---|---|
GET | /v1/account | nenhum | Empresa, ambiente e escopos da chave usada. |
GET | /v1/balances | balance: read | Saldos por moeda: disponível, a receber, reserva e bloqueado. |
POST | /v1/charges | charges: write | Criar cobrança |
GET | /v1/charges | charges: read | Listar cobranças |
GET | /v1/charges/:id | charges: read | Consultar cobrança |
POST | /v1/charges/:id/cancel | charges: write | Cancelar uma cobrança pendente |
POST | /v1/charges/:id/refunds | charges: write | Criar devolução |
GET | /v1/charges/:id/refunds | charges: read | Devoluções da cobrança. |
GET | /v1/refunds/:id | charges: read | Uma devolução. |
GET | /v1/charges/:id/disputes | disputes: read | Disputas (MED) da cobrança. |
POST | /v1/payment-links | charges: write | Criar link de pagamento |
GET | /v1/payment-links | charges: read | Links de pagamento |
GET | /v1/payment-links/:id | charges: read | Um link, com usos e recebido. |
PATCH | /v1/payment-links/:id | charges: write | Nome, limite de usos e validade. |
POST | /v1/payment-links/:id/pause · activate · archive | charges: write | Pausar, reativar ou arquivar. |
POST | /v1/payouts | payouts: write | Criar pagamento PIX |
GET | /v1/payouts | payouts: read | Pagamentos, mais recentes primeiro. |
GET | /v1/payouts/:id | payouts: read | Um pagamento. |
POST | /v1/payouts/:id/cancel | payouts: write | Cancela um pagamento ainda não enviado. |
POST | /v1/beneficiaries | payouts: write | Salva um destino de terceiro. |
GET | /v1/beneficiaries | payouts: read | Beneficiários (filtro rail). |
GET | /v1/beneficiaries/:id | payouts: read | Um beneficiário. |
POST | /v1/beneficiaries/:id/archive | payouts: write | Arquiva um beneficiário. |
GET | /v1/settlement-accounts | payouts: read | Contas de saque da empresa (cadastro só no painel). |
GET | /v1/disputes | disputes: read | Como funciona a MED |
GET | /v1/disputes/:id | disputes: read | Uma disputa, com o que a empresa já enviou. |
POST | /v1/disputes/:id/evidence | disputes: write | Enviar defesa |
POST | /v1/disputes/:id/defense | disputes: write | Defesa estruturada. |
PATCH | /v1/disputes/:id/comment | disputes: write | Explicação da empresa. |
GET | /v1/customers | customers: read | Clientes (os pagadores das cobranças), quem pagou por último primeiro; busca por ?q= e página por ?page=. |
GET | /v1/customers/:id | customers: read | Um cliente, com o pago por moeda e as cobranças mais recentes. |
GET | /v1/events | webhooks: read | Eventos já emitidos |
GET | /v1/events/:id | webhooks: read | Um evento pelo X-Event-Id. |
GET | /v1/banks?method=PSE | charges: read | Bancos do PSE (Colômbia): o código vai em customer.bankCode da cobrança. |
O que ainda não existe
- SDK oficial: ainda não existe. Use HTTP direto; os exemplos usam fetch (Node.js) e requests (Python).
- Chaves de API e endpoints de webhook: só pelo painel, com o código do app autenticador. Não há rota para isso na API.
- Aprovar ou recusar pagamentos: só no painel (a aprovação vira o evento payout.approved).
Hoje a API recebe e paga em BRL, por PIX. México (SPEI, em MXN) e USDT: em breve.