# 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](https://stacepay.com.br/docs/carteiras). 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

| Moeda | País | decimals | Receber (method) | Sacar |
| --- | --- | --- | --- | --- |
| `USDT` | Stablecoin (rede Tron) | 6 | `TRC20` (endereço de depósito com valor exato) | Envio para carteira Tron (TRC20) |
| `MXN` | México | 2 | `SPEI` (transferência para CLABE), `OXXO` (dinheiro, MX$10 a MX$10.000) | SPEI para CLABE |
| `COP` | Colômbia | 2 | `NEQUI_QR` (QR Nequi), `BREB` (QR Bre-B) | Bre-B por chave |
| `CLP` | Chile | 0 | `BANK_TRANSFER` (transferência bancária) | Transferência bancária |

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

`GET /fx/currencies`

_json_

```json
{
  "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`

_json_

```json
{
  "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.

| Campo | Tipo |  | Descrição |
| --- | --- | --- | --- |
| `currency` | string | obrigatório | "USDT", "MXN", "COP" ou "CLP". |
| `amount` | integer | obrigatório | Valor em unidade mínima da moeda. |
| `method` | string | opcional | Método de pagamento (tabela acima). Sem ele, usa o primeiro da moeda. |
| `description` | string | opcional | Descrição da cobrança. |
| `reference` | string | opcional | Seu identificador interno. |
| `payer` | object | opcional | Dados do pagador: name, email, document, phone. Exigências por moeda abaixo. |

| Moeda | Dados do pagador |
| --- | --- |
| MXN | `name` obrigatório no SPEI. `document` (CURP ou RFC) e `email` opcionais. |
| COP | `phone` opcional: celular de 10 dígitos começando com 3. |
| CLP | `name`, `email` e `document` (RUT válido) obrigatórios. |
| USDT | Nenhum. A resposta traz `instruction.address` (rede Tron) e `instruction.amount`: o pagador deve enviar exatamente esse valor, com as casas decimais. |

_curl_

```bash
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"}}'
```

_json_

```json
{
  "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.type | Quando | Campos |
| --- | --- | --- |
| `bank_transfer` | MXN SPEI | `clabe`, `reference`, `bank_name`, `beneficiary` |
| `voucher` | MXN OXXO | `reference`, `barcode_url` |
| `qr` | COP Nequi e Bre-B | `code`, `qr_url`, `key`, `checkout_url` |
| `redirect` | CLP | `url` 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}`

| Status | Significado |
| --- | --- |
| `pending` | Aguardando pagamento. |
| `paid` | Pago; o líquido entrou no saldo da moeda. |
| `expired` | Passou do prazo sem pagamento. |
| `failed` | Recusada 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.

| Campo | Tipo |  | Descrição |
| --- | --- | --- | --- |
| `currency` | string | obrigatório | "USDT", "MXN", "COP" ou "CLP". |
| `amount` | integer | obrigatório | Valor a enviar, em unidade mínima da moeda. |
| `destination` | object | obrigatório | Conta de destino. Campos por moeda abaixo. |

| Moeda | destination |
| --- | --- |
| USDT | `address`: endereço Tron (TRC20), começa com T. A taxa de envio da rede é descontada da reserva. |
| MXN | `clabe` (18 dígitos), `name` do titular. `document` opcional. |
| COP | `key`, `key_type` ("PHONE", "EMAIL" ou "CC"), `name` e `document` (CC) do titular. |
| CLP | `bank_code` (3 dígitos), `account_number`, `account_type` ("CACC", "SVGS", "VISTA", "RUT" ou "SALARY"), `name`, `document` (RUT) e `email` do titular. |

_curl_

```bash
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"}}'
```

_json_

```json
{
  "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}`

| Status | Significado |
| --- | --- |
| `processing` | Enviado, aguardando confirmação. |
| `paid` | Concluído. |
| `failed` | Falhou; 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](https://stacepay.com.br/docs/webhooks).
