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. Lo stesso SDK supporta anche NoPos Issue (scontrini e fatture): vedi NoPos Issue. Puoi usare la classe NoPos per Pay e Issue, oppure NoPosPay solo per i pagamenti (retrocompatibile).

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
  // Nota: se usi autoclose: true, non è necessario chiamare nopos.close() manualmente
  nopos.close();
});

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

Opzione 3: Apertura con Auto-close

Puoi abilitare la chiusura automatica del popup quando viene ricevuto un evento di pagamento usando l'opzione autoclose:

// Apri il form di pagamento con auto-close abilitato
nopos.open({
  amount: 10.00,
  currency: 'EUR',
  description: 'Test Payment',
  state: 'order_12345',
  autoclose: true  // Chiude automaticamente quando viene ricevuto l'evento 'payment'
}).then(() => {
  console.log('Iframe aperto e caricato');
});

// Ascolta gli eventi
nopos.on('payment', (data) => {
  console.log('Pagamento:', data.status, data.id);
  // Il popup si chiuderà automaticamente, non serve chiamare nopos.close()
});

nopos.on('close', () => {
  console.log('Iframe chiuso automaticamente dopo il pagamento');
});

Opzione 4: Apertura Diretta a un Provider Specifico

Puoi specificare un provider per andare direttamente alla pagina di pagamento di quel provider, saltando la selezione del provider:

// Apri direttamente il form di pagamento Stripe
nopos.open({
  amount: 10.00,
  currency: 'EUR',
  description: 'Test Payment',
  state: 'order_12345',
  provider: 'stripe'  // Vai direttamente a Stripe, senza mostrare la lista dei provider
}).then(() => {
  console.log('Iframe aperto e caricato');
});

// Puoi combinare provider con autoclose
nopos.open({
  amount: 10.00,
  currency: 'EUR',
  description: 'Test Payment',
  provider: 'mollie',
  autoclose: true
});

Provider disponibili comuni:

• stripe - Stripe
• mollie - Mollie
• viva - Viva Wallet
• sumup - SumUp
• satispay - Satispay

Opzione 5: Apertura per Configurazione Provider (senza amount)

Puoi aprire il popup senza specificare l'importo per permettere all'utente di configurare il provider di pagamento:

// Apri il popup per configurare il provider (senza importo)
nopos.open({
  currency: 'EUR',
  description: 'Configurazione Provider'
}).then(() => {
  console.log('Popup aperto per configurazione provider');
});

// Utile per permettere all'utente di selezionare/configurare un provider
// prima di procedere con il pagamento effettivo

// Puoi anche combinare con provider specifico
nopos.open({
  provider: 'stripe'
  // amount non specificato - apre Stripe per configurazione
});

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, opzionale): Importo del pagamento. Se omesso, il popup si apre per configurare il provider di 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)
• options.autoclose (boolean, opzionale): Chiude automaticamente il popup quando viene ricevuto un evento di pagamento (default: false)
• options.provider (string, opzionale): ID del provider per andare direttamente a un provider specifico (es. 'stripe', 'mollie')

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');
      }
      // Nota: se usi autoclose: true nelle opzioni, non serve chiamare nopos.close()
      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
• ✅ Auto-close: Opzione per chiudere automaticamente il popup quando viene ricevuto un evento di pagamento
• ✅ 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, opzionale): Importo del pagamento. Se omesso, il popup si apre per configurare il provider di pagamento senza specificare un importo
• 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
• width (number, opzionale): Larghezza dell'iframe in pixel (default: 500)
• height (number, opzionale): Altezza dell'iframe in pixel (default: 700)
• background (boolean, opzionale): Carica l'iframe in background (nascosto, per ricevere eventi senza mostrare l'interfaccia)
• autoclose (boolean, opzionale): Chiude automaticamente il popup quando viene ricevuto un evento di pagamento (default: false)
• provider (string, opzionale): ID del provider per andare direttamente a un provider specifico (es. 'stripe', 'mollie'). Se non specificato, viene mostrata la lista di tutti i provider disponibili

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: 'completed' | 'failed' | 'canceled' | 'pending';  // 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
pending	Pagamento in attesa (usato per pagamenti con link quando il merchant sceglie di non attendere)

Best Practice

1. Error Handling: Gestisci tutti i possibili stati del pagamento (completed, failed, canceled, pending)
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!