Payment Container

Documentazione per integrazione con il servizio TS Payment Container

Descrizione Flussi

Descrizione dei vari flussi operativi

Descrizione Flussi

Richiesta di pagamento

Creazione richiesta di pagamento 

Per creare una richiesta di pagamento deve essere invocata l’api [POST] /paymentRequest.  

Il beneficiario della richiesta deve: 

È possibile inserire in una richiesta di pagamento uno o più hubid di fatture che possono essere visualizzate e scaricate in formato pdf.

In fase di creazione della richiesta, il beneficiario può scegliere una o più soluzioni di pagamento tra cui “paga totale” o “paga a rate”. La request deve avere definiti i metodi di pagamento che sono iban e/o carta. Ciascun metodo può avere dei constraints ovvero delle condizioni per cui il metodo può essere attivo.  

È possibile inserire una data di scadenza alla richiesta di pagamento altrimenti verranno aggiunti 180 gg di default alla data dell’ultima rata.  

L’api restituisce un link per poter accedere alla richiesta, seguire l’iter e procedere al pagamento su un gateway di pagamento esterno (ad oggi TS Pay è l'unica integrazione). Inoltre, l’api restituisce anche il token da inserire nelle chiamate di visualizzazione o modifica richiesta. Il link della richiesta di pagamento viene inviato per e-mail al debitore se impostata la relativa mail. Il testo della mail è possibile personalizzarlo attraverso le preferenze. 

Una volta effettuato il pagamento su tspay, la richiesta verrà aggiornata con il pagamento saldato per l’intera richiesta o per una singola rata. 

Il debitore può comunicare di aver effettuato il pagamento tramite altre modalità diverse da tspay, selezionando in richiesta “pagamento già effettuato”, in questo caso la richiesta verrà aggiornata in “pagata” quando il creditore confermerà l’avvenuto pagamento. 

Per visualizzare l’anteprima dei documenti (formato pdf) inseriti in una richiesta è possibile utilizzare l’api [GET] /paymentRequest/document/{documentId}/preview.  

Per effettuare il download dei documenti è possibile tramite l’api [GET]/public/paymentRequest/{token}/documents/{documentId}/download. 

qodwu0A8t5BS9I6Y-drawing-99-1646322571.png

Disabilitare una richiesta di pagamento 

Per disabilitare un link di una richiesta di pagamento bisogna invocare l’api  [PATCH] /paymentRequest/{token}/disable. Inserire il token che viene restituito in fase di creazione della richiesta.  

Visualizzare una richiesta di pagamento 

Per visualizzare una richiesta di pagamento già creata è possibile tramite l’api  [GET] /public/paymentRequest/{token}. 

L’api restituisce tutte le informazioni inserite nella richiesta, compresa la ragione sociale e il logo dell’azienda creditrice. Inoltre, è possibile visualizzare lo stato dei pagamenti (paid/notpaid) delle singole rate. 

 

 

Mapping stati Payment Container e TsPay

Il mapping tra il servizio Payment Container e TsPay si può riassumere nel seguente schema:

Richiesta singola (TsPay link2Pay)

PAID -> active

ON_HOLD -> pending

NOT_PAID -> error, failed

Richiesta schedulata (TsPay link2Save)

SCHEDULED -> active (quando avverrà il pagamento alla data di scadenza sarà PAID)

​NOT_YET_PAID-> pending

NOT_PAID ​-> error, failed

​

Descrizione Flussi

Pagamenti

Sostituzione link di pagamento 

Per sostituire un link di pagamento già creato è possibile tramite l’api [PATCH] /public/paymentRequest/{token}/payment/{id}. Permette di generare un nuovo link di pagamento inserendo la modalità e la soluzione di pagamento a cui fare riferimento ma senza modificarne le condizioni. 

Pagamento manuale di una richiesta 

Per effettuare il pagamento manuale di una richiesta è possibile tramite l’api [POST] /paymentRequest/{token}/manualPayment. Permette di effettuare il pagamento manuale di una o più rate o dell’intera richiesta.  

In questo caso, dopo aver proceduto al pagamento, accedendo di nuovo al link della richiesta, risulterà il pagamento come già saldato e sarà possibile selezionare solo le rate non pagate. 

 

Descrizione Flussi

Preferenze

Creazione Preferenza 

E’ possibile creare una preferenza da applicare alle richieste di pagamento tramite l’api  [POST] /preferences/{companyId}.

Nel campo “company id” bisogna inserire lo uuid dell’azienda creditrice/owner della richiesta. 

È possibile creare una preferenza su una specifica azienda inserendo:  

Modifica Preferenza

La modifica di una preferenza precedentemente creata, è possibile tramite l’api [PATCH] /preferences/{companyId}.  

Visualizzazione Preferenza

La visualizzazione, di una preferenza creata su una specifica azienda, è possibile invocando l’api [GET] /preferences/{companyId}.  

 

Descrizione Flussi

Company Overview

Per verificare la presenza di fatture ricevute, inviate e scartate per una o più aziende a partire da un dato timestamp è possibile invocare api (https://b2bread-api-test.agyo.io/api/v2/items/overview). La stessa API vi permette di fare la stessa cosa anche con Payment Container. È stato aggiunto un nuovo campo specifico lastTimestampPayment

Successivamente al pagamento di una richiesta di pagamento, richiamando l’api [GET]/paymentRequest?ownerId={ownerId}&timestamp=1630387427000 è possibile visualizzare le richieste che si sono modificate rispetto a un dato timestamp.

 

API

Descrizione API del servizio Payment Container

API

Informazioni Generali

Swagger

L'ambiente di produzione non esponse swagger. 

Url base di produzione è: https://payment-container.agyo.io/

Headers

Per chiamare correttamente gli endpoint messi a disposizione dal servizio Payment Container, è necessario includere gli headers come descritto qui.

Tutte le API public non hanno necessità degli headers e possono essere utilizzate pubblicamente. Questo perchè anche un utente finale, non necessariamente TS Digital, può effettuare tali operazioni

In questa guida tutti gli endpoint sono descritti senza il prefisso /api/vX che va dunque anteposto

URLs UI

 

 

API

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:

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:

Modifica richiesta di pagamento

Permette di modificare una richiesta di pagamento 

[PATCH] /paymentRequest/{token} ?

Nella request abbiamo:

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:

Disabilitare richiesta di pagamento

Permette di disabilitare una richiesta di pagamento precedentemente creata

[PATCH] /paymentRequest/{token}/disable ?

Nella response l'API ritorna:

Visualizzare una singola richiesta di pagamento [API Pubblica]

Permette di visualizzare una richiesta di pagamento

[GET] /public/paymentRequest/{token}

Nella response l'API ritorna:

Visualizzare una singola richiesta di pagamento [API Autenticata]

Permette di visualizzare una richiesta di pagamento

[GET] /paymentRequest/{token} ?

Nella response l'API ritorna:

Visualizzare richieste di pagamento

Permette di visualizzare una lista di richieste di pagamento

[GET] /paymentRequest ?

Parametri obbligatori:

Parametri opzionali:

Nella response l'API ritorna:

Invio email

Permette l'invio manuale della mail di Creazione Richiesta.

[POST] /paymentRequest/{token}/sendMail ?

Nella request abbiamo:

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

API

Pagamento

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

Creazione link di pagamento

Permette di creare un link di pagamento facendo riferimento ad una payment request precedentemente configurata

[POST] /public/paymentRequest/{token}/pay

Nella request abbiamo:

Nella response l'API ritorna:

 

Permette di modificare le configurazioni di un link di pagamento precedentemente configurato e non ancora pagato

[PATCH] /public/paymentRequest/{token}/payment

Nella request abbiamo:

Nella response l'API ritorna:

 

Richiesta pagamento manuale

Permette di segnalare un pagamento come effettuato anche senza passare attraverso un iter di pagamento di Payment Container

[POST] /paymentRequest/{token}/manualPayment ?

Nella request abbiamo:

Nella response l'API ritorna:

 

 

API

Documenti

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

Preview di un documento

Permette di ricevere la preview di uno specifico documento contenuto in una payment request precedentemente configurata

[GET] /public/paymentRequest/{token}/documents/{documentId}/preview
[GET] /paymentRequest/{token}/documents/{documentId}/preview ?

Possibili parametri:

Nella response l'API ritorna:

XML del documento, HTML o PDF in base alla preview richiesta

Formati disponibili per tipologia di file
  ASSOSW ADE ASSOSWPDF ADEPDF RAW BASE64
AGYO_INVOICE

✅

Fallback

 ✅ ✅ ✅ ✅ ❌
DOC_STORE_DOCUMENT ❌ ❌ ❌ ❌

✅

Fallback

 ✅

Se si richiede un formato non valido per la tipologia di documento richiesta, verrà applicato il formato di fallback

Nel caso di Formato BASE64, ritorna esattamente la stessa struttura del Doc Store ovvero con anteposta la stringa data:application/pdf;base64,

L'api public segue il comportamento del flag allowDownloadBeforePayment. Se impostato a false in fase di creazione richiesta, il documento non può essere mostrato prima che il pagamento sia completato. L'api autenticata, invece, permette di visionare in qualunque momento il documento in oggetto.

Download di un documento

Permette di ricevere la preview di uno specifico documento contenuto in una payment request precedentemente configurata

[GET] /public/paymentRequest/{token}/documents/{documentId}/download
[GET] /paymentRequest/{token}/documents/{documentId}/download ?

Possibili parametri:

Nella response l'API ritorna:

XML del documento, PDF o stringa base64 in base al formato richiesto

Formati disponibili per tipologia di file
  XML PDF ASSOSW BASE64 RAW
AGYO_INVOICE ✅ ✅

✅

Fallback

 ❌ ❌
DOC_STORE_DOCUMENT ❌ ❌ ❌ ✅

✅

Fallback

Se si richiede un formato non valido per la tipologia di documento richiesta, verrà applicato il formato di fallback

Nel caso di Formato BASE64, ritorna esattamente la stessa struttura del Doc Store ovvero in formato DataURI con anteposta la stringa data:application/pdf;base64, 

L'api public segue il comportamento del flag allowDownloadBeforePayment. Se impostato a false in fase di creazione richiesta, il documento non può essere scaricato prima che il pagamento sia completato. L'api autenticata, invece, permette di scaricare in qualunque momento il documento in oggetto.

Upload documento Payment Container tramite TS Document Store

Proxy che permette di caricare un documento su TS Document Store, senza preoccuparsi di possedere un token tecnico dedicato

[POST] /documentStore ?

Request Body (multipart/form-data):

Upload documento Payment Container tramite TS Document Store (Base64)

Proxy che permette di caricare un documento su TS Document Store, senza la necessità di possedere un token tecnico dedicato.

[POST] /documentStore/base64 ?

Nella request abbiamo:

 

 

API

Preferenze

Il path parameter companyId è l'identificativo TS Digital di un'azienda correttamente registrata

Le preferenze non vincono mai sui valori impostati in una singola richiesta di pagamento. Questo permette di sovrascrivere le preferenze per delle richieste di pagamento specifiche.

Se daysDueDate non viene impostato, o viene impostato a 0, verranno aggiunti 180gg come valore di default alla data di scadenza dell'ultima rata (a meno di non aver impostato una due date specifica in richiesta)

Creazione di una preferenza

Permette di creare una preferenza per una specifica azienda

[POST] /preferences/{companyId} ?

Nella request abbiamo:

Nella response l'API ritorna:

 

Modifica di una preferenza

Permette di modificare una preferenza precedentemente creata per una specifica azienda

[PATCH] /preferences/{companyId} ?

Nella request abbiamo:

Nella response l'API ritorna:

 

Visualizzazione di una preferenza

Permette di modificare una preferenza precedentemente creata per una specifica azienda

[GET] /preferences/{companyId} ?

Nella response l'API ritorna:

 

Gerarchia priorità

daysDueDate

  1. dueDate inserita nella singola richiesta
  2. dueDate maggiore negli installments + daysDueDate nelle preferenze
  3. dueDate maggiore negli installments + 180gg

emailSettings.email

  1. creditor.email nella singola richiesta
  2. email preferenze
  3. nessuna email di reply-to

emailSettings.name:

  1. name nelle preferenze
  2. nome azienda recuperato dall'Anagrafica Ts Digital

emailSettings.bodyText:

  1. testo nelle preferenze
  2. testo standard fornito dalla piattaforma

 

API

Fatturazione

Per avvalersi le funzionalità di linking tra una fattura e una richiesta di pagamento, bisogna fare affidamento alla API dedicate disponibili qui

Creazione richiesta di pagamento - Swagger

[POST] https://b2bwrite-api-test.agyo.io/api/v1/payment/create ?

Questa API si comporta come la classica Creazione richiesta di pagamento, ma permette di visualizzare sulla fattura l'identificativo della richiesta di pagamento appena creata.

Inoltre permette, a fronte di una richiesta di pagamento successiva, di disabilitare la precedente mantenendo univoco il rapporto Fattura/Richiesta di pagamento.

Il payload utilizzato è il medesimo che potete trovare nella classica creazione richiesta di pagamento disponibile qui

Rimuovere richiesta di pagamento da una fattura - Swagger

[POST] https://b2bwrite-api-test.agyo.io/api/v2/invoices/{hubId}/removePaymentRequest ?

Questa API permette di rimuovere una richiesta di pagamento da una fattura e la disabilita automaticamente

API

Overview

Il path parameter companyId è l'identificativo TS Digital di un'azienda correttamente registrata.

Richiesta informazioni di Overview

Permette di recuperate informazioni di overview utili a fini statistici

[GET] /overview/{companyId} ?

Nella response l'API ritorna:

API

Esempi Payload

Creazione Richiesta di pagamento

{
    "creditor": {
        "identifiers": [
            {
                "type": "TS_DIGITAL_ID",
                "country": "Italy",
                "value": "5841dc57-59e9-4b82-b751-a03799a21cf6"
            }
        ]
    },
    "debtor": {
        "identifiers": [
            {
                "type": "VAT_NUMBER",
                "country": "IT",
                "value": "23434565432"
            }
        ],
        "name": "Debitore fannullone",
        "email": "test.debitore@teamsystem.com"
    },
    "totalAmount": {
        "currency": "EUR",
        "amount": "3299.99"
    },
    "availablePaymentPlans": [
        {
            "type": "MULTIPLE_INSTALLMENTS",
            "description": "Piano rateale",
            "installments": [
                {
                    "description": "Prima rata",
                    "dueDate": "2022-02-19T16:17:47.720Z",
                    "amount": {
                        "currency": "EUR",
                        "amount": "1000.00"
                    }
                },
                {
                    "description": "Seconda rata",
                    "dueDate": "2022-09-08T12:17:47.720Z",
                    "amount": {
                        "currency": "EUR",
                        "amount": "1000.00"
                    }
                },
                {
                    "description": "Terza rata",
                    "dueDate": "2022-10-08T12:17:47.720Z",
                    "amount": {
                        "currency": "EUR",
                        "amount": "1299.99"
                    }
                }
            ]
        },
        {
            "type": "SINGLE_INSTALLMENT",
            "description": "Pagamento totale",
            "installments": [
                {
                    "description": "Rata unica",
                    "dueDate": "2022-08-08T12:17:47.720Z",
                    "amount": {
                        "currency": "EUR",
                        "amount": "3299.99"
                    }
                }
            ]
        }
    ],
    "availablePaymentMethods": [
        {
            "name": "TS_PAY_BANK_TRANSFER"
        },
        {
            "name": "TS_PAY_CREDIT_CARD"
        }
    ],
    "paymentReason": "Fattura n.4 del 20 Luglio 2021",
    "ownerId": "5841dc57-59e9-4b82-b751-a03799a21cf6",
    "transmitterId": "5841dc57-59e9-4b82-b751-a03799a21cf6",
    "paymentDocuments": [
        {
            "type": "AGYO_INVOICE",
            "description": "test",
            "id": "8009cfb3-e7f1-43d1-a2a9-e1f263e5159c"
        },
        {
            "type": "DOC_STORE_DOCUMENT",
            "description": "file doc store test",
            "id": "d015f194-2609-4496-a7ec-6aba33a4b51c"
        }
    ]
}

Creazione di un pagamento

{
  "installmentIds": [
    "0.0",
    "0.1"
  ],
  "paymentMethodName": "TS_PAY_BANK_TRANSFER",
  "paymentPlanId": "0",
  "langLocale": "it-IT",
  "scheduled": true
}

Creazione di una preferenza

{
    "daysDueDate": 30,
    "emailSettings": {
        "bodyText": "Ciao benvenuto"
    }
}