---
title: "Create a BRL deposit into a customer's balance"
method: POST
path: "/deposits"
tags: ["Accounts"]
---

# Create a BRL deposit into a customer's balance

`POST /deposits`

## Request

- Base URL: `https://developers.ozav.io/v2`
- URL: `https://developers.ozav.io/v2/deposits`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Returns a Pix code (BR Code) the customer pays. When it is paid, the amount
becomes BRL **balance held for that customer**; nothing is converted. Convert
later with `POST /transfers` from that balance.

The deposit belongs to the customer (an individual or a company). The code
is issued on the account that carries that customer's money; the response
does not name it.

**`reference` is the idempotency lever.** The same `reference` for the same
customer returns the existing deposit with `200`: the same code while it is
payable, or its current status (`paid`, `expired`). The same `reference` with
a different `amount` is `409 DEPOSIT_IDEMPOTENCY_CONFLICT`.

Refusals, with named codes: deposits not enabled for your organization yet
(`422 DEPOSITS_NOT_ENABLED`); no account ready to receive for this customer
yet (`422 DEPOSIT_ACCOUNT_NOT_AVAILABLE`, the reason in the message);
a customer without name or document on file
(`422 CUSTOMER_PROFILE_INCOMPLETE`, also when the document is not a CPF or
a numeric CNPJ); the charge cannot be issued or was refused and will not
pass on retry (`422 DEPOSIT_RAIL_CANNOT_CHARGE`). When the deposit cannot be
created right now the answer is `503 DEPOSIT_UNAVAILABLE`: retry with the
same `reference`.

## Request body

- DepositCreateRequest
  - `customer_id` string, required: The customer who deposits (`ozav_cus_...`).
  - `amount` object, required
    - `currency` 'BRL', required
    - `value` string, required
  - `reference` string, required: Your idempotency handle for this deposit.

## Response `200`

The same deposit already existed (same `reference`); same code.

- Deposit
  - `id` string, required
  - `object` 'deposit', required
  - `customer_id` string, required
  - `status` 'awaiting_payment' | 'paid' | 'expired', required
  - `amount` object, required
    - `currency` 'BRL'
    - `value` string
  - `amount_paid` object, nullable
    - `currency` 'BRL'
    - `value` string
  - `pix` object, required
    - `br_code` string, nullable: The Pix code to pay; null once paid.
    - `expires_at` string, date-time, nullable
  - `reference` string, nullable
  - `paid_at` string, date-time, nullable
  - `created_at` string, date-time, nullable

## Other responses

- `201`: Deposit created; pay the BR Code.
- `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.
- `409`: Conflict (e.g. IDEMPOTENCY_KEY_REUSED).
- `422`: The request is well-formed but cannot be fulfilled - e.g. a `rail` that is not served (see `Rail.x-ozav-rail-availability`).
- `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)