StacePay Documentação da API / Moedas LATAM e USDT
Markdown

Moedas LATAM e USDT

Receba e saque em USDT e em pesos mexicanos, colombianos e chilenos. Cada moeda tem a sua carteira, com saldo separado do saldo em reais. Para trocar de uma carteira para outra sem sacar, veja Carteiras e conversão. As rotas em reais não mudam.

Valores sempre em unidade mínima da moeda: centavos para MXN e COP, peso inteiro para CLP, micro (6 casas) para USDT. Toda resposta traz decimals.

Moedas disponíveis

MoedaPaísdecimalsReceber (method)Sacar
USDTStablecoin (rede Tron)6TRC20 (endereço de depósito com valor exato)Envio para carteira Tron (TRC20)
MXNMéxico2SPEI (transferência para CLABE), OXXO (dinheiro, MX$10 a MX$10.000)SPEI para CLABE
COPColômbia2NEQUI_QR (QR Nequi), BREB (QR Bre-B)Bre-B por chave
CLPChile0BANK_TRANSFER (transferência bancária)Transferência bancária

Para saber o que está liberado para a sua conta agora:

GET/fx/currencies
{
  "object": "list",
  "data": [
    {
      "object": "fx_currency",
      "currency": "MXN",
      "name": "Peso mexicano",
      "country": "México",
      "decimals": 2,
      "charge_methods": ["spei", "oxxo"],
      "withdrawal_methods": ["spei"],
      "available": true
    }
  ]
}

Saldos

GET/fx/balances
{
  "object": "list",
  "data": [
    {"object": "fx_balance", "currency": "MXN", "decimals": 2, "available": 125000, "reserved": 0}
  ]
}

Criar cobrança

POST/fx/charges

Use um Idempotency-Key. KYC aprovado é obrigatório.

CampoTipoDescrição
currencystringobrigatório"USDT", "MXN", "COP" ou "CLP".
amountintegerobrigatórioValor em unidade mínima da moeda.
methodstringopcionalMétodo de pagamento (tabela acima). Sem ele, usa o primeiro da moeda.
descriptionstringopcionalDescrição da cobrança.
referencestringopcionalSeu identificador interno.
payerobjectopcionalDados do pagador: name, email, document, phone. Exigências por moeda abaixo.
MoedaDados do pagador
MXNname obrigatório no SPEI. document (CURP ou RFC) e email opcionais.
COPphone opcional: celular de 10 dígitos começando com 3.
CLPname, email e document (RUT válido) obrigatórios.
USDTNenhum. A resposta traz instruction.address (rede Tron) e instruction.amount: o pagador deve enviar exatamente esse valor, com as casas decimais.
curl -X POST https://stacepay.com.br/api/v1/fx/charges \
  -H "Authorization: Bearer nvx_live_..." \
  -H "Idempotency-Key: mx-0001" \
  -H "Content-Type: application/json" \
  -d '{"currency": "MXN", "method": "SPEI", "amount": 50000, "payer": {"name": "Juan Pérez"}}'
{
  "object": "fx_charge",
  "id": "fx_3b9d0e1a2c4f5a6b",
  "status": "pending",
  "currency": "MXN",
  "decimals": 2,
  "payment_method": "spei",
  "amount": 50000,
  "fee_amount": null,
  "net_amount": null,
  "description": null,
  "reference": null,
  "instruction": {
    "type": "bank_transfer",
    "clabe": "646180000000000000",
    "reference": "1234567",
    "bank_name": "STP",
    "beneficiary": "..."
  },
  "checkout_url": "https://stacepay.com.br/moeda/fx_3b9d0e1a2c4f5a6b",
  "expires_at": "2026-11-11T15:20:00-03:00",
  "paid_at": null,
  "created_at": "2026-11-10T15:20:00-03:00"
}

Mostre ao pagador o conteúdo de instruction ou mande o checkout_url, que já exibe as instruções. O formato muda pelo método:

instruction.typeQuandoCampos
bank_transferMXN SPEIclabe, reference, bank_name, beneficiary
voucherMXN OXXOreference, barcode_url
qrCOP Nequi e Bre-Bcode, qr_url, key, checkout_url
redirectCLPurl para o pagador concluir no banco

fee_amount e net_amount são preenchidos quando a cobrança é paga. O valor líquido entra no saldo da moeda.

Listar e buscar cobranças

GET/fx/charges?limit=20&offset=0
GET/fx/charges/{id}
StatusSignificado
pendingAguardando pagamento.
paidPago; o líquido entrou no saldo da moeda.
expiredPassou do prazo sem pagamento.
failedRecusada ou cancelada.

Criar saque

POST/fx/withdrawals

Use um Idempotency-Key. O valor, a taxa e uma pequena reserva para a taxa da rede ficam reservados no saldo da moeda; o que sobrar da reserva volta quando o saque termina.

CampoTipoDescrição
currencystringobrigatório"USDT", "MXN", "COP" ou "CLP".
amountintegerobrigatórioValor a enviar, em unidade mínima da moeda.
destinationobjectobrigatórioConta de destino. Campos por moeda abaixo.
Moedadestination
USDTaddress: endereço Tron (TRC20), começa com T. A taxa de envio da rede é descontada da reserva.
MXNclabe (18 dígitos), name do titular. document opcional.
COPkey, key_type ("PHONE", "EMAIL" ou "CC"), name e document (CC) do titular.
CLPbank_code (3 dígitos), account_number, account_type ("CACC", "SVGS", "VISTA", "RUT" ou "SALARY"), name, document (RUT) e email do titular.
curl -X POST https://stacepay.com.br/api/v1/fx/withdrawals \
  -H "Authorization: Bearer nvx_live_..." \
  -H "Idempotency-Key: mx-saque-0001" \
  -H "Content-Type: application/json" \
  -d '{"currency": "MXN", "amount": 100000, "destination": {"clabe": "012180001234567891", "name": "Juan Pérez"}}'
{
  "object": "fx_withdrawal",
  "id": "fxw_8c1d2e3f4a5b6c7d",
  "status": "processing",
  "currency": "MXN",
  "decimals": 2,
  "method": "spei",
  "amount": 100000,
  "fee_amount": 1000,
  "destination": {"clabe": "012180001234567891", "name": "Juan Pérez"},
  "failure_reason": null,
  "processed_at": null,
  "created_at": "2026-11-10T15:25:00-03:00"
}

Listar e buscar saques

GET/fx/withdrawals?limit=20&offset=0
GET/fx/withdrawals/{id}
StatusSignificado
processingEnviado, aguardando confirmação.
paidConcluído.
failedFalhou; o valor reservado volta ao saldo da moeda.

Webhooks

Eventos fx_charge.paid, fx_charge.expired, fx_charge.failed, fx_withdrawal.paid e fx_withdrawal.failed. Chegam a endpoints que assinam todos os eventos ou que listam esses nomes. Veja Webhooks.