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.

How to check status and retrieve info

By body hash

By reference

Return shape

Response fields

On this page