API per sviluppatori

Integra e personalizza

Avvia Payment for Stripe dalla tua app o dal tuo sito web con gli schemi URL e scegli quali prodotti compaiono nell'app direttamente dalla Dashboard di Stripe.

Integrazione con schemi URL

Avvia addebiti dalla tua app o dal tuo sito web, passa i dati dei clienti e gestisci i callback.

Nascondi i prodotti con i metadati

Tieni i prodotti solo online fuori dall'app con una singola chiave di metadati.

Integrazione con schemi URL

Come funziona

La tua app apre un payment:// URL con parametri

Payment for Stripe avvia ed elabora la transazione

Al termine, l'app reindirizza all'URL di callback con il risultato

Endpoint

Crea un addebito

payment://new?

Elabora un pagamento una tantum con importo, valuta e descrizione.

Parametri

Nome	Tipo	Obbligatorio	Descrizione
`amount`	integer	Sì	Importo in centesimi (ad esempio, 1000 = $10,00)
`currency`	string	No	Codice valuta ISO di tre lettere (predefinito: la valuta corrente dell'app)
`description`	string	No	Descrizione dell'addebito codificata in URL
`customer`Alias: `customer_id`	string	No	ID cliente Stripe esistente
`email`	string	No	E-mail del cliente per la ricevuta
`name`	string	No	Nome del cliente codificato in URL
`metadata`	string	No	Coppie chiave-valore personalizzate (JSON codificato in URL)
`callback`	string	No	URL a cui tornare dopo il completamento
`autoprocess`Alias: `auto`	boolean	No	Salta la schermata iniziale e avvia subito l'addebito
`auto_return`	boolean	No	Esegui la funzione di callback al caricamento dei risultati anziché attendere che il commerciante chiuda la finestra di dialogo dei risultati. Valore predefinito: false.

Vendi articoli dal tuo catalogo

payment://cart?

Inserisci nel carrello i prezzi dal tuo catalogo Stripe per il pagamento di persona. La vendita viene salvata come fattura Stripe pagata. Nulla viene inviato al cliente.

Parametri

Nome	Tipo	Obbligatorio	Descrizione
`prices`Alias: `line_items`	string	Sì	ID dei prezzi separati da virgole con quantità (ad esempio, price_abc:2,price_xyz:1)
`coupon`	string	No	Codice sconto Stripe da applicare al carrello
`customer`Alias: `customer_id`	string	No	ID cliente Stripe esistente
`email`	string	No	E-mail del cliente per la ricevuta
`name`	string	No	Nome del cliente codificato in URL
`metadata`	string	No	Coppie chiave-valore personalizzate (JSON codificato in URL)
`callback`	string	No	URL a cui tornare dopo il completamento
`autoprocess`Alias: `auto`	boolean	No	Salta la schermata iniziale e avvia subito l'addebito
`auto_return`	boolean	No	Esegui la funzione di callback al caricamento dei risultati anziché attendere che il commerciante chiuda la finestra di dialogo dei risultati. Valore predefinito: false.

Paga una fattura esistente

payment://invoice?

Riscuoti un pagamento di persona a fronte di una fattura Stripe esistente. Importo, valuta, cliente e imposta provengono dalla fattura. Qualsiasi modifica a questi dati viene rifiutata. Il commerciante effettua il pagamento con carta tramite lettore / Tap to Pay / inserimento manuale; in caso di successo, la fattura viene contrassegnata come pagata fuori banda e collegata tramite i metadati charge_id e payment_intent_id. Le fatture con abbonamenti, default_payment_method o con stato pagato, annullato o non esigibile vengono rifiutate con un errore gestibile. Fatture in bozza: iOS le finalizza per prime, Android le rifiuta con invoice_state_changed.

Parametri

Nome	Tipo	Obbligatorio	Descrizione
`id`	string	Sì	ID fattura Stripe (deve iniziare con in_)
`callback`	string	No	URL a cui tornare al termine dell'operazione. Riceve invoice_id e payment_intent_id in caso di successo.
`metadata`	string	No	Coppie chiave-valore personalizzate (JSON codificato in URL) unite ai metadati di PaymentIntent
`autoprocess`Alias: `auto`	boolean	No	Salta la schermata iniziale e avvia subito l'addebito.
`auto_return`	boolean	No	Esegui la funzione di callback al caricamento dei risultati anziché attendere che il commerciante chiuda la finestra di dialogo dei risultati. Valore predefinito: false.

Gestione dei callback

Al termine della transazione, Payment for Stripe reindirizza all'URL di callback specificato, con parametri di query che indicano il risultato. Per impostazione predefinita, il reindirizzamento si attiva dopo che il commerciante ha chiuso la finestra di dialogo con il risultato, consentendogli di intraprendere azioni successive all'addebito (invio di una ricevuta via e-mail, rimborso). Impostando `auto_return=true`, il reindirizzamento si attiverà non appena il risultato sarà noto. Supportato su iOS e Android.

Parametri di callback

Parametro	Valori	Descrizione
`status`	success \| error \| cancelled	Risultato della transazione
`charge_id`	string	ID di addebito Stripe (in caso di successo). iOS invia l'ID di addebito (ch_). Android invia l'ID PaymentIntent (pi_) e inserisce l'ID di addebito in stripe_charge_id.
`stripe_charge_id`	string	ID di addebito Stripe (ch_) in caso di successo. Solo per Android.
`invoice_id`	string	ID fattura Stripe (solo in caso di successo, flusso payment://invoice)
`payment_intent_id`	string	ID di pagamento Stripe PaymentIntent (in caso di successo). iOS: solo flusso payment://invoice. Android: per ogni transazione con carta.
`error`	string	Messaggio di errore (in caso di errore)

Addebito registrato ma la fattura non è stata contrassegnata come pagata: iOS restituisce status=error con charge_id, invoice_id e payment_intent_id. Android restituisce status=success con invoice_reconciliation_failed=true.

Campi legacy, mantenuti per le integrazioni precedenti: success, amount, currency, chargeId, cancelled, error[message]. Le nuove integrazioni dovrebbero leggere i campi sopra indicati.

Esempi

Addebito semplice

Addebita $10,00 con un solo importo

payment://new?amount=1000

Addebito con descrizione

Addebita € 25,00 con descrizione

payment://new?amount=2500&currency=eur&description=Coffee%20and%20pastry

Addebito con nuovo cliente

Addebita $50,00 e crea un record cliente

payment://new?amount=5000&name=John%20Smith&[email protected]

Addebito a un cliente esistente

Addebita $75,00 a un cliente Stripe esistente

payment://new?amount=7500&customer=cus_ABC123xyz

Addebito con metadati

Addebita $100,00 con metadati personalizzati per i tuoi record

payment://new?amount=10000&description=Invoice%20%231234&metadata=%7B%22order_id%22%3A%221234%22%2C%22location%22%3A%22Store%20A%22%7D

Elaborazione automatica con callback

Salta la schermata iniziale e torna all'app quando hai finito

payment://new?amount=3500&autoprocess=true&callback=myapp://payment-complete

Ritorno automatico all'esito

Attiva la funzione di callback non appena il risultato è noto, invece di attendere che il commerciante chiuda la finestra di dialogo del risultato.

payment://new?amount=3500&autoprocess=true&auto_return=true&callback=myapp://payment-complete

Carrello con articoli

Addebita i prodotti dal tuo catalogo Stripe

payment://cart?prices=price_coffee:2,price_muffin:1&[email protected]

Paga una fattura esistente

Raccoglie il pagamento di persona per una fattura Stripe esistente. Restituisce invoice_id e payment_intent_id in caso di successo.

payment://invoice?id=in_1ABC123xyz&autoprocess=true&callback=myapp://invoice-paid

Esempio completo

Tutti i parametri combinati per un flusso completamente integrato

payment://new?amount=15000&currency=usd&description=Service%20Fee&customer=cus_ABC123xyz&metadata=%7B%22invoice%22%3A%22INV-2024-001%22%7D&autoprocess=true&callback=myapp://payment-result

Codifica URL

Ricordati di codificare nell'URL i caratteri speciali dei valori dei parametri. Gli spazi diventano %20, le parentesi graffe diventano %7B e %7D.

Nascondi i prodotti con i metadati

Nascondere prodotti dall'app

L'app elenca i prodotti e i prezzi del tuo account Stripe. Per tenerne uno fuori dall'app (ad esempio articoli venduti solo tramite il tuo negozio online), aggiungi questa chiave di metadati al prodotto o al prezzo nella Dashboard di Stripe:

payment_hidden = true

Su un prodotto: nasconde il prodotto e tutti i suoi prezzi.

Su un prezzo: nasconde solo quel prezzo.

Rimuovi la chiave, o impostala su false, per mostrarlo di nuovo. Le modifiche si applicano al successivo caricamento dell'elenco prodotti nell'app.

I link del carrello continuano a funzionare

Nascondere influisce solo sull'elenco prodotti nell'app. Gli URL payment://cart che fanno riferimento a un prezzo nascosto continuano a funzionare e gli abbonamenti esistenti non sono interessati.

Pronto per l'integrazione?

Scarica l'app e inizia subito a testare la tua integrazione.

Scarica per iOS Scarica per Android

Contatta l'assistenza