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).

Caution

USDT confirmed on-chain has no automatic refund. See the refund and dispute policy.

Generating the checkout

Caution

The checkout page only renders payments addressed to the wallet of a registered partner (anti-phishing protection). A payload for an unknown wallet gets 404 “Merchant not recognized”.

Via API

curl -X POST https://api.tonramp.io/v1/wallet/trp/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tonr_YOUR_API_KEY" \
  -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:

• Your logo, when configured, or the 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.

Your brand on the checkout

In the console, under Checkout, you set the brand shown on the payment page of your charges:

• Logo: PNG, JPEG or WebP, up to 96 KB. A transparent background works better, because the page has light and dark themes.
• Brand colour: used on the amount and the pay button. The text colour over it is picked automatically by contrast, so a light brand does not produce an unreadable button.

Only the partner owner can change the branding.

What does not change: the “Powered by TonRamp” signature stays in the footer, and the payment itself happens in the TonRamp app, opened by the buttons on the page. Branding covers the entry page, not the whole flow.

Custom domain (CNAME to hosted.tonramp.io), what branding does not cover, and the DNS steps are in White label.

Querying status

Besides the webhook, you can query the order by tx_id with your API key:

curl https://api.tonramp.io/v1/wallet/trp/status/{tx_id} \
  -H "Authorization: Bearer tonr_YOUR_API_KEY"

The response includes status (pending, paid, completed, error, expired, cancelled, refunded) and flow (direct when paid in the app, pix_checkout when paid through PIX checkout). Details in API.

If the buyer loads balance with PIX inside the app, that top-up does not count as paying the order: the order is paid when they confirm the direct payment right after. If the same tx_id was already paid through PIX checkout, the app shows the order as paid and does not charge again.

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/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 /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