Sandbox

O sandbox da Moonip deixa você exercitar a integração inteira — criar cobrança, ler o QR, consultar status, testar idempotência — sem mover dinheiro e sem depender de credencial de adquirente.

Não existe host separado. É a mesma URL e o mesmo contrato de produção; o que muda é a chave.

#Como entrar no sandbox

Emita uma chave de teste no painel (ou pela API de chaves) e use-a normalmente:

Não há campo no corpo da requisição para escolher o ambiente — é a chave que decide, e só ela. Mandar um cabeçalho de ambiente na mão não muda nada: o gateway descarta e trata como cobrança real.

curl -X POST https://api.moonip.io/v1/charges \
  -H "Authorization: Bearer ak_test_SUA_CHAVE" \
  -H "Idempotency-Key: pedido-1234" \
  -H "Content-Type: application/json" \
  -d '{"amount": 15000, "currency": "BRL", "payment_method": "pix"}'

Resposta (abreviada):

{
  "id": "ch_a4521699-89a6-44a1-adb6-745862875e95",
  "object": "charge",
  "amount": 15000,
  "status": "pending",
  "payment_method": "pix",
  "pix": {
    "br_code": "00020126SANDBOX-PIX-8494424468F862C5DE279BA25204000053039865802BR",
    "qr_code_base64": "data:image/png;base64,iVBORw0KGgo...",
    "expires_at": "2026-07-30T18:14:12.338Z"
  }
}

#O que esperar do artefato

Todo artefato de sandbox carrega a marca SANDBOX no próprio valor — BR Code, código de barras, referência. Isso é de propósito: se um deles vazar para uma tela, um e-mail ou um relatório, o texto denuncia a origem, em vez de parecer uma cobrança de verdade que ninguém consegue liquidar.

O QR é gerado normalmente e renderiza; escaneá-lo no app do banco dá erro, porque o BR Code não é válido no Pix.

Os artefatos são determinísticos. A mesma cobrança devolve sempre os mesmos valores. Isso é o que permite testar retentativa e idempotência: se você repetir a mesma Idempotency-Key, recebe a mesma cobrança, não uma nova.

#Confirmando um pagamento de sandbox

O único desfecho que você consegue forçar é o paid, e é a alavanca de auto-teste do lojista para o fim a fim de webhook:

POST /v1/payments/{id}/confirm-sandbox

Numa cobrança criada com chave de teste (uma cobrança de sandbox), esta rota a torna PAID e dispara os webhooks normais — seu endpoint recebe a mesma entrega charge.paid que receberia em produção. Resposta: { "confirmed": true, "status": "PAID" }; uma cobrança já em estado final responde { "confirmed": false, "status": "…", "reason": "ALREADY_TERMINAL" }, e uma cobrança que não é de sandbox é recusada com 400.

Os SDKs a empacotam como payments.confirmSandbox(id) (node client.payments.confirmSandbox(id), python client.payments.confirm_sandbox(id), php $client->payments->confirmSandbox($id), dotnet client.Payments.ConfirmSandboxAsync(id)). A tela Ambiente de teste do painel faz o mesmo, e ainda simula um saque concluído; essas entregas levam X-Moonip-Test: true (veja Entregas de teste). O botão Testar do endpoint envia uma entrega de exemplo sem tocar em cobrança nenhuma.

#O que ainda não existe

Seja qual for o seu teste, conte com isto:

• A cobrança não se paga sozinha. O status fica em pending e não avança com o tempo — ele só muda quando você a confirma (acima). Isso é deliberado: um simulador que "paga" depois de N segundos deixa o teste dependente de relógio e impede exercitar o caso que mais importa, que é a cobrança nunca paga que expira.
• Só o paid pode ser forçado. refused, chargeback e outros desfechos negativos não podem ser definidos pela API. Está no plano, ainda não foi construído.
• Só Pix pela API pública, que é Pix-first hoje. O simulador internamente também cobre cartão, boleto e Multibanco, e eles aparecem aqui conforme o contrato público os expuser.

#Isolamento

O sandbox compartilha a mesma conta e o mesmo extrato da sua operação real — não é um ambiente separado com dados próprios. Cobranças de teste aparecem na sua listagem junto das reais, distinguíveis pela marca SANDBOX no artefato.

Se isso for um problema para o seu fluxo, crie um segundo cadastro só para testes.

Vazar uma chave ak_test_ não tem impacto financeiro — ela não consegue cobrar ninguém. Ainda assim, trate-a como credencial: ela lê os dados da sua conta.