How to check status and retrieve info
After sending, look up the final result and details. The SDK exposes two lookup functions.
By body hash
Use the Base64 hash of the signed message body payload.
import { getTonPayTransferByBodyHash } from "@ton-pay/api";
const info = await getTonPayTransferByBodyHash(bodyBase64Hash, {
chain: "testnet",
});By reference
Use the reference returned by createTonPayTransfer.
import { getTonPayTransferByReference } from "@ton-pay/api";
const info = await getTonPayTransferByReference(reference, {
chain: "testnet",
});Return shape
type CompletedTonPayTransferInfo = {
amount: string;
rawAmount: string;
senderAddr: string;
recipientAddr: string;
asset: string;
assetTicker?: string;
status: string;
reference: string;
bodyBase64Hash: string;
txHash: string;
traceId: string;
commentToSender?: string;
commentToRecipient?: string;
date: string;
errorCode?: number;
errorMessage?: string;
};Use status to drive UI state and use reference, bodyBase64Hash, and txHash for reconciliation.
For Toncoin payments, the recipient amount may be reduced by network fees. Use jettons or slightly overpay in TON when an exact settlement amount is required.
Response fields
amountstringrequired
Human-readable amount with decimals.
rawAmountstringrequired
Amount in base units; nano for TON and jetton base units.
senderAddrstringrequired
Sender wallet address.
recipientAddrstringrequired
Recipient wallet address.
assetstringrequired
Asset address. "TON" for coin or jetton master address.
statusstringrequired
Possible values:
pending– the transfer is created and awaits confirmation on the blockchain.success– the transfer is completed successfully; the trace completes without errors.error– the transfer fails; the trace completes with an error.
referencestringrequired
Tracking reference returned at creation time.
bodyBase64Hashstringrequired
Base64 hash of the signed message body content (payload). Used for lookups.
txHashstringrequired
Transaction hash assigned by the network.
traceIdstringrequired
Trace identifier for explorer.
commentToSenderstring
Optional note shown to the payer while signing. Public on-chain; avoid confidential data and keep under 120 characters to reduce gas.
commentToRecipientstring
Optional note shown to the payee after receipt. Public on-chain; avoid confidential data and keep under 120 characters to reduce gas.