# Richiesta di pagamento

Il path parameter `token` è l'identificativo univoco risultante dalla creazione di una Payment Request

#### Creazione richiesta di pagamento

Se si intende sfruttare questa api per avere un match univoco tra una fattura e una richiesta di pagamento, guardare la pagina [**Fatturazione**](https://digital-docs.ts-paas.com/books/payment-container/page/fatturazione "Fatturazione")

Permette di creare una richiesta di pagamento ``` [POST] /paymentRequest ? ``` Nella **request** abbiamo: - **`creditor`**: creditore della richiesta di pagamento - `identifiers`: lista di possibili identificativi riguardanti il soggetto. Per il creditore è necessario fornire un **TS\_DIGITAL\_ID** - `name`: non compilare per il creditore in quanto verrà recuperato automaticamente da anagrafica TS Digital - `holder`: non compilare per il creditore in quanto verrà recuperato automaticamente da anagrafica TS Digital - `logourl`: non compilare per il creditore in quanto verrà recuperato automaticamente da anagrafica TS Digital - `email`: compilare per utilizzare email custom di reply to inserita nella mail (vedere preferenze per capire le gerarchie) - **`debtor`**: debitore della richiesta di pagamento - `identifiers`: lista di possibili identificativi riguardanti il soggetto. - `name`: compilare in alternativa a holder (Persone giuridiche) - `holder`: compilare in alternativa a name (Persone fisiche) - `logourl`: non utilizzato per il debitore, non compilare - `email`: compilare se si vuole utilizzare la funzionalità di invio mail automatiche - **`paymentReason`**: causale di pagamento - **`totalAmount`**: ammontare totale della richiesta di pagamento - **`availablePaymentPlans`**: piani di pagamento a disposizione - `type`: tipologia di piano (singolo o multiplo) - `description`: descrizione del piano di pagamento - `installments`: rate che compongono il piano di pagamento - `description`: descrizione della rata - `dueDate`: scadenza della singola rata - `amount`: importo della rata - **`metadata`**: dati aggiuntivi che è possibile utilizzare ai fini di riconciliazione (max 100 caratteri totali) - **`availablePaymentMethods`**: metodi di pagamento a disposizione - `name`: metodo di pagamento accettato - `constraints`: minimali e massimali del singolo metodo di pagamento - `minimumAmount`: importo minimo per il metodo di pagamento - `maximumAmount`: importo massimo per il metodo di pagamento - **`ownerId`**: ownerId con identificativo TS Digital del creditore - **`transmitterId`**: transmitterId con identificativo TS Digital - **`paymentDocuments`**: identificativi dei documenti che compongono la richiesta di pagamento - `id`: identificativo del documento (hubId se fatture, o id se documento del document store) - `type`: tipo di documento - `description`: descrizione del documento - `allowDownloadBeforePayment`: booleano per inibire download prima che la richiesta sia completamente pagata (Default: true) - **`dueDate`**: data di scadenza della richiesta di pagamento - **`mailContent`**: contenuto della mail da fornire nel caso si voglia inviare del contenuto personalizzato (La mail può contenere i comuni tag html per i paragrafi e per la formattazione) - **`storeMailContent`**: valore booleano che indica se è necessario conservare il contenuto della mail inviato

I `constraints` hanno una priorità. Se vengono definiti sia nella request che nelle preferenze, avranno precedenza quelli della richiesta puntuale. Il `minimumAmount` può non essere definito ma in tal caso assumerà valore 0 con valuta EUR

Se un piano di pagamento è definito come SINGLE\_INSTALLMENT​ deve contenere una sola rata. Contrariamente se viene definito un MULTIPLE\_INSTALLMENTS deve contenere almeno due rate

Tutte le valute dei vari importi devono coincidere

Per inviare automaticamente una mail al debitore, contenete il link di pagamento, bisogna fornire l'indirizzo email compilando l'attributo **email** del **debtor**

Nella **response** l'API ritorna: - **`id`**: identificativo univoco della richiesta di pagamento creata - **`token`**: identificativo da utilizzare nelle altre chiamate API per fare riferimento alla richiesta di pagamento in oggetto - **`url`**: link per visualizzare la richiesta di pagamento tramite UI Payment Container e successivamente effettuare dei pagamenti --- #### Modifica richiesta di pagamento Permette di modificare una richiesta di pagamento ``` [PATCH] /paymentRequest/{token} ? ``` Nella **request** abbiamo: - **`debtor`**: debitore della richiesta di pagamento - `identifiers`: lista di possibili identificativi riguardanti il soggetto. *Se non compilato viene utilizzato quello già presente* - `name`: compilare in alternativa a holder (Persone giuridiche). *Se non passato viene utilizzato quello già presente* - `holder`: compilare in alternativa a name (Persone fisiche). *Se non compilato viene utilizzato quello già presente* - `email`: compilare se si vuole utilizzare la funzionalità di invio mail automatiche. *Se non compilato viene utilizzata la mail impostata in precedenza. Per eventualmente rimuovere la mail, valorizzare a stringa vuota* - **`paymentDocuments`**: identificativi dei documenti che compongono la richiesta di pagamento - `id`: identificativo del documento (hubId se fatture, o id se documento del document store) - `type`: tipo di documento - `description`: descrizione del documento - `allowDownloadBeforePayment`: booleano per inibire download prima che la richiesta sia completamente pagata (Default: true)

*Almeno un attributo deve essere valorizzato, altrimenti verrà restituito un errore. Per quanto riguarda **paymentDocuments**, è necessario fornire il nuovo elenco di documenti che andranno a sovrascrivere quelli precedentemente forniti*

*La modifica non è possibile se la richiesta di pagamento è nei seguenti stati: **PAID** \\ **EXTERNAL\_PAID***

Nella **response** l'API ritorna: - **`id`**: identificativo univoco della richiesta di pagamento modificata - **`token`**: identificativo da utilizzare nelle altre chiamate API per fare riferimento alla richiesta di pagamento in oggetto - **`url`**: link per visualizzare la richiesta di pagamento tramite UI Payment Container e successivamente effettuare dei pagamenti --- #### Disabilitare richiesta di pagamento Permette di disabilitare una richiesta di pagamento precedentemente creata ``` [PATCH] /paymentRequest/{token}/disable ? ``` Nella **response** l'API ritorna: - **`id`**: identificativo univoco della richiesta di pagamento disabilitata - `token`: identificativo token della richiesta di pagamento disabilitata - **`url`**: link disabilitato #### Visualizzare una singola richiesta di pagamento \[API Pubblica\] Permette di visualizzare una richiesta di pagamento ``` [GET] /public/paymentRequest/{token} ``` Nella **response** l'API ritorna: - **`token`**: token della richiesta di pagamento - **`creditor`**: creditore della richiesta di pagamento - **`debtor`**: debitore della richiesta di pagamento - **`paymentReason`**: causale di pagamento - **`totalAmount`**: ammontare totale della richiesta di pagamento - **`availablePaymentPlans`**: piani di pagamento a disposizione - **`id`**: identificativo del piano di pagamento - **`type`**: tipologia di piano (singolo o multiplo) - **`description`**: descrizione del piano di pagamento - **`installments`**: rate che compongono il piano di pagamento - **`id`**: identificativo della rata - **`description`**: descrizione della rata - **`dueDate`**: scadenza della singola rata - **`amount`**: importo della rata - **`availablePaymentMethods`**: metodi di pagamento a disposizione - **`name`**: metodo di pagamento accettato - **`constraints`**: minimali e massimali del singolo metodo di pagamento - **`minimumAmount`**: importo minimo per il metodo di pagamento - **`maximumAmount`**: importo massimo per il metodo di pagamento - **`ownerId`**: ownerId con identificativo TS Digital del creditore - **`transmitterId`**: transmitterId con identificativo TS Digital - **`paymentDocuments`**: identificativi dei documenti che compongono la richiesta di pagamento - **`documentId`**: identificativo del documento (interno a Payment Container non identificativo originale della fattura o documento su docstore) - **`type`**: tipo di documento - **`description`**: descrizione del documento - **`previewUrl`**: link per preview documento - **`downloadUrl`**: link per download documento - **`dueDate`**: data di scadenza della richiesta di pagamento - **`status`**: stato generale in cui si trova la richiesta di pagamento - **`createdAt`**: data in cui è stata creata la richiesta - **`payments`**: pagamenti effettuati per la richiesta di pagamento - **`id`**: identificativo univoco del pagamento - **`amount`**: importo del pagamento - **`paymentMethodName`**: metodo di pagamento utilizzato - **`paymentPlanId`**: identificativo del piano di pagamento - **`installmentIds`**: rate del pagamento - **`status`**: stato del pagamento - **`link`**: link di pagamento --- #### Visualizzare una singola richiesta di pagamento \[API Autenticata\] Permette di visualizzare una richiesta di pagamento ``` [GET] /paymentRequest/{token} ? ``` Nella **response** l'API ritorna: - **`token`**: token della richiesta di pagamento - **`creditor`**: creditore della richiesta di pagamento - **`debtor`**: debitore della richiesta di pagamento - **`paymentReason`**: causale di pagamento - **`totalAmount`**: ammontare totale della richiesta di pagamento - **`availablePaymentPlans`**: piani di pagamento a disposizione - **`id`**: identificativo del piano di pagamento - **`type`**: tipologia di piano (singolo o multiplo) - **`description`**: descrizione del piano di pagamento - **`installments`**: rate che compongono il piano di pagamento - **`id`**: identificativo della rata - **`description`**: descrizione della rata - **`dueDate`**: scadenza della singola rata - **`amount`**: importo della rata - **`metadata`**: dati aggiuntivi che sono stati inseriti in creazione della richiesta - **`availablePaymentMethods`**: metodi di pagamento a disposizione - **`name`**: metodo di pagamento accettato - **`constraints`**: minimali e massimali del singolo metodo di pagamento - **`minimumAmount`**: importo minimo per il metodo di pagamento - **`maximumAmount`**: importo massimo per il metodo di pagamento - **`ownerId`**: ownerId con identificativo TS Digital del creditore - **`transmitterId`**: transmitterId con identificativo TS Digital - **`paymentDocuments`**: identificativi dei documenti che compongono la richiesta di pagamento - **`documentId`**: identificativo del documento (interno a Payment Container non identificativo originale della fattura o documento su docstore) - **`type`**: tipo di documento - **`description`**: descrizione del documento - **`previewUrl`**: link per preview documento - **`downloadUrl`**: link per download documento - **`originalDocumentIds`**: mapping tra gli identificativi interni PaymentContainer e gli identificativi originali caricati (hubId o id DocStore) - **`dueDate`**: data di scadenza della richiesta di pagamento - **`status`**: stato generale in cui si trova la richiesta di pagamento - **`createdAt`**: data in cui è stata creata la richiesta - **`enabled`**: stato della richiesta che indica se abilitata o disabilitata - **`payments`**: pagamenti effettuati per la richiesta di pagamento - **`id`**: identificativo univoco del pagamento - **`amount`**: importo del pagamento - **`paymentMethodName`**: metodo di pagamento utilizzato - **`paymentPlanId`**: identificativo del piano di pagamento - **`installmentIds`**: rate del pagamento - **`status`**: stato del pagamento - **`link`**: link di pagamento - **`emailContent`**: contenuto della mail inviata al debitore al momento della creazione della richiesta --- #### Visualizzare richieste di pagamento Permette di visualizzare una lista di richieste di pagamento ``` [GET] /paymentRequest ? ``` Parametri **obbligatori**: - **`ownerId`**: ownerId di cui si ha il permesso per operare e per cui si richiede la lista - **`timestamp`**: unix timestamp in millisecondi (esempio: `1643361440000`) Parametri *opzionali*: - **`tokens`**: array di id di richieste di pagamento da visualizzare - **`size`**: numero di risultati per richiesta (default: **20**) - **`continuationToken`**: token per richiedere il blocco successivo (restituito nella risposta) - **`sort`**: chiavi di sorting possibili -> **createdAt** - **`direction`**: desc | asc rispetto alla chiave di sorting Nella **response** l'API ritorna: - **`content`**: lista di risultati con singola struttura identica alla richiesta singola \[Profilo Privato\] - **`continuationToken`**: token per richiedere altri risultati - **`hasNext`**: booleano che indica se ci sono altri risultati da visualizzare - **`size`**: massima dimensione dei risultati impostata nei filtri --- #### Invio email Permette l'invio manuale della mail di Creazione Richiesta. ``` [POST] /paymentRequest/{token}/sendMail ? ``` Nella request abbiamo: - **`email`**: indirizzo email a cui inviare la notifica (opzionale) Nella **response** l'API non torna nulla se non lo status code

Il campo `email` è opzionale. Se nella creazione della richiesta di pagamento era stato impostato il campo `email` del `debtor` verrà preso quel valore per inviare nuovamente una mail. Impostando `email` in questa API, questo valore avrà precedenza rispetto a quello del debtor, ma non lo sostituirà. Per modificare l'email del debtor per tutta la richiesta di pagamento, procedere utilizzando l'API dedicata di modifica della richiesta di pagamento

Il testo della mail è fornito di default da TS Digital. Alternativamente, se impostato il parametro `bodyText` nelle preferenze, verrà utilizzato questo in alternativa a quello di default.

Questa mail è esattamente la stessa che viene inviata automaticamente dal sistema se impostato il campo `email` del `debtor` nella richiesta di pagamento