> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swytchpay.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Depósitos

> Cobrança em moeda local — PIX, SPEI, PSE

<Note>**Beta** — o contrato da 1.0 em evolução, ainda não em produção. Os campos podem mudar até o lançamento.</Note>

## Criar depósito

`POST /v1/deposits`

```json theme={null}
{
  "amount": 50000,
  "currency": "MXN",
  "payment_method": "SPEI",
  "external_id": "orden-42",
  "payer": { "name": "Juan Pérez", "email": "juan@ok.mx", "document": "PEGJ850315HDFRRN01" },
  "metadata": { "player_id": "PL-42" }
}
```

Resposta `201`:

```json theme={null}
{
  "id": "dep_…", "status": "PENDING", "external_id": "orden-42",
  "currency": "MXN", "payment_method": "SPEI", "flow": "REDIRECT",
  "amount": 50000, "fee": 1500, "net": 48500,
  "charge": { "type": "spei", "redirect_url": "https://checkout…", "expires_at": 1781319147 },
  "expires_at": 1781319147
}
```

* `amount` é o valor cobrado, inteiro na menor unidade da moeda (centavos); `net` é o que entra no seu saldo, já sem a taxa.
* `currency` define a moeda do saldo. Sem ela, o default é `BRL`.
* `payment_method` escolhe o trilho; o `charge` da resposta vem no formato do método (EMV do PIX, CLABE do SPEI…).
* **Idempotência**: repetir o POST com o mesmo `external_id` devolve o depósito existente (`200`).
* `delivery` — só nos trilhos que redirecionam (SPEI, OXXO, PSE). `redirect` (padrão) devolve a URL da
  página de pagamento; `direct` devolve os dados no próprio `charge`, para você montar a sua tela. Veja
  **Como funciona um trilho REDIRECT**.

## Moedas e métodos

```
BRL    Brasil      PIX
MXN    México      SPEI · OXXO (ainda não habilitado)
COP    Colômbia    PSE · Nequi · Bank Transfer
ARS    Argentina   em breve
USDT   Cripto      carteira (TRON · ETH)
```

O `charge` da resposta vem no formato do método:

```
PIX    { type: "pix",  emv, qr_url }                     flow: "DIRECT"
SPEI   { type: "spei", redirect_url, expires_at }        flow: "REDIRECT"
OXXO   { type: "oxxo", redirect_url, expires_at }        flow: "REDIRECT"
PSE    { type: "pse",  redirect_url }                    flow: "REDIRECT"
USDT   { type: "usdt", address, network, expires_at }    flow: "DIRECT"
```

## Depósito em cripto (USDT)

Para receber **USDT** direto numa carteira, use `currency: "USDT"` e `payment_method: "USDT"`. Não há
pagador local — o `charge` devolve o endereço e a rede:

```json theme={null}
{
  "amount": 10000,
  "currency": "USDT",
  "payment_method": "USDT",
  "external_id": "orden-usdt-7",
  "crypto": { "network": "TRON" }
}
```

Resposta `201`:

```json theme={null}
{
  "id": "dep_…", "status": "PENDING", "currency": "USDT", "payment_method": "USDT",
  "amount": 10000,
  "charge": { "type": "usdt", "address": "TR7NHqjeK…", "network": "TRON", "expires_at": 1781319147 }
}
```

`amount` em USDT também é inteiro em centavos (`10000` = 100,00 USDT). A rede vai em `crypto.network`
(`TRON`, `ETH`…): o objeto `crypto` só existe no cripto, do mesmo jeito que `payer` só existe no fiat. O
pagador envia o USDT para o `address` na `network` indicada; a confirmação cai por webhook, igual ao fiat.

`flow` distingue **DIRECT** (o `charge` traz o que o pagador precisa — PIX e USDT) de **REDIRECT**
(o `charge` traz uma URL para onde você manda o pagador — SPEI, OXXO, PSE e Nequi).

### Como funciona um trilho REDIRECT

No PIX você recebe um código e mostra ao pagador. Nos trilhos LATAM é diferente, e a integração muda:

* **Há dois endereços, com papéis diferentes.** `charge.redirect_url` é para onde **você manda** o
  pagador: a página onde ele vê os dados e paga (no SPEI, a CLABE; no PSE, a escolha do banco).
  `callback_url` é para onde **ele volta** quando termina, e você informa na criação. Não confunda os
  dois: um é a ida, o outro é a volta.
* **A página é de uso único.** Depois de aberta ela não abre de novo. Guarde o `id` do depósito e
  crie uma cobrança nova se o pagador precisar recomeçar.
* **O valor precisa ser exato.** O pagador digita o valor no app do banco dele, e é ele que precisa
  bater. Diferente do PIX, onde o valor viaja dentro do código.
* **A volta não confirma nada; o webhook confirma.** Quem fechou a aba pode ter pago, e quem voltou
  pelo `callback_url` pode não ter. Só o evento `deposit.paid` diz que o dinheiro entrou.

### `delivery: "direct"` — os dados no `charge`, para a sua tela

Se você prefere montar a própria página (com a sua marca, sem mandar o pagador para fora), peça
`delivery: "direct"`. O `charge` volta com o que a página mostraria:

```json theme={null}
"charge": {
  "type": "spei", "clabe": "710969000336399298", "beneficiary": "LABSVELORA",
  "bank": "NVIO", "amount": 50000, "expires_at": 1781319147
}
```

Os dois modos são **excludentes**: no `direct` não há `redirect_url`, porque a URL é consumida ao
extrair os dados. Se a extração falhar, a resposta é um erro e a cobrança não fica de pé — crie outra
com `redirect`, que é sempre seguro.

## Consultar / listar

```
GET /v1/deposits/{id}
GET /v1/deposits?status=PAID&currency=MXN&cursor=dep_xxx&limit=20
```

Quando pago, o depósito ganha `paid_at`, `e2e_id` e `payer_details` (dados bancários do pagador).

## Estados

`PENDING → PAID` (pagamento confirmado) · `PENDING → EXPIRED` (venceu sem pagar). Um pagamento com atraso
pode levar `EXPIRED → PAID` — aceitamos, pois o dinheiro entrou.

<Info>Você não precisa fazer polling: registre um [webhook](/reference/webhooks) e reaja ao evento
`deposit.paid`.</Info>