TON API integration: payment acceptance and Jetton balances in 1-2 days

TON API integration: where incoming payment accounting breaks

TON API integration almost always starts with a simple scenario: a transfer event is received — and the amount is credited.

In practice, these are two independent processes: a transaction enters a block and gets confirmation, while accounting in your system is updated by a separate call.

If crediting is done based on sending rather than transaction confirmation, the balance grows before the transfer is finalized, and the diverging branch leaves money in the database that does not exist.

Then comes double crediting. The same event arrives again: the service restarted during an update, the notification was duplicated, a retry request fired after a timeout.

Without idempotency by transaction hash, the client sees a doubled balance, and the cause has to be found manually — by matching transfer history against database records.

A separate category of failures is Jettons. Each has its own contract, its own transfer rules, and its own fee deduction order, so Jetton balance reconciliation almost never matches what the interface shows.

Worse are "stuck" transfers: sending went through, confirmation did not arrive, the payment is visible neither in accounting nor in the report, and the client has already written to support.

The cost of these discrepancies is manual reconciliation: an engineer matches transfers on the network line by line against system records while the payment remains unidentified.

We break down how this is closed: exactly where to put transaction confirmation, how to separate repeated events, and what to use to reconcile Jetton balances without manual work.

What direct integration provides: speed and balance reconciliation

Connecting to the TON network is built on a subscription, not manual transfer checks: the service listens to blockchain events and receives a notification about an incoming payment at the moment of transaction confirmation.

The balance in the user account is updated a few seconds after the transfer, not after an operator checks the statement. Crediting time no longer depends on human workload — this is the main effect of direct integration.

The second layer is idempotent processing: each event comes with a unique transfer identifier, and repeated delivery does not create a second credit. This removes the class of failures with duplicates and stuck transfers between internal accounting and the network.

The operations log stores the transaction hash, sender, payment purpose, and confirmation status — any disputed situation can be reconstructed from it.

Automatic reconciliation runs on the same event stream: the service periodically compares the operations log with the state of addresses and Jetton wallet balances, and discrepancies enter a report before the client or support notices them.

The share of operations reconciled without human involvement is displayed in monitoring — it shows where manual work still remains.

Notifications about incoming payments go to the interface, email, or the customer's internal system, so crediting is picked up by business logic immediately.

In practice, crediting time drops to a few seconds, the share of automatically reconciled operations reaches 95% and above, and a "lost transfer" ceases to be a separate scenario: the payment is either visible in the log, or it is clear at which step it stopped.

Payment acceptance models: custodial, non-custodial, hybrid

Accepting payments on the TON network is primarily a question of who retains the private keys and who signs fund withdrawals. Key storage determines both the support effort and the maximum withdrawal speed you promise the user.

In a custodial model, keys are in our environment: withdrawals happen automatically, without manual confirmation — the price for this is separation of hot and cold storage and strict access control to the signing service.

In a non-custodial model, keys remain with you or the user: we track balances, but each withdrawal is confirmed on your side. The hybrid takes from both: the operational limit lives in a hot wallet, and the remainder is withdrawn to cold storage.

In practice, hybrid is chosen more often: automatic withdrawal works within the limit, and the entire volume of funds is not kept online. We fix the choice in a procedure — where keys are stored, who signs, and at what withdrawal size the second confirmation is connected.

Implementation procedure: from scheme audit to handover to support

We divide implementation into six stages, each with a measurable result and acceptance point. At any iteration, the customer sees what already works and can stop work without losing what has been done.

1. Audit of the current scheme. We analyze how incoming payments are accounted for today: which operations register is considered the source of truth, which addresses and contracts are involved, where statements and internal accounting diverge. The result is a current-state map with a list of discrepancies, which is also the acceptance point for the stage.
2. Payment flow scheme. We design addressing for incoming transfers: a unique payment identifier or a separate address per client, rules for matching a transfer to an order, handling underpayments and retries, reading Jetton balances. The approved scheme is the stage acceptance.
3. Test network. We set up an environment on test coins and run scenarios: successful payment, underpayment, repeated sending, transfer with the wrong token, payment against an expired invoice.
4. Failure testing. We break the connection to the node, duplicate transaction notifications, delay confirmation. The goal is that one transfer does not create a second payment, and scheduled reconciliation catches discrepancies.
5. Acceptance by procedure. We reconcile balances and the operations register against a checklist, resolving every discrepancy to zero. The stage is not closed until control sums match.
6. Handover to support. We provide documentation, the flow scheme, access, logs, and the incident response procedure, and train the on-call shift.

After that, TON API integration lives as an ordinary service — it can be developed without rebuilding the payment loop.

Configurations, schemes, and procedures that remain with you

Working payment acceptance is not yet the result: if the logic depends on one engineer's knowledge, the first team rotation or contractor change turns the service into a black box.

Therefore, along with the code, we hand over a set of artifacts that your specialists can use to run, maintain, and develop the integration themselves — without contacting the authors for every clarification.

• Integration documentation — which methods we call to create an invoice, track an incoming payment, and read Jetton balances; request and response structure, error code breakdown, and an unambiguous rule for how to respond to each of them.
• Key storage scheme — where the wallet keys physically reside, who gets access to them and by what algorithm, the rotation procedure, and the sequence of actions if compromise is suspected.
• Access policies — roles of services and people, minimum necessary permissions, separation of payment acceptance and fund withdrawal environments, so that leakage of one access does not open the entire wallet.
• Failure handling procedure — behavior when external nodes are unavailable and confirmation is delayed, retry rules, the point from which a payment is considered final, and the procedure for reconciling discrepancies.
• Support instructions — breakdown of typical requests (transaction not visible, amount does not match, status stuck), where to look at logs, what to tell the user, and at which step to involve engineers.
• Flow and state scheme — the path from invoice issuance to crediting with marked state persistence points: after a service restart, no payment is lost or duplicated.
• Acceptance and update checklist — a set of checks after changes on the external network side and a list of metrics that must be in monitoring so degradation is noticed before client complaints.

We put everything into your repository in the format accepted by your team — with change history and owners for sections. After that, the system lives by your rules, not by our memory of how it was assembled.

Case study: payment acceptance without manual reconciliation and lost transfers

A digital goods service came to us: it accepted payment in TON and Jettons, but every transfer was confirmed by a support operator.

The transaction identifier was matched against the order number manually, the amount and purpose were checked by eye, and only then were funds credited to the user account.

In the evening, the queue reached dozens of transfers, and the share of operations requiring manual review stayed at 100% — not a single payment went through without a human.

What we changed

We set up payment acceptance through the network's programmatic interface: subscription to incoming transfers, matching by address, amount, and purpose, automatic crediting with a separate manual review threshold for large amounts.

Jetton balances were no longer reconciled by a daily export — the discrepancy is calculated for each incoming payment and highlighted immediately, together with the operation context.

What we achieved

• share of operations with manual review — from 100% to 4%, the rest closes automatically within minutes;
• balance discrepancy response time — from several hours to 10-15 minutes, and we learn about the problem before the client does;
• the evening transfer queue disappeared as a phenomenon: support handles disputed cases rather than reconciliation.

Previously, discrepancies accumulated until the daily reconciliation, and finding the source retroactively was almost impossible — correspondence and exports had to be pulled up.

Now every payment is linked to an order from the first second, and the verification history is restored from the operations log.

If payment acceptance already works through a third-party service

Yes — migration is done without downtime: during payment acceptance migration, two schemes run in parallel.

The previous service continues to accept and credit funds, while our own handler runs alongside it, independently reading the same transactions from the network and keeping its own accounting.

Such dual-scheme operation removes the main risk — a gap at the moment of switching. The payment address for the transition period remains the same, so saved user details and wallets continue to work.

Each credit is reconciled across two sources — by transaction hash and by internal payment identifier; a discrepancy is visible immediately while the intermediary is still connected.

Operations history is transferred by export and matched against network data: old incoming payments, refunds, and statuses remain in the system, and reporting and support do not lose context.

We separately go through edge cases — payments at the moment the service is disconnected, partial incoming payments, repeated notifications, stuck confirmations.

Abandoning the intermediary is the last step; we do it only when reconciliation matches across the entire history depth.

External notifications are disabled, the source of truth becomes our own network handler, and the application reads Jetton balances and native coins directly through TON API.

From then on, crediting, statuses, and retries are controlled by our side — without someone else's processing speed limit and without waiting for someone else's support.

Technical concerns: confirmations, limits, access to keys

Before starting TON API integration, engineers ask the same five questions. Below are short answers: how we address each point without rewriting your product or taking control over funds.

Are there withdrawal limits?

We set the minimum amount, daily cap, and order of requests by policy on your side. If declined, the request does not disappear: it remains in the log with the reason.

Do you get access to private keys?

No. Signing remains in your environment — we connect with a limited-permission key and see only addresses and public data.

What about reprocessing operations?

Each operation is marked by hash: a repeated notification from the network does not create a second payment or double the balance.

What to do when the network node is unavailable?

We work through multiple entry points with automatic switching. Operations wait in a queue with retries; after recovery, we reconcile the log — no discrepancies remain.

Let's discuss the task: we'll review the scheme and come back with a work plan

So that the scope estimate is based on facts rather than assumptions, we need a picture of your side: how payments currently pass, where keys are stored, who owns the receiving wallet, and what limits apply to operations.

This forms an implementation plan with realistic launch timelines, not an "average market estimate."

Send us, in any form, what you already have:

• Current payment acceptance scheme: manual transfers, cash desk, acquiring, or a partially working TON integration.
• Integration requirements: which events need to be tracked — incoming transfers, Jetton balances, withdrawals — at what frequency and where to send the data.
• Infrastructure constraints: where services are deployed, who administers network nodes, what is required for storing operations history and access to it.
• Failure scenarios: an undelivered transfer, repeated sending, balance discrepancy — how they are handled now and who deals with such cases.
• Who on your side is responsible for key security and approves changes on the production environment.
• Desired launch timelines and the date by which payment acceptance must operate in production mode.

In response, you receive a scope estimate broken down by stages, an implementation plan with checkpoints, and a list of requirements for your side — what to prepare before the start.

Describe the task as it is, with current constraints and timelines: we'll discuss the details and come back with a plan.