API di piattaforma > JamioPlug > JamioPlug StripeConnect > Invoice

Imposta e riscuote un pagamento da parte di una customerReference verso un recipentReference.

Metodo

Input
Nome	Descrizione	Tipo	Opzionale
serverAddress	Indirizzo server da un Dominio esterno (per il Dominio della sessione corrente, utilizzare nullo o vuoto).	String	Y
token	Token di sessione (per la sessione corrente nel dominio corrente potrebbe essere null o vuoto).	String	Y
customerReference	Collegamento all'identità che effettua il pagamento.	Reference
recipientReference	Collegamento all'identità o elemento organizzativo che riceve i pagamenti.	Reference
invoiceItemData	Dato strutturato contenente i dati dell'InvoiceItem. L'elenco dei parametri che possono essere inseriti è consultabile qui. Tra questi è obbligatorio il parametro customer che viene ricavato in automatico dalla customerReference. E' necessario indicare anche il valore del parametro price o, in alternativa, amount e currency per specificare l'importo da addebitare.	Dataset
invoiceItemMetadata	Dato strutturato contenente i dati aggiuntivi utili a valorizzare i metadati dell'InvoiceItem. Non può contenere dati annidati o liste. Può contenere massimo 50 campi, con nomi di campo lunghi fino a 40 caratteri e valori di tipo stringa lunghi fino a 500 caratteri.	Dataset	Y
invoiceData	Dato strutturato contenente i dati dell'Invoice. L'elenco dei parametri che possono essere inseriti è consultabile qui. Tra questi sono obbligatori i parametri customer, default_payment_method e auto_advance. Il parametro customer è ricavato in automatico dalla customerReference. Il parametro default_payment_method è ricavato, in ordine di priorità, in automatico: •dal valore del paymentMethodReference; •dal valore del default_payment_method dato in input con il dato strutturato del parametro invoiceData. •dal valore del metodo di pagamento di default del Customer se non valorizzato o non specificato nel paymentMethodReference. Il parametro auto_advance è ricavato in automatico dal parametro autoAdvance. Nel caso i parametri customer, default_payment_method e auto_advance siano valorizzati sia in invoiceData che nei rispettivi parametri customerReference, paymentMethodReference e autoAdvance, essi vengono sostituiti con il valore specificato in customerReference, paymentMethodReference e autoAdvance.	Dataset	Y
invoiceMetadata	Dato strutturato contenente dati aggiuntivi utili a valorizzare i metadati dell'Invoice. Non può contenere dati annidati o liste. L'elenco dei parametri che possono essere inseriti è consultabile qui.	Dataset	Y
paymentMethodReference	Collegamento al PaymentMethod. Esso deve essere attivo per la recipientReference. Il parametro non è obbligatorio, in quanto può essere specificato nel parametro invoiceData, nel campo default_payment_method. Nel caso siano entrambi valorizzati, esso viene sostituito con il valore specificato in questo parametro.	Reference	Y
testMode	True se è richiesta l'esecuzione del metodo in modalità test di Stripe. Se non specificato, viene effettuata l'esecuzione del metodo in modalità live di Stripe. La modalità testMode indicata deve essere ammessa dalla configurazione.	Boolean	Y
autoAdvance	True se il pagamento dell'Invoice deve essere effettuato da Stripe in maniera asincrona rispetto alla chiamata al metodo; false se il pagamento deve essere realizzato in maniera sincrona rispetto alla chiamata al metodo. Se il parametro non viene specificato è pari a false. Il parametro non è obbligatorio, ma se non specificato viene impostato a valore false.	Boolean	Y
Output
Nome	Descrizione	Tipo
returnValue	Dato strutturato contenente le seguenti informazioni: •InvoiceItemId, stringa valorizzata con l'id dell'InvoiceItem creato dal metodo; •InvoiceId, stringa valorizzata con l'id dell'Invoice creata dal metodo; •InvoiceStatus, stringa che riporta lo stato raggiunto dalla Invoice creata dal metodo. Corrisponde alla proprietà status dell'Invoice. •Invoice, dato strutturato contenente le informazioni dell'Invoice creata dal metodo; Il metodo prevede diversi passaggi durante la sua esecuzione (vedi sezione Commenti), pertanto valorizza le suddette proprietà rispetto a quanto prodotto sino alle diverse condizioni di uscita previste.	Dataset

Commenti

Il Customer, cui fa riferimento il parametro customerReference, deve essere associato al Recipient, cui fa riferimento il parametro recipientReference, nella modalità test prevista.

Il metodo CreateFastInvoice è un'orchestrazione di diverse chiamante al servizio di pagamento Stripe, utili ad impostare e riscuotere un pagamento da parte di una CustomerReference verso un RecipentReference. Per FastInvoice si intende una Invoice in cui viene inserito un unico oggetto InvoiceItem. Nel dettaglio il metodo esegue i seguenti step:

1.Crea un InvoiceItem in Stripe(con i parametri invoiceItemData e invoiceItemMetadata). Per maggiori informazione sulla creazione di un InvoiceItem consultare la documentazione Stripe qui;

2.Crea una Invoice in Stripe(con i parametri invoiceMetadata e invoiceMetadata) in stato draft, in cui sarà inserito l'oggetto InvoiceItem generato al passo 1. Per maggiori informazioni sulla creazione di un Invoice consultare la documentazione Stripe qui;

3.Finalizza l'Invoice in Stripe creata al passo 2. Per maggiori informazioni sulla finalizzazione di un Invoice consultare la documentazione Stripe qui;

4.Esegue il pagamento dell'Invoice in Stripe finalizzata al passo 3. Per maggiori informazioni sul pagamento di un Invoice consultare la documentazione Stripe qui.

Per logiche del servizio di pagamento Stripe, può accadere che l'Invoice creata al passo 2, catturi degli InvoiceItem già presenti per quel Customer, creati precedentemente rispetto all'esecuzione del metodo. Inoltre per poter eseguire il pagamento automatico dell'Invoice, il metodo di pagamento specificato non deve richiedere ulteriori azioni da parte dell'utente interattivo per poter essere effettuato. Ad esempio i metodi di pagamento con autenticazione 3D Secure richiedono all'utente un livello aggiuntivo di autenticazione. Se tali metodi sono utilizzati nell'invocazione della CreateFastInvoice, non sarà eseguito il pagamento dell'Invoice fino a che l'utente interattivo non avrà effettuato l'autenticazione richiesta.

Il metodo CreateFastInvoice restituisce un dato strutturato contenente i valori ottenuti dai passaggi eseguiti durante la sua esecuzione, prevedendo più condizioni di uscita. Se uno dei passi successivi al primo step restituisce errore, il metodo non effettua rollback dei passaggi precedenti e restituisce un dato strutturato contenente i valori prodotti (vedi tabella per i dettagli). La condizione minimale di uscita senza restituire errore, è che sia stato costruito l'InvoiceItem. I punti di uscita del metodo CreateFastInvoice cambiano in funzione del parametro autoAdvance. Se autoAdvance è uguale a true i punti di uscita sono limitati a quanto previsto dai primi due step.

Si sconsiglia di specificare l'Id del Customer nel parametro di invoiceItemData e invoiceData, nel campo customer, poiché il metodo in automatico lo valorizza con l'Id ricavato dal collegamento specificato nel parametro customerReference. Nel caso siano valorizzati customer sia nel parametro di invoiceItemData e invoiceData, sia in customerReference, prevale il parametro customerReference.

Il metodo si comporta come segue:

Restituisce	Condizione
Dato strutturato con: •InvoiceItemId, valorizzato •InvoiceId, non valorizzato •InvoiceStatus, "none" •Invoice, non valorizzato	Se durante l'esecuzione del metodo CreateFastInvoice, Invoice non è stata creata in Stripe. Ad esempio se viene impostato il metodo di pagamento di default a valore stringa vuota. Il metodo CreateFastInvoice si ferma allo step 1, è necessario utilizzare il metodo CompleteFastInvoicePayment per completare i passi successivi.
Dato strutturato con: •InvoiceItemId, valorizzato •InvoiceId, valorizzato •InvoiceStatus, "draft" •Invoice, valorizzato	Se durante l'esecuzione del metodo CreateFastInvoice Invoice è stata creata ma non finalizzata in Stripe. Il metodo CreateFastInvoice si ferma allo step 2, è necessario utilizzare il metodo CompleteFastInvoicePayment per completare i passi successivi.
Dato strutturato con: •InvoiceItemId, valorizzato •InvoiceId, valorizzato •InvoiceStatus, "draft" •Invoice, valorizzato	Se autoAdvance uguale a true. Il metodo CreateFastInvoice raggiunge l'obiettivo dello step 2. Gli step 3 e 4 saranno svolti dal servizio di pagamento Stripe, pertanto non è necessario utilizzare il metodo CompleteFastInvoicePayment per completare i passi successivi.
Dato strutturato con: •InvoiceItemId, valorizzato •InvoiceId, valorizzato •InvoiceStatus, "open" •Invoice, valorizzato	Se durante l'esecuzione del metodo CreateFastInvoice Invoice è stata creata, finalizzata ma non pagata in Stripe. Il metodo CreateFastInvoice si ferma allo step 3, è necessario utilizzare il metodo CompleteFastInvoicePayment per completare il passo successivo.
Dato strutturato con: •InvoiceItemId, valorizzato •InvoiceId, valorizzato •InvoiceStatus, "paid" •Invoice, valorizzato	Se durante l'esecuzione del metodo Invoice è stata creata, finalizzata e pagata in Stripe. Il metodo CreateFastInvoice ha completato tutti gli step previsti, pertanto non è necessario utilizzare il metodo CompleteFastInvoicePayment.
Errore	Se testMode è valorizzato e non è presente, per l'identità o l'elemento organizzativo a cui fa riferimento RecipientReference, una configurazione che permette la chiamata nella modalità TestMode indicata.
Errore	Se customerReference non è associata al Recipient cui fa riferimento il parametro recipientReference.
Errore	Se customerReference è associata al Recipient cui fa riferimento il parametro recipientReference. ma il Customer non è presente in Stripe.
Errore	Se il parametro invoiceData contiene il campo default_payment_method, ma non viene valorizzato o PaymentMethod non è attivo per il Customer su quel determinato Recipient.
Errore	Se il parametro paymentMethodReference riporta un collegamento ad un PaymentMethod non è attivo per il Customer su quel determinato Recipient..

Autorizzazioni

Per eseguire il metodo è necessario possedere il permesso di Utilizzo sulla configurazione del Plug Stripe Connect.