Meet Merchant Receipt

Accept payments on the TRON network through a separate address for every invoice without giving the service private keys to the funds.

What the project is for

A conventional cryptocurrency payment setup often requires many wallets and private keys. This makes the infrastructure harder to maintain and creates an additional security risk.

Merchant Receipt assigns a separate settlement address with no private key to every invoice. The service detects payments, maintains history, runs checks and automation, but does not store keys capable of withdrawing received funds.

What merchants gain

What you need to begin

Signing in requires a message signature. This is not a transaction: authentication does not transfer funds or grant spending permission.

When network costs apply

Viewing data, creating invoices, receiving notifications and routine service requests do not send a transaction from the merchant wallet.

A real transaction may be required to register a factory, change its on-chain parameters or resolve an exception manually, such as issuing a refund, selecting a custom recipient or managing the factory wallet.

Learn more about network cost coverage by the service

How the system is organized

How a payment is processed

Key terms

Merchant

A person or company accepting payments through Merchant Receipt.

Factory

A project-specific payment setup combining its asset, recipient, processing rules and invoices.

Factory wallet

A smart-contract wallet used for factory assets and service operations.

Factory recipient

The address that receives funds when a payment is processed normally.

Invoice

A payment request with an amount, expiration time, rules and a separate payment address.

Invoice activation

Final processing of a received payment by a smart contract.

TMR

The service settlement token used to pay a factory's invoice processing fees.

Requires attention

An invoice that does not match its rules and requires a merchant decision.

Dashboard overview

A single workspace for configuring payment acceptance, monitoring invoices and resolving situations that require a merchant decision.

What the dashboard is for

Merchant UI is designed for day-to-day control of payment infrastructure. Use it to prepare a factory, verify its readiness, monitor payments and make decisions when automatic processing has been paused by the configured rules.

Main sections

Preliminary address check

This tool helps assess a prospective payer's address before accepting a payment. It looks for known labels on the address and analyzes its immediate incoming and outgoing interactions to a depth of one level.

Wallet and action confirmation

The dashboard opens after connecting the owner's wallet. Signing a message is enough to sign in: authentication does not transfer funds or send a transaction to the network.

You will encounter two types of confirmation. A message signature sends an instruction to the service without a network fee. A real transaction changes state on the TRON network and may require TRX, Bandwidth or Energy. Before every confirmation, the dashboard clearly identifies the operation type and purpose.

Dashboard for control, SDK for invoice flow

You can create an individual invoice manually in the dashboard. For an online store, application or another production service, we recommend creating invoices through the Node.js SDK on the merchant's own server.

Which devices to use

The interface adapts to different widths, but detailed tables, settings and manual operations are more convenient on a computer or tablet. Until a dedicated mobile application is available, we recommend at least a tablet-sized screen for full operation.

Additional interface verification

We plan to release a Google Chrome extension as an additional security layer. It will not be required for signing in or routine use.

The extension will be able to monitor important dashboard processes, verify the sources of loaded content and warn when the interface version is unknown or modified. Independent comparison of payment addresses with on-chain factory data is also planned.

Recommended workflow

Payment factory

A merchant's personal smart contract that defines invoice-processing rules and protects critical payment acceptance settings.

What a factory is

After an application is approved, a separate MerchantFactory contract is created on TRON. It is permanently linked to the owner's wallet and the selected asset. The factory calculates future invoice addresses, stores on-chain settings and pays processing fees from its own TMR balance.

A factory is not a shared customer wallet. In the normal flow, invoice funds are sent directly to the payout address selected by the merchant. Separate factories are useful for different projects, assets or payment models.

Factory settings

Settings are separated by purpose. On-chain parameters affect the movement of funds. The profile organizes work in the dashboard without changing contract logic.

On-chain parameters

Profile and integrations

The public invoice page uses the current recipient name and logo from the factory profile. This off-chain data cannot change the asset, payout address, invoice amount, or contract rules for moving funds.

Who controls what

Authority is deliberately separated. The service coordinates processing but cannot rewrite the merchant's financial terms.

How the fee is agreed

The fee is charged in TMR only when an invoice is activated. The factory contract stores active and scheduled terms separately: an increase cannot take effect earlier than 201,600 TRON blocks, approximately 7 days.

Discount when AML is disabled

If the merchant disables built-in AML screening, the effective invoice processing fee is reduced by the discount configured for the factory.

For the first 7 days after the factory starts, an introductory discount of 0.5 TMR per invoice applies. This grace period lets the merchant test the factory without built-in AML screening at a lower cost.

After the introductory period, the discount is 0.2 TMR per invoice. The base fee does not change; only the discount amount changes. Current terms are always displayed in the dashboard.

The service sets the discount, but the contract requires it to remain below the base fee. Only the owner decides whether AML is disabled. The lower cost means accepting additional risks, described separately in the AML section.

What TMR is

TMR is Merchant Receipt's service settlement token on TRON. It is used only to pay factory invoice-processing fees and keeps service expenses separate from customer funds.

The working supply is capped at 1,000,000,000 TMR with 6 decimals and is assigned in full to the main contract at launch. In the normal model, TMR moves only between the main contract and personal factories.

How the backing is protected

When TMR is transferred to a factory, an equal amount of USDT reaches the main contract in the same operation. If either side fails, the entire transaction is reverted.

Security of merchant funds

The factory smart contract cannot be upgraded by the service or receive new powers after publication. Financially significant restrictions can be verified directly on-chain.

The service can pause a factory to stop new processing, but it cannot redirect accepted funds to itself. The payout address and manual decisions remain under the owner's wallet control.

When a factory is ready

A factory is active when the service has enabled it, its asset and payout address are valid, and the recipient is ready to accept the selected token. The dashboard shows readiness problems separately instead of hiding them behind a single status.

Warming up the payout address

A warmed-up address is already activated on TRON and has a non-zero balance of the accepted TRC20 asset. When a token is sent to an empty balance, the token contract usually has to create a new state entry, so the operation consumes more Energy. A previously inactive address may also require additional network resources.

Network cost coverage

The service may provide Energy and Bandwidth for an individual merchant network operation and count the actual usage against the merchant's daily limit.

What the service covers

For selected merchants, the service may provide the resources required to execute transactions on TRON. In that case, the individual operation does not consume the owner's Energy and Bandwidth; actual usage is counted against the daily coverage limit.

Coverage may apply to factory setting changes, manual activation and invoice plan setup, factory and invoice wallet operations, and other actions that the owner confirms with an on-chain transaction.

Limits and resource availability

The daily limit is the maximum resource amount available to the account during the current accounting day. The remainder is shown in the account card and checked again before every operation.

The limit and the service's current resource capacity are different values. A positive limit remainder does not mean that the corresponding amount of Energy and Bandwidth is permanently reserved for the merchant.

What to check before signing

Check the Network cost row in the confirmation dialog. It shows the decision for the current attempt, so do not rely only on the account's general status.

How a covered operation is performed

When coverage is unavailable

When the preliminary check finds insufficient limit or service resources, the dashboard does not block the action. The confirmation dialog states that the factory owner pays, and the standard TRON mechanism applies.

If resources cannot be prepared after a covered operation has been confirmed, the merchant transaction is not submitted. The dashboard reports an error; a retry performs a new estimate and determines the network payer again.

Terms of availability

A displayed limit does not obligate the service to cover every subsequent operation and does not represent resources reserved in advance. For urgent operations, consider that your own wallet may need to cover the transaction when service coverage is temporarily unavailable.

Payment invoices

A dedicated settlement address for every order. It accepts payment without a private key and becomes a smart-contract wallet only when activated.

The invoice before activation

When a merchant creates an invoice, Merchant Receipt reserves its sequential number and calculates its future payment address. No smart-contract code exists at that address yet. It is still a valid TRON address, and the customer can already send the selected asset to it.

The address is derived by fixed rules from the factory, invoice number, and future wallet code. The same inputs always produce the same result, and the invoice cannot belong to another factory.

Why there is no private key

An invoice address is not created from a new key pair. Merchant Receipt therefore has no database of payment-address private keys, the merchant has no separate secret for every order, and the customer does not have to trust a server wallet to hold the funds.

Even if the Merchant Receipt servers are compromised, an invoice key cannot be exposed because no such key exists. Before the contract is activated, funds cannot be moved from the address with an ordinary signature. During activation, the predetermined wallet code appears at the exact calculated address and executes the configured rules.

Local calculation in merchant infrastructure

When invoices are created through the Node.js SDK, the address is calculated inside the merchant's infrastructure and checked through the merchant's selected TRON node. Our server repeats the calculation before monitoring begins, but it cannot silently replace the result with an arbitrary address: a mismatch stops invoice creation.

Creating an invoice

An invoice can be created manually in the dashboard or automatically through the SDK. In both cases, its monitoring and processing parameters are recorded before monitoring starts.

From invoice to wallet

Automatic and manual activation

With automatic activation, the service continues processing once the payment is confirmed and every configured condition has passed. In manual mode, the invoice still receives and records payments but does not become a contract until the merchant decides.

Auto-activation can be paused in the invoice card. If a protection rule stopped it, it cannot be resumed without reviewing the cause: the invoice remains in the attention queue.

AML check before payout

When AML is enabled for the factory and invoice, the service checks the source of funds before the normal automatic payout. The result is compared with the selected risk threshold: an acceptable payment continues, while elevated risk moves the invoice to manual processing.

During manual activation, the dashboard specifically reminds the merchant to perform an AML check when the selected plan sends any funds to the factory's normal recipient. For a refund, another custom address, or keeping funds on the invoice, the decision remains with the merchant.

What happens during activation

The factory publishes a compact smart contract at the predetermined address. During creation it reads the authorized plan, checks the factory-asset balance, and immediately executes the transfers. If a required part fails, the entire activation is reverted.

Normally, the complete current balance of the factory asset is swept to the payout address. For an exception, the merchant selects one of the limited scenarios in advance; arbitrary executable code cannot be supplied as a plan.

After activation: the invoice wallet

After publication, the address becomes a smart-contract wallet. It can hold TRX, the factory asset, and other detected TRC20 assets. The dashboard shows balances and transfer history, and lets the merchant add a token for tracking, send an asset, or grant an allowance.

Manual actions are not executed as ordinary server commands. The factory owner's wallet submits a real network transaction, while the execution layer verifies that the invoice belongs to that factory and owner. Before signing, the dashboard separately shows whether the service covers the network cost or the owner's resources are used.

What the invoice card contains

The card header always shows the invoice number, current activation state, and complete address with a copy action. The remaining information is organized by task.

Trust boundary

A dashboard session, API key, or webhook secret cannot replace the owner's wallet for manually moving funds. The interface shows in advance whether a transaction will be submitted, exactly what it will do, and who pays the network resources.

Preliminary address check

This tool helps assess a prospective payer's address before accepting a payment. It looks for known labels on the address and analyzes its immediate incoming and outgoing interactions to a depth of one level.

What the report includes

How to read the indicators

Own risk

The finding applies directly to the checked address or to known information about its owner.

Direct-connection risk

The finding comes from a direct interaction between the checked address and a labeled counterparty. It does not mean that all of the address's transactions are risky.

No labels found

The available database contains no known labels. This reduces the number of detected signals but does not by itself prove that the address is clean.

How to enrich a report with a full AML check

If no full result exists yet, you can request one directly from the preliminary report. If a result is already shown, you can refresh it to receive current data. Either action spends one check from the cumulative balance.

Where full checks come from

How to use the result

Start with the free preliminary assessment. If it is not enough, enrich the report with a full AML check and decide whether to accept payment from this address or request another one. The enriched report, including its risk categories, can be saved as a PDF.

Events and notifications

The dashboard preserves the operating history, highlights important events, and shows brief messages during an active session.

Three levels of information

Each level has a distinct purpose. The journal provides a complete timeline, the notification center collects selected important events, and toasts show the immediate result of a current action.

Event journal

The journal helps reconstruct the sequence of actions. Events remain there regardless of important-notification settings: invoice creation and processing, incoming and outgoing transfers, warnings, AML results, factory changes, and confirmed settings.

Records are associated with the merchant wallet address and loaded from the server. The history therefore remains available after a browser restart and when signing in from another device with the same wallet. Changing the language retranslates loaded records without altering stored data.

Important notifications

The notification center is a focused selection from the journal. It avoids the need to search manually for events relevant to daily operations and shows the unread count next to the bell.

Required notifications

These categories protect the core payment flow and therefore cannot be disabled.

Configurable categories

The merchant chooses which of these events should also appear in the important-notification list.

Managing subscriptions

What works online and without an open dashboard

A toast can be closed immediately or left to disappear automatically. It is a quick visual confirmation and does not replace the journal or notification center.

Working with unread notifications

Open the bell in the top bar to see the five latest notifications and the unread count. A record can be marked as read individually, or you can use Mark all as read. The complete paginated list is available in Events.

Connecting a webhook

Receive factory event messages as soon as Merchant Receipt records them.

When to use webhooks

Use webhooks to react to invoice creation, detected payments, AML results, invoice wallet publication and other changes without polling the API.

Connecting a factory

Endpoint requirements

Delivery and retries

Any 2xx response completes delivery. A timeout, network failure or other HTTP status triggers retries with increasing delay, up to eight attempts. Delivery therefore follows an at-least-once model.

Signature verification

The HMAC signature proves that Merchant Receipt created the request and that its body was not altered in transit.

Request headers

Content-Type: application/json
User-Agent: TMR-Webhook/1.0
TMR-Webhook-Id: evt_...
TMR-Webhook-Timestamp: 1788593164
TMR-Webhook-Key-Id: whkey_...
TMR-Webhook-Signature: v1=...

Timestamp is Unix time in seconds for this delivery attempt. The event occurrence time is stored in createdAt as ISO 8601 with milliseconds.

Signing string

{timestamp}.{eventId}.{rawRequestBody}

Safe processing order

Verification handshake

The verification button sends webhook.endpoint_verification with a random challenge. The receiver verifies the request and returns the same challenge with an HMAC proof. Success confirms both URL availability and possession of the correct secret.

HMAC-SHA256(secret, "tmr-webhook-verification." + challenge)

Webhook events

Every event uses a common envelope, a stable identifier and data for a specific invoice processing stage.

Common envelope

{
  "id": "evt_aba76349f970eeea724a7da0942bc0d3",
  "apiVersion": "2026-09-05",
  "type": "invoice.created",
  "createdAt": "2026-09-05T07:26:04.259Z",
  "factory": {
    "id": 1,
    "address": "TJW9sQLc5ZWJhqSAos5dumYyCvGNT3SrCp"
  },
  "data": {}
}

Amounts in minimal units are decimal strings so JavaScript does not lose precision. Empty optional data fields are omitted.

Supported events

Idempotent processing

Store id as the unique key for an incoming event. Different events such as invoice.published and settlement.sent can share one txId, so txId alone is not a valid deduplication key.

Node.js example

A minimal receiver verifies signatures, answers the handshake and handles invoice creation.

Preparation

npm install express

Pass the secret from factory parameters in TMR_WEBHOOK_SECRET before starting.

Connecting HTTPS

Place a reverse proxy such as Nginx in front of Node.js. It accepts the secure request on a public domain and forwards it to the local receiver without changing the route:

https://hooks.example.com/webhook
                 ↓ Nginx
http://127.0.0.1:3000/webhook

location = /webhook {
    proxy_pass http://127.0.0.1:3000/webhook;
    proxy_http_version 1.1;

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Webhook receiver

const crypto = require("node:crypto");
const express = require("express");

const app = express();
const secret = process.env.TMR_WEBHOOK_SECRET;
const processed = new Set();

if (!secret) throw new Error("TMR_WEBHOOK_SECRET is required");

app.use("/webhook", express.raw({ type: "application/json", limit: "1mb" }));

function safeHexEqual(expected, received) {
  if (!/^[a-f0-9]{64}$/i.test(received)) return false;
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(received, "hex")
  );
}

function verifyWebhook(req) {
  const id = String(req.get("TMR-Webhook-Id") || "");
  const timestamp = String(req.get("TMR-Webhook-Timestamp") || "");
  const signature = String(req.get("TMR-Webhook-Signature") || "");
  const seconds = Number(timestamp);

  if (!id || !Number.isInteger(seconds)) return null;
  if (Math.abs(Date.now() / 1000 - seconds) > 300) return null;

  const expected = crypto.createHmac("sha256", secret)
    .update(`${timestamp}.${id}.`)
    .update(req.body)
    .digest("hex");

  return safeHexEqual(expected, signature.replace(/^v1=/, "")) ? id : null;
}

app.post("/webhook", async (req, res) => {
  const id = verifyWebhook(req);
  if (!id) return res.status(401).json({ ok: false });

  const event = JSON.parse(req.body.toString("utf8"));
  if (event.id !== id) return res.status(400).json({ ok: false });

  if (event.type === "webhook.endpoint_verification") {
    const challenge = String(event.data?.challenge || "");
    if (!challenge) return res.status(400).json({ ok: false });
    const proof = crypto.createHmac("sha256", secret)
      .update(`tmr-webhook-verification.${challenge}`)
      .digest("hex");
    return res.json({ ok: true, challenge, proof: `v1=${proof}` });
  }

  if (processed.has(id)) return res.json({ ok: true, duplicate: true });

  if (event.type === "invoice.created") {
    console.log("New invoice:", event.data.invoiceNumber);
  }

  processed.add(id);
  return res.json({ ok: true });
});

app.listen(3000, () => console.log("Webhook receiver: http://127.0.0.1:3000"));

What the example does

Getting started with API

Merchant API lets a merchant server read factory and invoice data and create invoices through protected HTTP requests.

https://merchant.trc20.money/api/v1

Currently available

Creating an API key

Key restrictions

A key can be restricted to specific factories, minimum scopes, an expiration of up to 365 days and exact source IPs. Create separate keys for separate applications.

Merchant API boundary

Merchant API covers service data, invoices, webhooks, monitoring and explicitly scoped V3 service conversions. Network settings, arbitrary transfers and direct owner conversions use TRON API.

Authentication

Every request is signed with a dedicated Ed25519 integration key and protected from alteration and replay.

Headers

TMR-Key-Id: tmrk_...
TMR-Timestamp: 1788679200
TMR-Nonce: random_base64url
TMR-Content-SHA256: body_sha256_hex
TMR-Signature: ed25519_base64url
Idempotency-Key: stable-operation-id

Send Idempotency-Key only where the method description requires it. It is not a TMR header and does not replace the one-time nonce.

TMR1 canonical string

TMR1
{METHOD}
{PATH}
{SORTED_QUERY}
{BODY_SHA256}
{TIMESTAMP}
{NONCE}

The signature covers the method, path, sorted query, exact body, time and one-time nonce. Changing any part invalidates the signature.

Server checks

Use the Node.js SDK for normal integrations. It builds the canonical string, hashes exact bytes and sets headers automatically.

Factories

Factory methods return factories available to the API key, profile data, statistics, history and webhook configuration.

API methods

factoryAddress uses TRON Base58 format. A factory unavailable to the key returns FACTORY_NOT_FOUND without disclosing whether it exists.

Both conversion POST methods require an Idempotency-Key header and a JSON body containing { amountRaw }. The amount is a smallest-unit integer string that must fit uint88.

Response models

History parameters

Mutable data

Profile PATCH accepts any non-empty combination of displayName, description, invoicePrefix, notificationContact and paymentRecipientName. Omitted fields are preserved.

paymentLogoUrl is read-only. The logo POST endpoint accepts a binary PNG, JPEG or WebP body up to 5 MB.

{
  "enabled": true,
  "url": "https://shop.example/tmr/webhook",
  "events": ["invoice.created", "payment.detected"]
}

Webhook PUT requires the full object and an Idempotency-Key header. The secret is returned only when new credentials are created and is not disclosed later.

Invoices

Invoice API reserves a sequence, registers a calculated address and returns the subsequent payment state.

API methods

invoiceId may be an internal numeric ID or the full Base58 invoice address. The invoice is additionally restricted to the selected factory in every case.

Response models

List filters

Creating an invoice

Create requires an Idempotency-Key up to 128 characters. Repeating the same business request returns the created invoice, while changed parameters with the same key are rejected. A non-empty externalId is unique within the factory.

Action request bodies

// auto-activation
{ "enabled": false }

// aml/check
{ "target": "T..." }

activation/process and payment-link require no body. Special payout plans and wallet operations are outside Merchant API and run directly through TRON.

Realtime

The realtime channel delivers operational factory and invoice events without repeatedly polling Merchant API.

Obtaining a token

The request is signed with the regular TMR1 key and has no body. The token is valid for five minutes; event access is then limited by each factory's scopes.

Connection and subscription

const socket = io(origin, {
  path: "/merchant-socket",
  transports: ["websocket"],
  auth: { token }
});

socket.emit("factory:subscribe", {
  factoryAddress: "T...",
  lastEventId: ""
}, console.log);

socket.on("factory.event", (event) => console.log(event));

Pass the last processed event's lastEventId after reconnecting. The server replays missed events; an unknown cursor or excessive gap returns an explicit error.

Events

A single factory.event contains a unique id, API version, type, factory, createdAt and domain data in data. Invoice events require invoices:read; other factory events require factories:read.

{
  "id": "...",
  "apiVersion": "2026-09-05",
  "type": "payment.detected",
  "createdAt": "2026-09-08T12:00:00.000Z",
  "factory": { "id": 1, "address": "T..." },
  "data": { }
}

To leave one factory, emit factory:unsubscribe with its factoryAddress. Realtime is intended for operational interfaces, while webhooks remain the reliable business-event delivery channel.

API errors

The API returns a machine-readable error code, and the SDK preserves it in TmrApiError for predictable handling.

Response format

{
  "ok": false,
  "error": "INVALID_API_SIGNATURE"
}

Main categories

SDK error handling

try {
  await tmr.auth.check();
} catch (error) {
  console.error(error.code);
  console.error(error.status);
  console.error(error.details);
}

Retry only temporary network errors and safe idempotent operations. Nonce prevents signature replay, while Idempotency-Key protects the business operation during retry.

SDK overview

The SDK provides a TronWeb-style object interface and handles Merchant API signing and access to a selected TRON node.

Installation

Install the SDK in your server-side Node.js project from the official npm registry.

npm install @stark-core-labs/merchant-sdk

For production, pin the verified version and commit package-lock.json to your repository.

npm install --save-exact @stark-core-labs/merchant-sdk@0.4.3

Why use the SDK

The SDK reduces integration code by building TMR1 signatures, mapping errors, creating factory and invoice contexts and reading on-chain data through TronWeb. Most importantly, new invoice addresses are calculated locally on the merchant server.

Requirements

Initialization

const { TmrMerchant } = require("@stark-core-labs/merchant-sdk");

const tmr = new TmrMerchant(params);

The constructor accepts one params object. The API key identifier and private part are required; other properties have defaults or enable additional verification.

Constructor parameters

tron parameters

If tronWeb is not supplied, the SDK creates it from tron. If both are omitted, public TronGrid is used. The configured instance is always exposed as tmr.tronWeb.

Configuration examples

Minimal configuration

const tmr = new TmrMerchant({
  keyId: process.env.TMR_KEY_ID,
  privateKey: process.env.TMR_API_PRIVATE_KEY
});

Selected TRON node

const tmr = new TmrMerchant({
  keyId: process.env.TMR_KEY_ID,
  privateKey: process.env.TMR_API_PRIVATE_KEY,
  tron: {
    fullHost: "https://api.trongrid.io",
    headers: { "TRON-PRO-API-KEY": process.env.TRONGRID_KEY }
  }
});

Existing TronWeb instance

const { TronWeb } = require("tronweb");

const tronWeb = new TronWeb({ fullHost: process.env.TRON_FULL_HOST });
const tmr = new TmrMerchant({
  keyId: process.env.TMR_KEY_ID,
  privateKey: process.env.TMR_API_PRIVATE_KEY,
  tronWeb
});

Factories

List factories available to the API key, select one and continue within its isolated context.

Listing factories

const factories = await tmr.factory.list();
console.log(factories);

The method returns an array of factories available to the current API key. It requires the factories:read scope. The order matches the factory order in the dashboard menu.

Selecting a factory

Find a record by profile data and pass its address to at(address). The method creates a local factory context with profile, webhook, statistics and invoice services ready to use.

const factories = await tmr.factory.list();
const selected = factories.find(
  ({ displayName }) => displayName === "my_shop_1"
);

if (!selected) throw new Error("Factory my_shop_1 not found");

const factory = tmr.factory.at(selected.address);
const info = await factory.get();

console.log(info.asset.symbol, info.statistics.invoiceCount);

Factory methods

factory.get() response

By default, get() reads on-chain state through the configured TronWeb and requests statistics in parallel. Pass includeStatistics: false to receive only the network snapshot without a Merchant API request.

const onChainOnly = await factory.get({
  includeStatistics: false
});

The readOptions parameter

The apiOptions parameter

apiOptions is used by Merchant API methods, webhookOptions additionally accepts idempotencyKey, and transactionOptions is passed to TronWeb for on-chain changes.

FactoryInfo fields

All monetary values ending in Raw are returned as strings in the asset's smallest units. This prevents JavaScript precision loss.

Factory profile

The profile is stored in the Merchant API and is not an on-chain contract setting. set() updates only the supplied fields and does not change the webhook.

const profile = await factory.profile.get();

const updated = await factory.profile.set({
  displayName: "My shop",
  description: "Primary payment factory",
  invoicePrefix: "SHOP",
  notificationContact: "admin@example.com",
  paymentRecipientName: "Example LLC"
});

// Set the logo displayed on the public invoice page.
await factory.profile.setPaymentLogo("./logo.png");

// Remove the logo from the public invoice page.
await factory.profile.removePaymentLogo();

In SDK v0.4.3, update the recipient through profile.set() and manage the logo through setPaymentLogo() and removePaymentLogo(). The SDK reads the file internally; PNG, JPEG and WebP files up to 5 MB are supported.

Invoice-page recipient

Pass only paymentRecipientName, up to 60 characters, to change the displayed recipient while keeping every other profile field unchanged. An empty string removes the recipient name.

const profile = await factory.profile.set({
  paymentRecipientName: "Example LLC"
});

console.log(profile.paymentRecipientName);

Invoice-page logo

setPaymentLogo() accepts a local file path. The SDK reads the file through fs.promises.readFile(), detects its MIME type from the extension and signs the exact image bytes. A relative path is resolved from the current Node.js working directory.

const withLogo = await factory.profile.setPaymentLogo("./logo.png", {
  timeoutMs: 30000
});

console.log(withLogo.paymentLogoUrl);

const withoutLogo = await factory.profile.removePaymentLogo();
console.log(withoutLogo.paymentLogoUrl); // ""

Webhook configuration

A webhook informs the merchant server about events without continuous Merchant API polling. The configuration is replaced as a whole, so every set() call must include enabled, url, and the complete events list.

const webhook = await factory.webhook.set({
  enabled: true,
  url: "https://shop.example/tmr/webhook",
  events: ["invoice.created", "payment.detected"]
}, {
  idempotencyKey: "webhook-my-shop-v1"
});

console.log(webhook.secret); // Available only when new credentials are issued
console.log(await factory.webhook.get());
console.log(await factory.webhook.test());

The webhookOptions parameter

FactoryWebhook fields

test() calls only the saved endpoint and requires an enabled configuration. Tests are rate limited to one per factory every 30 seconds, up to 10 per API key and 30 per source IP per minute.

Factory statistics

const statistics = await factory.statistics.get();

Combined factory history

history() returns the combined statement shown in the dashboard: invoice payouts, TMR funding, fees and TMR withdrawals. Totals cover the complete selected period regardless of the current page size.

const page = await factory.history({
  period: "30d",
  operationType: "all",
  search: "INV-42",
  limit: 50
});

console.log(page.history);
console.log(page.summary);

The factoryHistoryOptions parameter

FactoryHistory response

FactoryHistoryItem fields

The method calls GET /api/v1/factories/{factoryAddress}/history and requires the View factory permission.

Factory wallet

A factory can hold TRX, TRC20 tokens, TMR and an operational USDT reserve. The wallet methods let the owner transfer TRX and TRC20, manually convert USDT to TMR, withdraw TMR back to USDT and read movements for a selected asset.

const wallet = tmr.factory.at(factoryAddress).wallet;

const trxRaw = await wallet.getTrxBalance();
const usdtRaw = await wallet.getTrc20Balance(usdtAddress);
const tmrRaw = await wallet.getTmrBalance();

const withdrawTxId = await wallet.withdrawTmr("500000");
const convertTxId = await wallet.convertUsdtToTmr("1000000");

const tokenTxId = await wallet.transferTrc20(
  tokenAddress,
  recipientAddress,
  "2500000"
);

const trxTxId = await wallet.transferTrx(
  recipientAddress,
  "3000000"
);

Wallet methods

Balance methods use only the selected TRON node. They do not submit a transaction, require a signer or use the Merchant API. A token contract address is required for TRC20.

All amounts are positive integers in the asset's smallest units. The SDK validates their format but preserves network errors caused by insufficient balance, resources or a rejected transaction.

Manual convertUsdtToTmr() is independent of the automatic funding toggle. The SDK does not precheck the setting or balance; the smart contracts validate current state during execution.

The historyOptions parameter

const page = await wallet.history({
  standard: "TRC20",
  assetAddress: tokenAddress,
  limit: 30
});

const nextPage = page.hasMore
  ? await wallet.history({
      standard: "TRC20",
      assetAddress: tokenAddress,
      limit: 30,
      cursor: page.nextCursor
    })
  : null;

FactoryWalletHistory response

FactoryWalletMovement fields

history() calls GET /api/v1/factories/{factoryAddress}/wallet/history and requires the View factory permission for the selected factory.

Smart contract interfaces

The SDK does not expose the universal executor as a standalone method. It builds only the supported TRX transfer or transfer() call for the selected TRC20 token.

interface IMainFactoryWallet {
    function convertFactoryUsdtToTmr(uint32 factoryId, uint256 amount) external;
    function convertFactoryTmrToUsdt(uint32 factoryId, uint256 amount) external;
}

interface IMerchantFactoryWallet {
    function executor(bytes calldata data) external;
}

interface ITrc20Transfer {
    function transfer(address recipient, uint256 amount) external returns (bool);
}

Changing on-chain settings

These methods change the MerchantFactory smart contract state directly on the TRON network. Merchant API is not involved: TronWeb builds the transaction, and only the wallet that owns the selected factory can authorize it.

const factory = tmr.factory.at(factoryAddress);

const txId = await factory.setMinimumInvoiceBalance(
  "1000000",
  { feeLimit: 20_000_000 }
);

console.log(txId);

Available methods

valueRaw parameters are whole numbers in the asset's smallest units. Use a string for large values to prevent JavaScript precision loss.

Smart contract interface

Only the public interface of the available operations is shown below, without implementation source code.

interface IMerchantFactorySettings {
    function setApprovedMaxFee(uint32 newApprovedMaxFee) external;
    function setPayoutAddress(address newPayoutAddress) external;
    function setMinimumInvoiceBalance(uint256 newMinimumInvoiceBalance) external;
    function setAutoConvertUsdtToTmrEnabled(bool enabled) external;
    function setAutoConvertUsdtRetainAmount(uint256 value) external;
    function setAmlEnabled(bool enabled) external;
}

The Solidity functions return no value. In JavaScript, txId is the result of submitting the transaction through TronWeb and can be used to check its network confirmation.

The transactionOptions parameter

Realtime events

A subscription receives events from the factory and its invoices without continuously polling the API. The SDK uses one Socket.IO connection per TmrMerchant instance even when several factories are selected.

const unsubscribe = factory.on("payment.detected", (event) => {
  console.log(event.data.invoiceAddress, event.data.amountRaw);
});

factory.once("invoice.published", (event) => {
  console.log("Invoice activated:", event.data.invoiceAddress);
}, {
  invoiceAddress,
  timeoutMs: 300_000
});

// When the persistent subscription is no longer needed
unsubscribe();

Managing subscriptions

The realtimeOptions parameter

Supported events

FactoryEvent format

{
  "id": "evt_...",
  "apiVersion": "2026-09-05",
  "type": "payment.detected",
  "createdAt": "2026-09-08T12:00:00.000Z",
  "factory": { "id": 1, "address": "T..." },
  "data": {
    "invoiceId": "25048383693",
    "invoiceAddress": "T...",
    "amountRaw": "350000000",
    "txId": "..."
  }
}

The SDK obtains a short-lived realtime token through a signed HTTP request. Factory events require factories:read and invoice events require invoices:read. Webhook settings do not affect realtime subscriptions.

Common errors

TMR and USDT conversions

For each direction, the SDK provides a service-paid operation and a direct factory-owner transaction.

Two execution modes

ViaService methods sign an HTTP request with the API key while the service General sends the transaction. OnChain methods call MainFactory V3 through the configured TronWeb, so the factory owner signs the transaction and pays its resources.

Service-paid operation

const factory = tmr.factory.at(factoryAddress);

const quota = await factory.conversion.getTmrToUsdtServiceQuota();

const withdrawal = await factory.conversion.tmrToUsdtViaService("1000000", {
  idempotencyKey: "withdraw-order-1842-v1"
});

const topup = await factory.conversion.usdtToTmrViaService("2500000", {
  idempotencyKey: "topup-order-1842-v1"
});

amountRaw is an integer string in the asset's smallest units and must fit uint88. idempotencyKey is required: retrying an identical successful request returns the stored result and does not create another transaction.

Direct owner transaction

const withdrawal = await factory.conversion.tmrToUsdtOnChain("1000000", {
  feeLimit: 100_000_000
});

const topup = await factory.conversion.usdtToTmrOnChain("2500000");
console.log(withdrawal.txId, topup.txId);

Direct methods accept a positive uint256 and do not call the Merchant API. They use the signer and transactionOptions of the configured TronWeb. An API key cannot replace the wallet signature.

Results and retries

A service response contains operationId, executionMode, direction, factoryId, factoryAddress, amountRaw and result; TMR-to-USDT also contains quota. A direct response contains executionMode, direction, amountRaw, txId and the original TronWeb result.

One idempotencyKey cannot be reused for another amount, factory or direction. If the first attempt is recorded as failed, use a new operation key after correcting the cause.

Main errors

Invoices

The factory context manages the invoice collection, while an individual invoice context combines its state, activation, wallet and events.

Two levels of operation

factory.invoice methods work with the selected factory's invoice collection. at(idOrAddress) creates a local object for one invoice without a network request. An integration can first find or create an invoice and then work only with its context.

const factory = tmr.factory.at(factoryAddress);
const page = await factory.invoice.list({ externalId: "order-1842" });

const invoice = factory.invoice.at(page.invoices[0].id);
const state = await invoice.state();

Invoice collection methods

The filters parameter

One invoice context

The internal identifier is stored in invoice.invoiceDbId, the address in invoice.invoiceAddress and the on-chain number in invoice.chainInvoiceId. When selected by id, the address and on-chain number are remembered after the first get() or state() call.

Activation and special payout plan

Normal processing can be requested through the Merchant API, automatic activation can be paused or resumed, and a manual AML check can be requested. A special payout plan is fixed by a separate factory owner transaction.

await invoice.activation.setPlan({
  mode: "split",
  transfers: [
    { address: supplierAddress, amountRaw: "250000000" },
    { address: reserveAddress, amountRaw: "100000000" }
  ],
  activate: true
});

PayoutPlan modes

Solidity interface

function getInvoiceException(address invoice) external view returns (address);

function getInvoicePayoutPlan(address invoice) external view returns (
  uint8 mode,
  bool activateRequested,
  uint8 count,
  address[3] memory recipients,
  uint256[3] memory amounts
);

function setInvoicePayoutPlanById(
  uint40 invoiceId,
  uint8 mode,
  bool activateRequested,
  address[3] calldata recipients,
  uint256[3] calldata amounts,
  uint8 count
) external;

Activated invoice wallet

After activation, the address remains a complete invoice wallet. The factory owner can read balances and transfer TRX or TRC20. Sending funds is only available after activation and requires a real factory owner transaction.

Events for one invoice

const unsubscribe = invoice.on("*", (event) => {
  console.log(event.type, event.data);
});

invoice.once("invoice.published", handler, { timeoutMs: 300_000 });
unsubscribe();

on receives every matching event, once receives only the first, and off removes handlers. The * wildcard inside an invoice context means only events for that invoice. If the context was created from an internal id, call get() or state() before subscribing so the SDK learns its address.

Available events are invoice.created, payment.detected, aml.pending, aml.approved, aml.rejected, manual_review.required, invoice.published, settlement.sent, invoice.expired and invoice.failed.

Access and signing

What happens to invoices if the service is unavailable

Funds held by factories and invoices remain under the merchant's full control. An unavailable dashboard, API or monitoring service does not transfer control to Merchant Receipt or block direct contract access.

What changes when the service stops

During normal operation Merchant Receipt monitors incoming funds and, once the conditions are met, activates an invoice using the service's network resources. If the service becomes unavailable, this automation waits for recovery. Funds are not transferred to the service and do not become accessible to it: the merchant can perform the required actions independently.

Rescue Merchant

rescue-merchant.trc20.money is a separate static page for direct factory and invoice management. It does not call the Merchant Receipt backend and reads state directly from the TRON network.

Available actions

Merchant procedure

Direct access through TronWeb

Rescue Merchant is a convenient interface, but it is not the only access path. A merchant's technical team can read and call public contract methods directly through TronWeb and any compatible node.

Rescue Merchant

An independent static interface for direct interaction with Merchant Receipt factories and invoices through the TRON network, without the dashboard, API or server-side monitoring.

What Rescue Merchant is for

Use the page when the main Merchant Receipt interface or server is temporarily unavailable and the merchant needs to inspect contract state or perform an operation authorized for the owner.

How independence is provided

Page interface

Network connection

Working with an invoice

Opening a protected link

The merchant can provide an operator with a deep link containing the factory, on-chain Invoice ID and expected invoice address.

https://rescue-merchant.trc20.money/#v=1
&factory=T...
&invoice=10217324555
&address=T...

What to prepare in advance

Recommendations

Merchant Receipt reduces the number of secrets and trusted parties, but secure integration also depends on how the merchant obtains invoice addresses, stores keys and verifies operations.

Merchant Receipt approach

Obtaining an invoice address securely

For production integration, calculate addresses on your own server with the Node.js SDK or a compatible independent implementation. The address shown to a customer should come from the merchant's calculation, not from a dashboard response or an arbitrary string supplied by an external service.

What to verify

Keys and access

Network transactions

Changing network settings, managing funds in a factory or activated invoice, and applying a special plan require a real TRON transaction. Before signing, the wallet should show the expected contract and action, while the application should verify the network, destination and call parameters.

When a problem is suspected

Reference materials

Concise definitions, data formats, statuses, errors and public Merchant Receipt contract interfaces.

Core concepts

Addresses, identifiers and amounts

TMR asset

TMR, or Merchant Receipt, is the project's service TRC10 asset with token ID 1005181 and 6 decimal places. A factory spends TMR when publishing invoices, so a merchant can see the processing price and the maximum fee it has authorized in advance.

Invoice statuses

A status describes a processing stage; it does not replace checking balances and transactions. Use invoice state, payments and timeline together for financial decisions.

Error codes

Merchant API returns a machine-readable code in error. The SDK places it in TmrApiError.code, the HTTP status in status and supporting data in details. If no HTTP response was received, status is 0.

HTTP statuses

Primary machine-readable codes

NativeTrxToken and native TRX

TRX has no TRC20 contract address, while an interface still needs consistent asset fields and balance reads. NativeTrxToken is a network adapter: it reports the name TRON, symbol TRX, 6 decimals and returns an address's native balance.

interface INativeTrxToken {
  // Returns the human-readable native asset name.
  function name() external pure returns (string memory);

  // Returns the native asset ticker.
  function symbol() external pure returns (string memory);

  // Returns TRX precision in decimal places.
  function decimals() external pure returns (uint8);

  // Reads the native TRX balance of an address in sun.
  function balanceOf(address account) external view returns (uint256);
}

Public contract interfaces

These functions can be read or called through a compatible TRON node without the Merchant Receipt dashboard. State-changing functions create a transaction and must be signed by the address authorized by the contract.

Main factory: discovery and conversion

interface IMainFactoryPublic {
  // Returns the address used to represent native TRX.
  function nativeTrxToken() external view returns (address);

  // Returns USDT balance, TMR circulation reserve and withdrawable surplus.
  function usdtAccounting() external view returns (
    uint256 usdtBalance, uint256 tmrInMain, uint256 reservedUsdt, uint256 availableUsdt
  );

  // Creates an on-chain request for a personal merchant factory.
  function requestMerchantFactory(uint32 fee, address token, bytes32 factorySalt)
    external returns (uint40 requestId);

  // Reads a factory publication request by its request ID.
  function getFactoryRequest(uint40 requestId) external view returns (
    address merchantOwner, uint32 fee, address token, bytes32 factorySalt, uint8 status
  );

  // Reads a registered personal factory by its numeric ID.
  function getFactory(uint32 factoryId) external view returns (
    address merchantOwner, address factory, address serviceProxy, uint32 fee, bool active
  );

  // Finds a registered factory record by its contract address.
  function getFactoryByAddress(address factoryAddress) external view returns (
    uint32 factoryId, address merchantOwner, address factory,
    address serviceProxy, uint32 fee, bool active
  );

  // Returns the number of factories registered for an owner.
  function getMerchantFactoryCount(address merchantOwner) external view returns (uint32);

  // Reads one owner's factory by its position in the registry.
  function getMerchantFactoryByIndex(address merchantOwner, uint32 index) external view returns (
    uint32 factoryId, address factory, address serviceProxy, uint32 fee, bool active
  );

  // Exchanges a factory's USDT for the same raw amount of TMR.
  function convertFactoryUsdtToTmr(uint32 factoryId, uint256 amount) external;

  // Returns TMR and sends the same raw amount of USDT to the factory owner.
  function convertFactoryTmrToUsdt(uint32 factoryId, uint256 amount) external;
}

The get... functions are available for reads. Converting funds belonging to a personal factory is restricted to that factory's registered owner. A new-factory request is only recorded on-chain and is not automatically accepted.

Personal factory: settings and invoices

interface IMerchantFactoryPublic {
  // Returns the factory's complete on-chain configuration and balances.
  function merchantFactoryInfo() external view returns (
    address mainFactory, address merchantOwner, uint32 fee, uint32 approvedMaxFee,
    bool active, address token, address payoutAddress, uint256 minimumInvoiceBalance,
    uint256 tmrBalance, uint256 usdtBalance, bool autoConvertUsdtToTmrEnabled,
    bool amlEnabled, uint32 amlFee
  );

  // Returns the active and pending V3 fee and its activation block.
  function feeSchedule() external view returns (
    uint32 activeFee, uint32 activeAmlFee, uint32 pendingFee,
    uint32 pendingAmlFee, uint64 activationBlock,
    uint32 activeEffectiveFee, uint32 pendingEffectiveFee
  );

  // Returns the USDT balance available for automatic conversion.
  function convertibleUsdtBalance() external view returns (uint256 amount);

  // Sets the maximum invoice fee approved by the factory owner.
  function setApprovedMaxFee(uint32 valueRaw) external;

  // Changes the recipient of standard invoice payouts.
  function setPayoutAddress(address payoutAddress) external;

  // Sets the minimum balance required for standard activation.
  function setMinimumInvoiceBalance(uint256 valueRaw) external;

  // Enables or disables automatic USDT-to-TMR replenishment.
  function setAutoConvertUsdtToTmrEnabled(bool enabled) external;

  // Sets the USDT amount excluded from automatic conversion.
  function setAutoConvertUsdtRetainAmount(uint256 valueRaw) external;

  // Enables or disables AML processing for future invoices.
  function setAmlEnabled(bool enabled) external;

  // Calculates the deterministic address of a future invoice.
  function predictInvoice(uint40 invoiceId) external view returns (address invoice);

  // Publishes an invoice when the factory's conditions are satisfied.
  function deployInvoice(uint40 invoiceId) external returns (address invoice);

  // Reads the special recipient configured for an invoice.
  function getInvoiceException(address invoice) external view returns (address);

  // Reads the typed payout plan configured for an invoice.
  function getInvoicePayoutPlan(address invoice) external view returns (
    uint8 mode, bool activateRequested, uint8 count,
    address[3] memory recipients, uint256[3] memory amounts
  );

  // Saves a payout plan and can request asynchronous invoice activation.
  function setInvoicePayoutPlanById(
    uint40 invoiceId, uint8 mode, bool activateRequested,
    address[3] calldata recipients, uint256[3] calldata amounts, uint8 count
  ) external;
}

Reading information and predicting an address need no signature. Settings and special payout-plan changes are restricted to the factory owner. deployInvoice accepts any transaction sender, but publication succeeds only when the factory's enforced conditions are met.

Invoice wallet access proxy

After activation, an invoice remains a smart-contract wallet. The contract at TZAehzArybCEoQNQp1SUdZsggZWwJSx6kB acts as a verifying proxy: it locates the invoice through the immutable main/personal factory relationship, verifies the owner and only then forwards the selected operation to the invoice wallet.

User scenarios

interface IInvoiceWalletExecutor {
  // Executes a prepared operation after validating the factory owner and invoice address.
  function execute(
    uint32 factoryId,
    uint40 invoiceId,
    address expectedInvoice,
    bytes calldata invoiceFallbackData
  ) external;
}