Autopayments and Withdrawal of funds - general information

❖ Definition of concepts

In order to be able to understand the mechanics of how Payments work in general in bots, you need to clearly understand what Variables are and how Balance works in a bot. Familiarize yourself with the BASIC CONCEPTS and DEFINITIONS in these manuals before continuing the study of this material - we will not explain or stipulate these concepts separately in future.

In the context of interaction with payments between the user and the bot, two directions can be distinguished:
1. From the user to the bot - Autopayments (Top-ups, Replenishments).
2. From bot to user - Autowithdrawals (Withdrawals, Payouts).
This section will give you an overview of both directions.

The following list of concepts and terms used in the existing auto payment system is 100% relevant only for the @MenuBuilderBot constructor. In other systems, the spheres defining concepts in payments may differ. Definitions of terms are given in the way they will be used in the texts, the purpose of these definitions is to indicate the boundaries of concepts and make it easier for you to understand the instructions given, however, you need to keep in mind that these definitions are not necessarily correct from the point of view of economic theory and may not be applicable to other bots constructors or payment systems, there is also no reason to consider them scientifically correct. In other words, the definitions provided are applicable only in the context of these manuals.

Payment - transfer of funds in the direction from the user to the bot (other names: Top-up, Replenishment). In general, the user's funds are transferred to the external (Third Party) wallet of the administrator, in any payment system. After that, their equivalent should be credited to the Balance in the bot.

In the context of comparing types of payments, saying "Payment" means rather the situation of manual replenishment of the User's Balance by the operator in the bot, through Feedback Forms. However, in general, the above definition of payment applies to both manual and automatic methods - more describing the principle, rather than pointing to any specific of these two types.

Autopayment is a Payment in which funds are credited to the Balance automatically by identifying the user account (payer) by any of the available methods (possible methods of user identification will be given below).

Sometimes, in groups or support, for simplicity, the whole system of Payments and Payouts is called "Autopayments".

Withdrawal of Funds - transfer of funds in the direction from the bot to the user (other names: Payout). In general, the funds available on the User's Balance in the bot, are going to his external (Third Party) wallet, in any payment system. At the same time, their equivalent must be debited from the Balance in the bot.

Semi-automatic withdrawal of funds is a Withdrawal of funds, in which the withdrawal from the Balance in the bot occurs automatically (when the user orders the Withdrawal), and the transfer to the wallet of the external (Third Party) payment system of the user, after confirmation by the admin, is made manually by admin himself. This method is implemented using the "Withdraw Button".

Autowithdrawal of funds is a Withdrawal when the deduction from the Balance in the bot (at the time your user orders the withdrawal) and the transfer of funds to the wallet of the external (Third Party) payment system of the user (using the API of this system) occur automatically right after Admin's confirmation. Please note that even with automatic withdrawal of funds, the participation of the administrator is required to confirm the payment (our security requirement). This method is implemented using the "Withdraw Button".

❖ Important features of autopayments and autowithdrawals

When working with autopayments and autowithdrawals, all funds are always stored on YOUR wallets.

Autopayments

When using autopayments, @MenuBuilderBot does not have direct access to your funds. The only thing that a payment processor can do is see your wallet balance and its changes, but it TECHNICALLY cannot interact with the funds on the balance in any other way (the prohibition is implemented by means of an external payment system and does not imply your trust in the constructor). This method is absolutely safe in relation to your funds in terms of interaction with the constructor and therefore is provided WITHOUT any special conditions.

IMPORTANT: The only exception in this case is the automatic payment through "Perfect Money". For some reason, it is impossible to set up rights in this system, therefore, even to organize the receipt of payments, you need to provide full access to your wallet.

Withdrawal of Funds - manual and semi-automatic

Manual and Semi-Automatic Withdrawals, as well as Deposits, are as secure, as you can trust yourself, since the actual transfer of funds is carried out manually by the admin. The system only generates a request and writes off virtual funds from the Balance in the bot using a specialized button. When using these methods, the @MenuBuilderBot constructor also TECHNICALLY does not have access to your funds.

Autowithdrawals

Automatic withdrawal of funds in this context stands apart. This is the only mode when the constructor needs full access to the funds in your wallet. For this reason, this method is NOT available to EVERYONE, but only to those who fully understand the mechanisms of automatic payments, security means and in a direct conversation have demonstrated their own adequacy and intellectual readiness. Automatic payments are provided on SPECIAL conditions that will be announced as a result of a personal interview, and only after a collective decision made on the possibility of connecting it. Without agreeing to the SPECIAL Terms, the connection of Autowithdrawals is not carried out.

Autowithdrawals are paid separately - regardless of everything else.

❖ Additional Autopayments features

The options below are available for all types of automatic payments and are specified during first connection.

Duplicate amount

Duplicate top-up amount in a separate variable or variables, both individual and global.
Allows you to save the total amount of replenishment - both - individually for each user and common for all users together.

Referral Parent Bonus

Automatic accrual of bonuses to referral parents of a user replenishing the balance - up the multi-level system.
Allows you to create referral bots where the profit of referral parents is directly depends on deposits. The amount can be indicated as a percentage of the replenishment amount, the number of possible levels will depend on the levels of the Referral System purchased in your bot.

Auto-convert amount

Accrual of incoming funds with their automatic conversion at the specified rate to another conditional currency.
● You can set the rate permanently, take it from some variable in your bot (preferably) or use Extension - automatic Currency Rates for conversion. 
● Different currencies (according to the exchange rate) can be charged into one variable (for example, any incoming currencies can be converted into US dollars or Russian rubles).

When calculating the rate in the autopayment functions, the fastest 10-minute rates will ALWAYS be used IF any of the Currency Rates options are enabled in your bot.

Income reports

Auto-replenishment reports can be sent to a specified group or channel.
● The report shows the top-up amounts, the data of payer, as well as the total amount on the account.

Accruals on different variables

Autopayments sent to the same wallet can be charged to different variables - at the user's choice.
● Available for systems where payments are identified using comments (see the list of possible types of identification below).
● To charge a payment for an additional variable, when replenishing, you can specify your prefix, added to the user ID in the comment.

You can create a prefix yourself. Usually 3-4 letters and dash "-" to separate it from the Usercode itself.
Prefix example: usd-, inv-
Comment example with prefix: usd-8888888 (Prefix and Usercode in the comment)

❖ Payment identification methods

In order for a payment received by an external payment system to be credited to the user who sent it in the bot, this user must be identified in some way.

Currently, the autopayment system uses three types of user identification.
1. Using the Comment - Usercode or Telegram ID added as a comment to the payment.
2. With the help of the Payer's Address - a unique wallet address from which the payment was made.
3. With the help of Issued Invoices - the bot generates links.

There are other ways to identify payments, for example, by generating an individual wallet for replenishment in cryptocurrency payments. However, this method of replenishment, being at the same time both more expensive and, more difficult to create and maintain, thus it is not currently considered, by us, to be of any interest in implementation.

Each of these three identification methods used in the system has its positive and negative sides.

1. Identification by Comment (Usercode or ID)

This method can be used only in those payment systems that support comments on payments. The essence of the method is that the user, having received in the bot and copying his Usercode or Telegram ID, adds it to the comment of his payment in the external payment system, as a result of which the robot, tracking the incoming transactions of the admin's wallet using the API, determines the user who has to receive the payment.

Benefits: The concept can be easily explained to users in the bot's messages and is also very easy to practically implement.

Disadvantages: not all systems support comments, sometimes users, through inattention, may forget to indicate or incorrectly indicate their data.

2. Identification by the Payer's Address (wallet)

This method is more relevant to payments in the cryptocurrency sphere, where the sender's wallet address, playing an important role, can be easily found in the blockchain and associated with the payment amount. The essence of this method is that the user saves the wallet address from which he will conduct transactions, in one of the bot's variables. As if saying thereby: "I will pay from this address". The bot, in turn, tracking incoming transactions on the admin's wallet in the public blockchain explorer, identifies the user by the wallet address he saved, if a payment was received from this address to the admin's wallet.

Advantages: ease of use for the user - all the user needs to do, to replenish, is to simply send funds from the personal wallet, the address of which he saved in the corresponding bot's variable, to the address specified by the admin.

Disadvantages: more complicated to implement, requires additional functionality in the bot itself, requires understanding and certain knowledge from the administrator who creates this type of automatic payment, more complex instructions for users are needed, in most cases users do not understand these instructions, it is impossible to make payments by transferring from exchanges and cryptobots and custodial wallets, as they use their own random addresses for transactions.

3. Identification by Issued Invoice (link)

The essence of the method is that the user from the bot initiates the creation of an individual payment link and, following it to his account in an external payment system, makes a payment by simply confirming the transaction. The admin can specify the payment amount in advance, as well as leave the user the opportunity to specify his own.

Advantages: ease of use for the user, the whole process comes down to following the link and making a payment in a familiar way in an external payment system.

Disadvantages: not many payment systems support this method. Creating a button in the bot for such a payment is a somewhat lengthy process.

4. Identification by Personal Wallet Address (address)

The essence of the method is that user getting PERSONAL crypto address being generated, according to the chosen network (blockchain). Any valid transaction (from anywhere: crypto exchanges, bots, dApps, custodial and non-custodial wallets) made to that address will be automatically accrued to the Balance of his Account.

Advantages: ease of use for the user, he doesn't have to bother from where and how he sends his funds any valid transaction will be processed.

Disadvantages: some systems have "minimal receival" sum limitations.

❖ Available systems

● Payeer (International) - USD, RUB, EUR, BTC, ETH, LTC, USDT, TRX and any available Coins and Tokens (by Usercode)
● CoinBase (International) - BTC, ETH, LTC, USDC, USDT and any available Coins and Tokens (by Usercode)
● Perfect Money (International) - USD, EUR (by Usercode)
● Tron (Crypto) - TRX, USDT and any available Coins and Tokens (by Wallet)
● TON (Crypto) - TON and any available Coins and Tokens (by Wallet, by Usercode)
● Binance (BSC-BEP20) (Crypto) - BNB, USDT and any available Coins and Tokens (by Wallet)
● Polygon (Crypto) - MATIC
● CryptoBot (Crypto) - BTC, ETH, BNB, USDT, USDC, TON (by Invoice)
● xRocket (Crypto) - BNB, TRX, ETH, TON, USDT plus any available Coins and Tokens (by Invoice)
● Cryptomus (Crypto) - BTC, ETH, BNB, USDT, USDC, TON, TRX, LTC, DOGE, DAI, DASH, SOL (by Address)
● PayOK (Russian) - Debit Cards (by Invoice)
● Telegram Stars - (by Invoice)

What will NOT be added:
FaucetPay - the API lacks the necessary capabilities.
PayTM, OVO, DANA - regional payment systems to which we do not have access.

 

❖ General auto payment settings

General settings for auto payments are made in your bot:
🔐Admin | 💸Autopayments

Top-up Group/Channel

One FREE group is provided for auto payment reports. The group can work both in public and private modes. If the group is not set, payment reports will be sent to the bot itself. You can set your own message for the report.

User Notification

You can set your own message that will be sent to the user upon successful accrual of funds.

If the message is not set, the user will not receive any additional notification.

❖ Error messages

FAILED❗️ 🆘 No user comment

This error appears if the user was not identified.

And so, once again: the user can be identified ONLY by the wallet address. If the wallet address in the TRANSACTION (in the blockchain) does not match the wallet address stored by him in the VARIABLE - the bot will show an error and nothing will be added to the Balance.

Reasons why the user was not identified:
1. The user did not set the wallet address at all.
2. The user set the wallet address AFTER he made the transaction.
3. The user made a transaction from crypto-exchange or other type of custodial wallet.

The most common reason is that users send transfers from exchanges or custodial wallets, so wallet addresses do not match.

To make sure that the wallet addresses does not match, you must:
1. Find the transaction on the blockchain using the TXID (hash) of the transaction (you can get it directly in the error message).
2. See the wallet address from which this transaction was actually sent.
3. Using the «/varget var_name user_id» command, you should see what wallet address your user has actually saved in his variable.
4. If these addresses do not match, you explain to the user everything that we have just explained to you here.

When comparing JetTon addresses in the TON network, one thing to keep in mind is that wallet addresses can have different formats.
 • base64 (with numbers, uppercase and lowercase Latin letters, «/» and «+») 
 • base64url (with «_» and «-» instead of «/» and «+»)
That is, addresses like: EQxx/xxx+xxxx and EQxx_xxx-xxxx are the addresses of the SAME wallet.

• • •

FAILED❗️ 🆘 Multiple users found

This error appears if SEVERAL accounts in your bot have specified the SAME wallet to identify their payment. The bot does not know which of them to credit.

Sometimes users indicate the addresses of crypto-exchanges from where those exchanges making withdrawals.
Sometimes users specify the same wallet for several of their accounts.

To correct the situation, find out from the user what address he indicated, where he got it and whether he used it for another account. Remove matching addresses in variables for all but one account.

• • •

❌ Invoice cannot be created.
Error Code: XXX
ℹ️ Report the problem to bot's Admin.

❌ Address cannot be created.
Error Code: XXX
ℹ️ Report the problem to bot's Admin.

Error Codes:
1 - PayID does not correspond to any Balance variable for this currency (check the specified PayID for this currency).
2 - There is no Checker for this PayID (check the specified PayID for this currency or whether the Checker is active).
3 - Incorrect PayID for the Balance variable of this currency (check which one is indicated and indicate the correct one).
4 - Checker is not active (enable or pay for Checker for this payment system).
5 - PayID matches the checker, but not the one for which the invoice was requested (check which PayID you specified for which currencies).

• • •

Unknown error:
BOT_PRECHECKOUT_TIMEOUT

After setting up the Checker, you did not restart your bot.

• • •

Enabled: ⏳

May occur when activating the Checker.
1. Check whether all necessary variables (balances, storage of wallet addresses, etc.) are specified.
2. The activation itself may take longer (just wait 1-2 minutes).
3. If you configure Cryptomus, it may return an error: "Cryptomus check exception. Code: -5, Message: You are restricted to access the site." There is something wrong with the Cryptomus settings. Most likely, you have set something like "only allowed IPs" so the checker's IP address cannot access.

• • •

FAILED❗️ 🆘 Variable not found

The Variable you set up does not start working right away. Set up variables in advance or wait a bit. (This is an old bug - it will be fixed one day.)