Add to wallet

{
  "issuance": {
    "issuer": "0x1111111111111111111111111111111111111111",
    "loyaltyId": "0x4242424242424242424242424242424242424242424242424242424242424242",
    "amount": "1000",
    "expiresAt": "0",
    "deadline": "1790965800",
    "nonce": "0x7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a",
    "chainId": "8453",
    "verifyingContract": "0x3333333333333333333333333333333333333333",
    "operationHash": "0x9999999999999999999999999999999999999999999999999999999999999999",
    "metadata": {
      "loyaltyId": "0x4242424242424242424242424242424242424242424242424242424242424242",
      "name": "Bloom Coffee Rewards",
      "symbol": "BLOOM",
      "media": "ipfs://bafy.../bloom.png",
      "description": "Rewards for Bloom Coffee customers."
    },
    "data": "0x"
  },
  "signature": "0xababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababab",
  "to": "0x2222222222222222222222222222222222222222"
}

// Run on your backend. Sign the issuance as shown in Signing.
// verifiedWallet is the recipient saved with this customer’s conversion.
const response = await fetch("https://api.loyfin.com/issuances", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-loyfin-api-key": process.env.LOYFIN_API_KEY
  },
  body: JSON.stringify({
    issuance,
    signature,
    to: verifiedWallet
  })
});

if (!response.ok) {
  throw new Error(await response.text());
}

const { issuance: session, duplicate } = await response.json();

curl https://api.loyfin.com/issuances \
  -X POST \
  -H "content-type: application/json" \
  -H "x-loyfin-api-key: $LOYFIN_API_KEY" \
  -d '{
  "issuance": {
    "issuer": "0x1111111111111111111111111111111111111111",
    "loyaltyId": "0x4242424242424242424242424242424242424242424242424242424242424242",
    "amount": "1000",
    "expiresAt": "0",
    "deadline": "1790965800",
    "nonce": "0x7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a",
    "chainId": "8453",
    "verifyingContract": "0x3333333333333333333333333333333333333333",
    "operationHash": "0x9999999999999999999999999999999999999999999999999999999999999999",
    "metadata": {
      "loyaltyId": "0x4242424242424242424242424242424242424242424242424242424242424242",
      "name": "Bloom Coffee Rewards",
      "symbol": "BLOOM",
      "media": "ipfs://bafy.../bloom.png",
      "description": "Rewards for Bloom Coffee customers."
    },
    "data": "0x"
  },
  "signature": "0xababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababab",
  "to": "0x2222222222222222222222222222222222222222"
}'

Store the issuance and show Awaiting wallet authorization, then give the private checkout URL to the intended customer. Checkout collects the recipient authorization and asks the customer wallet to submit the transaction with the action fee and gas. When mined, the indexer writes a completed Issuance event object.

• Wrong chainId or verifyingContract makes the signature invalid onchain.
• Expired buckets cannot be issued, and actions cannot execute after their deadline.
• A reused issuer nonce is treated as duplicate or rejected before balances change.

Add an Add to wallet button to your existing app. When a logged-in customer chooses an amount, your backend checks eligibility and the available balance, creates a conversion record, and reserves or deducts those points. It then signs the issuance using that record.

• Use operationHash to connect the Loyfin action with your internal database row. Use a secret-keyed HMAC or a stored random bytes32 value; do not publish a guessable raw-ID hash.
• Reserve or deduct the customer's spendable points in the brand account before publishing the signed issuance, so two fast requests cannot tokenize the same balance twice.
• Keep the conversion pending until finalized completion. Use verified completion webhooks by default. Polling or direct chain reads are fallbacks and must verify finality before completing the conversion.
• The session API is the default coordination path. The customer submits through Loyfin Checkout, or the brand can embed the same wallet-paid issue flow in its own interface.

Loyfin prevents replay of the same issuer nonce, but it cannot know whether two different nonces both spend the same points. The brand backend should use a row lock, serializable transaction, or atomic update that succeeds only when the customer has enough spendable balance.

• Create one internal operation row with a stable ID, operationHash, nonce, wallet address, amount, and status.
• Retry transient Loyfin API failures with the same signed payload instead of creating a fresh nonce for the same offchain deduction.
• Release reserved points only after verified expiry with reservationReleaseSafe: true, or equivalent finalized chain checks. Reconcile other failures before restoring points.