# Incasso

### Fattura attiva

#### Descrizione

Consente di ricevere un pagamento attraverso il servizio di TS Pay; chiamando l'endpoint **link2pay** si riceverà un'url col quale sarà possibile fare un pagamento.

---

#### [Richiesta link per effetture un pagamento](https://ts-pay-gateway-test.agyo.io/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#/API/createLinkToPay)

Genera un link per effettuare un pagamento attraverso il servizio di TS Pay.

```
[POST] /{itemId}/link2pay
```

Nella **request** in particolare abbiamo:

- `template` contenente il testo ed eventualmente il logo da visualizzare nella pagina del pagamento generata e raggiungibile al link restituito in risposta 
    - `title` titolo, generalmente usato per indicare la ragione sociale del merchant (es: "TeamSystem S.p.A.")
    - `desc` motivazione del pagamento (es: "Fattura di vendita")
    - `paymentRef` estremi della fattura (es: "Numero 123 del 15/06/2020")
    - `logo` link all'immagine da visualizzare come logo
- `callbackUrl` url cui reindirizzare l'utente una volta completata l'operazione. facoltativo
- `sourceTypes` sorgenti di pagamento accettate: carta di credito, SDD o entrambi (default)
- `maxPaymentsNumber` numero massimo di pagamenti consentiti (0=illimitato)
- `amount` l'importo da pagare espresso come numero intero in cui le ultime due cifre compongono la parte decimale (ad es. 1450 è da considerare come 14,50)
- `externalRef` un riferimento univoco al pagatore, da utilizzare in seguito come elemento di ricerca
- `metadata` elementi di tracciabilità, da utilizzare per la riconciliazione

Nella **response** l'API fornisce:

- `orderKey` identificativo dell'ordine
- `url` link da utilizzare per eseguire l'operazione

---

#### [Richiesta link per memorizzare una sorgente di pagamento per addebiti futuri](https://ts-pay-gateway-test.agyo.io/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#/API/createLinkToSave)

Genera un link per salvare una sorgente di pagamento attraverso il servizio di TS Pay.

```
[POST] /{itemId}/link2save
```

Nella **request** in particolare abbiamo:

- `template` contenente il testo ed eventualmente il logo da visualizzare nella pagina del pagamento generata e raggiungibile al link restituito in risposta 
    - `title` titolo, generalmente usato per indicare la ragione sociale del merchant (es: "TeamSystem S.p.A.")
    - `desc` motivazione del pagamento (es: "Fattura di vendita")
    - `paymentRef` estremi della fattura (es: "Numero 123 del 15/06/2020")
    - `logo` link all'immagine da visualizzare come logo
- `callbackUrl` url cui reindirizzare l'utente una volta completata l'operazione. facoltativo
- `sourceTypes` sorgenti di pagamento accettate: carta di credito, SDD o entrambi (default)
- `maxSourceNumber` numero massimo di sorgenti memorizzabili (0=illimitato, default=1)
- `maxAmount` l'importo massimo per gli addebiti, inteso come cumulativo, espresso come numero intero in cui le ultime due cifre compongono la parte decimale (ad es. 1450 è da considerare come 14,50)
- `contextId` il contesto a cui la memorizzazione della sorgente si applica, quindi nel caso specifico la fattura
- `externalRef` un riferimento univoco al pagatore, da utilizzare in seguito come elemento di ricerca
- `metadata` elementi di tracciabilità, da utilizzare per la riconciliazione

Nella **response** l'API fornisce:

- `orderKey` identificativo dell'ordine
- `url` link da utilizzare per eseguire l'operazione

---

#### [Addebito](https://ts-pay-gateway-dev.agyo.io/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#/API/createCharge)

Esegue l'addebito sulla sorgente salvata con il LinkToSave.

```
[POST] /{itemId}/charges
```

Tra gli **header** è previsto:

- `x-operation-key` chiave univoca dell'addebito con lo scopo di prevenire i doppi incassi, in modo che se si tenta una seconda operazione con la stessa chiave viene restituito un errore (opzionale)

Nella **request** in particolare abbiamo:

- `sourceKey` identifica la sorgente di pagamento memorizzata dal customer attraverso il LinkToSave
- `contextId` l'eventuale contesto precedentemente impostato
- `description` è la motivazione del pagamento, che finisce nel movimento
- `amount` l'importo da addebitare espresso come numero intero in cui le ultime due cifre compongono la parte decimale (ad es. 1450 è da considerare come 14,50)

Nella **response** l'API fornisce:

- `orderKey` identificativo dell'ordine
- `chargeKey` identificativo dell'addebito

---

#### [Esito pagamanto](https://ts-pay-gateway-test.agyo.io/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#/API/getChargesByOrderKey)

Da utilizzare per conoscere tutti i dettagli dell'addebito.

```
[GET] /{itemId}/charges/orders/{orderKey}
```

I **parametri** richiesti sono:

- `orderKey` path variable - key dell'ordine, ritornato dalla [chiamata alla creazione della richiesta di pagamento](#bkmrk-addebito).