POS Integration Guide

This guide walks POS terminal vendors through a complete integration with the RSA Platform POS API.

Prerequisites

• A PosApp client registered by the tenant admin (POST /admin/api/v1/clients)
• Your X-Api-Key stored securely in terminal configuration
• Network access to the POS API at https://api.yourchain.com/pos (or http://localhost:5003 in dev)

Authentication

POS terminals authenticate via the X-Api-Key header. No token refresh required.

curl "http://localhost:5003/pos/api/v1/..." \
  -H "X-Api-Key: rsa_live_your_key_here"

See API Keys for key creation and rotation.

SLA & Rate Limits

Integration Flow

Step 1: Member Lookup

When the member scans their card or enters their phone:

{
  "memberId": "3fa85f64-...",
  "firstName": "Jane",
  "tier": "Gold"
}

Step 2: Resolve Applicable Offers

Send the basket UPCs to get applicable offers:

{
  "memberId": "3fa85f64-...",
  "storeId": "store-uuid",
  "upcs": ["021000600003", "041220576836"]
}

Response includes appliedOffers[] with discount amounts per UPC.

Step 3: Create Basket

{
  "posTransactionId": "TXN-2026-001234",
  "storeId": "store-uuid",
  "memberId": "3fa85f64-...",
  "items": [
    { "upc": "021000600003", "quantity": 2, "unitPrice": 3.99 }
  ],
  "appliedOffers": [
    { "offerId": "offer-uuid", "discountAmount": 1.50 }
  ]
}

Step 4: Finalize Basket

After payment is captured:

Step 5: Earn Loyalty Points

{
  "memberId": "3fa85f64-...",
  "basketId": "basket-uuid",
  "referenceId": "TXN-2026-001234",
  "points": 125,
  "storeId": "store-uuid"
}

Voiding a Transaction

If the transaction is cancelled before finalization:

See Basket Lifecycle for the full state machine.

Feature Flags at POS

Check which features are enabled for your store at startup:

Use the response to conditionally show digital receipt options, fuel offer panels, etc.