GET /api/payment/status/abc123def456
Headers:
  API-Key: your-api-key-here

{
  "txId": "abc123def456",
  "status": "PENDING",
  "amount": 50.00,
  "reason": "Purchase payment",
  "createdAt": "2025-10-11T12:00:00",
  "expiresAt": "2025-10-11T13:00:00"
}

{
  "txId": "abc123def456",
  "status": "SUCCESS",
  "amount": 50.00,
  "reason": "Purchase payment",
  "resultCode": "IGFS_000",
  "tranId": "TR123456",
  "authCode": "AUTH789",
  "maskedPan": "1234****5678",
  "cardBrand": "VISA",
  "payerName": "Mario",
  "payerLastName": "Rossi",
  "createdAt": "2025-10-11T12:00:00"
}

// 1. Crea payment link
async function createPaymentLink(amount, reason) {
  const response = await fetch('/api/v1/paybylink', {
    method: 'POST',
    headers: {
      'API-Key': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: amount,
      reason: reason,
      terminalID: 'TML001',
      customerEmail: 'customer@example.com'
    })
  });

  const data = await response.json();
  return data; // { txId, paymentUrl, ... }
}

// 2. Mostra QR code con paymentUrl
function showQRCode(paymentUrl) {
  // Usa libreria QR code per generare QR
  // Mostra su schermo PayCC
}

// 3. Polling per verificare stato
async function pollPaymentStatus(txId) {
  const interval = setInterval(async () => {
    const response = await fetch(\`/api/payment/status/\${txId}\`, {
      headers: { 'API-Key': 'your-api-key' }
    });

    const status = await response.json();

    if (status.status === 'SUCCESS') {
      clearInterval(interval);
      showSuccessScreen(status);
    } else if (status.status === 'FAILED') {
      clearInterval(interval);
      showErrorScreen(status);
    }
  }, 2000); // Ogni 2 secondi
}

Descrizione: Verifica se il terminale è connesso via WebSocket e pronto a ricevere comandi di pagamento.

Autenticazione: Header API-Key

GET /api/v1/90011004/connection
Headers:
  API-Key: your-api-token-here

{
  "status": "ok",
  "data": {
    "terminalId": "90011004",
    "connectionStatus": "ONLINE",
    "connected": true,
    "sessions": 1,
    "lastActivity": "2026-02-10T10:56:03Z",
    "connectedSince": "2026-02-10T09:30:00Z",
    "server": "pgbesrv01"
  }
}

{
  "status": "ok",
  "data": {
    "terminalId": "90011004",
    "connectionStatus": "OFFLINE",
    "connected": false,
    "sessions": 0,
    "lastSeen": "2026-02-10T08:45:00Z"
  }
}

{
  "status": "ok",
  "data": {
    "terminalId": "99999999",
    "connectionStatus": "NEVER_CONNECTED",
    "connected": false,
    "sessions": 0,
    "message": "Terminal has never connected to the system"
  }
}

Descrizione: Restituisce l'ultima transazione elaborata dal terminale.

Autenticazione: Header API-Key

GET /api/v1/90011004/status
Headers:
  API-Key: your-api-token-here

{
  "status": "ok",
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2025-10-26T14:30:00",
    "method": "CARD",
    "status": "OK",
    "amountCents": 1050,
    "currency": "EUR",
    "terminalId": "90011004",
    "message": "Transazione approvata",
    "auth": {
      "authCode": "123456",
      "stan": "000123"
    },
    "card": {
      "brand": "VISA",
      "maskedPan": "4242****4242",
      "entry": "ICC"
    }
  }
}

{
  "status": "ok",
  "data": null
}

Descrizione: Cerca una transazione specifica tramite UUID.

Autenticazione: Header API-Key

GET /api/v1/550e8400-e29b-41d4-a716-446655440000/uuid
Headers:
  API-Key: your-api-token-here

{
  "status": "ok",
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "status": "OK",
    "amountCents": 1050,
    ...
  }
}

{
  "status": "error",
  "message": "Transaction not found"
}

Descrizione: Invia un comando di scansione barcode/QR al terminale. L'app Android apre la fotocamera, scansiona il codice e restituisce il valore scansionato.

Autenticazione: Header API-Key

POST /api/v1/91010001/scan
Headers:
  API-Key: your-api-token-here
  Content-Type: application/json

Body:
{
  "uuid": "scan-abc-12345"
}

• uuid opzionale - ID univoco richiesta (auto-generato se omesso)

{
  "status": "ok",
  "data": {
    "terminalID": "91010001",
    "uuid": "scan-abc-12345",
    "service": "SCAN",
    "message": "Scan request sent to terminal 91010001"
  }
}

{
  "uuid": "scan-abc-12345",
  "service": "SCAN",
  "amount": 0,
  "terminalId": "91010001"
}

{
  "uuid": "scan-abc-12345",
  "service": "SCAN",
  "result": "OK",
  "scannedValue": "8001234567890",
  "barcodeFormat": "EAN_13",
  "timestamp": "2026-02-18T14:30:45.123Z",
  "terminalId": "91010001",
  "appVersion": "x.x.x",
  "deviceModel": "Ingenico APOS A8"
}

{
  "uuid": "scan-abc-12345",
  "service": "SCAN",
  "result": "CANCELLED",
  "scannedValue": null,
  "barcodeFormat": null,
  "timestamp": "2026-02-18T14:30:50.000Z",
  "terminalId": "91010001"
}

GET /api/v1/scan-abc-12345/uuid
Headers:
  API-Key: your-api-token-here

// Response:
{
  "status": "ok",
  "data": {
    "uuid": "scan-abc-12345",
    "createdAt": "2026-02-18T14:30:45",
    "method": "SCAN",
    "status": "OK",
    "amountCents": 0,
    "scan": {
      "scannedValue": "8001234567890",
      "barcodeFormat": "EAN_13",
      "scanResult": "OK"
    }
  }
}

  Partner                     ServerPOS                    Terminal POS
    │                             │                             │
    │  POST /scan {uuid}          │                             │
    │────────────────────────────►│                             │
    │                             │  Redis + WebSocket push     │
    │  ◄── 200 OK (uuid) ────────│────────────────────────────►│
    │                             │                             │
    │                             │                  Apre fotocamera
    │                             │                  Scansiona barcode
    │                             │                             │
    │                             │  ◄── POST /receipt ─────────│
    │                             │  {result:"OK",              │
    │                             │   scannedValue:"800123..."}│
    │  GET /{uuid}/uuid           │                             │
    │────────────────────────────►│                             │
    │  ◄── {method:"SCAN",       │                             │
    │       scan:{scannedValue}} │                             │
    │                             │                             │

async function scanBarcode(terminalId) {
  // 1. Invia comando SCAN
  const response = await fetch(`${API_BASE}/${terminalId}/scan`, {
    method: 'POST',
    headers: {
      'API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({})
  });

  const { data } = await response.json();
  const uuid = data.uuid;

  // 2. Polling risultato (timeout 60s)
  return new Promise((resolve, reject) => {
    const startTime = Date.now();
    const interval = setInterval(async () => {
      // Timeout check
      if (Date.now() - startTime > 60000) {
        clearInterval(interval);
        reject(new Error('Scan timeout (60s)'));
        return;
      }

      const res = await fetch(`${API_BASE}/${uuid}/uuid`, {
        headers: { 'API-Key': API_KEY }
      });
      const result = await res.json();

      if (result.data && result.data.scan) {
        clearInterval(interval);
        if (result.data.scan.scanResult === 'OK') {
          resolve(result.data.scan); // { scannedValue, barcodeFormat }
        } else {
          reject(new Error('Scan ' + result.data.scan.scanResult));
        }
      }
    }, 2000);
  });
}

Descrizione: Invia testo formattato al terminale per la stampa su stampante termica integrata.

Autenticazione: Header API-Key

POST /api/v1/91010001/print
Headers:
  API-Key: your-api-token-here
  Content-Type: application/json

Body:
{
  "uuid": "print-abc-12345",
  "text": "===== RICEVUTA =====\nArticolo 1       10.00\nArticolo 2        5.50\n--------------------\nTOTALE           15.50\n\nGrazie per l'acquisto!"
}

POST /api/v1/91010001/print
Headers:
  API-Key: your-api-token-here
  Content-Type: application/json

Body:
{
  "uuid": "print-qr-67890",
  "type": "qr",
  "text": "https://payglobe.co/pay/abc123",
  "label": "Scansiona per pagare"
}

{
  "status": "ok",
  "data": {
    "terminalID": "91010001",
    "uuid": "print-abc-12345",
    "service": "PRINT",
    "message": "Print request sent to terminal 91010001"
  }
}

{
  "uuid": "print-abc-12345",
  "service": "PRINT",
  "result": "OK",
  "terminalId": "91010001"
}

{
  "uuid": "print-abc-12345",
  "service": "PRINT",
  "result": "KO",
  "errorDescription": "Carta finita",
  "terminalId": "91010001"
}

GET /api/v1/print-abc-12345/uuid
Headers:
  API-Key: your-api-token-here

// Response (OK):
{
  "status": "ok",
  "data": {
    "uuid": "print-abc-12345",
    "createdAt": "2026-02-18T14:35:00",
    "method": "PRINT",
    "status": "OK",
    "amountCents": 0,
    "print": {
      "printResult": "OK",
      "errorDescription": null
    }
  }
}

// Response (KO):
{
  "status": "ok",
  "data": {
    "uuid": "print-abc-12345",
    "createdAt": "2026-02-18T14:35:00",
    "method": "PRINT",
    "status": "KO",
    "amountCents": 0,
    "print": {
      "printResult": "KO",
      "errorDescription": "Carta finita"
    }
  }
}

async function printText(terminalId, text) {
  // 1. Invia comando PRINT
  const response = await fetch(`${API_BASE}/${terminalId}/print`, {
    method: 'POST',
    headers: {
      'API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ text: text })
  });

  const { data } = await response.json();
  const uuid = data.uuid;

  // 2. Polling risultato (timeout 30s)
  return new Promise((resolve, reject) => {
    const startTime = Date.now();
    const interval = setInterval(async () => {
      if (Date.now() - startTime > 30000) {
        clearInterval(interval);
        reject(new Error('Print timeout (30s)'));
        return;
      }

      const res = await fetch(`${API_BASE}/${uuid}/uuid`, {
        headers: { 'API-Key': API_KEY }
      });
      const result = await res.json();

      if (result.data && result.data.print) {
        clearInterval(interval);
        if (result.data.print.printResult === 'OK') {
          resolve(result.data.print);
        } else {
          reject(new Error(result.data.print.errorDescription || 'Print failed'));
        }
      }
    }, 2000);
  });
}

// Uso - Stampa testo:
await printText('91010001', '===== RICEVUTA =====\nTotale: 15.50 EUR');

// Uso - Stampa QR Code:
async function printQR(terminalId, url, label) {
  const response = await fetch(`${API_BASE}/${terminalId}/print`, {
    method: 'POST',
    headers: {
      'API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ type: 'qr', text: url, label: label })
  });
  // ... stesso polling di printText()
}

await printQR('91010001', 'https://payglobe.co/pay/abc123', 'Scansiona per pagare');

const API_BASE = 'https://ricevute.payglobe.it/serverpos/api/v1';
const API_KEY = 'your-api-token-here';
const TERMINAL_ID = '90011004';

// 1. Invia pagamento
async function sendPayment(amount) {
  const uuid = generateUUID(); // Genera UUID univoco

  const response = await fetch(`${API_BASE}/${TERMINAL_ID}/pay`, {
    method: 'POST',
    headers: {
      'API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      uuid: uuid,
      amount: amount, // in centesimi
      service: 'PAYCC'
    })
  });

  if (!response.ok) {
    throw new Error('Errore invio pagamento');
  }

  console.log('Pagamento inviato:', uuid);
  return uuid;
}

// 2. Polling stato pagamento
async function pollPaymentStatus(uuid) {
  return new Promise((resolve, reject) => {
    const interval = setInterval(async () => {
      try {
        const response = await fetch(`${API_BASE}/${uuid}/uuid`, {
          headers: { 'API-Key': API_KEY }
        });

        const result = await response.json();

        if (result.status === 'ok' && result.data) {
          const txStatus = result.data.status; // "OK" o "KO"

          if (txStatus === 'OK') {
            clearInterval(interval);
            resolve(result.data); // Pagamento approvato
          } else if (txStatus === 'KO') {
            clearInterval(interval);
            reject(new Error(result.data.message)); // Pagamento rifiutato
          }
          // Se ancora PENDING, continua il loop
        }
      } catch (error) {
        clearInterval(interval);
        reject(error);
      }
    }, 3000); // Polling ogni 3 secondi

    // Timeout dopo 5 minuti
    setTimeout(() => {
      clearInterval(interval);
      reject(new Error('Timeout: pagamento non completato'));
    }, 300000);
  });
}

// 3. Esempio utilizzo completo
async function processPayment(amount) {
  try {
    // Invia richiesta pagamento
    const uuid = await sendPayment(amount);
    console.log('In attesa di conferma pagamento...');

    // Attendi risultato tramite polling
    const result = await pollPaymentStatus(uuid);
    console.log('Pagamento completato!', result);

    // Mostra scontrino / conferma all'utente
    showReceipt(result);
  } catch (error) {
    console.error('Errore:', error);
    // Mostra errore all'utente
    showError(error.message);
  }
}

// Genera UUID v4
function generateUUID() {
  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => {
    const r = Math.random() * 16 | 0;
    return (c === 'x' ? r : (r & 0x3 | 0x8)).toString(16);
  });
}