Ambiente sandbox

O sandbox (ambiente demo) replica o fluxo Pix inteiro — cobrança, confirmação, saque, disputa e webhook — sem mover dinheiro de verdade. É onde você valida a integração antes de ir para produção.

URL base

O sandbox atende em um endereço próprio. Chamar api.avexus.app com credenciais de teste não funciona — e, pior, com credenciais de produção você estaria movendo dinheiro real.

Sandbox

https://sandbox-api.avexus.app

Cuidado

Os dois ambientes têm banco de dados, filas e credenciais próprios. As chaves (x-api-key / x-token) do sandbox não valem em produção, e vice-versa — gere as do sandbox em Integração, no painel, com o ambiente Sandbox selecionado.

Sua conta é a mesma nos dois: o login serve para ambos; o que muda é o ambiente escolhido no painel.

Valores mágicos

No sandbox, o valor da cobrança decide o desfecho. Assim você exercita cada estado da máquina de status de forma determinística: basta cobrar o valor correspondente.

Valor	Desfecho
11.11	PENDING — fica pendente (só a expiração natural age)
12.22	FAILED
13.33	REFUNDED — confirma e reverte
14.44	EXPIRED
15.55	DISPUTE_NEEDS_RESPONSE
16.66	DISPUTE_IN_REVIEW
17.77	DISPUTE_WON
18.88	DISPUTE_LOST
qualquer outro	CONFIRMED

Dica

Qualquer valor fora da tabela resulta em CONFIRMED. Para simular um pagamento bem-sucedido, use 4.00, 197.00, o que preferir — contanto que não seja um dos valores mágicos. Note que 12.23 confirma: a tabela casa o valor exato em centavos, não uma faixa.

Como testar

Crie a cobrança normalmente com o valor do desfecho que você quer. Ela nasce PENDING e, depois de um intervalo curto, o sandbox a conduz ao status alvo — nos casos de disputa, a cobrança é confirmada, a disputa é aberta e avançada até o sub-status indicado.

POST /api/transactions — simular uma cobrança que falha

curl --request POST \
  --url https://sandbox-api.avexus.app/api/transactions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "amount": 12.22,
    "external_ref": "teste_falha_001",
    "payment_method": "Pix",
    "requester": {
      "name": "Maria Souza",
      "email": "maria@example.com",
      "phone": "11999999999",
      "document": "12468239008"
    }
  }'

POST /api/transactions — simular uma disputa perdida

curl --request POST \
  --url https://sandbox-api.avexus.app/api/transactions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "amount": 18.88,
    "external_ref": "teste_disputa_001",
    "payment_method": "Pix",
    "requester": {
      "name": "Maria Souza",
      "email": "maria@example.com",
      "phone": "11999999999",
      "document": "12468239008"
    }
  }'

Acompanhe a transição consultando a cobrança ou — melhor — registrando um webhook para receber cada mudança em tempo real. Se preferir testar só o transporte, POST /api/webhooks/{magic_id}/test dispara uma entrega assinada na hora.

O que testar antes de ir para produção

• Confirmação — o caminho feliz, com o webhook liberando o pedido.
• Falha e expiração — a sua tela oferece gerar um novo código?
• Reentrega — derrube o seu endpoint de propósito e confira se o retry chega.
• Assinatura inválida — o seu handler recusa um POST forjado?
• Idempotência — processe a mesma entrega duas vezes e verifique se o efeito colateral acontece uma vez só.
• Saldo insuficiente no saque — peça mais do que tem e trate o 422.

Cuidado

Os valores mágicos valem apenas no sandbox. Em produção, o status de cada cobrança reflete o processamento real do adquirente.

Veja também

• Status de transação — o que cada status significa.
• Receber webhooks — as transições em tempo real.
• Quickstart — a primeira cobrança, passo a passo.