Payment Modes

The TapRails SDK supports two distinct payment execution models. The right choice depends on your product’s custody model.

POOL Mode (Custodial)

POOL mode allows a company to pre-fund a TapRails-managed payment pool. Payments are authorized against the available pool balance, so end users don’t need to sign an on-chain transaction at checkout.

When to use POOL mode

POOL mode is a good fit when:

Your app manages user balances or spending limits on your backend.
You want the simplest possible integration without requiring users to connect or manage a wallet.
Your company funds payments from a pre-funded TapRails pool.
You want users to tap and pay without signing an on-chain transaction at checkout.
You’re building experiences such as corporate spending, prepaid wallets, or other managed payment products.

Your backend is responsible for maintaining the pool balance and ensuring sufficient funds are available for payments.

Configuration

ContactlessCryptoSDK.initialize({
  mode: PaymentMode.POOL,
  pool: {
    customerId: 'customer_456',  // Your internal customer identifier
  },
  // ...
});

How the pool works

Fund your company pool through the TapRails dashboard. The pool wallet is created and managed through Privy.
When a customer makes a payment, TapRails processes the payment against the company pool.
TapRails sends USDC from the pool wallet to the merchant wallet in a single on-chain transaction.
Once the transaction is confirmed, TapRails sends a webhook containing the payment details, including the customer_wallet.
Use the webhook data to reconcile payments and associate transactions with your internal customer records.

The pool wallet is created and managed through Privy. TapRails does not expose or require the pool wallet’s private key on the SDK side.No private key management is required when integrating POOL mode.

SESSION_KEY Mode (Non-Custodial)

In SESSION_KEY mode, payments are funded directly from the user’s wallet using a delegated session authorization. The user approves the session once and sets a configurable spending limit. After setup, TapRails can process subsequent payments without requiring the user to manually approve every transaction.

Non-Custodial Security: TapRails does not take custody of user funds in SESSION_KEY mode. The user retains full control of their wallet, while the session authorization limits what payments can be executed on their behalf.

When to use SESSION_KEY mode

SESSION_KEY mode is a good fit when:

Your app is a non-custodial wallet, DeFi product, or self-custody experience.
Users control their own funds on-chain.
You want instant payments without requiring users to approve every transaction.
You want to abstract gas and transaction submission from the user experience.
Your wallet uses infrastructure such as WalletConnect, Privy, Magic, MPC, or your own wallet infrastructure.

SESSION_KEY mode is designed for applications where users retain control of their funds while TapRails handles the payment flow on their behalf within the permissions granted by the session authorization.

Configuration

ContactlessCryptoSDK.initialize({
  mode: PaymentMode.SESSION_KEY,
  sessionKey: {
    walletAddress: '0x1234...abcd',  // User's wallet
    defaultDailyLimit: '100.00',     // Max USDC per day
    autoRenew: true,                 // Re-setup when key expires
    onSignTransaction: async (tx) => {
      // Your wallet integration:
      return await walletProvider.signTransaction(tx);
    },
    onSetupComplete: () => console.log('Session key ready'),
    onSetupCancel: () => console.log('User cancelled setup'),
  },
});

Session key lifecycle

State	What happens
No key	The SDK detects that no active session exists and presents the setup flow.
Valid key	Payments can be authorized using the active session without requiring user interaction for each payment.
Expired key	The SDK prompts the user to create a new session before the next payment.
Revoked	The session is invalidated and the associated key is removed from the device and TapRails.

Security properties

Session keys are ECDSA keypairs generated on the user’s device and stored using platform-secured key storage.
The private key never leaves the user’s device.
Configurable spending limits restrict the maximum amount that can be authorized through a session.
Sessions can be revoked from the SDK or TapRails dashboard.
User funds remain in the user’s wallet when using SESSION_KEY mode.

POOL vs SESSION_KEY

	POOL	SESSION_KEY
Funding model	Company-funded pool	User’s wallet
User wallet required	No	Yes
User setup	None	One-time authorization
Per-payment UX	Instant	Instant after setup
Spending control	Pool balance	Configurable session limit
User funds remain self-custodied	No	Yes
Best for	Fintechs, expense tools, managed wallets	Non-custodial wallets, DeFi apps

Switching Modes

You can only initialize the SDK in one mode per app session. To switch modes, call ContactlessCryptoSDK.initialize() again with the new configuration (e.g., after a user logs in with a wallet). This resets the API client.

Get Started

Use Cases

React Native SDK

API

Webhooks

Coverage

POOL Mode (Custodial)

When to use POOL mode

Configuration

How the pool works

SESSION_KEY Mode (Non-Custodial)

When to use SESSION_KEY mode

Configuration

Session key lifecycle

Security properties

POOL vs SESSION_KEY

Switching Modes

​POOL Mode (Custodial)

​When to use POOL mode

​Configuration

​How the pool works

​SESSION_KEY Mode (Non-Custodial)

​When to use SESSION_KEY mode

​Configuration

​Session key lifecycle

​Security properties

​POOL vs SESSION_KEY

​Switching Modes

POOL Mode (Custodial)

When to use POOL mode

Configuration

How the pool works

SESSION_KEY Mode (Non-Custodial)

When to use SESSION_KEY mode

Configuration

Session key lifecycle

Security properties

POOL vs SESSION_KEY

Switching Modes