Sandbox testing guide

All sandbox-specific tooling in one place: PIX test keys, conversion lifecycle helpers, and KYC forcing.

Sandbox simulates the external systems BlendFi integrates with: PIX DICT, the exchange, and custody. This page documents all the fixed test data and control endpoints you can use to drive your integration without waiting for real external events.

The `sandbox:control` capability

Every POST /v1/test_helpers/* endpoint requires the sandbox:control capability. Sandbox keys issued during onboarding include this capability by default. If you receive a missing_capability error, contact support to have it added to your key.

The capability does not exist in production. Any call to a test_helpers endpoint against a sk_live_… key returns 404.

PIX test keys

Sandbox does not query the real PIX DICT. Use the keys below in the pix_key field of your offramp quote request to get deterministic lookup results.

Working keys

These keys resolve successfully and return a synthetic holder.

Key type	Value
`cpf`	Any valid CPF (e.g. `52998224725`)
`cnpj`	Any valid CNPJ (e.g. `11222333000181`)
`email`	`sandbox@blendfi.com.br`
`phone`	`+5511999990001`
`evp`	`00000000-0000-0000-0000-000000000001`

CPF and CNPJ keys auto-resolve: the document number itself becomes the holder's document, so any valid CPF or CNPJ works without a fixed value.

Not-found keys

These keys always return a pix_key_not_found error (HTTP 422). Use them to verify your error-handling path.

Key type	Value
`email`	`notfound@blendfi.com.br`
`phone`	`+5511000000000`
`evp`	`00000000-0000-0000-0000-000000000000`

Any key not listed in either table above also returns pix_key_not_found.

Conversion lifecycle helpers

These endpoints let you advance a conversion through its lifecycle without waiting for real PIX payments or on-chain deposits. All require the sandbox:control capability and an Idempotency-Key header.

Endpoint	What it does
`POST /v1/test_helpers/conversions/{id}/simulate-onramp-pix-paid`	Simulates the PIX payment arriving for an onramp conversion. Drives it to `funded` and creates the transaction record.
`POST /v1/test_helpers/conversions/{id}/simulate-offramp-deposit`	Simulates the USDT deposit for an offramp conversion. A full amount drives it to `funded` and starts the Pix payout; an underpaid or overpaid amount routes it to `standby`.
`POST /v1/test_helpers/conversions/{id}/expire`	Expires an awaiting-deposit conversion
`POST /v1/test_helpers/conversions/{id}/fail`	Fails a conversion with a specified reason

All endpoints return the updated conversion object. The full request and response schemas are in the API reference.

Simulate onramp PIX paid

Body fields:

Field	Type	Required	Description
`amount`	string	No	Decimal amount to credit (e.g. `"500.00"`). Omit to use the quoted amount. Pass a different value to test underpaid or overpaid deposits.

Simulate offramp deposit

Body fields:

Field	Type	Required	Description
`amount`	string	No	Decimal amount to credit (e.g. `"500.00"`). Omit to use the quoted amount. Pass a different value to drive the conversion to `standby` (underpaid or overpaid).

Expire

Body fields:

Field	Type	Required	Description
`occurred_at`	ISO 8601 datetime	No	Backdates the event. Defaults to now.

Fail

Body fields:

Field	Type	Required	Description
`reason`	string	Yes	One of: `pix_expired`, `pix_rejected`, `crypto_deposit_expired`, `crypto_deposit_rejected`, `settlement_failed`, `compliance_rejected`
`occurred_at`	ISO 8601 datetime	No	Backdates the event. Defaults to now.

KYC helper

Forces a KYC review outcome for a user who has an existing KYC submission in progress. Requires the sandbox:control capability.

POST /v1/test_helpers/users/{id}/kyc

Body fields:

Field	Type	Required	Description
`status`	string	Yes	One of: `approved`, `rejected`, `in_review`

Returns the user's updated KYC status. The full schema is in the API reference.

Submission required

The user must have an existing KYC submission before you call this endpoint. Start one through the standard KYC flow first; then use this helper to force the outcome instead of waiting for the review pipeline.

Sandbox & keys, environment overview and how to get a key
Postman collection, pre-built requests for every test helper
Errors catalog, error codes you may encounter during testing

On this page