Skip to main content

​
ContactlessCryptoSDK.initialize()

Call initialize() once at app startup — before rendering any components that use TapRails hooks or the PaymentFlowManager. 
import { ContactlessCryptoSDK } from '@taprails/tap-to-pay';

ContactlessCryptoSDK.initialize(config: SDKConfig): void

​
SDKConfig

interface SDKConfig {
  apiKey: string;
  apiUrl: string;
  environment: 'sandbox' | 'production';
  merchantId?: string;
  mode?: PaymentMode;
  pool?: PoolConfig;
  sessionKey?: SessionKeyConfig;
}

​
Fields

​
apiKey
string
required
Your TapRails API key. Use pk_test_... for sandbox and pk_live_... for production. Do not commit this to version control — load from environment variables or a secrets manager.
​
apiUrl
string
required
Base URL of your TapRails backend instance (e.g., https://api.yourcompany.com). No trailing slash.
​
environment
'sandbox' | 'production'
required
Controls which environment header is sent with API requests. Use sandbox during development.
​
merchantId
string
Your merchant identifier. Required when the app operates in merchant mode (accepting payments). Can be overridden per-call in useNFCMerchant.
​
mode
PaymentMode
Payment mode — PaymentMode.POOL or PaymentMode.SESSION_KEY. See Payment Modes.
​
pool
PoolConfig
Configuration for POOL mode. Provide customerId to identify the paying customer.
​
sessionKey
SessionKeyConfig
Configuration for SESSION_KEY mode. Provide the user’s wallet address, daily limit, and transaction signer callback.

​
PoolConfig

interface PoolConfig {
  customerId: string;
}
​
customerId
string
required
The identifier for the customer in your TapRails dashboard. Used to debit from the correct pool wallet.

​
SessionKeyConfig

interface SessionKeyConfig {
  walletAddress: string;
  defaultDailyLimit: string;
  autoRenew: boolean;
  durationMs?: number;
  onSignTransaction: (tx: ApprovalTransaction) => Promise<string>;
  onSetupComplete?: () => void;
  onSetupCancel?: () => void;
}
​
walletAddress
string
required
The user’s onchain wallet address (e.g., 0x1234...abcd). This is the wallet that funds payments.
​
defaultDailyLimit
string
required
Maximum USDC spend per day via the session key, as a decimal string (e.g., "100.00").
​
autoRenew
boolean
required
If true, when a session key expires the SDK automatically triggers re-setup before the next payment.
​
durationMs
number
Session key validity duration in milliseconds. Defaults to 24 hours if not specified.
​
onSignTransaction
(tx: ApprovalTransaction) => Promise<string>
required
Callback invoked when the user must sign the ERC-20 approval transaction to create a session key. Integrate with your wallet provider (e.g., WalletConnect, Privy, Magic). Return the signed transaction hash.
​
onSetupComplete
() => void
Optional callback invoked when session key setup completes successfully.
​
onSetupCancel
() => void
Optional callback invoked when the user cancels session key setup.

​
ApprovalTransaction

Passed to onSignTransaction: 
interface ApprovalTransaction {
  to: string;    // Contract address to call
  data: string;  // Encoded calldata
  value: string; // ETH value (usually "0" for ERC-20 approvals)
}

​
Other Methods

​
ContactlessCryptoSDK.getConfig()

Returns the current SDKConfig. Throws APIError with code SDK_NOT_INITIALIZED if called before initialize(). 
const config = ContactlessCryptoSDK.getConfig();
console.log(config.merchantId);

​
ContactlessCryptoSDK.isInitialized()

Returns true if initialize() has been called, false otherwise. 
if (!ContactlessCryptoSDK.isInitialized()) {
  // Show onboarding or delay rendering payment UI
}

​
Examples

import { ContactlessCryptoSDK, PaymentMode } from '@taprails/tap-to-pay';

ContactlessCryptoSDK.initialize({
  apiKey: process.env.TAPRAILS_API_KEY!,
  apiUrl: 'https://api.acmepay.com',
  environment: 'production',
  merchantId: 'merchant_acme_pos_1',
  mode: PaymentMode.POOL,
  pool: {
    customerId: user.id,
  },
});