Accettare un pagamento con Satispay

Come configurare l'integrazione con Satispay

Web

Mobile

Utilizza Payment Element per integrare un modulo di pagamento Stripe personalizzato nel tuo sito web o nella tua applicazione e offrire metodi di pagamento ai clienti. Per configurazioni e personalizzazioni avanzate, consulta la guida all’integrazione Accettare un pagamento.

Configurare Stripe
Lato server

Per iniziare, crea un account Stripe.

Utilizza le nostre librerie ufficiali per accedere all’API Stripe dalla tua applicazione:

Raccogliere i dati di pagamento
Lato client

A questo punto è tutto pronto per acquisire i dati di pagamento sul client con Payment Element. Payment Element è un componente di interfaccia utente preintegrato che semplifica l’acquisizione dei dati di pagamento per vari metodi di pagamento.

Payment Element contiene un iframe che invia a Stripe le informazioni sul pagamento in modo sicuro tramite una connessione HTTPS. Evita di inserire Payment Element all’interno di un altro iframe, perché alcuni metodi di pagamento richiedono il reindirizzamento a un’altra pagina per la conferma del pagamento.

Affinché l’integrazione funzioni, l’indirizzo della pagina di pagamento deve iniziare con https:// anziché con http://. Puoi testare l’integrazione senza usare HTTPS, ma ricorda di abilitarlo quando sarà tutto pronto per accettare i pagamenti in modalità live.

Configurare Stripe. js

Payment Element è automaticamente disponibile come funzione di Stripe.js. Includi lo script Stripe.js nella tua pagina di pagamento aggiungendolo all’oggetto head del tuo file HTML. Carica sempre Stripe.js direttamente da js.stripe.com per mantenere la conformità alle norme PCI. Non includere lo script in un pacchetto e non ospitarne una copia personale.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/clover/stripe.js"></script>
</head>

Crea un’istanza di Stripe con il seguente JavaScript nella pagina di pagamento:

checkout.js
// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

Aggiungi Payment Element alla pagina di pagamento

Il componente Payment Element deve avere uno spazio dedicato nella pagina di pagamento. Crea un nodo DOM (contenitore) vuoto con ID univoco nel modulo di pagamento:

checkout.html
<form id="payment-form">
  <div id="payment-element">
    <!-- Elements will create form elements here -->
  </div>
  <button id="submit">Submit</button>
  <div id="error-message">
    <!-- Display error message to your customers here -->
  </div>
</form>

Una volta caricato il modulo sopra menzionato, crea un’istanza di Elements con i parametri mode, amount e currency. Questi valori determinano i metodi di pagamento visualizzati dal cliente. Per specificare un nuovo metodo di pagamento nel tuo modulo, assicurati di abilitarlo nella Dashboard.

checkout.js
const options = {
  mode: 'payment',
  amount: 1000,
  currency: 'eur',
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in checkout form
const elements = stripe.elements(options);

// Create and mount the Payment Element
const paymentElementOptions = { layout: 'accordion'};
const paymentElement = elements.create('payment', paymentElementOptions);
paymentElement.mount('#payment-element');

Puoi personalizzare il componente Payment Element perché si accordi al design del tuo sito specificando l’oggetto appearance in options al momento della creazione del provider Elements.

Raccogli indirizzi

By default, the Payment Element only collects the necessary billing address details. Some behavior, such as calculating tax or entering shipping details, requires your customer’s full address. You can:

Use the Address Element to take advantage of autocomplete and localization features to collect your customer’s full address. This helps ensure the most accurate tax calculation.
Collect address details using your own custom form.

Creare un PaymentIntent
Lato server

Eseguire la logica aziendale personalizzata immediatamente prima della conferma del pagamento

Vai alla fase 5 della guida ai pagamenti per eseguire la tua logica aziendale personalizzata immediatamente prima della conferma del pagamento. Altrimenti, segui i passaggi riportati di seguito per un’integrazione più semplice, che utilizza stripe.confirmPayment sul client per confermare il pagamento e gestire eventuali azioni successive.

Quando il cliente invia il modulo di pagamento, utilizza un PaymentIntent per facilitare il processo di conferma e pagamento. Crea sul tuo server un PaymentIntent con i parametri amount e currency abilitati. Decidi sempre quanto addebitare sul lato server, che è un ambiente sicuro, anziché sul lato client. In questo modo impedisci ai client malintenzionati di scegliere un proprio prezzo.

Il PaymentIntent include una chiave privata client. Restituisci questo valore al tuo client affinché Stripe.js lo utilizzi per completare la procedura di pagamento in modo sicuro.

Inviare il pagamento a Stripe
Lato client

Utilizza stripe.confirmPayment per completare il pagamento utilizzando i dettagli di Payment Element.

Fornisci un return_url a questa funzione per indicare dove Stripe deve reindirizzare l’utente dopo il completamento del pagamento. L’utente può essere dapprima reindirizzato su un sito intermedio, come una pagina di autorizzazione della banca, prima di essere reindirizzato al return_url. In caso di esito positivo, i pagamenti con carta vengono immediatamente reindirizzati al return_url.

Se vuoi impedire il reindirizzamento per i pagamenti con carta una volta completato il pagamento, puoi impostare il reindirizzamento su if_required. In questo modo vengono reindirizzati solo i clienti che utilizzano metodi di pagamento basati sul reindirizzamento.

checkout.js
const form = document.getElementById('payment-form');
const submitBtn = document.getElementById('submit');

const handleError = (error) => {
  const messageContainer = document.querySelector('#error-message');
  messageContainer.textContent = error.message;
  submitBtn.disabled = false;
}

form.addEventListener('submit', async (event) => {
  // We don't want to let default form submission happen here,
  // which would refresh the page.
  event.preventDefault();

  // Prevent multiple form submissions
  if (submitBtn.disabled) {
    return;
  }

  // Disable form submission while loading
  submitBtn.disabled = true;

  // Trigger form validation and wallet collection
  const {error: submitError} = await elements.submit();
  if (submitError) {
    handleError(submitError);
    return;
  }

  // Create the PaymentIntent and obtain clientSecret
  const res = await fetch("/create-intent", {
    method: "POST",
  });

  const {client_secret: clientSecret} = await res.json();

  // Confirm the PaymentIntent using the details collected by the Payment Element
  const {error} = await stripe.confirmPayment({
    elements,
    clientSecret,
    confirmParams: {
      return_url: 'https://example.com/order/123/complete',
    },
  });

  if (error) {
    // This point is only reached if there's an immediate error when
    // confirming the payment. Show the error to your customer (for example, payment details incomplete)
    handleError(error);
  } else {
    // Your customer is redirected to your `return_url`. For some payment
    // methods like iDEAL, your customer is redirected to an intermediate
    // site first to authorize the payment, then redirected to the `return_url`.
  }
});

FacoltativoGestire gli eventi successivi al pagamento

Stripe invia un evento payment_intent.succeeded quando il pagamento viene completato. Utilizza la Dashboard, un webhook personalizzato o una soluzione partner per ricevere questi eventi ed eseguire azioni come l’invio della conferma di un ordine al cliente, la registrazione della vendita in un database o l’avvio del flusso di lavoro per una spedizione.

Ascolta questi eventi invece di attendere un callback dal client. Sul client, il cliente potrebbe chiudere la finestra del browser o uscire dall’app prima dell’esecuzione del callback e i client malintenzionati potrebbero manipolare la risposta. La configurazione dell’integrazione per l’ascolto di eventi asincroni ti consente anche di accettare metodi di pagamento diversi in futuro. Ulteriori informazioni sulle differenze tra tutti i metodi di pagamento supportati.

Gestisci gli eventi manualmente nella dashboard
Utilizza la dashboard per visualizzare i pagamenti di test nella dashboard, inviare le ricevute tramite email, gestire i bonifici o ritentare i pagamenti non riusciti.
Crea un webhook personalizzato
Crea un gestore webhook personalizzato per rilevare gli eventi e creare flussi di pagamento asincroni personalizzati. Esegui il test e il debug in locale dell’integrazione webhook con la CLI di Stripe.
Integra un’app preimpostata
Gestisci eventi comuni dell’attività, come l’automazione, il marketing e i saldi, integrando una richiesta di registrazione del partner.

FacoltativoSeparare l'autorizzazione dall'acquisizione

Puoi separare l’autorizzazione dall’acquisizione per creare un addebito immediatamente, ma acquisire i fondi in un secondo momento. Stripe annulla il PaymentIntent e invia un evento payment_intent.canceled se il pagamento non viene acquisito durante la finestra di 7 giorni.

Se sei sicuro di non poter acquisire il pagamento, ti consigliamo di annullare il PaymentIntent anziché attendere che trascorrano i 7 giorni.

Indicare a Stripe di eseguire solo l’autorizzazione

Per indicare che vuoi separare l’autorizzazione dall’acquisizione, imposta capture_method su manual quando crei il PaymentIntent. Il parametro indica a Stripe di limitarsi ad autorizzare l’importo sul conto Satispay del cliente.

Acquisire i fondi

Dopo l’avvenuta autorizzazione, lo stato del PaymentIntent diventa requires_capture. Per acquisire i fondi autorizzati, crea una richiesta di acquisizione del PaymentIntent.

Stripe acquisisce l’importo totale autorizzato per impostazione predefinita. Puoi anche specificare che amount_to_capture sia minore o uguale al totale.

Opzionale Cancel the authorization

Per annullare un’autorizzazione, puoi annullare il PaymentIntent.

Testare l'integrazione

Per testare la tua integrazione, scegli il metodo di pagamento e tocca Paga. In una sandbox, verrai reindirizzato a una pagina di pagamento di test dove potrai approvare o rifiutare il pagamento.

In modalità live, toccando Paga verrai reindirizzato al sito web di Satispay, senza potere approvare o rifiutare il pagamento con Satispay.

Codici di errore

La tabella seguente illustra in dettaglio i codici di errore comuni e le azioni consigliate:

Codice di errore	Azione consigliata
`payment_intent_invalid_currency`	Inserisci una valuta supportata.
`missing_required_parameter`	Controlla il messaggio di errore per sapere di più sul parametro richiesto.
`payment_intent_payment_attempt_failed`	Questo codice può essere visualizzato nel campo last_payment_error.code di un PaymentIntent. Consulta il messaggio di errore per informazioni dettagliate sul motivo dell’errore e suggerimenti su come gestirlo.
`payment_intent_authentication_failure`	Questo codice può apparire nella sezione last_payment_error.code campo di un PaymentIntent. Controlla se il messaggio di errore ha un motivo dettagliato dell’errore e suggerimenti sulla gestione degli errori. Questo errore si verifica quando si attiva manualmente un errore durante il test dell’integrazione.
`payment_intent_redirect_confirmation_without_return_url`	Specifica un `return_url` quando confermi un PaymentIntent.