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

# Cross-Border Spend

> Enable stablecoin payroll recipients to spend locally at point of sale — across wallets, across borders.

**Cross-Border Spend** allows global payroll platforms, international neo-banks, and remittance applications to give remote workers, contractors, and expats instant brick-and-mortar spending power anywhere in the world.

By combining stablecoins on Base (USDC) with TapRails NFC tap-to-pay infrastructure, payroll platforms bypass expensive foreign exchange (FX) markups, SWIFT wire delays, and intermediary banking fees.

***

## The Cross-Border Problem & Solution

```mermaid theme={null}
graph TD
    subgraph Traditional Cross-Border Payment
        A[Employer / Payer] -->|Cross-Border Transfer| B[Banks / Intermediaries]
        B -->|FX + Transfer Fees| C[Recipient Bank Account]
        C -->|Card / Mobile Payment| D[Merchant]
    end

    subgraph TapRails
        E[Employer / Payer] -->|USDC Transfer| F[Recipient Wallet]
        F -->|NFC Tap| G[Merchant App]
        G -->|On-Chain Settlement| H[Merchant Wallet]
    end
```

<CardGroup cols={2}>
  <Card title="Without TapRails" icon="xmark">
    Workers wait 3–5 business days for cross-border wires and lose 3-7% in banking fees and inflated FX conversion rates.
  </Card>

  <Card title="With TapRails" icon="check">
    Workers spend their USDC payroll earnings immediately at local NFC payment terminals with zero delay and near-zero chain gas fees.
  </Card>
</CardGroup>

***

## Treasury Management Options

When enabling cross-border spend for payroll recipients, you can choose between two treasury models:

### 1. Corporate Treasury Pool (`PaymentMode.POOL`)

Your company maintains a pre-funded USDC treasury pool on TapRails. When contractors tap their phone to pay a merchant, TapRails handles the rest.

* **Pros:** Ultra-fast, gasless for the end-user, no transaction signing required by contractor.
* **Best for:** Neobanks, employer-sponsored card alternatives, corporate expense programs.

### 2. User Self-Custody (`PaymentMode.SESSION_KEY`)

Contractors hold USDC directly in their self-custody wallet (or embedded smart account). They sign a daily spending allowance session key once, enabling frictionless local taps.

* **Pros:** Non-custodial, contractor retains full control of funds at all times.
* **Best for:** Web3 payroll protocols, contractor crypto wallets.

***

## Step 1. Check Pool Treasury Balance

If using `PaymentMode.POOL`, monitor your company's available liquidity programmatically via the Management API.

```bash theme={null}
curl -X GET https://api.taprails.xyz/api/v1/management/pool/balance \
  -H "x-api-key: pk_live_your_public_key"
```

### Sample Response

```json theme={null}
{
  "currency": "USDC",
  "network": "base-mainnet",
  "pool_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "available_balance": "150000.00",
  "reserved_balance": "2500.00",
  "pending_settlements": 4,
  "updated_at": "2026-08-08T14:10:00Z"
}
```

***

## Step 2. Auto-Top-Up Workflow with Webhooks

To guarantee uninterrupted spending power for your users across timezone boundaries, listen for `pool.low_balance` webhooks and trigger automated treasury deposits.

```typescript server.ts theme={null}
import express from 'express';
import { ethers } from 'ethers';

const app = express();
app.use(express.json());

const THRESHOLD = 10000.00; // Trigger auto top-up if pool drops below $10,000 USDC

app.post('/webhooks/taprails', async (req, res) => {
  const { event, data } = req.body;

  if (event === 'pool.low_balance') {
    const currentBalance = parseFloat(data.available_balance);
    console.warn(`[WARNING] Pool balance low: $${currentBalance} USDC`);

    if (currentBalance < THRESHOLD) {
      console.log('Initiating automated treasury top-up on Base network...');
      await triggerBaseUsdcDeposit(50000); // Deposit $50,000 USDC
    }
  }

  res.status(200).send({ status: 'ok' });
});

async function triggerBaseUsdcDeposit(amountUsdc: number) {
  // Execute corporate wallet transaction on Base L2 to pool deposit address
  console.log(`Successfully deposited $${amountUsdc} USDC to TapRails Pool.`);
}
```

***

## Step 3. Mobile Spend Integration for Payroll Recipients

In your mobile app, configure `ContactlessCryptoSDK` with `PaymentMode.POOL`. Users can spend their earnings at local point-of-sale terminals with zero setup.

```tsx PayrollSpendCard.tsx theme={null}
import React, { useState } from 'react';
import { View, Text, TouchableOpacity, StyleSheet } from 'react-native';
import { PaymentFlowManager } from '@taprails/tap-to-pay';

export function PayrollSpendCard({ userBalance }: { userBalance: string }) {
  const [showTapToPay, setShowTapToPay] = useState(false);

  return (
    <View style={styles.cardContainer}>
      <Text style={styles.label}>Available Payroll Balance</Text>
      <Text style={styles.balance}>${userBalance} USDC</Text>

      <TouchableOpacity 
        style={styles.spendButton}
        onPress={() => setShowTapToPay(true)}
      >
        <Text style={styles.buttonText}>Tap to Spend Locally</Text>
      </TouchableOpacity>

      {showTapToPay && (
        <PaymentFlowManager
          config={{
            type: 'customer',
            onComplete: (data) => {
              console.log('Cross-border local payment completed:', data);
              setShowTapToPay(false);
            },
            onCancel: () => setShowTapToPay(false),
            onError: (err) => {
              console.error('Spend Error:', err.message);
              setShowTapToPay(false);
            },
          }}
          onCustomerCancel={() => setShowTapToPay(false)}
        />
      )}
    </View>
  );
}

const styles = StyleSheet.create({
  cardContainer: { backgroundColor: '#1A1A1A', padding: 24, borderRadius: 16, margin: 16 },
  label: { color: '#A78BFA', fontSize: 14, textTransform: 'uppercase' },
  balance: { color: '#FFFFFF', fontSize: 32, fontWeight: 'bold', marginVertical: 12 },
  spendButton: { backgroundColor: '#7C3AED', paddingVertical: 14, borderRadius: 10, alignItems: 'center' },
  buttonText: { color: '#FFFFFF', fontSize: 16, fontWeight: '600' },
});
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Pool Management API" icon="vault" href="/api-reference/management/pool/get-balance">
    View full Pool API endpoint specifications.
  </Card>

  <Card title="Coverage & Chains" icon="globe" href="/coverage/chains">
    Check supported blockchain networks and currencies.
  </Card>
</CardGroup>