Merchant Acceptance (SoftPOS)

Merchant Acceptance (SoftPOS) allows payment aggregators, merchant acquirers, and point-of-sale (POS) software providers to transform standard Android smartphones into contactless stablecoin payment terminals — requiring zero extra hardware. With TapRails, merchants generate ECDSA-signed NFC payment requests on-device. Any customer phone can tap to settle payments instantly into the merchant’s wallet of choice.

Platform Requirement: The merchant device emitting the NFC invoice must be Android (5.0+) due to Apple iOS Host Card Emulation (HCE) restrictions. However, customer devices tapping the terminal can be either iOS or Android.

Architecture Overview

Step 1. Provision a Merchant via Management API

Before an Android device can emit payment invoices, your backend must provision a merchant account using your Secret API Key (sk_live_... or sk_test_...).

curl -X POST https://api.taprails.xyz/api/v1/management/merchants/create \
  -H "x-api-key: sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Artisan Coffee Roasters",
    "email": "pos@artisancoffee.com"
  }'

Sample Response

{
  "merchant_id": "mch_9f8a7b6c5d4e",
  "name": "Artisan Coffee Roasters",
  "email": "pos@artisancoffee.com",
  "wallet_address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
  "status": "active",
  "created_at": "2026-08-08T12:00:00Z"
}

Step 2. High-Level POS Integration (`PaymentFlowManager`)

Embed the ready-to-use merchant flow into your Android POS application.

MerchantPosScreen.tsx

import React, { useState } from 'react';
import { View, Text, TouchableOpacity, StyleSheet } from 'react-native';
import { PaymentFlowManager, MerchantFlowData } from '@taprails/tap-to-pay';

export function MerchantPosScreen() {
  const [activePayment, setActivePayment] = useState<string | null>(null);

  const startCheckout = (amount: string) => {
    setActivePayment(amount);
  };

  return (
    <View style={styles.container}>
      <Text style={styles.header}>POS Terminal</Text>

      {/* POS Keypad or Quick Charge Buttons */}
      <View style={styles.buttonRow}>
        <TouchableOpacity style={styles.amountButton} onPress={() => startCheckout('5.00')}>
          <Text style={styles.btnText}>$5.00</Text>
        </TouchableOpacity>
        <TouchableOpacity style={styles.amountButton} onPress={() => startCheckout('15.50')}>
          <Text style={styles.btnText}>$15.50</Text>
        </TouchableOpacity>
        <TouchableOpacity style={styles.amountButton} onPress={() => startCheckout('42.00')}>
          <Text style={styles.btnText}>$42.00</Text>
        </TouchableOpacity>
      </View>

      {/* Active NFC Payment Screen */}
      {activePayment && (
        <PaymentFlowManager
          config={{
            type: 'merchant',
            onComplete: (data) => {
              const { paymentRequest, txHash } = data as MerchantFlowData;
              console.log('Payment Received!', paymentRequest?.paymentId, txHash);
              setActivePayment(null);
            },
            onCancel: () => setActivePayment(null),
            onError: (error) => {
              console.error('POS Payment Error:', error.message);
              setActivePayment(null);
            },
          }}
          amount={activePayment}
          onMerchantCancel={() => setActivePayment(null)}
        />
      )}
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, padding: 24, justifyContent: 'center' },
  header: { fontSize: 24, fontWeight: 'bold', textAlign: 'center', marginBottom: 30 },
  buttonRow: { flexDirection: 'row', justifyContent: 'space-around' },
  amountButton: { backgroundColor: '#7C3AED', padding: 20, borderRadius: 12, width: 90, alignItems: 'center' },
  btnText: { color: '#FFF', fontWeight: 'bold', fontSize: 16 },
});

Step 3. Low-Level Control (`useNFCMerchant`)

For custom POS interfaces with specific branded animations or hardware integration (e.g., thermal receipt printers), use useNFCMerchant.

CustomPosScreen.tsx

import React, { useState } from 'react';
import { View, Text, Button, ActivityIndicator } from 'react-native';
import { useNFCMerchant, writeSignedInvoice } from '@taprails/tap-to-pay';

export function CustomPosScreen() {
  const { createPaymentRequest, isCreating, paymentRequest, error, reset } = useNFCMerchant();
  const [isBroadcasting, setIsBroadcasting] = useState(false);

  const handleCharge = async (amount: string) => {
    // 1. Create signed payment request on TapRails backend
    const request = await createPaymentRequest({
      amount: amount,
      merchantId: 'mch_9f8a7b6c5d4e',
    });

    if (!request) return;

    // 2. Start emitting signed invoice via HCE
    setIsBroadcasting(true);
    try {
      await writeSignedInvoice(request);
      console.log('Invoice broadcast started. Waiting for customer tap...');
    } catch (err) {
      console.error('HCE emission error:', err);
    }
  };

  return (
    <View style={{ padding: 24 }}>
      {isCreating && <ActivityIndicator size="large" color="#7C3AED" />}

      {paymentRequest && isBroadcasting && (
        <View style={{ alignItems: 'center' }}>
          <Text style={{ fontSize: 28, fontWeight: 'bold' }}>${paymentRequest.amount} USDC</Text>
          <Text style={{ marginTop: 12 }}>Ready for Customer Tap...</Text>
          <Button title="Cancel Charge" onPress={reset} />
        </View>
      )}

      {!paymentRequest && (
        <Button title="Charge $25.00" onPress={() => handleCharge('25.00')} />
      )}
    </View>
  );
}

Step 4. POS Ledger & Transaction Reconciliation

You can query historic merchant transactions via the Management API to populate merchant sales reporting or reconcile daily shift totals.

curl -X GET "https://api.taprails.xyz/api/v1/management/merchants/mch_9f8a7b6c5d4e/transactions?limit=10" \
  -H "x-api-key: pk_live_your_public_key"

Response Example

{
  "merchant_id": "mch_9f8a7b6c5d4e",
  "transactions": [
    {
      "payment_id": "pay_8a9b7c6d",
      "amount": "25.00",
      "currency": "USDC",
      "status": "CONFIRMED",
      "customer_address": "0x3C44CdD45919C5042ee38125724790038E84671b",
      "tx_hash": "0xe670ec64341771606e55d6b4ca35a96d846515b5924fc07989d4d5483a936a5",
      "created_at": "2026-08-08T13:45:10Z"
    }
  ],
  "total": 1
}

Get Started

Use Cases

React Native SDK

API

Webhooks

Coverage

Merchant Acceptance (SoftPOS)

Architecture Overview

Step 1. Provision a Merchant via Management API

Sample Response

Step 2. High-Level POS Integration (`PaymentFlowManager`)

Step 3. Low-Level Control (`useNFCMerchant`)

Step 4. POS Ledger & Transaction Reconciliation

Response Example

Next Steps

Cross-Wallet Tap-to-Pay

Webhooks Guide

​Architecture Overview

​Step 1. Provision a Merchant via Management API

​Sample Response

​Step 2. High-Level POS Integration (PaymentFlowManager)

​Step 3. Low-Level Control (useNFCMerchant)

​Step 4. POS Ledger & Transaction Reconciliation

​Response Example

​Next Steps

Cross-Wallet Tap-to-Pay

Webhooks Guide

Architecture Overview

Step 1. Provision a Merchant via Management API

Sample Response

Step 2. High-Level POS Integration (`PaymentFlowManager`)

Step 3. Low-Level Control (`useNFCMerchant`)

Step 4. POS Ledger & Transaction Reconciliation

Response Example

Next Steps