Pular para o conteúdo
AvexusAvexus Docs

Cobranças

Uma cobrança é o pedido de pagamento Pix: você informa o valor e o pagador, a Avexus devolve o copia-e-cola (BR Code) e avisa por webhook quando o dinheiro entra.

Método Endpoint Descrição
POST /api/transactions Cria uma cobrança Pix
GET /api/transactions Consulta cobranças (magic_id, status, external_ref, end_to_end, limit, resend)
POST /api/transactions/{magic_id}/refund Estorno — indisponível, veja abaixo

Criar cobrança

Seção intitulada “Criar cobrança”

POST /api/transactions

Headers obrigatórios: Content-Type, x-api-key, x-token, idempotency-key. Opcional: x-timezone.

Corpo da requisição

Seção intitulada “Corpo da requisição”
Campo Tipo Obrigatório Descrição
amount number Sim Valor da cobrança em BRL, maior que zero
requester.name string Sim Nome do pagador (até 255 caracteres)
requester.email string Não E-mail do pagador
requester.phone string Não Telefone do pagador
requester.document string Não CPF/CNPJ do pagador, somente dígitos
external_ref string Não A sua referência (id do pedido), até 255 caracteres
payment_method string Não Pix (único valor aceito hoje)
expires_in number Não Expiração em segundos, entre 60 e 86400
description string Não Descrição da cobrança, até 500 caracteres
splits object[] Não Repasse para outros lojistas — veja split de pagamento
POST /api/transactions — cobrança simples
curl --request POST \
  --url https://api.avexus.app/api/transactions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "amount": 4.00,
    "external_ref": "pedido_1042",
    "requester": {
      "name": "Maria Souza",
      "email": "maria@example.com",
      "phone": "11999999999",
      "document": "12468239008"
    },
    "payment_method": "Pix",
    "expires_in": 3600,
    "description": "Pedido 1042"
  }'

Resposta

Seção intitulada “Resposta”

A cobrança nasce em PENDING e traz o qr_code (copia-e-cola) para exibir ao pagador:

201 — Transaction created
{
  "code": 201,
  "content": {
    "magic_id": "rU1w01Ct6QL3",
    "amount": 4.00,
    "currency": "BRL",
    "status": "PENDING",
    "decline_reason": null,
    "description": "Pedido 1042",
    "payment_method": "Pix",
    "qr_code": "00020101021226870014br.gov.bcb.pix2565qrcode...",
    "end_to_end": "E60789431202607241838V2JYEP7TUZ6",
    "requester": {
      "name": "Maria Souza",
      "email": "maria@example.com",
      "phone": "11999999999",
      "document": "12468239008"
    },
    "external_ref": "pedido_1042",
    "created_at": "2026-07-24T18:38:25.688Z",
    "updated_at": "2026-07-24T18:38:26.703Z"
  },
  "message": "Transaction created",
  "timestamp": "2026-07-24T18:38:26.703Z"
}

Limites da conta

Seção intitulada “Limites da conta”

Antes de chamar o adquirente, a Avexus confere os limites vigentes da sua conta — eles são relidos a cada cobrança, então uma mudança feita pelo operador vale já na próxima:

Limite Resposta ao estourar
Valor mínimo 400 · amount is below the minimum charge of R$ …
Valor máximo 400 · amount is above the maximum charge of R$ …
Total do dia 422 · daily charge limit of R$ … reached (R$ … already issued today)

O limite diário responde 422 e não 400 de propósito: o payload está certo, o que acabou foi a cota — e “corrija a requisição” seria um conselho errado.

Sem expires_in, vale o prazo padrão configurado para a plataforma.

Cobrança com split

Seção intitulada “Cobrança com split”

O array splits repassa parte da cobrança para outros lojistas da Avexus. Cada item carrega amount OU percentage — nunca os dois.

Campo Tipo Descrição
recipient string Identificador público do lojista recebedor (mch_…). Precisa ser um parceiro autorizado.
amount number Valor fixo a repassar, em BRL. Exclusivo com percentage.
percentage number Percentual do valor bruto (máx. 2 casas decimais, ≤ 100). Exclusivo com amount.
description string Descrição livre do repasse (opcional).
POST /api/transactions — cobrança com split
curl --request POST \
  --url https://api.avexus.app/api/transactions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "amount": 250.00,
    "external_ref": "pedido_marketplace_42",
    "requester": {
      "name": "Maria Souza",
      "email": "maria@example.com",
      "phone": "11999999999",
      "document": "12468239008"
    },
    "payment_method": "Pix",
    "description": "Pedido com split",
    "splits": [
      { "recipient": "mch_VVuz_g_ybTfj", "amount": 40.00, "description": "vendedor A" },
      { "recipient": "mch_XYZ789abcdef", "percentage": 15.5, "description": "comissão parceiro" }
    ]
  }'

A resposta traz o array splits com o valor de cada recebedor já resolvido em reais — o percentage é convertido na criação e nunca recalculado:

201 — cobrança com split criada
{
  "code": 201,
  "content": {
    "magic_id": "rU1w01Ct6QL3",
    "amount": 250.00,
    "currency": "BRL",
    "status": "PENDING",
    "decline_reason": null,
    "description": "Pedido com split",
    "payment_method": "Pix",
    "qr_code": "00020101021226870014br.gov.bcb.pix...",
    "end_to_end": "E60789431202607241838V2JYEP7TUZ6",
    "requester": { "name": "Maria Souza", "email": "maria@example.com", "phone": "11999999999", "document": "12468239008" },
    "splits": [
      {
        "recipient": "mch_VVuz_g_ybTfj",
        "name": "Vendedor A",
        "amount": 40.00,
        "percentage": null,
        "description": "vendedor A"
      },
      {
        "recipient": "mch_XYZ789abcdef",
        "name": "Parceiro",
        "amount": 38.75,
        "percentage": 15.5,
        "description": "comissão parceiro"
      }
    ],
    "external_ref": "pedido_marketplace_42",
    "created_at": "2026-07-24T18:38:27.307Z",
    "updated_at": "2026-07-24T18:38:27.307Z"
  },
  "message": "Transaction created",
  "timestamp": "2026-07-24T18:38:27.310Z"
}

Consultar cobranças

Seção intitulada “Consultar cobranças”

GET /api/transactions

Parâmetro Descrição
magic_id Identificador da cobrança na Avexus
status Filtra por status (ex.: CONFIRMED)
external_ref Filtra pela sua referência
end_to_end Filtra pelo identificador end-to-end do Pix
limit Máximo de resultados. Padrão 20, teto 100
resend true reenfileira o webhook das cobranças retornadas
GET /api/transactions — listar
curl --request GET \
  --url 'https://api.avexus.app/api/transactions?limit=20' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
GET /api/transactions — por external_ref
curl --request GET \
  --url 'https://api.avexus.app/api/transactions?external_ref=pedido_1042&limit=20' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
GET /api/transactions — por magic_id
curl --request GET \
  --url 'https://api.avexus.app/api/transactions?magic_id=rU1w01Ct6QL3' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
GET /api/transactions — por status
curl --request GET \
  --url 'https://api.avexus.app/api/transactions?status=CONFIRMED&limit=20' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'

Reenviar o webhook (resend=true)

Seção intitulada “Reenviar o webhook (resend=true)”

Perdeu uma notificação? A consulta com resend=true reenfileira o webhook das cobranças retornadas:

GET /api/transactions — com reenvio de webhook
curl --request GET \
  --url 'https://api.avexus.app/api/transactions?magic_id=rU1w01Ct6QL3&resend=true' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'

A message do envelope confirma o reenvio: Transactions returned, webhooks queued for resend.

Estorno

Seção intitulada “Estorno”

POST /api/transactions/{magic_id}/refund

Veja também

Seção intitulada “Veja também”