> For the complete documentation index, see [llms.txt](https://docs.omypayments.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.omypayments.com/api/api-endpoints/deposits.md).

# Deposits

A **deposit** is money that arrived at one of your addresses without an invoice behind it. Someone sent funds directly to an address of yours, we detected the transfer on-chain, took our fee and credited the rest to the asset balance. This section lets you read those deposits from your backend.

> **Base URL**: `https://api.omypayments.com`\
> **Version**: `v2` (all endpoints below start with `/2.0/...`)\
> **Auth**: add your API key in the header: `apiKey: <yourApiKey>`\
> **Permission**: the API key must have the **invoice** permission enabled — deposits are the incoming-payment side of the same permission, and there is no separate deposit flag. Without it requests are rejected with `403 Forbidden`.

**Deposit or invoice?**

Both put money on your balance, and both charge you a platform fee. The difference is who initiated the accounting:

* An **invoice** is something you created up front: an expected amount, a payment page, a status you can follow from `new` to `finished`.
* A **deposit** is discovered after the fact. Nobody announced it - a transfer simply landed on your address, and we recorded it. There is nothing to create and nothing to cancel.

If you only ever charge customers through invoices, you may still see deposits: a customer paying an old address again, or a top-up you sent yourself, both arrive as deposits.

**Prerequisites**

* Deposits are created by us, not by you. There is no endpoint to create one.
* Amounts follow the usual rule: integer strings in the token's minimal units. See Assets for `decimals`.
* The deposit id is not something you can guess ahead of time. You learn it either from the ledger - deposits appear in the transaction list under the `deposit` opcode - or from a callback.

**Deposit statuses**

| Status     | Meaning                                                                                        |
| ---------- | ---------------------------------------------------------------------------------------------- |
| `success`  | Credited to your asset balance, minus our fee.                                                 |
| `frozen`   | Held for a compliance check. The funds are not on your available balance until it is resolved. |
| `refunded` | The received amount was sent back to the sender.                                               |

There is no `pending` state here: a deposit is only recorded once the incoming transfer has been confirmed on-chain.

**Fees**

Every deposit carries a `fee` object with what we charged. Deposits have **no network fee** — the sender paid the on-chain cost of the transfer, so `fee.network` is always `null` for this entity. Only `fee.service` is populated.

For deposits recorded before the USD figure started being stored, `fee.service.amountInUsd` is `null` while the crypto amount is present. That is missing history, not a zero fee.

***