Depósitos - SwytchPay

Beta — o contrato da 1.0 está em evolução. Esta página descreve o que a API aceita e devolve hoje.

Criar depósito

POST https://api.go.swytchpay.app/v1/deposits

{
  "external_id": "orden-42",
  "amount_cents": 50000,
  "currency": "MXN",
  "method": "SPEI",
  "payer": { "name": "Juan Pérez", "email": "juan@ok.mx", "document": "PEGJ850315HDFRRN01" }
}

Campo	Tipo
`external_id`	string	obrigatório	O id do pedido no seu sistema, até 120 caracteres. Repetir o POST com o mesmo `external_id` devolve o depósito existente (`200`).
`amount_cents`	inteiro	um dos dois	O valor na menor unidade da moeda. `50000` em MXN são 500,00 pesos.
`amount_minor`	string	um dos dois	O mesmo valor, como texto (`"50000"`). Mandar os dois só vale se forem o mesmo número.
`currency`	string		ISO 4217. Sem ela, `BRL`. Há depósito em `BRL`, `MXN` e `COP`.
`method`	string		Em maiúsculas: `PIX`, `SPEI`, `PSE`. Sem ele, o método padrão da moeda.
`payer.name`	string	obrigatório	O nome de quem paga.
`payer.document`	string		CPF ou CNPJ, RFC ou CURP, cédula. Recomendado.
`payer.email`	string
`payer.phone`	string	no PSE	Obrigatório na Colômbia.
`payer.address`	string	no PSE	Obrigatório na Colômbia.
`pse.bank_code`	string	no PSE	O banco do pagador, `CO` seguido do código (`CO1007`).

O valor é amount_cents (ou amount_minor) e o método é method. Um corpo com amount recebe 400, e um payment_method é ignorado — o depósito cai no método padrão da moeda. Campos que a API não conhece (metadata, delivery, callback_url) também são ignorados.

Na Colômbia (PSE) o corpo leva o banco e o contato do pagador:

{
  "external_id": "orden-43",
  "amount_cents": 20000000,
  "currency": "COP",
  "method": "PSE",
  "payer": {
    "name": "Ana Ribeiro", "document": "1032456789",
    "phone": "+57 300 123 4567", "address": "Cra 7 # 71-21, Bogotá"
  },
  "pse": { "bank_code": "CO1007" }
}

Resposta 201 (200 quando o external_id já existia):

{
  "id": "dep_mrp8k2n4x91",
  "object": "deposit",
  "external_id": "orden-42",
  "status": "PENDING",
  "amount_cents": 50000,
  "fee_cents": 1000,
  "net_cents": 49000,
  "method": "SPEI",
  "payment_method": "SPEI",
  "currency": "MXN",
  "flow": "REDIRECT",
  "charge": { "type": "spei", "redirect_url": "https://…", "expires_at": 1788367323 },
  "environment": "live",
  "expires_at": 1788367323,
  "paid_at": null,
  "created_at": 1788363723
}

amount_cents é o valor cobrado; net_cents é o que entra no seu saldo, já sem a taxa (fee_cents).
As datas (created_at, expires_at, paid_at) são epoch em segundos.
A resposta traz também payer, customer, e2e_id e metadata (sempre {} na 1.0).

O `charge` por método

PIX    { type: "pix",  emv, qr_url }                    flow: "DIRECT"
SPEI   { type: "spei", redirect_url, expires_at }       flow: "REDIRECT"
PSE    { type: "pse",  redirect_url, expires_at }       flow: "REDIRECT"

No PIX, o emv é o copia-e-cola e vira QR Code no seu front. No SPEI e no PSE, o charge traz a página do adquirente para onde você manda o pagador. Se a página não tiver sido gerada, o charge vem null.

Como funciona um trilho REDIRECT

A página é de uso único e vence em charge.expires_at. Se o pagador precisar recomeçar, crie outra cobrança.
O valor precisa ser exato. No SPEI o pagador digita o valor no app do banco dele.
Sair da página não confirma nada. Quem fechou a aba pode ter pago. Só o webhook deposit.paid diz que o dinheiro entrou.

Depósito em cripto (USDT)

O USDT não passa por POST /v1/deposits. Cada conta tem um endereço próprio na rede, que você obtém em GET /v1/crypto-addresses?network=tron — e o que entrar nele vira um depósito sozinho, com o aviso por webhook.

Consultar

GET /v1/deposits/{id}

Quando pago, o depósito ganha paid_at, e2e_id e payer_details (os 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.

​Criar depósito

​O charge por método

​Como funciona um trilho REDIRECT

​Depósito em cripto (USDT)

​Consultar

​Estados

Criar depósito

O `charge` por método

Como funciona um trilho REDIRECT

Depósito em cripto (USDT)

Consultar

Estados