🇬🇧
A simple guide on how to integrate TON payments into your app on Directual.
Hello and welcome! Today, we're going to show you how to integrate TON payments into your app on Directual. Oh, and you might want to check out our video tutorial.
TON is an incredible new blockchain built on the Telegram infrastructure. It’s designed as a distributed supercomputer, or “superserver”, intended to provide a variety of products and services to contribute to the development of the decentralized vision for the new internet. You can learn more about TON here.
To show you what this looks like in practice, we'll look at a simple app with regular users and an administrator. The administrator creates bills, and the users pay them.
Let's log in as an administrator and take a look at the My Bills page. This is where you'll find bills that need to be paid, as well as those that have been paid or canceled. Bills have three statuses: New, Paid, and Canceled. This is what it looks like on the page.
The admin page shows all the bills. You can sort them by status or even create a new bill.
The admin can also set the amount in TONs and who the bill is for.
Let's take a look at the data structures of our app. You can find them on the Database tab.
Now, let's take a look at the menu. Here you'll find a link to the My Bills page, which is accessible to everyone. There's also a folder with pages that are only accessible to the administrator.
In addition to the standard web pages, we've got two custom pages: All Bills and My Bills. The All Bills page has two tabs. The first tab has a table view component linked to an administrator-only endpoint.
The second tab has a multistep form component that's also linked to an admin-only endpoint. This form is used to create bills. Let's take a look at the fields. There are just three fields: the amount in TONs, the customer, which is a dropdown linked to an endpoint, and a hidden status field with a default value of New. By default, all new bills are set to status New.
You'll find the Cards view component on the My Bills page, along with an endpoint.
This endpoint, through which the cards receive data, has two filters: Bill User ID equals the user ID, and Status equals the parameter passed by the component, allowing one endpoint to be used for both card view components.
For the card itself, we just use plain HTML. When you click on it, it takes you to a subpage of the My Bills page. This page is also set as the home page.
Now, let’s get TON payments set up. First, we need a wallet. You can use any wallet you like, but I'll be using Wallet from Telegram.
In the app, go to the plugins section and install the free TON plugin from the marketplace. This plugin includes components for web pages and extra steps for different scenarios. You can find all the info you need on this plugin in the official documentation.
Let's start with the web part and add the plugin to the page. Go to the subpage, which is the bill page. This section only shows up if the bill status is New. If the status is Paid, another section will appear.
We only need to worry about the payment component for new bills, so we've put it in this section. It works with an endpoint that gets a single bill object from this subpage. We just insert the wallet where we'll be getting the payments and pull the data from the endpoint. This also includes the amount in nano TONs and the order number.
Just a heads-up: We create all bills in TONs. We use a scenario to populate the nano TONs field.
This scenario runs for all new objects and if the amount in the TONs field has been changed. The amount in nano TONs is just the amount in TONs multiplied by the global constant.
We use the bill ID as the order number. This is how we'll identify the payment. We also need to set up a webhook to receive notifications. Just create a new webhook and enable the CORS option to avoid any errors.
Just copy the URL of this webhook to the component. Now save it and test it out.
In our app, just tap on any new bill to see the Connect wallet button.
Just a heads-up: this button isn't available on paid or canceled bills.
Let's get the wallet connected. We will be using Telegram Wallet.
The wallet says that the My Bills app wants to connect and that all transactions will still be approved by us.
Just a heads-up: You can customize the icon or name in the web app settings under the Icons and General Settings tabs.
We got the wallet connected, great! We can also disconnect it or confirm a transaction.
Now the selected wallet is back up and running, so we click Confirm. The amount will be taken from the wallet. All done! The transaction was a success.
Now, let’s take a look at the Webhook structure. Here, we see that we got a notification, but we need to remember that this notification isn't the same as a transaction confirmation.
In any case, it's a good idea to check the blockchain. You can use Tonscan to check your wallet and see if a transaction with the right amount and comments actually went through.
Now, let’s get the transaction retrieval automated. To do this, just create a new data structure—let's call it TON Transactions—and add the necessary fields. We'll need to add the user ID, amount, link to the bill, and a transaction processing flag, which should be a boolean type.
Also, we need a structure that will serve as a trigger, made up of just one object. This object will run the scenario on a schedule.
Ok, let’s put together a few scenarios. Just put them in a folder called TON. The first scenario is called Get TON Transactions. This scenario is going to use the single trigger object, which is going to run on a daily schedule. These types of scenarios retrieve all the objects from the structure and then process them. In our case, it's just one object with an ID of one.
Let's add the Get TON Transactions step. This step gives us a response in JSON format, which we need to save. To do that, just add another JSON field to the trigger and go back to the scenario.
In this step, you'll need to specify the address where you want to receive transactions and the response field.
You can check the debug panel to see that the TON API service gave us a JSON containing all the transactions.
To parse them, we need to have an array of links to future transactions. We just need to add the array link field to the TON Transactions structure. Let's go back to the scenario and add the JSON step to parse the response.
If you add comments, it'll make the scenarios easier to follow. Next, let's set up the JSON step and decide on the response structure. This is how the JSON is structured, which we'll use to parse it. Next, let's set up the parsing rules.
The data is stored in the API response field. We broke down the JSON Transactions array into objects that we stored in the Transactions array.
The docs say which fields we should be looking at: mainly value and comment.
We grab the value from this JSON and add it to the Amount nano TONS field of future transaction objects. We also pull the comment from the Decoded Body object.
We just need to add the text field to the comment field. Now, save it. Next, we need to process the transactions that are stored in the Array link field. We'll do this in another scenario, so let's add the Link scenario step and set up the transaction processing scenario itself. This scenario works with the TON Transactions structure without any triggers because we'll call it with the Link scenario step.
First, we check to see if the transaction has already been processed. Just a heads-up: We added the Is Processed field. If this field is true, we just exit the scenario. This means the transaction has already been processed. If it hasn't been processed yet, we'll get it done.
For clarity, let's run this scenario and see what happens. The Link scenario step can work with an array of linked objects and send them to another scenario.
Let's run it and see how it works. Just send the trigger object through the debug panel, and we'll take a look. The logs show that everything is working as it should be, and we can see all the transactions in the data structure.
Here's the last one—the one we just did. There are more transactions in the list. You can filter out some old ones if the comment field is empty. Either the transaction is being processed or the comment is empty.
Next, we'll get the bill ID from this comment. You can find out how to do this in the documentation. It's a bit of a tricky one, but it's basically just a regular expression. You can just copy it from the official documentation. This is the simplest way to get the order number. We use the Comment field and switch the Coding mode on, which lets us use JavaScript to process the data.
Once we've got the bill ID, we can open it as a linked object and change the status to Paid, and set the Is Processed flag to True.
Now, save and publish the scenario. Let’s take a look at the transaction retrieval step. Test the scenario using the debug panel. Send the object and take a look. The bill status changes to Paid. It worked!
Now, let’s talk about the notifications we get from the webhook. They're mainly used to get transactions from the blockchain in a timely manner. To run a scenario by trigger, we need a link to this trigger. So, we add a context variable of Link type to the Trigger structure.
Next, we need to populate this context variable.
Just a heads-up: We've got the ID in the Link field, and it's set to one.
Once you get the notification, it might take a few minutes for the transaction to show up on the blockchain. Let's set a delay of three minutes. Once that's done, we'll send the trigger object—a linked object from the context variable—to our Get TON Transactions scenario.
It's possible that the blockchain might not be fast enough in three minutes, so let's check it twice. After three minutes and after six minutes.
This way, a chain of two launches of the Get TON Transactions scenario ensures that the user sees their transaction in near real-time.
If you follow these steps, you'll be able to successfully integrate TON payments into your app on Directual. Join our no-code community, share your ideas and ask questions. See you next time!
TON (The Open Network) is a fast-growing blockchain that mainly uses Telegram's infrastructure, making it simple to buy, withdraw, and integrate into apps. Using TON lets you tap into Telegram's massive ecosystem and provide your users with a simple way to pay.
You'll need a TON wallet, which you can register via Wallet from Telegram or any other provider. You'll also need to install the free TON plugin from the Directual marketplace.
Just open your Directual dashboard, go to the Marketplace tab, and start browsing. If you see a plugin you'd like to use, just select it and click Install. You can also do this from the Plugins section within your app.
Hop into our cozy community and get help with your projects, meet potential co-founders, chat with platform developers, and so much more.
