QR Login - Loyalty.lt API Documentation

curl -X POST "https://staging-api.loyalty.lt/en/shop/auth/qr-login/generate" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "device_name": "Shop Plugin - Checkout",
    "shop_id": 123
  }'

const response = await fetch('https://staging-api.loyalty.lt/en/shop/auth/qr-login/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key',
    'X-API-Secret': 'your_api_secret'
  },
  body: JSON.stringify({
    device_name: 'Shop Plugin - Checkout',
    shop_id: 123
  })
});

const data = await response.json();
console.log('QR Code URL:', data.data.qr_code);
console.log('Session ID:', data.data.session_id);

{
  "success": true,
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "qr_code": "loyaltylt://qr-login?code=abcd1234efgh5678ijkl9012mnop3456&session=550e8400-e29b-41d4-a716-446655440000",
    "partner_name": "Coffee Paradise",
    "partner_id": 45,
    "shop_id": 123,
    "expires_at": "2024-12-08T15:35:00.000Z"
  }
}

POST

{locale}

shop

auth

qr-login

generate

curl -X POST "https://staging-api.loyalty.lt/en/shop/auth/qr-login/generate" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "device_name": "Shop Plugin - Checkout",
    "shop_id": 123
  }'

const response = await fetch('https://staging-api.loyalty.lt/en/shop/auth/qr-login/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key',
    'X-API-Secret': 'your_api_secret'
  },
  body: JSON.stringify({
    device_name: 'Shop Plugin - Checkout',
    shop_id: 123
  })
});

const data = await response.json();
console.log('QR Code URL:', data.data.qr_code);
console.log('Session ID:', data.data.session_id);

{
  "success": true,
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "qr_code": "loyaltylt://qr-login?code=abcd1234efgh5678ijkl9012mnop3456&session=550e8400-e29b-41d4-a716-446655440000",
    "partner_name": "Coffee Paradise",
    "partner_id": 45,
    "shop_id": 123,
    "expires_at": "2024-12-08T15:35:00.000Z"
  }
}

The QR Login system allows users to authenticate on desktop/web by scanning a QR code with their mobile app. This is commonly used in custom shop plugin integrations.

QR Login requires Shop API authentication (X-API-Key and X-API-Secret headers) and real-time WebSocket support via Ably.

Authentication Flow

Create a new QR login session that generates a scannable QR code.

Endpoint

POST /{locale}/shop/auth/qr-login/generate

Authentication

X-API-Key

string

required

API key from Partners Portal

X-API-Secret

string

required

API secret from Partners Portal

Request Body

device_name

string

Optional name for the device requesting loginExample: "Shop Plugin - Checkout"

shop_id

integer

Optional shop ID for multi-shop partners

Response

success

boolean

Indicates if session was created successfully

data

object

Show data

session_id

string

Unique session identifier (UUID)

qr_code

string

Deep link URL for QR code: loyaltylt://qr-login?code={code}&session={session_id}

partner_name

string

Name of the partner business

partner_id

integer

Partner’s unique identifier

shop_id

integer

Shop ID if provided (nullable)

expires_at

string

ISO 8601 timestamp when session expires (5 minutes)

curl -X POST "https://staging-api.loyalty.lt/en/shop/auth/qr-login/generate" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "device_name": "Shop Plugin - Checkout",
    "shop_id": 123
  }'

const response = await fetch('https://staging-api.loyalty.lt/en/shop/auth/qr-login/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key',
    'X-API-Secret': 'your_api_secret'
  },
  body: JSON.stringify({
    device_name: 'Shop Plugin - Checkout',
    shop_id: 123
  })
});

const data = await response.json();
console.log('QR Code URL:', data.data.qr_code);
console.log('Session ID:', data.data.session_id);

{
  "success": true,
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "qr_code": "loyaltylt://qr-login?code=abcd1234efgh5678ijkl9012mnop3456&session=550e8400-e29b-41d4-a716-446655440000",
    "partner_name": "Coffee Paradise",
    "partner_id": 45,
    "shop_id": 123,
    "expires_at": "2024-12-08T15:35:00.000Z"
  }
}

Generate Ably Token

Get a secure Ably JWT token to subscribe to real-time QR login events.

Endpoint

POST /{locale}/shop/ably/token

Request Body

session_id

string

required

The session ID from the generate endpoint

Response

data.token

string

Ably JWT token for WebSocket connection

data.expires

integer

Unix timestamp when token expires

data.channel

string

Ably channel name (automatically determined based on session type)

data.session_type

string

Type of session: login or card_scan

curl -X POST "https://staging-api.loyalty.lt/en/shop/ably/token" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "session_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

// After generating session, get Ably token
const tokenResponse = await fetch('https://staging-api.loyalty.lt/en/shop/ably/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key',
    'X-API-Secret': 'your_api_secret'
  },
  body: JSON.stringify({
    session_id: sessionId
  })
});

const { data } = await tokenResponse.json();

// Connect to Ably with the token
const ably = new Ably.Realtime({ token: data.token });
const channel = ably.channels.get(data.channel); // Use channel from response

channel.subscribe('qr_login_status', (message) => {
  console.log('Status:', message.data.status);
  
  if (message.data.status === 'confirmed') {
    console.log('User:', message.data.user);
    console.log('Token:', message.data.token);
    // User is authenticated!
  }
});

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires": 1702054500,
    "channel": "qr-login:550e8400-e29b-41d4-a716-446655440000",
    "session_type": "login"
  }
}

Real-time Integration (Ably)

After generating a session and obtaining an Ably token, subscribe to the WebSocket channel to receive login status updates in real-time.

Channel Name

qr-login:{session_id}

Example: qr-login:550e8400-e29b-41d4-a716-446655440000

Event Name	Description
`qr_login_status`	Login status changed (scanned, confirmed, expired)

Ably Connection Example

import Ably from 'ably';

// 1. Get token from API response
const { token, channel } = ablyTokenResponse.data;

// 2. Connect to Ably
const ably = new Ably.Realtime({ token: token });

// 3. Subscribe to channel
const ablyChannel = ably.channels.get(channel);

// 4. Listen for status updates
ablyChannel.subscribe('qr_login_status', (message) => {
  const { status, user, token, refresh_token } = message.data;
  
  if (status === 'scanned') {
    console.log('User scanned QR, waiting for confirmation...');
  }
  
  if (status === 'confirmed') {
    console.log('User authenticated:', user.name);
    // Store tokens and redirect user
    localStorage.setItem('access_token', token);
    localStorage.setItem('refresh_token', refresh_token);
  }
});

Status: scanned

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "scanned"
}

Status: confirmed

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "confirmed",
  "user": {
    "id": 123,
    "name": "Jonas Jonaitis",
    "phone": "+37060000000",
    "email": "jonas@example.com"
  },
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh_token": "a1b2c3d4e5f6...",
  "expires_in": 3600
}

Alternative to WebSockets: poll the session status periodically.

Endpoint

POST /{locale}/shop/auth/qr-login/poll/{session_id}

Path Parameters

session_id

string

required

The QR login session ID

Response Statuses

Status	Description
`pending`	Waiting for user to scan QR code
`scanned`	User scanned QR, waiting for confirmation
`confirmed`	User confirmed login, tokens available
`expired`	Session expired (after 5 minutes)

curl -X POST "https://staging-api.loyalty.lt/en/shop/auth/qr-login/poll/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

// Polling approach (fallback when WebSockets unavailable)
async function pollQrLogin(sessionId) {
  const response = await fetch(
    `https://staging-api.loyalty.lt/en/shop/auth/qr-login/poll/${sessionId}`,
    {
      method: 'POST',
      headers: {
        'X-API-Key': 'your_api_key',
        'X-API-Secret': 'your_api_secret'
      }
    }
  );
  
  const data = await response.json();
  return data;
}

// Poll every 2 seconds
const interval = setInterval(async () => {
  const result = await pollQrLogin(sessionId);
  
  if (result.data.status === 'confirmed') {
    clearInterval(interval);
    // Handle successful login
  } else if (result.data.status === 'expired') {
    clearInterval(interval);
    // Handle expired session
  }
}, 2000);

{
  "success": true,
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending",
    "expires_at": "2024-12-08T15:35:00.000Z"
  }
}

{
  "success": true,
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "confirmed",
    "user": {
      "id": 123,
      "name": "Jonas Jonaitis",
      "phone": "+37060000000",
      "email": "jonas@example.com"
    },
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "refresh_token": "a1b2c3d4e5f6...",
    "expires_in": 3600
  }
}

{
  "success": false,
  "message": "QR session expired or not found",
  "code": "QR_SESSION_NOT_FOUND"
}

Session Timeline

Generate Session

Partner creates QR session (valid for 5 minutes)

Display QR Code

Convert deep link to QR code image for user to scan

Subscribe to Events

Connect to Ably WebSocket or start polling

User Scans

Mobile app user scans QR code (status: scanned)

User Confirms

User confirms login in mobile app (status: confirmed)

Receive Tokens

Shop plugin receives JWT tokens via WebSocket/polling

Error Codes

Code	Description	HTTP Status
`AUTH_FORBIDDEN`	Invalid or missing API credentials	403
`RESOURCE_NOT_FOUND`	Shop not found or access denied	404
`QR_SESSION_NOT_FOUND`	Session expired or invalid	404
`RESOURCE_EXPIRED`	QR code has expired	410
`INTERNAL_ERROR`	Server error	500

Best Practices

Use WebSockets

Prefer Ably WebSockets over polling for real-time updates

Handle Expiration

Sessions expire after 5 minutes - show countdown to users

Secure Storage

Store received tokens securely after successful login

Fallback Polling

Implement polling as fallback if WebSockets fail

Validate Credentials QR Card Scan

​QR Login System

​Authentication Flow

​Generate QR Login Session

​Endpoint

​Authentication

​Request Body

​Response

​Generate Ably Token

​Endpoint

​Request Body

​Response

​Real-time Integration (Ably)

​Channel Name

​Events to Subscribe

​Ably Connection Example

​Event Payload: qr_login_status

​Poll QR Login Status (Fallback)

​Endpoint

​Path Parameters

​Response Statuses

​Session Timeline

​Error Codes

​Best Practices

Use WebSockets

Handle Expiration

Secure Storage

Fallback Polling

QR Login System

Authentication Flow

Generate QR Login Session

Endpoint

Authentication

Request Body

Response

Generate Ably Token

Endpoint

Request Body

Response

Real-time Integration (Ably)

Channel Name

Events to Subscribe

Ably Connection Example

Event Payload: `qr_login_status`

Poll QR Login Status (Fallback)

Endpoint

Path Parameters

Response Statuses

Session Timeline

Error Codes

Best Practices