Depósitos

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

Criar depósito

POST /v1/deposits

{
  "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:

{
  "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:

{
  "amount": 10000,
  "currency": "USDT",
  "payment_method": "USDT",
  "external_id": "orden-usdt-7",
  "crypto": { "network": "TRON" }
}

Resposta 201:

{
  "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:

"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.

Você não precisa fazer polling: registre um webhook e reaja ao evento deposit.paid.

Introdução

API

Criar depósito

Moedas e métodos

Depósito em cripto (USDT)

Como funciona um trilho REDIRECT

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

Consultar / listar

Estados

​Criar depósito

​Moedas e métodos

​Depósito em cripto (USDT)

​Como funciona um trilho REDIRECT

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

​Consultar / listar

​Estados

Criar depósito

Moedas e métodos

Depósito em cripto (USDT)

Como funciona um trilho REDIRECT

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

Consultar / listar

Estados