From efc9b5294a1e8054a17716da977f7f54f6aa6008 Mon Sep 17 00:00:00 2001 From: kaladin <335095@niuitmo.ru> Date: Tue, 28 Oct 2025 17:23:42 +0300 Subject: [PATCH 1/8] add stub --- docs.json | 6 +++++ payments/overview.mdx | 52 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 58 insertions(+) create mode 100644 payments/overview.mdx diff --git a/docs.json b/docs.json index a0873129a..a982fd604 100644 --- a/docs.json +++ b/docs.json @@ -277,6 +277,12 @@ "ecosystem/ai" ] }, + { + "group": "Payment processing", + "pages": [ + "payments/overview" + ] + }, { "group": "Standard contracts", "pages": [ diff --git a/payments/overview.mdx b/payments/overview.mdx new file mode 100644 index 000000000..0f1fe1fab --- /dev/null +++ b/payments/overview.mdx @@ -0,0 +1,52 @@ +--- +title: "Payment processing overview" +sidebarTitle: "Overview" +--- + +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 5 seconds. Once a transaction 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). + +The masterchain coordinates all workchain activity and produces blocks approximately every 5 seconds. When monitoring payments, you need to verify that the transaction exists in a masterchain block rather than just in a shard chain. Most TON libraries provide methods to check whether a transaction has achieved masterchain finality. + +## Supported assets + +TON supports several asset types for payment processing: + +**Toncoin** is the native currency of the network. Every wallet can receive Toncoins 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 address rather than your main wallet. Transfer notifications include sender information and transfer amounts. + +**NFTs** follow the TEP-62 standard and represent unique digital assets. While less common for payment processing, some applications accept NFTs as payment or proof of ownership. NFT transfers work similarly to Jettons, with ownership tracked in individual item contracts. + +## Implementation approaches + +Three main approaches exist for implementing payment processing on TON: + +**Self-built solution**: You run your own indexer that connects to TON nodes or liteservers, 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 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 Toncoins, 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 masterchain block, retrieving all transactions in that block, 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. + +## Next steps + +Understanding payment processing fundamentals enables you to choose the right implementation approach for your application. The following sections provide detailed guides for monitoring specific asset types and building payment infrastructure on TON. From 3bed54515147d3316e7063c17cc70b127bd65c33 Mon Sep 17 00:00:00 2001 From: kaladin <335095@niuitmo.ru> Date: Tue, 28 Oct 2025 17:35:00 +0300 Subject: [PATCH 2/8] more and links --- payments/jettons.mdx | 0 payments/overview.mdx | 17 ++++++++++------- payments/toncoin.mdx | 0 3 files changed, 10 insertions(+), 7 deletions(-) create mode 100644 payments/jettons.mdx create mode 100644 payments/toncoin.mdx diff --git a/payments/jettons.mdx b/payments/jettons.mdx new file mode 100644 index 000000000..e69de29bb diff --git a/payments/overview.mdx b/payments/overview.mdx index 0f1fe1fab..d7264be9a 100644 --- a/payments/overview.mdx +++ b/payments/overview.mdx @@ -13,9 +13,9 @@ Off-chain processing monitors blockchain state changes from outside the network. ## Transaction finality -TON achieves transaction finality after a single masterchain block confirmation, typically within 5 seconds. Once a transaction 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). +TON achieves transaction finality after a single masterchain block confirmation, typically within 5 seconds. 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). -The masterchain coordinates all workchain activity and produces blocks approximately every 5 seconds. When monitoring payments, you need to verify that the transaction exists in a masterchain block rather than just in a shard chain. Most TON libraries provide methods to check whether a transaction has achieved masterchain finality. +The masterchain coordinates all workchain activity and produces blocks approximately every 5 seconds. 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 transaction included in masterchain as finalized by the network. ## Supported assets @@ -23,17 +23,20 @@ TON supports several asset types for payment processing: **Toncoin** is the native currency of the network. Every wallet can receive Toncoins 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 address rather than your main wallet. Transfer notifications include sender information and transfer amounts. +**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. -**NFTs** follow the TEP-62 standard and represent unique digital assets. While less common for payment processing, some applications accept NFTs as payment or proof of ownership. NFT transfers work similarly to Jettons, with ownership tracked in individual item contracts. +Read more about [how Jettons work](/standard/tokens/jettons/how-it-works). + +- [Toncoin processing](/payments/toncoin) +- [Jetton processing](/payments/jettons) ## Implementation approaches Three main approaches exist for implementing payment processing on TON: -**Self-built solution**: You run your own indexer that connects to TON nodes or liteservers, 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-built solution**: You run your own service that connects to some TON API or [liteserver](/ecosystem/rpc/overview), 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 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. +**Self-hosted payment processor**: Open-source payment processors like [Bicycle](https://github.com/gobicycle/bicycle) 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. @@ -43,7 +46,7 @@ The choice depends on your requirements for control, development resources, and Payment monitoring requires polling for new blocks and filtering transactions that affect your addresses. For Toncoins, 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 masterchain block, retrieving all transactions in that block, 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. +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. diff --git a/payments/toncoin.mdx b/payments/toncoin.mdx new file mode 100644 index 000000000..e69de29bb From b0ca0fb859dd2ca29898ed5b940b3d2b2f97e5a4 Mon Sep 17 00:00:00 2001 From: kaladin <335095@niuitmo.ru> Date: Tue, 28 Oct 2025 17:37:08 +0300 Subject: [PATCH 3/8] stubs --- docs.json | 5 ++++- payments/jettons.mdx | 8 ++++++++ payments/toncoin.mdx | 8 ++++++++ 3 files changed, 20 insertions(+), 1 deletion(-) diff --git a/docs.json b/docs.json index a982fd604..6fdf9afc4 100644 --- a/docs.json +++ b/docs.json @@ -280,7 +280,10 @@ { "group": "Payment processing", "pages": [ - "payments/overview" + "payments/overview", + "payments/toncoin", + "payments/jettons" + ] }, { diff --git a/payments/jettons.mdx b/payments/jettons.mdx index e69de29bb..97a171405 100644 --- a/payments/jettons.mdx +++ b/payments/jettons.mdx @@ -0,0 +1,8 @@ +--- +title: "Jettons payments processing" +sidebarTitle: "Jettons" +--- + +import { Stub } from '/snippets/stub.jsx'; + + diff --git a/payments/toncoin.mdx b/payments/toncoin.mdx index e69de29bb..852268608 100644 --- a/payments/toncoin.mdx +++ b/payments/toncoin.mdx @@ -0,0 +1,8 @@ +--- +title: "Toncoin payments processing" +sidebarTitle: "Toncoin" +--- + +import { Stub } from '/snippets/stub.jsx'; + + From 091b48fd1f98f05c4d13efc633a324606fce7607 Mon Sep 17 00:00:00 2001 From: kaladin <335095@niuitmo.ru> Date: Tue, 28 Oct 2025 17:43:11 +0300 Subject: [PATCH 4/8] spell --- resources/dictionaries/custom.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/resources/dictionaries/custom.txt b/resources/dictionaries/custom.txt index 34664e436..a887d35e8 100644 --- a/resources/dictionaries/custom.txt +++ b/resources/dictionaries/custom.txt @@ -628,6 +628,7 @@ pytoniq queryable ragpull recv +reconnections redeclaration redeclared redistributable From 3486e4dcd3f814c6c4afe143c90169811eb95fa3 Mon Sep 17 00:00:00 2001 From: verytactical <186486509+verytactical@users.noreply.github.com> Date: Tue, 28 Oct 2025 20:14:11 +0400 Subject: [PATCH 5/8] Dewater --- payments/overview.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/payments/overview.mdx b/payments/overview.mdx index d7264be9a..a3f426589 100644 --- a/payments/overview.mdx +++ b/payments/overview.mdx @@ -50,6 +50,4 @@ The typical monitoring flow involves fetching the latest workchain blocks, retri 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. -## Next steps -Understanding payment processing fundamentals enables you to choose the right implementation approach for your application. The following sections provide detailed guides for monitoring specific asset types and building payment infrastructure on TON. From a6dc2178df4d0d358233609e2923c3c2447c2823 Mon Sep 17 00:00:00 2001 From: verytactical <186486509+verytactical@users.noreply.github.com> Date: Tue, 28 Oct 2025 20:14:41 +0400 Subject: [PATCH 6/8] Dewater2 --- payments/overview.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/payments/overview.mdx b/payments/overview.mdx index a3f426589..6d6b0a635 100644 --- a/payments/overview.mdx +++ b/payments/overview.mdx @@ -50,4 +50,3 @@ The typical monitoring flow involves fetching the latest workchain blocks, retri 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. - From 6f92d4a87ccdd8d4a6a2b053091bb5af0c0f0b0c Mon Sep 17 00:00:00 2001 From: verytactical <186486509+verytactical@users.noreply.github.com> Date: Tue, 28 Oct 2025 20:18:12 +0400 Subject: [PATCH 7/8] Update payments/overview.mdx --- payments/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/payments/overview.mdx b/payments/overview.mdx index 6d6b0a635..6e1d826af 100644 --- a/payments/overview.mdx +++ b/payments/overview.mdx @@ -23,7 +23,7 @@ TON supports several asset types for payment processing: **Toncoin** is the native currency of the network. Every wallet can receive Toncoins 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. +[**Jettons**](/standard/tokens/jettons/overview) 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](/standard/tokens/jettons/how-it-works). From cfee7e743e71896c5ebfc79c90d089deecc0b627 Mon Sep 17 00:00:00 2001 From: Your Name Date: Tue, 28 Oct 2025 20:20:14 +0400 Subject: [PATCH 8/8] formatting --- payments/overview.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/payments/overview.mdx b/payments/overview.mdx index 6e1d826af..cdc7e86c3 100644 --- a/payments/overview.mdx +++ b/payments/overview.mdx @@ -49,4 +49,3 @@ Payment monitoring requires polling for new blocks and filtering transactions th 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. -