Sandbox & testing

Use sandbox mode as your test environment. No real USDT, no TronGrid key required.

DANGER

Never enable AUTLANTIC_PAYMENTS_SANDBOX in production.

Enable sandbox

export AUTLANTIC_PAYMENTS_SANDBOX=true
export AUTLANTIC_PAYMENTS_WEBHOOK_SECRET=whsec_test_123   # optional

import { AutlanticPayments } from "@autlantic/payments";

const payments = AutlanticPayments.fromEnv();
// or
const payments = new AutlanticPayments({ sandbox: true, webhookSecret: "whsec_test_123" });

Test transaction hashes

Pass these as txHash in verifyByTxHash while sandbox: true:

Test tx hash	Scenario	Expected result
sandbox_payment_confirmed	Successful payment	ok: true
sandbox_payment_short	Underpayment	PAYMENT_SHORT
sandbox_payment_expired	Expired checkout	PAYMENT_EXPIRED
sandbox_payment_wrong_address	Wrong wallet	PAYMENT_WRONG_ADDRESS
sandbox_payment_too_early	Tx before session	PAYMENT_TOO_EARLY
sandbox_payment_not_found	Tx not on chain	PAYMENT_TX_NOT_FOUND
sandbox_payment_invalid_hash	Bad hash format	INVALID_TX_HASH

Legacy aliases (sandbox_confirm_test, sandbox_success, etc.) still work.

Trigger test events

Like stripe trigger — no tx hash needed:

const payments = new AutlanticPayments({ sandbox: true, webhookSecret: "whsec_test" });

const success = payments.emitTestEvent({
  scenario: "payment.confirmed",
  merchantRef: "order_1001",
  amountUsdt: 49,
  payToAddress: "TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH",
});

console.log(success.event);
console.log(success.webhook?.body, success.webhook?.signature);

const failed = payments.emitTestEvent({
  scenario: "payment.failed.short",
  merchantRef: "order_1002",
  amountUsdt: 20,
  payToAddress: "TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH",
});

if (!failed.verification.ok) {
  console.log(failed.verification.code); // PAYMENT_SHORT
}

List scenarios:

payments.listTestScenarios().forEach((s) => {
  console.log(s.id, s.testTxHash, s.description);
});

Scenario ids

Scenario id	Event type
payment.confirmed	payment.confirmed
payment.failed.short	payment.failed
payment.failed.expired	payment.failed
payment.failed.wrong_address	payment.failed
payment.failed.too_early	payment.failed
payment.failed.tx_not_found	payment.failed
payment.failed.invalid_hash	payment.failed

CLI

npx autlantic-payments scenarios

npx autlantic-payments trigger payment.confirmed \
  --merchant-ref order_1 --amount 20 \
  --to TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH

npx autlantic-payments sandbox \
  --merchant-ref order_3 --amount 20 \
  --to TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH \
  --tx sandbox_payment_confirmed

Live mode (optional)

Use real Tron tx hashes (64 hex) + TRONGRID_API_KEY with sandbox off.

Autlantic product

The Autlantic membership platform uses the same npm SDK in production. For end-to-end checkout testing on a store, set AUTLANTIC_PAYMENTS_SANDBOX=true on web and worker services.