Checkout

Checkout flow

1. Your backend generates a TRP payload with the payment data (in USDT)
2. The payload is sent to the frontend as a universal link
3. The buyer scans the QR code or clicks the link
4. The checkout page detects the platform:
   • Telegram User-Agent → redirects to the bot
   • Preference cookie → redirects accordingly
   • No preference → renders page with buttons (Telegram / Web)
5. The buyer confirms the amount and signs the USDT transfer via TonConnect
6. The merchant receives USDT in the wallet specified in the payload
7. Your system queries the status via API

Note

The merchant charges directly in USDT. No fiat conversion (BRL/USD/EUR) is performed by the protocol: the amount shown to the buyer equals what the merchant receives (minus the TonRamp fee).

Generating the checkout

Via Web Generator

Visit trp.tonramp.io and fill in:

• Destination TON wallet
• Merchant ID
• Payment amount in USDT
• Transaction ID (optional, auto-generated)

Via API

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

Via code (client-side)

import { generateTrpPayload } from '@/utils/trp'

const payload = generateTrpPayload(
  'UQBJ6gU8gh_jRrzYDlfw9cpCwHaSn2mrK4O-1h8CDENehGYJ',
  'store123',
  '100.00',
  'USDT',
  'tx123456'
)

const checkoutUrl = `https://trp.tonramp.io/trp/${payload}`

Checkout page

The checkout page at trp.tonramp.io/trp/\{payload\} displays:

• TonRamp logo
• Merchant name
• Amount formatted in USDT
• QR code with the universal link
• “Pay via Telegram” button
• “Pay via Browser” button
• Payment status (polling every 5 seconds)

Note

The checkout supports light and dark themes automatically, with manual toggle.

Querying status

After the buyer clicks the link, you can query the status:

curl https://api.tonramp.io/api/v1/trp/status/{tx_id}

Response:

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

Possible statuses: pending, paid, completed, expired.

Quote API

Before confirming the payment, the mini app fetches a quote to get the final amount (with fee) and balance:

curl -H "Authorization: Bearer {token}" \
  https://api.tonramp.io/api/v1/trp/quote/{payload}

Response:

{
  "merchant": "store123",
  "wallet_dest": "UQBJ6gU8gh_...",
  "amount_usdt": 100.00,
  "fee_usdt": 1.0,
  "total_required_usdt": 101.00,
  "user_balance_usdt": 120.0,
  "has_sufficient_balance": true,
  "tx_id": "tx123456",
  "quote_id": "abc123",
  "quote_ttl_seconds": 120
}

Caution

The quote endpoint requires authentication (Bearer token). The quote_id must be passed to the payment execution endpoint to protect against amount/destination manipulation.

Fees

Each TRP payment charges:

• Fixed fee: max(1 USDT, 1% of the charged amount)
• TON gas: a small on-chain cost of a few millicents of TON, paid by the buyer from their wallet

Example for a 100 USDT charge:

• Amount to the merchant: 100.00 USDT
• TonRamp fee: 1.00 USDT
• Total debited from the buyer: 101.00 USDT

Payment flow in the mini app

When the buyer clicks “Pay via Telegram” or “Pay via Browser”:

1. The mini app reads start_param from Telegram WebApp (or ?startapp= in the URL)
2. If the parameter starts with trp01, it redirects to the confirmation screen
3. The screen calls GET /api/v1/trp/quote/{payload} to get amount, fee, total, and balance
4. Displays: merchant, USDT amount, fee, total, buyer balance
5. If insufficient balance: “Top up with PIX” button (top-up flow being built out)
6. If sufficient balance: “Confirm payment” button generates the TonConnect transaction
7. The buyer signs the transfer in their wallet
8. USDT is transferred: amount to the merchant + fee to the TonRamp hot wallet, atomic in a single signature