Deposit Synchronizations

Access Prerequisites

• Permission (module): viewDeposits — and, for the By transaction hash mode, also syncDepositFromChain
• License/Feature: DEPOSITS_HANDLING
• Menu container: GENERAL → Operations group

What it is / when to use

A tool for recovering on-chain deposits that never reached the customer's wallet. The screen has two modes:

• By transaction hash (recommended) — you provide the network and the hash. The system reads the transaction on-chain, credits the deposit and also checks whether that wallet's webhook is correctly configured on Tatum, creating or fixing whatever is wrong. This is the mode that addresses the root cause of the ticket.
• By block — reprocesses an entire block. Use it when you don't have the hash, when the network is not covered by the hash mode, or when you need to sweep several transactions at once.

Why the deposit never arrived

Automatic crediting depends on a webhook that Tatum fires when the customer's wallet receives value. If that wallet has no webhook registered, or if the webhook points to an outdated callback URL (domain or environment change), the value lands on the blockchain and nothing happens on the platform. Reprocessing the block credits that one deposit, but the next deposit to the same wallet fails again. The hash mode fixes the configuration, which is why it is preferred.

Prerequisites

• Permission: viewDeposits to open the screen; syncDepositFromChain to use the hash mode (dual permission — CPM enum + dynamic module in DB). Without syncDepositFromChain, the mode selector does not appear and only the block mode is available.
• License/Feature: DEPOSITS_HANDLING enabled (without it the menu item does not appear at all).
• Dependencies from other screens: the destination user of the on-chain deposit must have a mapped wallet; the transaction must target a monitored wallet in order to generate a credit.

Mode 1 — By transaction hash

Covered networks

Ethereum, Polygon, BSC, TRON and Bitcoin. For Solana, XRPL and other networks, use the block mode — in the selector, networks that are not covered appear disabled.

Step by step

1. Access the Operations → Deposit Synchronizations menu.
2. Keep the By transaction hash mode selected.
3. Select the Network where the deposit was made.
4. Paste the Transaction hash exactly as shown on the network explorer (the field is trimmed; required).
5. Confirm by clicking Sync transaction and wait — the query is synchronous and may take a few seconds.
6. Read the report that appears below the form.

Reading the report

The report has two tables. The first, Deposits, shows what happened to each amount received by a system wallet:

Status	What it means	What to do
Credited	The deposit has just been posted to the customer's balance	Nothing — close the ticket
Already credited	The deposit had already been posted before	Nothing — check the customer's balance/statement to confirm
Ignored	There is no credit to make: internal transfer between platform wallets, zero amount, or currency/token not registered	Read the Detail column; if it says the currency is not supported, register the token before retrying
Failed	The system tried to credit and could not	Read the Detail column and proceed to the manual credit (below)

The second, Tatum webhooks, shows the wallet configuration check:

Action	What it means
Already correct	The webhook existed and pointed to the right URL — nothing was changed
Created	The wallet had no webhook at all; one was created now
Fixed	The webhook pointed to another URL; it was recreated with the correct URL (the old URL appears in the detail)
Failed	Tatum rejected the operation — read the detail and escalate to the technical team

Whenever there is a Created or Fixed, the screen highlights a notice: from that point on, the next deposits to that wallet arrive on their own.

Webhook fixed, but the transaction did not process

These are two independent things, and it is normal for one to succeed and the other not to.

If the report says the webhook was Created or Fixed but the deposit shows as Failed (or no row appears under Deposits), the outcome is still useful: the wallet configuration is repaired and future deposits will come in normally. Only this transaction's amount is missing.

For that amount, proceed with the manual credit on the customer's record:

1. Open Users → User list and go into User details - General.
2. Use the Credit balance action (requires the ADMIN_BALANCE_CONTROL module).
3. Enter the token and the amount exactly as shown in the report (Amount and Asset columns) — keep every decimal place.
4. Describe the ticket and the transaction hash in the justification, so the entry stays traceable in the audit trail.

Before crediting manually, confirm no credit was posted

Manual credit is not idempotent: if the amount already went through, you will credit it twice and there is no automatic rollback.

Before posting, confirm that the report row is not marked Credited or Already credited, and check the customer's statement looking for the transaction hash. When in doubt, do not credit — escalate to the technical team.

Mode 2 — By block

Step by step

1. Access the Operations → Deposit Synchronizations menu.
2. Select the By block mode.
3. Select the Network (e.g.: Ethereum, BSC, Polygon, Arbitrum, Optimism, Avalanche, Base, Moonbeam) — the list comes from getNetworks().
4. Enter the Block number to reprocess (the field is trimmed; required).
5. Confirm by clicking Reprocess block — calls reprocessBlock({ network, blockNumber }).
6. Monitor the success or error feedback (snackbar).

The block mode does not fix the configuration

Reprocessing the block recovers that one deposit, but it does not look at the wallet's webhook. If the cause is a missing webhook or a wrong URL, the problem returns on the next deposit. Whenever you have the hash and the network is covered, prefer the hash mode.

Fields

Field	What it is	Required?	System/backend effect
Network	Target blockchain	Yes	Defines the chain queried by ExternalBlockchainProvider; validates against the list of enabled networks. In hash mode, networks that are not covered are disabled
Transaction hash	On-chain transaction identifier	Yes (hash mode)	Triggers syncTransactionByHash({ network, txHash }): reads the transaction, credits the legs targeting system wallets and audits the webhooks of the wallets involved
Block number	Block to reprocess	Yes (block mode)	Triggers re-reading of the block; transactions to monitored wallets generate a credit via FMS (idempotent by txHash)

Actions and modals

• Sync transaction: validates the form, trims the hash and calls syncTransactionByHash. The form is not cleared on success — the hash stays on screen so you can copy it into the ticket. The report appears below the form.
• Reprocess block: validates the form, trims the block number and calls reprocessBlock. On success, clears the form; on error, displays the message returned by the backend.

Business rules / cautions

Caution

• Network and hash must match. A valid hash queried on the wrong network returns "transaction not found". Check the explorer before opening a technical ticket.
• In block mode, provide the exact block number — reprocessing the wrong range will not create the missing credit.
• If the network list fails to load, the screen displays an error — verify service availability before trying.
• Native transfers made through an internal contract call are not detected by the hash mode; use the block mode in those cases. Token transfers show up normally.
• The tenant's default fiat currency and the USD→EUR bridge affect the reading/reconciliation of credited amounts.

• Financial values: handled as BigNumber — no rounding. When copying an amount from the report into a manual credit, keep every decimal place.
• Idempotency: the credit is idempotent by txHash — syncing the same transaction (or reprocessing the same block) multiple times does not duplicate credits. If FinLib returns E00021 "already processed", that deposit had already been credited (success). Manual credit does not have this protection.
• Transaction with more than one recipient: if the same transaction pays two system wallets, idempotency by hash means only the first leg produces an entry. The report warns when this happens — the remaining ones need a manual credit.
• APPROVED status: crediting the user presupposes a user with status APPROVED.
• Targeted fix, not bulk: the hash mode fixes the webhook of the wallets in that transaction. For a broad correction, escalate to the technical team.

Related screens

• User details - General — where the manual balance credit lives
• Manage Manual Payments
• Manage Withdrawals
• Back to Financial index