Depósitos

Criar depósito

POST /v1/deposits

{
  "amount_cents": 10000,
  "external_id": "pedido-42",
  "payer": { "name": "Player Um", "email": "p1@ok.io", "phone": "+5511988887777", "document": "11144477735" },
  "expires_in_sec": 3600,
  "metadata": { "player_id": "PL-42" }
}

Resposta 201:

{
  "id": "dep_…", "status": "PENDING", "external_id": "pedido-42",
  "amount_cents": 10000, "fee_cents": 350, "net_cents": 9650,
  "pix": { "emv": "000201…", "qr_url": null },
  "expires_at": 1781319147
}

amount_cents é o valor cobrado do player; net_cents é o que entra no seu saldo (já descontada a taxa).
pix.emv é o copia-e-cola. Renderize o QR a partir dele no seu app.
Idempotência: repetir o POST com o mesmo external_id devolve o depósito existente (200).
currency / payment_method — a moeda e o trilho. Sem eles, BRL / PIX, exatamente como sempre foi.
Todo depósito devolve também currency, payment_method, flow (DIRECT ou REDIRECT) e charge — a forma de pagar no formato do trilho. No PIX, charge é { "type": "pix", "emv", "qr_url" } (o mesmo que pix).

Depósito em pesos mexicanos (SPEI)

{
  "amount_cents": 50000,
  "currency": "MXN",
  "payment_method": "SPEI",
  "external_id": "pedido-mx-42",
  "payer": { "name": "Ana Ribeiro", "email": "ana@ok.mx", "document": "RIRA850315HDF" },
  "delivery": "redirect"
}

O SPEI é um trilho REDIRECT: não existe código copia-e-cola; o pagador faz uma transferência para uma CLABE gerada por cobrança, com o valor exato. Você escolhe como recebe isso em delivery:

delivery: "redirect"   (default)  charge: { type: "spei", redirect_url, expires_at }
                                  → mande o pagador para redirect_url. A página é de USO ÚNICO e mostra CLABE,
                                    beneficiário, banco e valor. Não abra a URL do seu lado.
delivery: "direct"                charge: { type: "spei", clabe, beneficiary, bank, amount_cents, expires_at }
                                  → nós abrimos a página uma vez e devolvemos os dados; monte a sua própria tela.
                                    Não há redirect_url — a URL foi consumida na extração.

A CLABE é única por cobrança: a conciliação é pela conta, não por referência.
charge.expires_at é o mesmo expires_at do depósito, em epoch. A validade que vale é a nossa: vencido, o depósito expira e a CLABE deixa de ser paga.
O pagador precisa transferir o valor exato. Vale o amount_cents do charge.
payer.document é o RFC ou CURP do pagador.
A confirmação chega pelo webhook deposit.paid, como no PIX.

No modo direct, se a página não trouxer os dados a cobrança é recusada com PROVIDER_ERROR — a URL de uso único já foi consumida e não há como voltar ao redirect. Crie outra cobrança, com delivery: "redirect".

Consultar / listar

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

Quando pago, o depósito ganha paid_at, e2e_id e payer_details (dados bancários do pagador, úteis para antifraude e conciliação).

Estados

PENDING → PAID (pagamento confirmado) · PENDING → EXPIRED (venceu sem pagar). Um PIX pago 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

Integração de corretora

Criar depósito

Depósito em pesos mexicanos (SPEI)

Consultar / listar

Estados

​Criar depósito

​Depósito em pesos mexicanos (SPEI)

​Consultar / listar

​Estados

Criar depósito

Depósito em pesos mexicanos (SPEI)

Consultar / listar

Estados