Accettare un pagamento

Innanzitutto, devi creare un account Stripe. Registrati ora.

Lato server

Per questa integrazione sono necessari endpoint sul server che comunicano con l’API Stripe. Utilizza le nostre librerie ufficiali per accedere all’API Stripe dal tuo server:

# Available as a gem
sudo gem install stripe

# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Lato client

L’SDK React Native è open source e completamente documentato. Internamente, utilizza SDK iOS nativi e Android. Per installare l’SDK React Native di Stripe, esegui uno dei seguenti comandi nella directory del progetto (a seconda del gestore di pacchetti utilizzato):

yarn add @stripe/stripe-react-native

Poi, installa alcune altre dipendenze necessarie:

• Per iOS, vai alla directory ios ed esegui pod install per garantire che vengano installate anche le dipendenze native necessarie.
• Per Android, non ci sono più dipendenze da installare.

Inizializzazione di Stripe

Per inizializzare Stripe nell’app React Native, esegui il wrapping della schermata di pagamento con il componente StripeProvider oppure utilizza il metodo di inizializzazione initStripe. È richiesta solo la chiave pubblicabile dell’API in publishableKey. L’esempio seguente spiega come inizializzare Stripe utilizzando il componente StripeProvider.

import { useState, useEffect } from 'react';
import { StripeProvider } from '@stripe/stripe-react-native';

function App() {
  const [publishableKey, setPublishableKey] = useState('');

  const fetchPublishableKey = async () => {
    const key = await fetchKey(); // fetch key from your server here
    setPublishableKey(key);
  };

  useEffect(() => {
    fetchPublishableKey();
  }, []);

  return (
    <StripeProvider
      publishableKey={publishableKey}
      merchantIdentifier="merchant.identifier" // required for Apple Pay
      urlScheme="your-url-scheme" // required for 3D Secure and bank redirects
    >
      {/* Your app code here */}
    </StripeProvider>
  );
}

Visualizza le impostazioni delle modalità di pagamento e abilita le modalità di pagamento che vuoi accettare. Per creare un PaymentIntent è necessario che sia abilitata almeno una modalità di pagamento.

Per impostazione predefinita, Stripe abilita le carte e altri metodi di pagamento tra i più utilizzati per aiutarti a raggiungere più clienti. Detto ciò, ti consigliamo di attivare ulteriori metodi pertinenti per la tua attività e i tuoi clienti. Per ulteriori informazioni sul supporto di prodotti e metodi di pagamento, consulta la sezione Supporto per il metodo di pagamento. Per le commissioni consulta la nostra pagina delle tariffe.

Questa integrazione utilizza tre oggetti dell’API Stripe:

1. PaymentIntent: Stripe lo utilizza per rappresentare la tua intenzione di riscuotere un pagamento da un cliente, monitorando i tentativi di addebito e le modifiche dello stato del pagamento durante la procedura.

2. (Optional) Customer: per configurare un metodo di pagamento per pagamenti futuri, devi associarlo a un oggetto Customer. Crea un oggetto Customer quando il cliente crea un account con la tua attività. Se il cliente effettua il pagamento come ospite, puoi creare un oggetto Customer prima del pagamento e associarlo successivamente alla tua rappresentazione interna dell’account del cliente.

3. (Facoltativo) Chiave temporanea per l’oggetto Customer (facoltativa): l’oggetto Customer contiene informazioni sensibili che non possono essere recuperate direttamente da un’app. Una chiave temporanea consente all’SDK di accedere temporaneamente all’oggetto Customer.

Per motivi di sicurezza, la tua app non può creare questi oggetti. Aggiungi invece un endpoint sul tuo server per:

1. Recuperare l’oggetto Customer o ne crea uno nuovo.
2. Creare una chiave temporanea per l’oggetto Customer.
3. Crea un PaymentIntent con i parametri importo, valuta e cliente. Inoltre, se lo ritieni opportuno, puoi includere il parametro automatic_payment_methods. Stripe abilita la funzionalità per impostazione predefinita nell’ultima versione dell’API.
4. Restituisce la chiave privata client del Payment Intent, la stringa secret della chiave temporanea, l’id del cliente e la tua chiave pubblicabile alla tua app.

I metodi di pagamento mostrati ai clienti durante il completamento della transazione sono inclusi anche nel PaymentIntent. Puoi consentire a Stripe di acquisire i metodi di pagamento dalle impostazioni della Dashboard oppure puoi elencarli manualmente. Indipendentemente dall’opzione che sceglierai, ricorda che la valuta specificata nel PaymentIntent filtra il metodo di pagamento mostrato al cliente. Ad esempio, se specifichi eur nel PaymentIntent e hai abilitato OXXO nella Dashboard, il cliente non vedrà OXXO perché questo metodo non supporta i pagamenti in eur.

A meno che la tua integrazione non richieda un’opzione con codice per offrire i metodi di pagamento, Stripe consiglia l’opzione automatica. Ciò è dovuto al fatto che Stripe valuta le limitazioni dei metodi di pagamento, la valuta e altri parametri per determinare l’elenco dei metodi di pagamento accettati. I metodi di pagamento che migliorano la conversione e che sono più pertinenti alla valuta e alla posizione del cliente hanno la priorità.

# Create a Customer (use an existing Customer ID if this is a returning customer)
curl https://api.stripe.com/v1/customers \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -X "POST"

# Create an Ephemeral Key for the Customer
curl https://api.stripe.com/v1/ephemeral_keys \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -H "Stripe-Version: 2025-06-30.basil" \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \

# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="eur" \
  # In the latest version of the API, specifying the `automatic_payment_methods` parameter
  # is optional because Stripe enables its functionality by default.
  -d "automatic_payment_methods[enabled]"=true \

Prima di visualizzare Payment Element per dispositivi mobili, la tua pagina di pagamento dovrebbe:

• Mostrare i prodotti acquistati e l’importo totale
• Acquisire le eventuali informazioni richieste per la spedizione
• Includere un pulsante di pagamento per aprire l’interfaccia utente di Stripe

Nella procedura di pagamento della tua app, invia una richiesta di rete all’endpoint di back-end che hai creato nella fase precedente e chiama initPaymentSheet dall’hook useStripe.

export default function CheckoutScreen() {
  const { initPaymentSheet, presentPaymentSheet } = useStripe();
  const [loading, setLoading] = useState(false);

  const fetchPaymentSheetParams = async () => {
    const response = await fetch(`${API_URL}/payment-sheet`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
    });
    const { paymentIntent, ephemeralKey, customer } = await response.json();

    return {
      paymentIntent,
      ephemeralKey,
      customer,
    };
  };

  const initializePaymentSheet = async () => {
    const {
      paymentIntent,
      ephemeralKey,
      customer,
    } = await fetchPaymentSheetParams();

    const { error } = await initPaymentSheet({
      merchantDisplayName: "Example, Inc.",
      customerId: customer,
      customerEphemeralKeySecret: ephemeralKey,
      paymentIntentClientSecret: paymentIntent,
      // Set `allowsDelayedPaymentMethods` to true if your business can handle payment
      //methods that complete payment after a delay, like SEPA Debit and Sofort.
      allowsDelayedPaymentMethods: true,
      defaultBillingDetails: {
        name: 'Jane Doe',
      }
    });
    if (!error) {
      setLoading(true);
    }
  };

  const openPaymentSheet = async () => {
    // see below
  };

  useEffect(() => {
    initializePaymentSheet();
  }, []);

  return (
    <Screen>
      <Button
        variant="primary"
        disabled={!loading}
        title="Checkout"
        onPress={openPaymentSheet}
      />
    </Screen>
  );
}

Quando il cliente tocca il pulsante Checkout, chiama presentPaymentSheet() per aprire la scheda. Quando il cliente completa il pagamento, la scheda si chiude e la promessa si risolve con uno StripeError<PaymentSheetError> opzionale.

export default function CheckoutScreen() {
  // continued from above

  const openPaymentSheet = async () => {
    const { error } = await presentPaymentSheet();

    if (error) {
      Alert.alert(`Error code: ${error.code}`, error.message);
    } else {
      Alert.alert('Success', 'Your order is confirmed!');
    }
  };

  return (
    <Screen>
      <Button
        variant="primary"
        disabled={!loading}
        title="Checkout"
        onPress={openPaymentSheet}
      />
    </Screen>
  );
}

Se non si verificano errori, comunica all’utente che la procedura è terminata (ad esempio, visualizzando una schermata di conferma d’ordine).

Impostare allowsDelayedPaymentMethods su true consente di utilizzare i metodi di pagamento con notifica differita come i conti bancari degli Stati Uniti. Per questi metodi di pagamento, lo stato finale del pagamento non è noto al completamento di PaymentSheet, in quanto va a buon fine o meno in un secondo momento. Se supporti questi tipi di metodi di pagamento, informa il cliente che il suo ordine è confermato e procedi all’evasione (ad esempio alla spedizione del prodotto), spedisci il suo prodotto) solo quando avrai ricevuto il pagamento.

Quando un cliente esce dalla tua app (ad esempio, per autenticarsi in Safari o nell’app della sua banca), offri un modo per tornare automaticamente alla tua app. Molti metodi di pagamento require un URL di reindirizzamento. Se non ne fornisci uno, non possiamo mostrare agli utenti i metodi di pagamento che richiedono un URL di reindirizzamento, anche se li hai abilitati.

Per fornire un URL di ritorno:

1. Registra un URL personalizzato. I link universali non sono supportati.
2. Configura il tuo URL personalizzato.
3. Configura il tuo componente principale per inoltrare l’URL all’SDK di Stripe come mostrato di seguito.

import { useEffect, useCallback } from 'react';
import { Linking } from 'react-native';
import { useStripe } from '@stripe/stripe-react-native';

export default function MyApp() {
  const { handleURLCallback } = useStripe();

  const handleDeepLink = useCallback(
    async (url: string | null) => {
      if (url) {
        const stripeHandled = await handleURLCallback(url);
        if (stripeHandled) {
          // This was a Stripe URL - you can return or add extra handling here as you see fit
        } else {
          // This was NOT a Stripe URL – handle as you normally would
        }
      }
    },
    [handleURLCallback]
  );

  useEffect(() => {
    const getUrlAsync = async () => {
      const initialUrl = await Linking.getInitialURL();
      handleDeepLink(initialUrl);
    };

    getUrlAsync();

    const deepLinkListener = Linking.addEventListener(
      'url',
      (event: { url: string }) => {
        handleDeepLink(event.url);
      }
    );

    return () => deepLinkListener.remove();
  }, [handleDeepLink]);

  return (
    <View>
      <AwesomeAppComponent />
    </View>
  );
}

In più, imposta il returnURL quando chiami la modalità initPaymentSheet:

await initPaymentSheet({
  ...
  returnURL: 'your-app://stripe-redirect',
  ...
});

Per ulteriori informazioni sugli schemi di URL nativi, consulta la documentazione relativa ad Android e a iOS.

Stripe invia un evento payment_intent.succeeded quando il pagamento viene completato. Utilizza lo strumento webhook Dashboard o segui la guida ai webhook per ricevere questi eventi ed eseguire azioni come l’invio di una email per la 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 una chiamata di ritorno dal client. Sul client, il cliente potrebbe chiudere la finestra del browser o uscire dall’app prima dell’esecuzione della chiamata di ritorno e i client malintenzionati potrebbero manipolare la risposta. La configurazione dell’integrazione per l’ascolto di eventi asincroni ti consente di accettare diversi tipi di modalità di pagamento con una sola integrazione.

Oltre alla gestione dell’evento payment_intent.succeeded, è consigliabile gestire altri eventi durante la riscossione di pagamenti tramite Payment Element:

Per ulteriori informazioni su come testare la tua integrazione, consulta la sezione Test.