Nuvio Partner POS API

{
  "cardToken": "DISC00000000000000000000"
}

// Read card
const cardResponse = await fetch('/card', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer pos_xxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ cardToken })
})

const card = await cardResponse.json()

// Apply discount locally
if (card.programType === 'DISCOUNT') {
  applyDiscount(card.discountPercent)
}

// Commit transaction
await fetch('/transaction', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer pos_xxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    transactionId,
    cardToken,
    type: 'ADD',
    amountOriginal,
    amountPaid,
    status: 'CONFIRMED'
  })
})

Authorization: Bearer pos_<api_key>

POST /api/pos/v1/pair

{
  "pairingCode": "1234-5678",
  "deviceFingerprint": "register-01",
  "source": "android-pos",
  "installationName": "Front counter"
}

200 OK

{
  "status": "PAIRED",
  "merchantId": "merch_demo_krk",
  "merchantName": "Nuvio Demo Merchant",
  "apiKey": "pos_xxxxxxxxxxxxxxxxxxxxxx",
  "baseUrl": "https://loyalty.nuvio.group/api/pos/v1"
}

Scanner input -> Partner loyalty adapter -> Nuvio Partner POS API
                                      |
                                      +-> Partner cashier UI
                                      +-> Partner checkout engine
                                      +-> Partner receipt close and fiscalization
                                      +-> Final transaction commit

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "cardToken is required.",
    "requestId": "req_01JERR2YJ2V8"
  }
}

{
  "error": {
    "code": "PAIRING_CODE_INVALID",
    "message": "The provided pairing code is invalid or expired.",
    "requestId": "req_01JPAIR7Y8X4"
  }
}

{
  "error": {
    "code": "CARD_NOT_FOUND",
    "message": "The scanned card could not be resolved for this merchant.",
    "requestId": "req_01JCARD4X1E0"
  }
}

{
  "error": {
    "code": "TRANSACTION_ALREADY_PROCESSED",
    "message": "The transactionId was already processed for this merchant.",
    "requestId": "req_01JTXN9M4C1",
    "idempotentReplay": true
  }
}

Sale total: 100.00 PLN
Cashback available: 30.00 PLN

POS behavior:
- 30.00 PLN covered by cashback
- 70.00 PLN collected normally

Commit payload:
{
  "transactionId": "txn_cashback_1002",
  "cardToken": "CASH0000000000000000000",
  "type": "REDEEM",
  "amountOriginal": 10000,
  "amountPaid": 7000,
  "cashbackUsed": 3000,
  "status": "CONFIRMED"
}

1. Call POST /card
2. If programType is POINTS or STAMPS, call POST /rewards
3. Render rewards as partner-owned tiles
4. If cashier selects a reward, commit REDEEM_REWARD
5. If no reward is selected, close checkout and commit ADD