---
title: "Simulate a Pix credit into a sandbox BRL account (sandbox only)"
method: POST
path: "/accounts/{account_id}/simulate/credit"
tags: ["Accounts"]
---

# Simulate a Pix credit into a sandbox BRL account (sandbox only)

`POST /accounts/{account_id}/simulate/credit`

## Request

- Base URL: `https://developers.ozav.io/v2`
- URL: `https://developers.ozav.io/v2/accounts/{account_id}/simulate/credit`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Simulates a Pix that a payer sends into a sandbox BRL account. The credit is
added to the account's `balance`, listed on `GET /accounts/{account_id}/movements`
and announced with `account.credited`, the same three things a real Pix into a
live account produces. Use it to build and test your deposit handling before a
live account receives money.

To test the conversion, create a transfer with `source.type: account` from this
account to the customer's wallet. In the sandbox the balance is debited at once,
the transfer completes, and the refusals are the live ones: below the BRL 1,000
floor, or above the balance not already committed to an open order
(`422 ACCOUNT_BALANCE_INSUFFICIENT`).

Available only to test-environment API keys on sandbox BRL accounts. A live
key, or an account in another currency, gets `404 SIMULATION_NOT_AVAILABLE`.

This route takes no `Idempotency-Key`: every call is a new credit.

## Path parameters

- `account_id` string, required

## Request body

- object
  - `amount` string, required: The amount the payer sends, in BRL, as a decimal string with at most 2 decimal places. Must be positive.

## Response `201`

The credit, in the same shape `GET /accounts/{account_id}/movements` lists it.

- AccountMovement: One credit into a named fiat account, as the account's institution reports it. Amounts are decimal strings, never JSON numbers.
  - `id` string, required: The entry's identifier. Stable across reads; use it to de-duplicate. It is the institution's own identifier where the statement is read live, and an OZAV id (`ozav_amov_...`) on a BRL account. The same id arrives in `account.credited`.
  - `object` 'account_movement', required
  - `direction` 'credit', required: Only credits are listed today - money that arrived in the account.
  - `amount` string, required: The amount the payer sent, as a decimal string in `currency`.
  - `currency` string, required: Uppercase ISO 4217 code or stablecoin symbol (e.g. BRL, USD, EUR, MXN, USDC, USDT). Uppercase is the canonical form: values are accepted case-insensitively on input but are always uppercase in responses.
  - `occurred_at` string, date-time, required: When the institution booked the credit (RFC 3339, UTC).
  - `reference` string: The free text the payer sent with the transfer, when the rail carries one. Absent means the rail carried none.
  - `payer` object: Who paid, when the institution reports it. Absent when it does not.
    - `name` string
    - `document` string: The payer's tax or registration document, as reported.
  - `received` object: The amount that actually landed, when the institution reports it separately from `amount` (international wires lose correspondent charges). Absent means the institution reports one figure only.
    - `amount` string, required
    - `currency` string, required: Uppercase ISO 4217 code or stablecoin symbol (e.g. BRL, USD, EUR, MXN, USDC, USDT). Uppercase is the canonical form: values are accepted case-insensitively on input but are always uppercase in responses.

## Other responses

- `400`: The request is invalid.
- `401`: Missing or invalid API key.
- `403`: The organization lacks the entitlement (code ENTITLEMENT_REQUIRED) or the key lacks the scope (code INSUFFICIENT_SCOPE). On money-moving requests (POST /transfers, POST /wallets/{wallet_id}/transfers) a compliance hold on the customer answers with code COMPLIANCE_HOLD: the hold is reviewed and lifted on OZAV's side; retrying does not clear it. When the only hold is a pause until pending onboarding documents are received, a withdrawal answers CUSTOMER_DOCUMENTS_PENDING instead: send what `requirements` on GET /customers/{id} lists; OZAV lifts the pause after reviewing it. On OZAV Services (live without the platform's KYB), any API outside decisions, screenings, lists and self-custody wallets answers with code PRODUCTION_NOT_ACTIVATED.
- `404`: The resource does not exist, is not visible to the caller, or the id was malformed for this position (see "Resource ids" under Errors). These share one status; `code` and `message` tell them apart.
- `503`: A dependency OZAV needs (storage, a resource lookup) could not be reached, so OZAV fails closed rather than guess. Safe to retry with the same `Idempotency-Key` where the operation accepts one.

---

[API](https://skmtc.dev/ozav/apis/ozav-api.md) - [All operations](https://skmtc.dev/ozav/apis/ozav-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ozav/apis/ozav-api/revisions/4133dc2109d7?raw)