Skip to main content
Payment processing on TON refers to monitoring and handling blockchain transactions for business applications. While simple use cases can rely entirely on smart contracts, most real-world payment systems require off-chain processing to track deposits, manage user balances, send confirmations, and integrate with existing business logic.

​
On-chain vs off-chain processing

On-chain processing executes all payment logic within smart contracts. When a user sends TON or Jettons to a contract, the contract immediately processes the payment and updates state. This works for simple scenarios like direct peer-to-peer transfers or automated market makers, but becomes impractical when you need user accounts, payment history, refunds, or integration with external systems. Off-chain processing monitors blockchain state changes from outside the network. Your application observes transactions, verifies their validity, updates internal databases, and triggers business logic. Exchanges, merchants, and payment processors use this approach because it provides flexibility to implement complex workflows, maintain user data, and integrate with traditional systems.

​
Transaction finality

TON achieves transaction finality after a single masterchain block confirmation, typically within 1 second. Once a transaction from a shardchain appears in a masterchain block, it becomes irreversible. This differs from blockchains like Ethereum where merchants wait for multiple confirmations (usually 12-15 blocks, taking 2-3 minutes) or Bitcoin where 6 confirmations are standard (about 60 minutes). Since the Catchain 2.0 update, the masterchain coordinates all workchain activity and produces blocks approximately every 400 milliseconds. When monitoring payments, you need to verify that the transaction was included in a masterchain block rather than just in a shardchain. Most TON APIs provide methods to check whether a transaction has achieved masterchain finality or, better yet, only consider a transaction included in the masterchain as finalized by the network.

​
Supported assets

TON supports several asset types for payment processing: Toncoin is the native currency of the network. Every wallet can receive Toncoin directly without additional setup. Transfers are simple value transfers between addresses, making Toncoin the easiest asset to process. Jettons are fungible tokens following the TON Enhancement Proposal 74 (TEP-74) standard. Each Jetton type has a master contract and individual wallet contracts for each holder. When processing Jetton payments, you monitor the Jetton wallet contract associated with your deposit address. Transfer notifications include sender information and transfer amounts. Read more about how Jettons work.

​
Implementation approaches

Three main approaches exist for implementing payment processing on TON: Self-built solution: You run your own service that connects to some TON API or liteserver, monitors blocks for relevant transactions, and maintains a database of payment events. This requires building infrastructure to fetch blocks, parse transactions, handle reconnections, and manage state. The advantage is complete control over the implementation and no dependency on external services. The disadvantage is significant development and maintenance effort. Self-hosted payment processor: Open-source payment processors like Bicycle and Spice harvester provide ready-to-deploy solutions that handle blockchain monitoring and expose APIs for your application. You deploy the processor on your infrastructure, configure it for your wallet addresses and asset types, and consume its API to track payments. This balances control with reduced development effort, though you still manage the infrastructure. Third-party payment processor: External services handle all blockchain interaction and provide simple APIs or webhooks for payment notifications. You integrate their SDK or API, and they manage infrastructure, monitoring, and maintenance. This is fastest to implement but introduces dependency on the service provider and typically involves transaction fees. The choice depends on your requirements for control, development resources, and operational complexity. High-volume applications often build custom solutions, while smaller merchants prefer third-party services.

​
Monitoring payments

Payment monitoring requires polling for new blocks and filtering transactions that affect your addresses. For Toncoin, you check for incoming messages to your wallet address. For Jettons, you monitor the Jetton wallet contract associated with your address for transfer notifications. The typical monitoring flow involves fetching the latest workchain blocks, retrieving all transactions from them, filtering for transactions involving your addresses, parsing transaction data to extract amounts and metadata, verifying the transaction reached finality, and updating your internal payment records. Most applications poll for new blocks every few seconds. More sophisticated systems use multiple strategies: polling for recent data, webhooks from indexing services for real-time notifications, and periodic reconciliation to catch any missed transactions.