NoPos Pay - Guida all'Utilizzo

Questa pagina ti mostra come integrare NoPos Pay nella tua applicazione con esempi pratici e test interattivi.

Test interattivo

Clicca il link qui sotto per aprire una finestra popup con il form di pagamento NoPos:

Incassa con NoPos

URL del test

Ecco l'URL completo per testare NoPos Pay:

https://app.nopos.it/pay?client_id=test_client_123&amount=10.00&currency=EUR&description=Test%20Payment&redirect_uri=https://example.com/payment-result&state=order_12345

Parametri del test

Il test utilizza i seguenti parametri:

• client_id: test_client_123 (obbligatorio)
• amount: 10.00 (obbligatorio)
• currency: EUR (obbligatorio)
• description: Test Payment
• redirect_uri: https://example.com/payment-result (opzionale)
• state: order_12345 (parametro personalizzato per tracking)

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

Parametro state

Il parametro state è un campo opzionale che ti permette di passare dati personalizzati che verranno restituiti nei webhook. Questo è utile per:

• Tracking ordini: Passa l'ID dell'ordine per collegare il pagamento
• Identificazione utente: Includi l'ID utente per personalizzare l'esperienza
• Dati di sessione: Mantieni informazioni di contesto durante il flusso di pagamento

Esempi di utilizzo

• state=order_12345 → Per tracciare un ordine specifico
• state=user_67890 → Per identificare l'utente
• state=session_abc123 → Per mantenere il contesto di sessione
• state=order_12345_user_67890 → Per combinare più informazioni

Il valore del state verrà restituito esattamente come inviato nei webhook di pagamento, permettendoti di collegare facilmente la transazione ai tuoi dati interni.

Codice di esempio

Ecco come implementare il pulsante di pagamento nella tua applicazione:

<a href="#" onclick="window.open('https://app.nopos.it/pay?client_id=YOUR_CLIENT_ID&amount=10.00&currency=EUR&description=Test%20Payment&redirect_uri=https://yourdomain.com/payment-result&state=order_12345','popup','width=500,height=700,scrollbars=yes,resizable=yes'); return false;" 
   style="background: black; color: white; padding: 12px 20px; border-radius: 25px; text-decoration: none; display: inline-flex; align-items: center; gap: 8px; font-weight: 500; font-family: system-ui, -apple-system, sans-serif; font-size: 14px; border: none; cursor: pointer;">
  <span>Incassa con NoPos</span>
  <svg xmlns="http://www.w3.org/2000/svg" fill="white" viewBox="0 0 68 68" style="width: 20px; height: 20px">
    <path d="M21.1037 14.2218C21.1037 17.1208 18.7536 19.4709 15.8546 19.4709C12.9556 19.4709 10.6055 17.1208 10.6055 14.2218C10.6055 11.3228 12.9556 8.97266 15.8546 8.97266C18.7536 8.97266 21.1037 11.3228 21.1037 14.2218Z" fill="white" />
    <path d="M57.1232 53.4991C57.1232 56.3981 54.7731 58.7482 51.8741 58.7482C48.9751 58.7482 46.625 56.3981 46.625 53.4991C46.625 50.6001 48.9751 48.25 51.8741 48.25C54.7731 48.25 57.1232 50.6001 57.1232 53.4991Z" fill="white" />
    <path clip-rule="evenodd" d="M15.8516 46.5903V26.8037C20.4678 26.792 24.5024 24.306 26.6989 20.6018L42.8267 36.728C43.5473 37.4485 44.7793 36.9382 44.7793 35.9193V14.2227C48.6961 14.2227 51.8712 17.3975 51.8712 21.3138V40.7573C51.8642 40.7573 51.8572 40.7573 51.8502 40.7573C47.7522 40.7573 44.1097 42.7074 41.8002 45.7301L24.8961 28.8277C24.1755 28.1072 22.9434 28.6175 22.9434 29.6364V53.6815C19.0267 53.6815 15.8516 50.5067 15.8516 46.5903Z" fill="white" fill-rule="evenodd" />
  </svg>
</a>

Note importanti

• Questo è un ambiente di test, non vengono processati pagamenti reali
• Sostituisci YOUR_CLIENT_ID con il tuo client ID reale
• Le informazioni dell'app (nome e logo) vengono recuperate automaticamente dal backend
• Configura redirect_uri (opzionale) per gestire il ritorno dal pagamento
• Assicurati che il tuo client_id sia configurato correttamente nel backend NoPos

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

Gestione del Completamento del Pagamento

NoPos Pay comunica il risultato del pagamento attraverso tre metodi:

1. Popup (Raccomandato)

// Apri NoPos Pay in popup
const popup = window.open(
  'https://app.nopos.it/pay?client_id=YOUR_CLIENT_ID&amount=10.00&currency=EUR&description=Test%20Payment&redirect_uri=https://yourdomain.com/payment-result&state=order_12345',
  'nopos-payment',
  'width=500,height=700,scrollbars=yes,resizable=yes'
);

// Ascolta i messaggi dal popup
window.addEventListener('message', function(event) {
  if (event.origin !== 'https://app.nopos.it') return;
  
  if (event.data.target === 'payment_complete') {
    const { id, status, state, provider } = event.data;
    
    // Gestisci il risultato del pagamento
    handlePaymentResult(id, status, state, provider);
    
    // Chiudi il popup
    if (popup) popup.close();
  }
});

2. Iframe

// Funzione semplice per creare iframe di pagamento
function createPaymentIframe(paymentData) {
  // Crea iframe
  const iframe = document.createElement('iframe');
  iframe.style.position = 'fixed';
  iframe.style.top = '50%';
  iframe.style.left = '50%';
  iframe.style.transform = 'translate(-50%, -50%)';
  iframe.style.width = '500px';
  iframe.style.height = '700px';
  iframe.style.border = 'none';
  iframe.style.borderRadius = '8px';
  iframe.style.boxShadow = '0 4px 20px rgba(0,0,0,0.15)';
  iframe.style.zIndex = '1000';
  iframe.setAttribute('allow', 'payment');

  // Aggiungi al body
  document.body.appendChild(iframe);

  // URL pagamento
  const params = new URLSearchParams({
    client_id: paymentData.clientId,
    amount: paymentData.amount,
    currency: paymentData.currency || 'EUR',
    description: paymentData.description,
    state: paymentData.state || '',
    redirect_uri: paymentData.redirectUri || ''
  });

  iframe.src = `https://app.nopos.it/pay?${params}`;

  // Gestisce messaggi
  function handleMessage(event) {
    if (event.origin !== 'https://app.nopos.it') return;
    
    if (event.data.target === 'payment_complete') {
      const { id, status, state, provider } = event.data;
      
      // Gestisci risultato
      console.log('Payment result:', { id, status, state, provider });
      
      // Rimuovi iframe
      iframe.remove();
      window.removeEventListener('message', handleMessage);
    }
  }

  window.addEventListener('message', handleMessage);
}

// Utilizzo
document.getElementById('payButton').addEventListener('click', () => {
  createPaymentIframe({
    clientId: 'YOUR_CLIENT_ID',
    amount: '25.00',
    currency: 'EUR',
    description: 'Pagamento Iframe',
    state: 'order_123'
  });
});

3. Redirect URI

// Gestisci il risultato dal redirect
function handleRedirectResult() {
  const urlParams = new URLSearchParams(window.location.search);
  const id = urlParams.get('id');
  const status = urlParams.get('status');
  const state = urlParams.get('state');
  const provider = urlParams.get('provider');
  
  if (id && status) {
    handlePaymentResult(id, status, state, provider);
  }
}

// Esegui al caricamento della pagina
document.addEventListener('DOMContentLoaded', handleRedirectResult);

Struttura del Messaggio

interface PaymentCompleteMessage {
  target: 'payment_complete';
  id: string;            // ID univoco della transazione
  status: string;        // Stato del pagamento
  state: string;         // Parametro state originale (se fornito)
  provider: string;      // ID del provider utilizzato per il pagamento
}

Stati del Pagamento

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

Best Practice

1. Sicurezza: Verifica sempre l'origine dei messaggi postMessage
2. Fallback: Implementa sia postMessage che redirect_uri per massima compatibilità
3. Error Handling: Gestisci tutti i possibili stati del pagamento
4. Cleanup: Chiudi popup e pulisci listener quando appropriato

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 nella tua applicazione
5. Implementa la gestione del completamento pagamento
6. Testa con transazioni reali

---

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