StacePay Documentação da API / Carteiras e conversão
Markdown

Carteiras e conversão

Cada moeda tem a sua própria carteira, com saldo separado: BRL (saldo principal), USDT, MXN, COP e CLP. Você recebe direto na moeda, converte de uma carteira para outra sem sacar e saca quando quiser.

AçãoComoOnde cai
ReceberPOST /charges (Pix em BRL) ou POST /fx/charges (USDT, MXN, COP, CLP)Na carteira da moeda cobrada
ConverterPOST /conversionsSai da carteira de origem e entra na de destino. Nada é sacado.
SacarPOST /withdrawals (Pix) ou POST /fx/withdrawalsSai da carteira para fora da StacePay

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

Saldos

GET/wallets

Lista todas as carteiras disponíveis para a sua conta, inclusive BRL. reserved é o valor separado para saques em andamento.

{
  "object": "list",
  "data": [
    { "object": "wallet", "currency": "BRL", "decimals": 2, "available": 1250000, "reserved": 0, "convertible": true },
    { "object": "wallet", "currency": "USDT", "decimals": 6, "available": 184120000, "reserved": 0, "convertible": true }
  ]
}

Cotação

Mostra quanto entra na carteira de destino, já descontadas as taxas. Não debita nada.

POST/conversions/quote
CampoTipoDescrição
from_currencystringobrigatórioCarteira de origem: BRL, USDT, MXN, COP ou CLP.
to_currencystringobrigatórioCarteira de destino, diferente da origem.
amountintegerobrigatórioValor a converter, em unidade mínima da moeda de origem.
curl -X POST https://stacepay.com.br/api/v1/conversions/quote \
  -H "Authorization: Bearer nvx_live_..." \
  -H "Content-Type: application/json" \
  -d '{"from_currency": "BRL", "to_currency": "USDT", "amount": 100000}'
{
  "object": "conversion_quote",
  "from_currency": "BRL",
  "to_currency": "USDT",
  "amount": 100000,
  "fee_amount": 500,
  "estimated_amount": 184120000,
  "rate": 0.18504,
  "from_decimals": 2,
  "to_decimals": 6
}

A conversão usa a cotação do momento em que é executada, que pode variar um pouco em relação à prévia.

Converter

POST/conversions

Use um Idempotency-Key. KYC aprovado é obrigatório. Os campos são os mesmos da cotação.

curl -X POST https://stacepay.com.br/api/v1/conversions \
  -H "Authorization: Bearer nvx_live_..." \
  -H "Idempotency-Key: conv-0001" \
  -H "Content-Type: application/json" \
  -d '{"from_currency": "BRL", "to_currency": "USDT", "amount": 100000}'
{
  "object": "conversion",
  "id": "cv_3f9a1c2b7d4e5f60",
  "status": "completed",
  "from_currency": "BRL",
  "to_currency": "USDT",
  "from_decimals": 2,
  "to_decimals": 6,
  "amount": 100000,
  "fee_amount": 500,
  "converted_amount": 184110000,
  "rate": 0.18503,
  "failure_reason": null,
  "completed_at": "2026-11-10T15:20:02-03:00",
  "created_at": "2026-11-10T15:20:00-03:00"
}

O valor de amount sai da carteira de origem na hora. Com completed, converted_amount já está na carteira de destino.

Listar e buscar

GET/conversions?limit=20&offset=0
GET/conversions/{id}

Status possíveis

StatusSignificado
processingOrigem debitada, aguardando a confirmação da troca.
completedConvertido. converted_amount entrou na carteira de destino.
failedRecusada; o valor volta inteiro para a carteira de origem. Motivo em failure_reason.

Webhooks

EventoQuando
conversion.completedA conversão foi concluída e o destino creditado.
conversion.failedA conversão foi recusada e a origem devolvida.

Receber e sacar USDT

A carteira USDT funciona na rede Tron (TRC20).