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ção | Como | Onde cai |
|---|---|---|
| Receber | POST /charges (Pix em BRL) ou POST /fx/charges (USDT, MXN, COP, CLP) | Na carteira da moeda cobrada |
| Converter | POST /conversions | Sai da carteira de origem e entra na de destino. Nada é sacado. |
| Sacar | POST /withdrawals (Pix) ou POST /fx/withdrawals | Sai 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
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.
| Campo | Tipo | Descrição | |
|---|---|---|---|
from_currency | string | obrigatório | Carteira de origem: BRL, USDT, MXN, COP ou CLP. |
to_currency | string | obrigatório | Carteira de destino, diferente da origem. |
amount | integer | obrigatório | Valor 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
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
Status possíveis
| Status | Significado |
|---|---|
processing | Origem debitada, aguardando a confirmação da troca. |
completed | Convertido. converted_amount entrou na carteira de destino. |
failed | Recusada; o valor volta inteiro para a carteira de origem. Motivo em failure_reason. |
Webhooks
| Evento | Quando |
|---|---|
conversion.completed | A conversão foi concluída e o destino creditado. |
conversion.failed | A conversão foi recusada e a origem devolvida. |
Receber e sacar USDT
A carteira USDT funciona na rede Tron (TRC20).
- Receber:
POST /fx/chargescom"currency": "USDT". A resposta traz o endereço de depósito e o valor exato a enviar (com casas decimais que identificam o pagamento). Veja Moedas. - Sacar:
POST /fx/withdrawalscom"currency": "USDT"e"destination": {"address": "T..."}.