Testes no Sandbox

O sandbox permite conduzir uma transação por todo o seu ciclo de vida sem movimentação real de dinheiro. Duas ferramentas tornam isso possível: dados de teste que disparam comportamentos específicos de conformidade e um endpoint de forçar eventos que simula os callbacks externos (webhooks do gateway, notificações da rede de payout) que normalmente fazem uma transação avançar.

Forçando Transições de Status

Endpoint: POST /organizations/{tenant}/fx/transactions/{transactionId}/events
Autenticação: Nível de agente
Disponibilidade: Somente sandbox/staging — este endpoint não existe em produção.

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/fx/transactions/$TRANSACTION_ID/events \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{
  "event": "payment_authorized",
  "message": "Optional description"
}'

Eventos Disponíveis

Se a transação não estiver em um estado válido para o evento, o endpoint retorna um erro explicando o estado atual.

Fluxo de Teste Típico (Cartão + 3DS)

1. Crie a transação → status WaitingChallenge3ds, paymentStatus: ActionRequired
2. Force o 3DS: { "event": "payment_authorized" }
3. A transação progride automaticamente → PayoutAccepted → ManualReview → ReviewApproved → PaymentCaptured → WaitingPayout
4. Force a entrega: { "event": "payout_paid" }
5. A transação chega a Completed

Fluxo de Teste Típico (ACH)

1. Crie a transação → progride para WaitingSettlement
2. Force a liquidação: { "event": "ach_settled" }
3. A transação progride automaticamente → PaymentSettled → PaymentCaptured → WaitingPayout
4. Force a entrega: { "event": "payout_paid" }
5. A transação chega a Completed

Cenários de Teste de Conformidade

Determinados valores nos dados do remetente disparam comportamentos específicos de conformidade no sandbox:

Retenção na Rede de Payout

Use o nome de remetente JULIO SOLANO para disparar uma retenção de conformidade na rede de payout:

{ "firstName": "JULIO", "lastName": "SOLANO", "...": "..." }

A transação chega a PayoutHold após a integração de payout. Libere-a com o evento forçado hold_released (ou ela é liberada pela rede/backoffice).

Fluxo esperado:

... → ProcessingPayout → PayoutHold → [hold released] → PayoutReleased → ...

Rejeição na Rede de Payout (Dados do Recebedor Ausentes)

Use o zipcode 96738 no endereço de cobrança do remetente para disparar uma falha de validação de dados do recebedor na rede de payout:

{ "address": { "zipcode": "96738", "...": "..." } }

A rejeição depende de dados do beneficiário ausentes (país, cidade, estado). Se o destinatário tiver dados de endereço completos, a transação é aceita independentemente do zipcode.

Recusa de Pagamento

Use um token de cartão que o sandbox do gateway rejeite, ou um token expirado. A transação chega a PaymentDeclined → Cancelled.

Recusa no 3DS

Ao ser redirecionado para a página de challenge 3DS, escolha "Decline" (quando o sandbox oferece essa opção). O gateway reporta a falha e a transação passa a PaymentDeclined → Cancelled.

Cartões de Teste

Use os cartões de teste do sandbox para simular cenários de 3DS. A lista completa está em Cartões de teste do Payments Gateway. Os mais comuns:

Tokenize-os via SDK do gateway e depois passe o token como paymentMethod.token ao criar uma conta de financiamento.

Polling de Status

Depois de criar uma transação, faça polling em GET /organizations/{tenant}/fx/transactions/{transactionId} e observe:

Para a trilha de auditoria completa das transições, use GET /fx/transactions/{transactionId}/status — veja Transação. Em produção, prefira webhooks em vez de polling.