---
title: "Create a personal deposit (PIX → DePix)"
method: POST
path: "/api/deposit"
tags: ["pay"]
---

# Create a personal deposit (PIX → DePix)

`POST /api/deposit`

## Request

- Base URL: `https://api.depixapp.com`
- URL: `https://api.depixapp.com/api/deposit`
- Auth: HTTP bearer

Generates a PIX QR; when the owner pays it, DePix is delivered to `depixAddress`. Requires scope `wallet_write` on the API-key path. A provider business rejection returns HTTP 400 `validation_error` (the provider message is preserved in `response.errorMessage`) — not a 200. A provider that does not answer at all (timeout or network failure) returns HTTP 503 `service_unavailable` and IS worth retrying; it was an HTTP 500 until 2026-08-04. With a sk_test_ key the response is synthetic (`sandbox: true`, no provider call, no row). Track settlement by polling GET /api/deposits/{id} (5–15 s interval) and/or via the deposit.* webhooks. Supports Idempotency-Key. **Fee**: 2% + R$ 0.99, DEDUCTED from the amount — `amountInCents` is what the payer pays by PIX, and the DePix credited to `depixAddress` is that minus the fee (a R$ 100.00 / 10000 deposit credits R$ 97.01 / 9701 in DePix). Current rates: https://depixapp.com/en/#landing-fees.

## Headers

- `Idempotency-Key` string

## Request body

- DepositCreateRequest: Personal deposit request: generates a PIX QR whose payment delivers DePix to `depixAddress`.
  - `amountInCents` integer, required: Deposit amount in cents (BRL). Accepted range: 500–600000 (R$ 5,00–R$ 6.000,00). Account-level and per-key limits may restrict it further.
  - `depixAddress` string, required: Liquid address that will receive the DePix once the PIX settles.
  - `payer_tax_number` string, required: CPF or CNPJ of the PIX payer. Required — omitting it returns 400 `tax_number_required`. Always validated and forwarded to the payment provider.
  - `verification_flow` boolean: Set to `true` only when this deposit is the one being made IN ORDER TO VERIFY the account (the round trip described by GET /api/verification). That deposit does not consume the receive cap reported by GET /api/vault/status, so a new account does not spend part of its limit just to unlock the merchant tools. Worth ONCE and only up to the verification amount — the excess consumes the cap normally, as does every other deposit from the owner's own document. Ignored (never an error) when the account is already verified or is an agent account, which verifies by proving a domain instead. A non-boolean value returns 400 `validation_error`.

## Response `200`

QR issued.

- DepositCreateResponse: Deposit creation result (HTTP 200 — success only). A provider business rejection is NOT a 200: it returns HTTP 400 `validation_error` with the upstream message preserved in `response.errorMessage`, mirroring POST /api/withdraw.
  - `async` boolean, required: Always false — QR generation is synchronous.
  - `response` object, required: PIX QR payload (live or sandbox).
    - `qrCopyPaste` string, required: PIX copy-and-paste (BR Code) payload the payer uses. In sandbox this is a SANDBOX-…-DO-NOT-PAY placeholder that must never be paid.
    - `qrImageUrl` string, nullable, required: URL (or data URI) of the rendered QR image. Always set on live; null on sandbox (nothing to render). Served from a provider-controlled host that can change: allow it dynamically rather than hard-coding it.
    - `id` string, required: Deposit id — poll GET /api/deposits/{id} with it. Prefixed sandbox_ in test mode.
    - `sandbox` boolean: Present and true only on sk_test_ responses (synthetic sandbox: no PIX, no DePix, nothing to pay).

## Other responses

- `400`: Invalid input, amount outside 500–600000, account limit, per-key spending limit, missing payer tax number, or upstream rejection (provider refused the request — passed through as validation_error, with the provider message in response.errorMessage).
- `401`: Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.
- `403`: The API key lacks the `wallet_write` scope required by this operation. May also be `account_blocked`, or an operation-specific 403 — see the error catalog.
- `409`: A request with the same Idempotency-Key is still in flight — retry after `retry_after` seconds.
- `422`: The Idempotency-Key was already used with a different request body (strict byte-level comparison of the parsed body).
- `429`: Rate limited, or too many PAID transactions for the same payer CPF/CNPJ (`payer_velocity_limit`: max 2 paid per sliding 30-minute window, deposits + checkouts combined; unpaid/expired QRs don't count). Retry after `retry_after` seconds (also in the Retry-After header).

---

[API](https://skmtc.dev/depixapp/apis/depix-api.md) · [All operations](https://skmtc.dev/depixapp/apis/depix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/depixapp/apis/depix-api/revisions/04094536dd0f?raw)