Pagamentos e saques/Payment API

API de pagamentos

Crie e gerencie sessões de pagamento em criptomoedas com a API de pagamentos da 2328.io.

A API de pagamentos permite criar sessões de pagamento, redirecionar clientes para um checkout hospedado e acompanhar o status do pagamento.

Criar pagamento

Cria uma sessão de pagamento e retorna uma URL para o cliente realizar o pagamento.

Parâmetros da requisição

Campo	Tipo	Obrigatório	Descrição
`amount`	decimal	sim	Valor do pagamento na moeda informada, ex.: `100.00`
`currency`	string	sim	Moeda fiduciária (USD, EUR, RUB, …) ou criptomoeda (USDT, TRX, BTC, …)
`order_id`	string	sim	Seu ID de pedido, ex.: `ORDER-12345` (até 128 caracteres)
`to_currency`	string	não	Criptomoeda pré-selecionada
`network`	string	não*	Código da rede (obrigatório quando `to_currency` está definido ou `currency` é uma criptomoeda)
`url_return`	string	não	URL de redirecionamento após o pagamento, ex.: `https://your-site.com/return`
`url_success`	string	não	Alternativa a `url_return`
`url_callback`	string	não	URL para notificações de webhook, ex.: `https://your-site.com/webhook`
`invite_code`	string	não	Código do indicador
`fee_split`	decimal	não	Parcela da taxa do comerciante repassada ao pagador, 0–100 (%). 0 = comerciante paga integralmente, 100 = pagador paga integralmente. Sobrescreve a configuração do projeto. Exemplo: `30` (pagador cobre 30% da taxa).
`price_markup`	decimal	não	Acréscimo ou desconto sobre o valor da fatura, −99 a 100 (%). Sobrescreve a configuração do projeto. Exemplo: `5` (+5%) ou `-10` (10% de desconto).
`description`	string	não	Descrição opcional da fatura (máx. 200 caracteres). Exibida ao pagador na página de pagamento. Exemplo: `Premium plan — Order #12345`.
`ttl_seconds`	int	não	Tempo de vida da fatura em segundos, de `300` (5 minutos) a `86400` (24 horas). Após esse período a fatura expira e não pode mais ser paga. Padrão: `3600` (1 hora). Exemplo: `3600`.

Resposta

JSON

{
  "state": 0,
  "result": {
    "uuid": "abc123-def456-...",
    "order_id": "ORDER-12345",
    "amount": "100.00",
    "currency": "USD",
    "amount_usd": "100.00",
    "exchange_rate": null,
    "url": "https://2328.io/pay/abc123-def456-...",
    "tg_deeplink": "https://t.me/my2328bot?start=pay_abc123-def456-...",
    "expires_at": "2026-01-11T21:00:00Z",
    "created_at": "2026-01-11T20:00:00Z",
    "payer_currency": "USDT",
    "payer_amount": "100.50",
    "network": "TRX-TRC20",
    "address": "TXYZabc123...",
    "payment_status": "check",
    "txid": null,
    "payment_amount": null,
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

Redirecione o cliente para result.url para concluir o pagamento.
tg_deeplink — deeplink do bot do Telegram para pagamento via Telegram MiniApp.
qr — QR code (data URI) do endereço de depósito codificado em base64. Presente quando um endereço já foi atribuído (quando network é informado junto com to_currency, ou quando currency é uma criptomoeda); caso contrário, null.
txid, payment_amount — null até que o cliente pague. Preenchidos assim que a transação é detectada on-chain. Escute o webhook payment_status: paid para saber quando.
exchange_rate — null se a conversão ainda não se aplica (por exemplo, a taxa fiat → cripto ainda não foi travada). Preenchido assim que a moeda do pagador é definida.

Credentials

Project UUIDAPI key

RequestPOST/v1/payment

curl -X POST https://api.2328.io/api/v1/payment \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Response

Click Try it to see the response here.

Informações do pagamento

Obtenha o status atual de um pagamento por uuid ou order_id.

Parâmetros da requisição

Campo	Tipo	Obrigatório	Descrição	Valores
`uuid`	string	sim*	UUID do pagamento (de `result.uuid` na criação)
`order_id`	string	sim*	Seu ID de pedido

Pelo menos um entre uuid e order_id é obrigatório.

RequestPOST/v1/payment/info

curl -X POST https://api.2328.io/api/v1/payment/info \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Response

Click Try it to see the response here.

Lista de pagamentos

Obtenha uma lista de todos os pagamentos com filtros e paginação.

Parâmetros da requisição

Campo	Tipo	Obrigatório	Descrição
`status`	string	não	Filtrar por status do pagamento (veja References)
`date_from`	date	não	Data inicial (YYYY-MM-DD), ex.: `2026-01-01`
`date_to`	date	não	Data final (YYYY-MM-DD), ex.: `2026-01-31`
`page`	int	não	Número da página, padrão `1`
`per_page`	int	não	Itens por página, padrão `15`, máximo `5000`

RequestPOST/v1/payment/list

curl -X POST https://api.2328.io/api/v1/payment/list \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Response

Click Try it to see the response here.