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

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 una mail con il contenuto custom
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

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