Testing 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.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 /v1/beneficiaries request with the magic dict key on the Pix payment instruction:

`paymentInstruction.dictKey`	`paymentInstruction.dictKeyType`	Outcome
`reject@sandbox.trace.finance`	`EMAIL`	The Pix instruction is rejected; `BENEFICIARY_PAYMENT_INSTRUCTION_REJECTED` fires shortly after submission.

"paymentInstruction": {
  "rail": "PIX_KEY",
  "asset": "BRL",
  "dictKeyType": "EMAIL",
  "dictKey": "reject@sandbox.trace.finance"
}

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 /v1/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.

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

Getting started

Compliance Requirements

API principles

Webhooks

Journeys

Beneficiaries

Force the pending state

Force a rejection

Pix payment instructions

Force a payment-instruction rejection

Force a withdrawal failure

Crypto wallet instructions

​Beneficiaries

​Force the pending state

​Force a rejection

​Pix payment instructions

​Force a payment-instruction rejection

​Force a withdrawal failure

​Crypto wallet instructions

​Related

Beneficiaries

Force the pending state

Force a rejection

Pix payment instructions

Force a payment-instruction rejection

Force a withdrawal failure

Crypto wallet instructions

Related