> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taprails.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Initialize

> Configure the TapRails SDK with your API credentials and payment mode.

## ContactlessCryptoSDK.initialize()

Call `initialize()` once at app startup — before rendering any components that use TapRails hooks or the `PaymentFlowManager`.

```ts theme={null}
import { ContactlessCryptoSDK } from '@taprails/tap-to-pay';

ContactlessCryptoSDK.initialize(config: SDKConfig): void
```

***

## SDKConfig

```ts theme={null}
interface SDKConfig {
  apiKey: string;
  apiUrl: string;
  environment: 'sandbox' | 'production';
  merchantId?: string;
  aid: string;
  mode?: PaymentMode;
  pool?: PoolConfig;
  sessionKey?: SessionKeyConfig;
}
```

### Fields

<ParamField path="apiKey" type="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.
</ParamField>

<ParamField path="apiUrl" type="string" required>
  Base URL of your TapRails backend instance (e.g., `https://api.yourcompany.com`). No trailing slash.
</ParamField>

<ParamField path="environment" type="'sandbox' | 'production'" required>
  Controls which environment header is sent with API requests. Use `sandbox` during development.
</ParamField>

<ParamField path="merchantId" type="string">
  Your merchant identifier. Required when the app operates in **merchant mode** (accepting payments). Can be overridden per-call in `useNFCMerchant`.
</ParamField>

<ParamField path="aid" type="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).
</ParamField>

<ParamField path="mode" type="PaymentMode">
  Payment mode — `PaymentMode.POOL` or `PaymentMode.SESSION_KEY`. See [Payment Modes](/configuration/payment-modes).
</ParamField>

<ParamField path="pool" type="PoolConfig">
  Configuration for POOL mode. Provide `customerId` to identify the paying customer.
</ParamField>

<ParamField path="sessionKey" type="SessionKeyConfig">
  Configuration for SESSION\_KEY mode. Provide the user's wallet address, daily limit, and transaction signer callback.
</ParamField>

***

## PoolConfig

```ts theme={null}
interface PoolConfig {
  customerId: string;
}
```

<ParamField path="customerId" type="string" required>
  The identifier for the customer in your TapRails dashboard. Used to debit from the correct pool wallet.
</ParamField>

***

## SessionKeyConfig

```ts theme={null}
interface SessionKeyConfig {
  walletAddress: string;
  defaultDailyLimit: string;
  autoRenew: boolean;
  durationMs?: number;
  onSignTransaction: (tx: ApprovalTransaction) => Promise<string>;
  onSetupComplete?: () => void;
  onSetupCancel?: () => void;
}
```

<ParamField path="walletAddress" type="string" required>
  The user's onchain wallet address (e.g., `0x1234...abcd`). This is the wallet that funds payments.
</ParamField>

<ParamField path="defaultDailyLimit" type="string" required>
  Maximum USDC spend per day via the session key, as a decimal string (e.g., `"100.00"`).
</ParamField>

<ParamField path="autoRenew" type="boolean" required>
  If `true`, when a session key expires the SDK automatically triggers re-setup before the next payment.
</ParamField>

<ParamField path="durationMs" type="number">
  Session key validity duration in milliseconds. Defaults to 24 hours if not specified.
</ParamField>

<ParamField path="onSignTransaction" type="(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.
</ParamField>

<ParamField path="onSetupComplete" type="() => void">
  Optional callback invoked when session key setup completes successfully.
</ParamField>

<ParamField path="onSetupCancel" type="() => void">
  Optional callback invoked when the user cancels session key setup.
</ParamField>

***

## ApprovalTransaction

Passed to `onSignTransaction`:

```ts theme={null}
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()`.

```ts theme={null}
const config = ContactlessCryptoSDK.getConfig();
console.log(config.merchantId);
```

### ContactlessCryptoSDK.isInitialized()

Returns `true` if `initialize()` has been called, `false` otherwise.

```ts theme={null}
if (!ContactlessCryptoSDK.isInitialized()) {
  // Show onboarding or delay rendering payment UI
}
```

***

## Examples

<CodeGroup>
  ```tsx POOL mode theme={null}
  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,
    },
  });
  ```

  ```tsx SESSION_KEY mode theme={null}
  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'),
    },
  });
  ```
</CodeGroup>