[MARCA] Documentação

Sandbox

Simuladores disponíveis somente no ambiente de sandbox (chaves sk_sandbox_); em produção as rotas respondem 404. Cada simulação é enfileirada e percorre o mesmo fluxo de produção — aviso do banco, confirmação do Pix, eventos e webhooks —, então o que você recebe no sandbox é o que receberá em produção.

Simular pagamento

POST /v1/sandbox/charges/{charge_id}/simulate_payment

Somente sandbox. Simula o recebimento de um Pix para a cobrança, disparando o mesmo fluxo de produção (eventos payment.received e charge.paid). Com duplicate_webhook: true, o evento é entregue duas vezes; com out_of_order: true, payment.received chega depois de charge.paid — use para testar idempotência do seu sistema.

Exige o cabeçalho Idempotency-Key (os SDKs enviam automaticamente).

Parâmetros

NomeOndeTipoDescrição
charge_id obrigatóriocaminhostring

Corpo da requisição

CampoTipoDescrição
amountstring (valor)

Valor pago; por padrão, o valor da cobrança.

delay_secondsinteger
duplicate_webhookboolean
out_of_orderboolean
paid_onstring (date)

Só em cobrança com vencimento — data do pagamento simulado (testa juros, multa e desconto).

methodstring
pixboleto

Cobrança híbrida — boleto simula o pagamento pela linha digitável.

Respostas

  • 202 Simulação enfileirada.
  • 401 Chave ausente, inválida, expirada ou revogada.
  • 403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
  • 404 Recurso não encontrado (ou pertencente a outra unidade).
  • 409 Conflito de estado: `idempotency-key-in-progress`, `charge-not-active`, `payment-not-unmatched`,

Exemplo

curl -X POST "https://api.exemplo.com.br/v1/sandbox/charges/ch_01J9Z3F0A1B2C3D4E5F6G7H8J9/simulate_payment" \
  -H "Authorization: Bearer $PIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "149.90"
}'

Identificador nos logs: api.sandbox.simulate_payment

Simular expiração

POST /v1/sandbox/charges/{charge_id}/simulate_expiration

Somente sandbox. Expira a cobrança imediatamente (evento charge.expired).

Exige o cabeçalho Idempotency-Key (os SDKs enviam automaticamente).

Parâmetros

NomeOndeTipoDescrição
charge_id obrigatóriocaminhostring

Respostas

  • 202 Simulação enfileirada.
  • 401 Chave ausente, inválida, expirada ou revogada.
  • 403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
  • 404 Recurso não encontrado (ou pertencente a outra unidade).
  • 409 Conflito de estado: `idempotency-key-in-progress`, `charge-not-active`, `payment-not-unmatched`,

Exemplo

curl -X POST "https://api.exemplo.com.br/v1/sandbox/charges/ch_01J9Z3F0A1B2C3D4E5F6G7H8J9/simulate_expiration" \
  -H "Authorization: Bearer $PIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Identificador nos logs: api.sandbox.simulate_expiration

Simular Pix lido de um QR impresso

POST /v1/sandbox/static_qrs/{static_qr_id}/simulate_payment

Usa o valor fixo do QR ou amount (obrigatório quando o pagador digita o valor).

Exige o cabeçalho Idempotency-Key (os SDKs enviam automaticamente).

Parâmetros

NomeOndeTipoDescrição
static_qr_id obrigatóriocaminhostring

Corpo da requisição

CampoTipoDescrição
amountstring (valor)

Valor em reais, duas casas decimais, separador ponto.

Respostas

  • 202 Simulação enfileirada.
  • 401 Chave ausente, inválida, expirada ou revogada.
  • 403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
  • 404 Recurso não encontrado (ou pertencente a outra unidade).
  • 429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.

Exemplo

curl -X POST "https://api.exemplo.com.br/v1/sandbox/static_qrs/sq_01J9Z3F0A1B2C3D4E5F6G7H8J9/simulate_payment" \
  -H "Authorization: Bearer $PIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "25.00"
}'

Identificador nos logs: api.sandbox.simulate_static_qr_payment

Simular Pix sem cobrança

POST /v1/sandbox/payments/simulate_unmatched

Somente sandbox. Simula um Pix recebido na chave da unidade sem cobrança associada (evento payment.unmatched).

Exige o cabeçalho Idempotency-Key (os SDKs enviam automaticamente).

Corpo da requisição

CampoTipoDescrição
amount obrigatóriostring (valor)

Valor em reais, duas casas decimais, separador ponto.

Respostas

  • 202 Simulação enfileirada.
  • 401 Chave ausente, inválida, expirada ou revogada.
  • 403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida

Exemplo

curl -X POST "https://api.exemplo.com.br/v1/sandbox/payments/simulate_unmatched" \
  -H "Authorization: Bearer $PIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "80.00"
}'

Identificador nos logs: api.sandbox.simulate_unmatched

Simular a decisão do pagador numa assinatura

POST /v1/sandbox/subscriptions/{subscription_id}/simulate_decision

Somente sandbox. approve: o pagador aprova a adesão (e paga o 1º Pix, se houver) — subscription.approved; reject: recusa — subscription.rejected; cancel_by_payer: cancela depois, pelo app do banco — subscription.canceled. Para simular o débito de um ciclo, use simulate_payment na cobrança do ciclo; para um débito que não aconteceu, simulate_expiration (com three_in_seven_days, vira nova tentativa).

Exige o cabeçalho Idempotency-Key (os SDKs enviam automaticamente).

Parâmetros

NomeOndeTipoDescrição
subscription_id obrigatóriocaminhostring

Corpo da requisição

CampoTipoDescrição
decisionstring
approverejectcancel_by_payer

Respostas

  • 202 Simulação enfileirada.
  • 401 Chave ausente, inválida, expirada ou revogada.
  • 403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
  • 404 Recurso não encontrado (ou pertencente a outra unidade).

Exemplo

curl -X POST "https://api.exemplo.com.br/v1/sandbox/subscriptions/sub_01J9Z3F0A1B2C3D4E5F6G7H8J9/simulate_decision" \
  -H "Authorization: Bearer $PIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "decision": "approve"
}'

Identificador nos logs: api.sandbox.simulate_subscription_decision

Simular MED

POST /v1/sandbox/payments/{payment_id}/simulate_med

Somente sandbox. Simula um bloqueio cautelar por MED no pagamento (evento med.blocked) e, se outcome = refunded, a devolução por MED (refund.succeeded com nature = med_fraud).

Exige o cabeçalho Idempotency-Key (os SDKs enviam automaticamente).

Parâmetros

NomeOndeTipoDescrição
payment_id obrigatóriocaminhostring

Corpo da requisição

CampoTipoDescrição
outcomestring
refundedreleased

Respostas

  • 202 Simulação enfileirada.
  • 401 Chave ausente, inválida, expirada ou revogada.
  • 403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
  • 404 Recurso não encontrado (ou pertencente a outra unidade).

Exemplo

curl -X POST "https://api.exemplo.com.br/v1/sandbox/payments/pay_01J9Z3F0A1B2C3D4E5F6G7H8J9/simulate_med" \
  -H "Authorization: Bearer $PIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "outcome": "refunded"
}'

Identificador nos logs: api.sandbox.simulate_med