Testing in sandbox

Magic values and triggers the Trace Finance sandbox accepts to simulate compliance outcomes during homologation.

Beneficiaries

A beneficiary you create auto-approves by default. Use the triggers below to force other outcomes.

Force the pending state

Send entity.address.addressLine2 containing no-auto (case-sensitive, substring match) to keep the beneficiary in its initial pending state. Use this to validate UI states, polling, and webhook delivery before the decision lands.

"address": {
  "addressLine1": "Rua Augusta, 500",
  "addressLine2": "Apto 12 no-auto"
}

Force a rejection

Send any of the following values to receive a rejected beneficiary.

Field	Value	Simulated reason
entity.taxId.value (with type: CPF)	12345678909	Tax ID owner deceased
entity.taxId.value (with type: CNPJ)	50676745000143	Company deregistered
entity.firstName + entity.lastName	John + Doe (exact)	Name match on sanctions list
entity.address.country	KP, IR, SY, or CU	Sanctioned country

Pix payment instructions

A Pix instruction either approves (auto-approves in sandbox, behind a real compliance review in production) or rejects after the review settles. Once approved, the customer’s withdrawal against the instruction either completes or fails on the rail. The triggers below let you exercise both terminal-failure paths from your integration without waiting for real upstream errors.

Force a payment-instruction rejection

Use this trigger to develop and verify your BENEFICIARY_PAYMENT_INSTRUCTION_REJECTED handler. Submit a POST /api/beneficiaries request with the magic dict key on the Pix payment instruction:

paymentInstruction.dictKey	paymentInstruction.dictKeyType	Outcome
[e-mail]	EMAIL	The Pix instruction is rejected; BENEFICIARY_PAYMENT_INSTRUCTION_REJECTED fires shortly after submission.

"paymentInstruction": {
  "rail": "PIX_KEY",
  "asset": "BRL",
  "dictKeyType": "EMAIL",
  "dictKey": "[e-mail]"
}

Any other dict key follows the normal sandbox resolution path.

The endpoint responds 201 Created with the new instruction in PENDING_REVIEW — same shape as a normal submission. Shortly after, the BENEFICIARY_PAYMENT_INSTRUCTION_REJECTED webhook arrives with the rejection on the affected instruction:

{
  ...,
  "instruction": {
    ...,
    "currentState": {
      "status": "REJECTED",
      "reason": {
        "code": "COMPLIANCE_REJECTED",
        "message": "An unknown error occurred.",
        ...
      },
      ...
    },
    ...
  },
  ...
}

A rejected instruction is terminal — register a new instruction, or a new beneficiary if the entity data was wrong, to retry.

Force a withdrawal failure

Use this trigger to develop and verify your OPERATION_FAILED handler. Register a beneficiary with any normal dict key so the instruction approves cleanly, then submit a POST /api/operations/withdrawal request using a quote whose sourceAmount cents select the simulated outcome:

sourceAmount cents	currentState.reason.code	currentState.reason.message
.04	INVALID_ACCOUNT	”Invalid account.”
.05	CPF_CNPJ_ACCOUNT_HOLDER_MISMATCH	”CPF/CNPJ of the receiving user is not consistent with the account holder credited.”
.06	CLIENT_ACCOUNT_BALANCE_BLOCKED	”Client’s account balance is blocked.”
.07	INSUFFICIENT_BALANCE	”Insufficient balance.”
.08	TRANSACTION_LIMIT_EXCEEDED	”Daily equal transaction limit exceeded.”
.09	PROCESSING_ERROR	”Transaction processing failed.”

Any other cents value settles the withdrawal normally. The trigger reads sourceAmount on the outbound withdrawal only — beneficiary registration is unaffected, so an approved beneficiary stays usable across all six triggers.

Quote 500.04 BRL → 500.04 BRL (or any same-asset amount whose cents are .04), then submit the withdrawal against the approved instruction. The endpoint responds 201 Created with the operation in REQUESTED — same shape as a normal withdrawal. Shortly after, the OPERATION_FAILED webhook arrives with the matching reason on currentState:

{
  ...,
  "sourceAmount": { "value": "500.04", "asset": "BRL", "decimals": 2 },
  ...,
  "currentState": {
    "status": "FAILED",
    "reason": {
      "code": "INVALID_ACCOUNT",
      "message": "Invalid account.",
      ...
    },
    ...
  },
  ...
}

The webhook is terminal — no further events fire for this operation. Cycle through the six magic cents values to exercise six independent rail-error branches of your handler without re-registering beneficiaries.

Crypto wallet instructions

Crypto wallets are screened against a real chain-analysis provider in both sandbox and production. There is no sandbox-only mock layer. To simulate a rejected beneficiary, send a paymentInstruction.address that the provider rejects in the real world: for example, an address with an invalid format or checksum, or a publicly known blocklisted address.

The same submission against production returns the same rejection.

Related

• Environments — sandbox and production base URLs
• Beneficiaries — what gets screened and what stays on your side
• Register a beneficiary — step-by-step procedure for submitting beneficiaries and payment instructions
• Test webhooks in sandbox — develop and verify webhook handlers