Initialize

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;
  aid: string;
  mode?: PaymentMode;
  pool?: PoolConfig;
  sessionKey?: SessionKeyConfig;
}

Fields

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.

string

required

Base URL of your TapRails backend instance (e.g., https://api.yourcompany.com). No trailing slash.

'sandbox' | 'production'

required

Controls which environment header is sent with API requests. Use sandbox during development.

string

Your merchant identifier. Required when the app operates in merchant mode (accepting payments). Can be overridden per-call in useNFCMerchant.

string

required

The unique Application Identifier (AID) assigned to your organization in the TapRails dashboard. This is required for correctly routing NFC communications between the customer (reader) and merchant (HCE emulator).

PaymentMode

Payment mode — PaymentMode.POOL or PaymentMode.SESSION_KEY. See Payment Modes.

PoolConfig

Configuration for POOL mode. Provide customerId to identify the paying customer.

SessionKeyConfig

Configuration for SESSION_KEY mode. Provide the user’s wallet address, daily limit, and transaction signer callback.

PoolConfig

interface PoolConfig {
  customerId: string;
}

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;
}

string

required

The user’s onchain wallet address (e.g., 0x1234...abcd). This is the wallet that funds payments.

string

required

Maximum USDC spend per day via the session key, as a decimal string (e.g., "100.00").

boolean

required

If true, when a session key expires the SDK automatically triggers re-setup before the next payment.

number

Session key validity duration in milliseconds. Defaults to 24 hours if not specified.

(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.

() => void

Optional callback invoked when session key setup completes successfully.

() => 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',
  aid: 'F05441505241494C53', // Your unique partner AID
  mode: PaymentMode.POOL,
  pool: {
    customerId: user.id,
  },
});

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

const { address, signTransaction } = useWallet();

ContactlessCryptoSDK.initialize({
  apiKey: process.env.TAPRAILS_API_KEY!,
  apiUrl: 'https://api.acmepay.com',
  environment: 'production',
  aid: 'F05441505241494C53', // Your unique partner AID
  mode: PaymentMode.SESSION_KEY,
  sessionKey: {
    walletAddress: address,
    defaultDailyLimit: '500.00',
    autoRenew: true,
    onSignTransaction: signTransaction,
    onSetupComplete: () => analytics.track('session_key_created'),
  },
});

Get Started

Use Cases

React Native SDK

API

Webhooks

Coverage

ContactlessCryptoSDK.initialize()

SDKConfig

Fields

PoolConfig

SessionKeyConfig

ApprovalTransaction

Other Methods

ContactlessCryptoSDK.getConfig()

ContactlessCryptoSDK.isInitialized()

Examples

​ContactlessCryptoSDK.initialize()

​SDKConfig

​Fields

​PoolConfig

​SessionKeyConfig

​ApprovalTransaction

​Other Methods

​ContactlessCryptoSDK.getConfig()

​ContactlessCryptoSDK.isInitialized()

​Examples

ContactlessCryptoSDK.initialize()

SDKConfig

Fields

PoolConfig

SessionKeyConfig

ApprovalTransaction

Other Methods

ContactlessCryptoSDK.getConfig()

ContactlessCryptoSDK.isInitialized()

Examples