Teste em Sandbox

Visão Geral

O ambiente sandbox permite simular diferentes cenários de webhook sem afetar transações reais. Utilize o header X-Sandbox-Scenario em qualquer request para controlar o resultado do webhook recebido.

Este recurso funciona apenas em sandbox. Em produção, o header é ignorado e o comportamento é determinado pelo resultado real da transação.

Como Usar

Adicione o header X-Sandbox-Scenario a qualquer request de Cash-In, Cash-Out ou Refund:

curl -X POST https://api.safirapay.com/api/pix/cash-out \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Sandbox-Scenario: error:insufficient-funds" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 150.00,
    "details": {
      "key": "recipient@email.com",
      "keyType": "EMAIL",
      "name": "Recipient Name",
      "document": "39284918812"
    },
    "externalId": "test-error-001"
  }'

const response = await axios.post(
  'https://api.safirapay.com/api/pix/cash-out',
  {
    value: 150.00,
    details: {
      key: 'recipient@email.com',
      keyType: 'EMAIL',
      name: 'Recipient Name',
      document: '39284918812',
    },
    externalId: 'test-error-001',
  },
  {
    headers: {
      Authorization: `Bearer ${token}`,
      'X-Sandbox-Scenario': 'error:insufficient-funds',
    },
  }
);

response = requests.post(
    "https://api.safirapay.com/api/pix/cash-out",
    json={
        "value": 150.00,
        "details": {
            "key": "recipient@email.com",
            "keyType": "EMAIL",
            "name": "Recipient Name",
            "document": "39284918812",
        },
        "externalId": "test-error-001",
    },
    headers={
        "Authorization": f"Bearer {token}",
        "X-Sandbox-Scenario": "error:insufficient-funds",
    },
)

Cenários Disponíveis

Cenários de Erro

Simule diferentes tipos de falha no webhook:

Valor do Header	Descrição	Webhook Status
`error:insufficient-funds`	Conta sem saldo suficiente	`ERROR`
`error:invalid-pix-key`	Chave PIX não existe no DICT	`ERROR`
`error:document-mismatch`	Documento não corresponde ao titular da chave	`ERROR`
`error:account-blocked`	Conta de destino bloqueada ou encerrada	`ERROR`
`error:duplicate-id`	ID de envio duplicado	`ERROR`

Cenário de Sucesso

Valor do Header	Descrição	Webhook Status
`success`	Força sucesso (comportamento padrão)	`CONFIRMED`
(sem header)	Comportamento padrão do sandbox	`CONFIRMED`

Cenários de Delay

Simule processamento lento para testar timeouts e retry:

Valor do Header	Descrição	Webhook Status
`delayed:5s`	Sucesso após 5 segundos extras	`CONFIRMED`
`delayed:30s`	Sucesso após 30 segundos extras	`CONFIRMED`
`delayed:60s`	Sucesso após 60 segundos extras	`CONFIRMED`

O delay máximo permitido é de 120 segundos. Valores acima serão limitados automaticamente.

Exemplos de Webhook Recebido

Webhook de Sucesso (padrão)

{
  "event": "CashOut",
  "status": "CONFIRMED",
  "transactionType": "PIX",
  "movementType": "DEBIT",
  "transactionId": "12345",
  "externalId": "test-success-001",
  "endToEndId": "E17745159XI4QA0EGFU",
  "feeAmount": 0.50,
  "originalAmount": 150.00,
  "finalAmount": 150.50,
  "processingDate": "2026-03-26T10:00:00.000Z",
  "errorCode": null,
  "errorMessage": null,
  "counterpart": {
    "name": "Recipient Name",
    "document": "*.284.918-**",
    "bank": {}
  },
  "metadata": {}
}

Webhook de Erro (error:insufficient-funds)

{
  "event": "CashOut",
  "status": "ERROR",
  "transactionType": "PIX",
  "movementType": "DEBIT",
  "transactionId": "12345",
  "externalId": "test-error-001",
  "endToEndId": null,
  "feeAmount": 0.50,
  "originalAmount": 150.00,
  "finalAmount": 150.50,
  "processingDate": "2026-03-26T10:00:00.000Z",
  "errorCode": "INSUFFICIENT_FUNDS",
  "errorMessage": "Conta sem saldo",
  "counterpart": {
    "name": null,
    "document": null,
    "bank": {}
  },
  "metadata": {}
}

Quando o status é ERROR, o campo endToEndId será null (pois o PIX nunca foi confirmado pelo Banco Central) e os campos errorCode e errorMessage descrevem o motivo da falha.

Endpoints Compatíveis

O header X-Sandbox-Scenario funciona com todos os endpoints transacionais:

Endpoint	Método	Descrição
`/api/pix/cash-in`	POST	Gerar cobrança PIX (QR Code)
`/api/pix/cash-out`	POST	Pagamento PIX por chave
`/api/pix/cash-out/qrcode`	POST	Pagamento PIX por QR Code
`/api/pix/refund-in`	POST	Solicitação de estorno

Comportamento

A API processa o request normalmente e retorna 201 Created com status PENDING. O header não altera a resposta imediata — apenas o webhook subsequente.

Após ~1 segundo (ou mais, se usar delayed:), o webhook é enviado para a URL configurada com o cenário simulado.

Seu sistema recebe o webhook com o status correspondente ao cenário (CONFIRMED ou ERROR) e deve processar de acordo.

Importante: O header X-Sandbox-Scenario controla apenas o webhook. A resposta HTTP do endpoint sempre retorna sucesso (201 Created) com status: "PENDING", independente do cenário escolhido. O resultado final (sucesso ou erro) chega via webhook.

Restrições

O header X-Sandbox-Scenario funciona exclusivamente com contas configuradas em modo sandbox. Se sua conta está configurada com um provedor de produção e você enviar o header, a API retornará um erro:

{
  "statusCode": 400,
  "message": "X-Sandbox-Scenario header is only supported in sandbox mode. This account is not configured with a sandbox provider."
}

Certifique-se de que sua conta está em modo sandbox antes de usar este recurso. Se você receber este erro, entre em contato com suporte@safirapay.com para verificar a configuração da sua conta.

Boas Práticas

Teste todos os cenários

Implemente tratamento para cada status de webhook (CONFIRMED, PENDING, ERROR) antes de ir para produção.

Valide os campos de erro

Quando status é ERROR, use errorCode e errorMessage para determinar a ação adequada (retry, notificar usuário, etc.).

Teste com delay

Use cenários delayed: para verificar se seu sistema lida corretamente com webhooks que demoram a chegar.

Idempotência

Use transactionId como chave de idempotência. O mesmo webhook pode ser reenviado em caso de falha de entrega.

Teste em Sandbox

Teste todos os cenários

Valide os campos de erro

Teste com delay

Idempotência

Nesta página