Dashboard

Simular pagamentos

Referência

Pagar em sandbox simula a confirmação bancária de uma cobrança pendente criada em ambiente sandbox, sem esperar por um pagamento real. É a forma de testar de ponta a ponta o fluxo de confirmação (mudança de status da cobrança e o webhook payment.success) sem sair do sandbox.

Só funciona em contas sandbox. Chamar este endpoint com o chargeId de uma cobrança de uma conta de produção (accountNumber que não começa com SANDBOX_) é recusado com 400 NOT_SANDBOX_ACCOUNT.

Como funciona

POST /v1/wallet/pay/:chargeId, sem corpo. O chargeId é o identificador retornado na criação da cobrança.

1

A API busca a cobrança pelo chargeId. Se não existir, responde 404 CHARGE_NOT_FOUND.

2

Se a cobrança já estiver paga, responde 200 de forma idempotente, sem gerar nenhum evento novo.

3

Se a conta dona da cobrança não for sandbox, responde 400 NOT_SANDBOX_ACCOUNT.

4

Caso contrário, monta um evento de PIX recebido no mesmo formato que a Celcoin envia em produção (com dados fictícios) e o processa pelo mesmo pipeline interno de webhooks usado para pagamentos reais.

5

Responde imediatamente 200 com status: "PROCESSING". A confirmação definitiva (cobrança PAID e o webhook payment.success) acontece de forma assíncrona, igual a um pagamento de verdade.

Respostas possíveis

SituaçãoHTTPCorpo
chargeId não existe404error.code: CHARGE_NOT_FOUND
Conta da cobrança não é sandbox400error.code: NOT_SANDBOX_ACCOUNT
Cobrança já estava paga200message, chargeId, status: "PAID"
Simulação disparada com sucesso200chargeId, status: "PROCESSING", message
JSON
{
  "chargeId": "cha_1774530966959_frgj3ptax",
  "status": "PROCESSING",
  "message": "Evento enviado para processamento"
}
JSON
{
  "message": "Cobranca ja foi paga",
  "chargeId": "cha_1774530966959_frgj3ptax",
  "status": "PAID"
}

Erros seguem o envelope padrão da API:

JSON
{
  "error": {
    "message": "simulatePayment disponivel apenas para contas sandbox",
    "code": "NOT_SANDBOX_ACCOUNT",
    "details": null,
    "timestamp": "2026-07-14T21:39:36.322Z"
  }
}

Para quais cobranças funciona

  • •Funciona com cobranças PENDING de pix e pix_automatico geradas pelo Checkout Transparente, e também com a cobrança PIX de Cobrança Imediata: são os casos em que a cobrança fica aguardando confirmação bancária.
  • •Também confirma uma cobrança de boleto sandbox pendente, porque a simulação localiza a cobrança pelo identificador interno da transação, não pelo método de pagamento originalmente escolhido.
  • •Cobrança de cartão não se beneficia disso: no sandbox, o cartão já nasce aprovado na criação da cobrança. Chamar este endpoint nela apenas confirma o que já é verdade, retornando o efeito idempotente "Cobranca ja foi paga".

Perguntas frequentes

Preciso enviar algum corpo na requisição?▾
Não. O único dado da chamada é o chargeId na própria URL. Não há campos no body.
O status PROCESSING quer dizer que falhou?▾
Não. É o comportamento esperado: o evento fake foi enviado para processamento, e a confirmação definitiva (cobrança PAID e o webhook payment.success) acontece de forma assíncrona, exatamente como aconteceria com um pagamento real.
Posso chamar esse endpoint em produção?▾
Não. Qualquer conta cujo accountNumber não comece com SANDBOX_ é recusada com 400 NOT_SANDBOX_ACCOUNT.
Chamar esse endpoint duas vezes paga a cobrança duas vezes?▾
Não. Da segunda chamada em diante, a cobrança já está com status PAID e a API responde de forma idempotente (200, "Cobranca ja foi paga"), sem novo crédito e sem disparar um novo webhook.
Isso substitui o QR Code sandbox gerado na cobrança?▾
Não, é complementar. Você continua gerando a cobrança normalmente pelo Checkout Transparente ou pela Cobrança Imediata. Este endpoint só simula que alguém pagou aquele QR Code, sem precisar de um app de banco de testes.
Essa página foi útil?