Pular para o conteúdo
AvexusAvexus Docs

Quickstart

Neste guia você cria uma cobrança Pix de ponta a ponta: registrar o webhook → criar a cobrança → exibir o qr_code → receber a confirmação.

Pré-requisitos

Seção intitulada “Pré-requisitos”
  • O par x-api-key (pk_…) e x-token (sk_…), gerado no painel em Integração → Chaves de API. O sk_ aparece uma única vez.
  • Um endpoint HTTPS público para receber webhooks (opcional, mas recomendado).

Se ainda não gerou as chaves, comece por Autenticação.

  1. Registre um webhook (opcional, recomendado)

    Assim você recebe a confirmação do pagamento em tempo real, sem polling.

    POST /api/webhooks
    curl --request POST \
      --url https://api.avexus.app/api/webhooks \
      --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 '{
        "url": "https://seu-servidor.com.br/webhooks/avexus",
        "events": ["transaction", "withdraw", "dispute"]
      }'

    Guarde o secret retornado — é com ele que você valida a assinatura HMAC das entregas:

    Resposta 201
    {
      "code": 201,
      "content": {
        "magic_id": "wh_03UdoKvLNLHg",
        "url": "https://seu-servidor.com.br/webhooks/avexus",
        "secret": "whsec_2f1f9e5cbe7b4b3c9a6d",
        "events": ["transaction", "withdraw", "dispute"],
        "active": true,
        "created_at": "2026-07-24T18:38:25.688Z",
        "updated_at": "2026-07-24T18:38:26.703Z"
      },
      "message": "Webhook created",
      "timestamp": "2026-07-24T18:38:26.703Z"
    }

  2. Crie a cobrança Pix

    Envie o valor, a sua referência (external_ref) e os dados do pagador:

    POST /api/transactions
    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"
      }'

    A resposta vem com status PENDING e o copia-e-cola do Pix:

    Resposta 201
    {
      "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"
    }

  3. Exiba o qr_code para o pagador

    O campo qr_code é o payload Pix copia-e-cola (BR Code). Você pode:

    • renderizá-lo como QR code na sua interface (qualquer biblioteca serve); e/ou
    • oferecer um botão “copiar código” para o pagador colar no app do banco.

    A cobrança expira depois do tempo definido em expires_in (em segundos).

  4. Receba o webhook de confirmação

    Quando o pagador conclui o Pix, a Avexus envia um POST para o seu endpoint com o evento TRANSACTION e o status CONFIRMED:

    Webhook de transação (payload)
    {
      "data": {
        "magic_id": "rU1w01Ct6QL3",
        "amount": 4.00,
        "currency": "BRL",
        "status": "CONFIRMED",
        "decline_reason": null,
        "description": "Pedido 1042",
        "payment_method": "Pix",
        "qr_code": "00020101021126700014br.gov.bcb.pix...",
        "end_to_end": "E60789431202607241838V2JYEP7TUZ6",
        "external_ref": "pedido_1042",
        "requester": {
          "name": "Maria Souza",
          "email": "maria@example.com",
          "phone": "11999999999",
          "document": "12468239008"
        },
        "movement": {
          "payer": {
            "name": "Maria Souza",
            "document": "12468239008",
            "bank": "BANCO INTER S.A.",
            "agency": "0001",
            "account": "123456-7"
          },
          "payee": {
            "name": "Sua Loja LTDA",
            "document": "12345678000190",
            "bank": "BANCO INTER S.A.",
            "agency": "0001",
            "account": "765432-1"
          }
        },
        "created_at": "2026-07-24T18:38:25.688Z",
        "updated_at": "2026-07-24T18:41:06.467Z"
      },
      "event": "TRANSACTION"
    }

    Valide o header x-webhook-signature com HMAC SHA256 antes de processar — veja o guia de webhooks.

  5. (Alternativa) Consulte o status por polling

    Se preferir, consulte a cobrança pela sua referência:

    GET /api/transactions
    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'

Próximos passos

Seção intitulada “Próximos passos”