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.

Response fields

amount · string · required

Human-readable amount with decimals.

rawAmount · string · required

Amount in base units; nano for TON and jetton base units.

senderAddr · string · required

Sender wallet address.

recipientAddr · string · required

Recipient wallet address.

asset · string · required

Asset address. “TON” for coin or jetton master address.

status · string · required

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.

reference · string · required

Tracking reference returned at creation time.

bodyBase64Hash · string · required

Base64 hash of the signed message body content (payload). Used for lookups.

txHash · string · required

Transaction hash assigned by the network.

traceId · string · required

Trace identifier for explorer.

commentToSender · string

Optional note shown to the payer while signing. Public on-chain; avoid confidential data and keep under 120 characters to reduce gas.

commentToRecipient · string

Optional note shown to the payee after receipt. Public on-chain; avoid confidential data and keep under 120 characters to reduce gas.