writeSignedInvoice

writeSignedInvoice enables the Android HCE layer to emit a signed payment invoice over NFC. When a customer taps their phone to the merchant device, the invoice is read by the customer’s app.

This function requires an Android device with HCE support. It will not work on iOS.

Import

import { writeSignedInvoice } from '@taprails/tap-to-pay';

Signature

async function writeSignedInvoice(
  invoice: {
    id: string;
    merchantAddress: string;
    amount: number;      // Amount in µUSDC (micro-USDC = USDC × 1,000,000)
    expiresAt: number;   // Unix timestamp in milliseconds
  },
  setHasExchangedData: (value: boolean) => void
): Promise<void>

Parameters

string

required

The paymentId returned from createPayment / useNFCMerchant.

string

required

The merchant’s wallet address (merchantWallet from the payment response).

number

required

Amount in micro-USDC (µUSDC). Multiply the USDC decimal amount by 1,000,000.

// $25.00 USDC → 25,000,000 µUSDC
amount: Math.round(parseFloat('25.00') * 1_000_000)

number

required

Unix timestamp in milliseconds when the invoice expires. Use expiresAt from the createPayment response directly.

(value: boolean) => void

required

Callback invoked with true when the customer’s device successfully reads the NFC tag. Use this to transition to a “processing” state on the merchant screen.

What it does internally

Signs the invoice payload with the merchant’s ECDSA private key (stored in Keychain)
Serializes the signed payload as JSON
Wraps it in an NDEF Text record
Starts HCE emulation via react-native-hce
Listens for the HCE_STATE_READ event (customer tap)
On read: invokes setHasExchangedData(true), then cancels the session after 1.5s

Example

import { useNFCMerchant, writeSignedInvoice } from '@taprails/tap-to-pay';

const { createPaymentRequest, paymentRequest } = useNFCMerchant();
const [exchanged, setExchanged] = useState(false);

const startPayment = async () => {
  const request = await createPaymentRequest({ amount: '25.00' });
  if (!request) return;

  await writeSignedInvoice(
    {
      id: request.paymentId,
      merchantAddress: request.merchantWallet,
      amount: Math.round(25 * 1_000_000),  // µUSDC
      expiresAt: request.expiresAt!,
    },
    setExchanged
  );
};

useEffect(() => {
  if (exchanged) {
    console.log('Customer tapped — waiting for backend confirmation');
  }
}, [exchanged]);

writeSignedInvoice returns as soon as HCE emulation starts — it does not block until the customer taps. The setHasExchangedData callback fires asynchronously when the tap occurs.

Get Started

Use Cases

React Native SDK

API

Webhooks

Coverage

writeSignedInvoice

Import

Signature

Parameters

What it does internally

Example

​Import

​Signature

​Parameters

​What it does internally

​Example

Import

Signature

Parameters

What it does internally

Example