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 varie modalità 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/v3/"></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

Per impostazione predefinita, Payment Element raccoglie solo i dettagli relativi all’indirizzo di fatturazione necessari. Per acquisire l’indirizzo di fatturazione completo di un cliente (ad esempio, per calcolare l’imposta su beni e servizi digitali) o l’indirizzo di spedizione, utilizza Address Element.

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

FacoltativoSeparare l'autorizzazione dall'acquisizione

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_redirect_confirmation_without_return_url`	Specifica un `return_url` quando confermi un PaymentIntent.