API REST

Base URL

https://api.tonramp.io

Autenticação

Para usar a API REST de parceiro é preciso uma API key no formato tonr_<prefix>_<secret>, criada no console do parceiro.

O acesso ao console é por magic link:

Envie POST /v1/partner/auth/request-link com o e-mail cadastrado.
Você recebe um link por e-mail; ao abri-lo, a sessão emite um token JWT.
Com a sessão de owner, crie uma API key em POST /v1/partner/api-keys. A chave bruta é exibida uma única vez — guarde com segurança. Ela pode ser revogada a qualquer momento.

Envie a API key nas chamadas autenticadas no header:

Authorization: Bearer tonr_<prefix>_<secret>

Endpoints sob /v1/partner/... (como GET /v1/partner/transactions) usam o token JWT da sessão do parceiro, também enviado como Authorization: Bearer ....

Endpoints

POST /v1/wallet/trp/generate

Gera um payload TRP e retorna os links de pagamento.

Request:

curl -X POST https://api.tonramp.io/v1/wallet/trp/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tonr_SUA_API_KEY" \
  -d '{
    "wallet": "UQBJ6gU8gh_jRrzYDlfw9cpCwHaSn2mrK4O-1h8CDENehGYJ",
    "merchant": "store123",
    "amount": 100.00,
    "currency": "USDT",
    "tx_id": "pedido-001"
  }'

Response (200):

{
  "success": true,
  "payload": "trp010148UQBJ6gU8...",
  "deep_link": "https://trp.tonramp.io/trp/trp01...",
  "telegram_link": "https://t.me/TonRmpBot/tonramp?startapp=trp01..."
}

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
`wallet`	string	Sim	Endereço TON de destino (10-48 chars)
`merchant`	string	Sim	ID do estabelecimento
`amount`	number	Sim	Valor do pagamento em USDT (ex: 100.00 = 100,00 USDT)
`currency`	string	Não	Moeda fixa: `USDT` (padrão). Outros valores são rejeitados.
`tx_id`	string	Sim	ID da transação (máx 64 chars)
`merchant_id`	number	Não	Loja ativa sob o parceiro. Ausente = caminho 1:1 (wallet do parceiro). Ver Merchants.

O generate não abre o checkout PIX. Esse trilho é só o POST /v1/c, para o mesmo tx_id não virar dois pagamentos.

POST /v1/c

Cria o checkout PIX do pedido. Mesma autenticação por API key. Ver Checkout PIX.

POST /v1/wallet/trp/parse

Decodifica um payload TRP e retorna os campos.

Request:

curl -X POST https://api.tonramp.io/v1/wallet/trp/parse \
  -H "Content-Type: application/json" \
  -d '{"payload": "trp010148UQBJ6gU8gh_jRrzYDlfw9cpCwHaSn2mrK4O-1h8CDENehGYJ0208store1230305100000404USDT0508tx12345699045D57"}'

Response (200):

{
  "success": true,
  "data": {
    "wallet": "UQBJ6gU8gh_jRrzYDlfw9cpCwHaSn2mrK4O-1h8CDENehGYJ",
    "merchant": "store123",
    "amount": 10000,
    "currency": "USDT",
    "tx_id": "tx123456",
    "crc_valid": true
  }
}

POST /v1/wallet/trp/validate

Valida o CRC de um payload TRP.

curl -X POST https://api.tonramp.io/v1/wallet/trp/validate \
  -H "Content-Type: application/json" \
  -d '{"payload": "trp010148UQBJ6gU8gh_jRrzYDlfw9cpCwHaSn2mrK4O-1h8CDENehGYJ0208store1230305100000404USDT0508tx12345699045D57"}'

Response: {"valid": true} ou {"valid": false}

GET /v1/trp/status/{tx_id}

Consulta o status de uma transação TRP.

Request:

curl "https://api.tonramp.io/v1/trp/status/pedido-001?token=abc123def456"

Response (200):

{
  "status": "pending",
  "amount": "10000",
  "currency": "USDT",
  "updated_at": "2026-03-26T12:00:00Z"
}

Response (403): Token inválido ou ausente.

Response (404): Transação não encontrada.

Status possíveis:

Status	Descrição
`pending`	Aguardando pagamento
`error`	Falha no processamento
`paid`	Pagamento recebido, processando a entrega
`completed`	USDT entregue, transação concluída
`expired`	Expirou sem pagamento

POST /v1/trp/preference

Salva a preferência de plataforma do usuário em cookie.

Request:

curl -X POST https://api.tonramp.io/v1/trp/preference \
  -H "Content-Type: application/json" \
  -d '{"platform": "telegram"}'

Response (200):

{
  "success": true,
  "platform": "telegram"
}

Plataformas aceitas: telegram, google (web)

O cookie tonramp_platform é setado com SameSite=None para funcionar cross-origin.

GET /v1/partner/transactions

Lista paginada das transações TRP do parceiro. Use para conciliação.

Query params:

Parâmetro	Descrição
`status`	Filtra por status (opcional)
`search`	Busca textual (opcional)
`limit`	Itens por página, 1 a 200 (padrão conforme servidor)
`offset`	Deslocamento para paginação

Request:

curl "https://api.tonramp.io/v1/partner/transactions?status=completed&limit=50&offset=0" \
  -H "Authorization: Bearer <token>"

Response (200):

{
  "items": [
    {
      "id": 123,
      "parent_tx_id": "tx123456",
      "partner_id": 7,
      "partner_name": "store123",
      "amount_brl": null,
      "amount_usdt": 100.00,
      "status": "completed",
      "status_label": "completed",
      "paid": true,
      "completed": true,
      "payer_wallet": "UQBJ6gU8gh_jRrzYDlfw9cpCwHaSn2mrK4O-1h8CDENehGYJ",
      "unit_price": 1.0,
      "service_fee": 1.0,
      "created_at": "2026-03-26T12:00:00Z",
      "expiration_time": "2026-03-26T12:30:00Z",
      "close_time": "2026-03-26T12:05:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Cada item contém os campos: id, parent_tx_id, partner_id, partner_name, amount_brl, amount_usdt, status, status_label, paid, completed, payer_wallet, unit_price, service_fee, created_at, expiration_time, close_time.

Página de checkout

GET /trp/{payload}

Renderiza a página de checkout a partir de um payload TRP.

Parâmetros de query (opcionais):

Parâmetro	Valores	Descrição
`layout`	`vertical`, `horizontal`	Layout da página (padrão: vertical)
`theme`	`light`, `dark`, `auto`	Tema visual (padrão: auto)
`lang`	`pt-br`, `en`, `es`	Idioma (padrão: detectado pelo navegador)
`merchant_name`	string	Nome de exibição do comerciante

Exemplo:

https://trp.tonramp.io/trp/{payload}?layout=horizontal&theme=dark&lang=en

Rate Limiting

Endpoint	Limite
`POST /v1/wallet/trp/generate`	30/minuto
`POST /v1/wallet/trp/parse`	30/minuto
`POST /v1/wallet/trp/validate`	30/minuto
`GET /v1/trp/status/\{tx_id\}`	60/minuto
`POST /v1/trp/preference`	10/minuto

Respostas com rate limit excedido retornam HTTP 429 Too Many Requests.