Testing in sandbox

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

Overview

The sandbox base URL is https://api.sandbox.tracefinance.com. It runs the same state machines as production, so most requests follow the happy path by default: beneficiaries approve, payment instructions clear, and operations settle.

To exercise the other branches, the sandbox recognizes a set of deterministic magic values and triggers. Sending one forces a specific compliance or settlement outcome without waiting for a real upstream error, so you can develop and verify each path during homologation. The sections below list every trigger, grouped by the resource it acts on.

To build the webhook handler that receives the resulting events, see Test webhooks in sandbox.

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.identificationDocument.value (with type: CPF)	12345678909	Tax ID owner deceased
entity.identificationDocument.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 /v1/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, the 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. To retry, register a new instruction, or a new beneficiary if the entity data was wrong.

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 /v1/operations/withdrawals 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, so beneficiary registration is unaffected and 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, the 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.

Force a custody-attestation document rejection

A crypto beneficiary also submits a custody attestation document. Independently of wallet screening, you can reject the beneficiary through its document check by uploading the attestation with a filename that contains the lowercase word reject, either inline on POST /v1/beneficiaries or via POST /v1/beneficiaries/{beneficiaryId}/documents.

Uploaded filename	Outcome
reject.pdf, custody-reject.png, …	The custody-attestation check fails and the instruction is rejected; BENEFICIARY_PAYMENT_INSTRUCTION_REJECTED fires after the review settles, with the reason on instruction.currentState.reason.message.

Put reject in the file’s name, not its extension, and keep the letters together; a space or symbol between them (rej ect) breaks the match. Any other filename follows the normal screening path.

Deposits

In sandbox, the deposit amount decides its QR code’s outcome:

Deposit amount (sourceAmount)	Outcome
8.00	The QR code is never paid
9.00	The QR code expires
Any other amount	The QR code is paid

Crypto test tokens

The sandbox uses a fixed set of test tokens for crypto deposits, swaps, and withdrawals. These are mock ERC-20 contracts that Trace Finance controls. They mirror the shape of the real assets but hold no monetary value, so you can move them freely during homologation.

Everything in the sandbox runs on the Ethereum testnet (Sepolia), never on mainnet. The API always reports the network as ETHEREUM, the same value it uses in production, but in the sandbox that value resolves to Sepolia. The contract addresses below are Sepolia deployments and carry no value. Never treat them as the real USDT, USDC, or BRL tokens.

Only the ETHEREUM network is available in the sandbox today. Other networks are not yet supported for sandbox testing.

Name	symbol	network	contractAddress	decimals
Trace Finance BRL	BRLT	ETHEREUM (Sepolia testnet)	0x2588a80f342ea4f24c91c0148a3d6e832ce9dca9	6
Trace Mock USDT	USDT	ETHEREUM (Sepolia testnet)	0x164afc6456b21b4b1bd505a69be35cc2d9692fd8	6
Trace Mock USDC	USDC	ETHEREUM (Sepolia testnet)	0xca732283fd24c588d9084b1ae357b540e9e7b2f3	6

Related

• Environments — sandbox and production base URLs
• Crypto assets and networks — production stablecoins, networks, and contract addresses
• Beneficiaries — what gets screened and what stays on your side
• Register a beneficiary — step-by-step procedure for submitting beneficiaries and payment instructions
• Deposit — end-to-end deposit with a PIX dynamic QR code
• Test webhooks in sandbox — develop and verify webhook handlers