In breve: la tua app o il tuo sito web apre un URL payment://, Payment for Stripe preleva il pagamento e poi apre il tuo URL di callback con il risultato. Nessun SDK. Nessun lavoro lato server. Funziona allo stesso modo su iPhone e Android, con alcune differenze indicate di seguito.
Il riferimento completo è disponibile all'indirizzo paymentforstripe.com/api.
Come funziona
- La tua app apre un
payment://con parametri. - Payment for Stripe apre e configura la vendita. Il commerciante riceve il pagamento tramite un lettore, Tap to Pay o carta prepagata.
- Al termine dell'operazione, l'app apre l'URL
callbackcon il risultato aggiunto come parametro di query.
Il commerciante deve aver effettuato l'accesso. Se arriva un link mentre è in corso un altro pagamento, l'app lo rifiuta e la tua callback riceve error=charge_in_progress.
Crea un addebito: payment://new
Un pagamento una tantum di un importo da te stabilito.
| Nome | Tipo | Necessario | Descrizione |
|---|---|---|---|
amount
|
intero | SÌ | Importo nell'unità più piccola della valuta, maggiore di 1000 = $10,00. |
currency
|
corda | NO | Codice ISO di tre lettere, come usd o eur. Se lo si omette, l'app utilizzerà la valuta già impostata. |
description
|
corda | NO | Descrizione dell'addebito. Codificala in URL. |
customer
|
corda | NO | ID cliente Stripe esistente ( cus_…). Anche customer_id funziona. Quando impostato, email e name vengono ignorati. |
email
|
corda | NO | Indirizzo email del cliente. Crea un nuovo cliente. |
name
|
corda | NO | Nome del cliente. Codificalo in URL. Crea un nuovo cliente. |
metadata
|
corda | NO | Oggetto JSON codificato in URL contenente coppie chiave-valore, aggiunto al pagamento. Si applicano i limiti di metadati di Stripe. |
callback
|
corda | NO | URL da aprire al termine della vendita. |
autoprocess
|
booleano | NO | true si salta la tastiera e la ricarica inizia immediatamente. Valore predefinito: false. |
auto_return
|
booleano | NO | true la funzione di callback viene attivata non appena il risultato è noto. Il valore predefinito false: la funzione di callback attende che il commerciante chiuda la schermata dei risultati. |
payment://new?amount=2500¤cy=eur&description=Coffee%20and%20pastry payment://new?amount=3500&autoprocess=true&auto_return=true&callback=myapp://payment-complete Un collegamento con un amount mancante, pari a zero o non numerico viene ignorato.
Crea una fattura dal tuo catalogo: payment://cart
Il carrello viene riempito con i prezzi del catalogo prodotti Stripe. Il venditore effettua quindi l'addebito come di consueto e la vendita viene salvata in Stripe come fattura pagata con i relativi articoli. Non viene inviata alcuna fattura via e-mail al cliente.
| Nome | Tipo | Necessario | Descrizione |
|---|---|---|---|
prices
|
corda | SÌ | Coppie price_id:quantity separate da virgole, come price_abc:2,price_xyz:1. Anche line_items funziona. |
coupon
|
corda | NO | Codice sconto Stripe da applicare al carrello. |
customer
|
corda | NO | ID cliente Stripe esistente. Anche customer_id funziona. |
email
|
corda | NO | Indirizzo email del cliente. Crea un nuovo cliente. |
name
|
corda | NO | Nome del cliente. Codificalo in URL. |
metadata
|
corda | NO | Oggetto JSON codificato in URL contenente coppie chiave-valore. |
callback
|
corda | NO | URL da aprire al termine della vendita. |
autoprocess
|
booleano | NO | Il pagamento inizia true una volta che tutti i prezzi (e i coupon) sono stati caricati. |
auto_return
|
booleano | NO | Come sopra. Valore predefinito: false. |
payment://cart?prices=price_coffee:2,price_muffin:1&email=customer@example.com Non inviare amount insieme ai prices. Il totale viene calcolato a partire dai prezzi e un link che li contenga entrambi verrà ignorato. I prezzi nascosti con l' opzione payment_hidden funzionano comunque.
Paga una fattura esistente: pagamento://fattura
Consente di riscuotere un pagamento di persona per una fattura Stripe aperta. L'importo, la valuta, il cliente e le tasse vengono ricavati direttamente dalla fattura. In caso di esito positivo, l'app contrassegna la fattura come pagata. Compatibile con iPhone e Android.
| Nome | Tipo | Necessario | Descrizione |
|---|---|---|---|
id
|
corda | SÌ | ID fattura Stripe. Deve iniziare con in_. Invia una fattura aperta. Su iPhone, viene prima finalizzata una bozza. Su Android, una bozza viene rifiutata con error=invoice_state_changed. |
metadata
|
corda | NO | Oggetto JSON codificato in URL, aggiunto al PaymentIntent. |
callback
|
corda | NO | URL da aprire al termine della vendita. Recupera invoice_id e payment_intent_id in caso di successo. |
autoprocess
|
booleano | NO | L'addebito true inizia solo dopo che i controlli della fattura sono andati a buon fine e solo quando è collegato un lettore di carte. |
auto_return
|
booleano | NO | Come sopra. Valore predefinito: false. |
payment://invoice?id=in_1ABC123xyz&autoprocess=true&callback=myapp://invoice-paid La fattura definisce la vendita, quindi qualsiasi amount, currency, customer, customer_id, email, name, description, coupon, prices o line_items viene rifiutato con l' error=invoice_invalid_param. Anche le fatture pagate, annullate, non esigibili, di importo pari a $0, collegate a un abbonamento o impostate per addebitare un metodo di pagamento predefinito vengono rifiutate, ognuna con il proprio errore invoice_… `.
La richiamata
L'app aggiunge questi elementi al tuo URL di callback:
| Nome | Tipo | Inviato | Descrizione |
|---|---|---|---|
status
|
corda | Sempre | success, error o cancelled. |
charge_id
|
corda | Sul successo | L'ID del pagamento. Su iPhone è l'addebito Stripe ( ch_…). Su Android è il PaymentIntent ( pi_…). |
stripe_charge_id
|
corda | Solo Android | La tariffa Stripe ( ch_…). |
payment_intent_id
|
corda | Sul successo | L'oggetto PaymentIntent. iPhone lo invia solo per payment://invoice. Android lo invia per ogni pagamento con carta. |
invoice_id
|
corda | Link alle fatture | La fattura pagata, per payment://invoice. |
amount
|
intero | Sul successo | Importo addebitato, nell'unità più piccola. |
currency
|
corda | Sul successo | Codice ISO in minuscolo. |
error
|
corda | In caso di errore | Un codice breve come charge_in_progress o invoice_already_paid, oppure un messaggio leggibile per una carta rifiutata. |
myapp://payment-complete?status=success&charge_id=ch_3Qx…&success=true&amount=3500¤cy=usd&chargeId=ch_3Qx… Hai bisogno dello stesso ID su entrambe le piattaforme? Leggi prima stripe_charge_id, poi usa charge_id come fallback.
Per le integrazioni precedenti, l'app invia anche success=true, chargeId, cancelled=true e error[message]. Il nuovo codice dovrebbe leggere status.
Un annullamento apre immediatamente la callback. Il successo o l'errore di un addebito attende che il commerciante chiuda la schermata dei risultati, a meno che non si passi auto_return=true. Su iPhone, una vendita in contanti non apre mai la callback, poiché non è stato addebitato nulla.
Codifica URL
- Codifica ogni valore che contiene spazi o simboli. Gli spazi diventano
%20,{e}diventano%7Be%7D,"diventa%22,:diventa%3A. - Se l'URL di callback ha una propria stringa di query, codifica l'intero callback in modo che il simbolo
&non divida il linkpayment://. - Le virgole e i due punti nei
pricespossono rimanere come sono.
I metadati {"order_id":"1234","location":"Store A"} diventano:
payment://new?amount=10000&description=Invoice%20%231234&metadata=%7B%22order_id%22%3A%221234%22%2C%22location%22%3A%22Store%20A%22%7D Anche il vecchio formato metadata[order_id]=1234 funziona.