NoPos Pay - Guida all'Utilizzo

Questa pagina ti mostra come integrare NoPos Pay nella tua applicazione usando il nostro SDK JavaScript.

Test interattivo

Prova il nostro SDK con la pagina di test che mostra un esempio completo di integrazione.

Integrazione con SDK

Il nostro SDK JavaScript gestisce automaticamente la creazione dell'iframe, gli eventi postMessage, e include un pulsante di chiusura integrato.

Installazione

Includi lo script SDK nella tua pagina:

<script src="https://app.nopos.it/sdk/sdk.js"></script>

Oppure se usi TypeScript, puoi includere anche le definizioni di tipo:

/// <reference path="https://app.nopos.it/sdk/sdk.d.ts" />

Utilizzo Base

Opzione 1: Pulsante Stilizzato (Raccomandato)

Il modo più semplice per integrare NoPos Pay è utilizzare il pulsante stilizzato incluso nell'SDK:

<div id="payment-button"></div>

<script src="https://app.nopos.it/sdk/sdk.js"></script>
<script>
  const nopos = new NoPosPay({
    clientId: 'YOUR_CLIENT_ID'
  });

  // Crea il pulsante "Incassa con NoPos"
  nopos.createButton({
    amount: 10.00,
    currency: 'EUR',
    description: 'Test Payment',
    state: 'order_12345'
  }, '#payment-button');
</script>

Opzione 2: Apertura Manuale

// Inizializza NoPos Pay
const nopos = new NoPosPay({
  clientId: 'YOUR_CLIENT_ID',
  baseUrl: 'https://app.nopos.it' // opzionale, default: https://app.nopos.it
});

// Apri il form di pagamento in iframe (con Promise)
nopos.open({
  amount: 10.00,
  currency: 'EUR',
  description: 'Test Payment',
  state: 'order_12345',
  redirectUri: 'https://yourdomain.com/payment-result'
}).then(() => {
  console.log('Iframe aperto e caricato');
}).catch((error) => {
  console.error('Errore:', error);
});

// Ascolta gli eventi
nopos.on('open', () => {
  console.log('Iframe aperto');
});

nopos.on('load', () => {
  console.log('Iframe caricato');
});

nopos.on('error', (data) => {
  console.error('Errore:', data.error);
});

nopos.on('providers', (data) => {
  console.log('Provider disponibili:', data.providers);
  // data.providers è un array di provider con id, name e user
});

nopos.on('user', (data) => {
  if (data.user) {
    console.log('Utente autenticato:', data.user);
  } else {
    console.log('Utente non autenticato');
  }
});

nopos.on('payment', (data) => {
  console.log('Pagamento completato:', data);
  // data contiene: id, status, provider
  // Chiudi l'iframe automaticamente
  nopos.close();
});

nopos.on('close', () => {
  console.log('Iframe chiuso');
  // Utile per pulire lo stato o tracciare quando l'utente chiude il pagamento
});

API Reference

Constructor

const nopos = new NoPosPay(config);

Parametri:

• config.clientId (string, obbligatorio): Il tuo client ID NoPos
• config.baseUrl (string, opzionale): URL base di NoPos (default: https://app.nopos.it)

Metodi

open(options) - Apre l'iframe di pagamento (restituisce una Promise)

• options.amount (number, obbligatorio): Importo del pagamento
• options.currency (string, opzionale): Valuta (default: EUR)
• options.description (string, opzionale): Descrizione del pagamento
• options.state (string, opzionale): Parametro personalizzato per tracking
• options.redirectUri (string, opzionale): URI di redirect dopo il pagamento
• options.width (number, opzionale): Larghezza iframe in px (default: 500)
• options.height (number, opzionale): Altezza iframe in px (default: 700)
• options.background (boolean, opzionale): Carica iframe in background (nascosto, per ricevere eventi)

close() - Chiude l'iframe di pagamento (chiamato automaticamente al completamento del pagamento o tramite il pulsante X integrato)

isOpen() - Verifica se l'iframe è aperto (restituisce boolean)

createButton(options, container) - Crea un pulsante stilizzato "Incassa con NoPos"

• options (PaymentOptions, obbligatorio): Opzioni di pagamento
• container (HTMLElement|string, opzionale): Elemento o selettore CSS dove appendere il pulsante. Se omesso, il pulsante viene solo creato ma non aggiunto al DOM
• Restituisce: HTMLButtonElement - L'elemento button creato

on(event, callback) - Registra un listener per gli eventi

• Eventi disponibili: open, load, error, providers, user, payment, close

off(event, callback) - Rimuove un listener per gli eventi

Esempio Completo

<!DOCTYPE html>
<html>
<head>
  <title>NoPos Pay Integration</title>
  <script src="https://app.nopos.it/sdk/sdk.js"></script>
</head>
<body>
  <div id="payment-button"></div>

  <script>
    const nopos = new NoPosPay({
      clientId: 'YOUR_CLIENT_ID'
    });

    // Setup event listeners
    nopos.on('providers', (data) => {
      console.log('Provider caricati:', data.providers.length);
    });

    nopos.on('user', (data) => {
      if (data.user) {
        console.log('Benvenuto', data.user.email);
      }
    });

    nopos.on('payment', (data) => {
      if (data.status === 'completed') {
        alert('Pagamento completato con successo!');
      } else {
        alert('Pagamento fallito o annullato');
      }
      nopos.close();
    });

    nopos.on('close', () => {
      console.log('Pagamento chiuso');
    });

    // Crea il pulsante "Incassa con NoPos"
    nopos.createButton({
      amount: 25.50,
      currency: 'EUR',
      description: 'Ordine #12345',
      state: 'order_12345',
      width: 600,  // Personalizza dimensione
      height: 800
    }, '#payment-button');
  </script>
</body>
</html>

Caratteristiche dell'SDK

• ✅ Pulsante stilizzato: Metodo createButton() per creare un pulsante "Incassa con NoPos" pronto all'uso
• ✅ Iframe integrato: Gestisce automaticamente la creazione e il posizionamento dell'iframe
• ✅ Pulsante di chiusura: Include un pulsante X in alto a destra per chiudere facilmente
• ✅ Backdrop: Overlay di sfondo sempre visibile con chiusura al click
• ✅ Tastiera ESC: Chiudi premendo il tasto ESC
• ✅ Modalità background: Carica iframe nascosto per ricevere eventi senza mostrare l'interfaccia
• ✅ Personalizzabile: Dimensioni iframe configurabili
• ✅ Promise-based: API asincrona con supporto Promise/async-await
• ✅ Gestione eventi: Gestisce automaticamente tutti gli eventi postMessage
• ✅ Sicurezza: Verifica automaticamente l'origine dei messaggi
• ✅ TypeScript: Include definizioni di tipo complete
• ✅ Minimale: Codice conciso, nessuna dipendenza

Parametri di Pagamento

• amount (number, obbligatorio): Importo del pagamento
• currency (string, opzionale): Valuta (default: EUR)
• description (string, opzionale): Descrizione del pagamento
• state (string, opzionale): Parametro personalizzato per tracking (restituito nei webhook)
• redirectUri (string, opzionale): URI di redirect dopo il pagamento

Informazioni dell'app

Le informazioni dell'app (nome e logo) vengono recuperate automaticamente dal backend utilizzando il client_id. Questo significa che:

• Più sicuro: Le informazioni dell'app non vengono passate nell'URL
• Più pulito: URL più corti e leggibili
• Centralizzato: Le informazioni dell'app sono gestite dal backend
• Consistente: Logo e nome sempre aggiornati

Eventi PostMessage

NoPos Pay comunica lo stato del pagamento e le informazioni disponibili tramite eventi postMessage. L'SDK gestisce automaticamente questi eventi.

Eventi Disponibili

1. open

Questo evento viene inviato quando l'iframe viene aperto.

interface OpenData {
  target: 'open';
}

Esempio:

nopos.on('open', () => {
  console.log('Iframe aperto');
  // Utile per analytics
});

2. load

Questo evento viene inviato quando l'iframe ha finito di caricare.

interface LoadData {
  target: 'load';
}

Esempio:

nopos.on('load', () => {
  console.log('Iframe caricato');
  // Nascondi loading spinner
});

3. error

Questo evento viene inviato quando si verifica un errore (parametri non validi, errore di caricamento, ecc.).

interface ErrorData {
  target: 'error';
  error: string;
}

Esempio:

nopos.on('error', (data) => {
  console.error('Errore:', data.error);
  // Mostra messaggio di errore all'utente
});

4. providers

Questo evento viene inviato quando i provider di pagamento sono disponibili per la selezione.

interface ProvidersMessage {
  target: 'providers';
  providers: Array<{
    id: string;          // ID del provider (es. "stripe", "sumup")
    name: string;        // Nome del provider
    user: {
      id: string;
      name: string;
      email?: string;
    } | null;            // Informazioni utente del provider (null se non connesso)
  }>;
}

Esempio:

nopos.on('providers', (data) => {
  console.log('Provider disponibili:', data.providers);
  // data.providers è un array di provider con id, name e user
});

5. user

Questo evento viene inviato quando le informazioni dell'utente sono disponibili.

interface UserMessage {
  target: 'user';
  user: {
    id: string;
    email: string;
    firstName?: string;
    lastName?: string;
    pictureId?: string;
  } | null;              // null se l'utente non è autenticato
}

Esempio:

nopos.on('user', (data) => {
  if (data.user) {
    console.log('Utente autenticato:', data.user);
  } else {
    console.log('Utente non autenticato');
  }
});

6. payment

Questo evento viene inviato quando un pagamento è stato completato.

interface PaymentMessage {
  target: 'payment';
  id: string;            // ID univoco della transazione
  status: string;        // Stato del pagamento
  provider: string;      // ID del provider utilizzato per il pagamento
}

Esempio:

nopos.on('payment', (data) => {
  console.log('Pagamento completato:', data);
  // data contiene: id, status, provider
  nopos.close(); // Chiude automaticamente l'iframe
});

7. close

Questo evento viene inviato quando l'iframe di pagamento viene chiuso (tramite il pulsante X, programmaticamente, o dopo il completamento del pagamento).

interface CloseData {
  target: 'close';
}

Esempio:

nopos.on('close', () => {
  console.log('Iframe chiuso');
  // Utile per pulire lo stato dell'applicazione o tracciare abbandoni
});

Stati del Pagamento

Stato	Descrizione
completed	Pagamento completato con successo
failed	Pagamento fallito
canceled	Pagamento annullato dall'utente

Best Practice

1. Error Handling: Gestisci tutti i possibili stati del pagamento (completed, failed, canceled)
2. State Parameter: Usa il parametro state per tracciare ordini e sessioni
3. Webhook: Implementa anche i webhook per una gestione affidabile lato server
4. Sicurezza: L'SDK verifica automaticamente l'origine dei messaggi per garantire la sicurezza

Configurazione dell'app

Per configurare le informazioni della tua app:

1. Accedi al dashboard NoPos
2. Vai alla sezione "App"
3. Seleziona la tua app
4. Configura il nome e carica il logo
5. Le informazioni saranno automaticamente disponibili per NoPos Pay

Prossimi passi

1. Registrati su NoPos per ottenere le tue credenziali
2. Configura il tuo ambiente di produzione
3. Imposta nome e logo della tua app nel dashboard
4. Integra NoPos Pay usando l'SDK nella tua applicazione
5. Testa con la pagina di test
6. Implementa i webhook per una gestione completa lato server
7. Testa con transazioni reali

---

Test completato con successo? Prosegui con l'integrazione completa!