---
title: "Payment Hub"
description: "Payment Hub di Fabrick: documentazione in preparazione."
url: "https://docs.fabrick.com/payment-hub-and-orchestra/payment-hub/"
language: "it"
---

# Payment Hub

## Introduzione

Questo documento descrive le API del modulo di pagamento della piattaforma PACE (Fabrick), esposte sotto il path base /api/fabrick/pace/v4.0/mods/payment/v2.0/back. Tali API sono pensate per essere invocate dai clienti e coprono la gestione dei pagamenti (bill), delle relative transazioni ed esecuzioni, dei mandati e degli strumenti di pagamento salvati (token carta, mandati SDD).

Per ogni API sono riportati: una descrizione funzionale, le tabelle dei parametri di input, un esempio di richiesta e di risposta in formato JSON e i principali codici di errore restituiti. I campi/DTO condivisi tra più API sono descritti una sola volta in questa sezione introduttiva e richiamati per riferimento nelle sezioni successive.

### Autenticazione e header comuni

Tutte le API descritte in questo documento richiedono, oltre agli eventuali header specifici indicati per singolo endpoint, i seguenti header comuni:

- `Api-Key` (obbligatorio: Sì): API key fornita dal client per l'autenticazione S2S.
- `Auth-Schema` (obbligatorio: Sì): Valore fisso: S2S.

*Alcuni endpoint richiedono inoltre l'header Auth-Token, necessario per risolvere la sessione utente personificata (merchant e tenant) tramite il meccanismo di "personificazione" della piattaforma. Quando presente, tale requisito è indicato esplicitamente nella riga "Autenticazione" di ciascuna API.*

### Struttura della risposta (ResponseDto)

Salvo diversa indicazione, tutte le risposte sono incapsulate in una busta comune ResponseDto, con la seguente struttura:

- `status` (string (enum); obbligatorio: Sì): Esito dell'operazione: OK, KO, UNAUTHORIZED, PENDING.
- `errors` (array di ErrorDto; obbligatorio: No): Elenco degli errori riscontrati, valorizzato in caso di esito diverso da OK.
- `payload` (object; obbligatorio: No): Corpo della risposta specifico dell'endpoint, descritto nella relativa sezione.

**ErrorDto**

- `code` (string; obbligatorio: Sì): Codice identificativo dell'errore (es. PAYM-REQUIRED-400).
- `description` (string; obbligatorio: No): Descrizione testuale dell'errore.
- `params` (object; obbligatorio: No): Eventuali parametri aggiuntivi a corredo dell'errore.

### Tipi condivisi

I seguenti DTO ricorrono in più API e vengono descritti qui una sola volta; nelle sezioni successive sono richiamati per nome.

**MoneyDTO**

- `amount` (number; obbligatorio: Sì): Importo.
- `currency` (string; obbligatorio: Sì): Valuta, codice ISO 4217 (es. EUR).

**PaymentAllowedMethodsDTO**

- `customerMethods` (array di string; obbligatorio: No): Metodi di pagamento disponibili per il cliente finale.
- `businessMethods` (array di string; obbligatorio: No): Metodi di pagamento disponibili in ambito B2B
- `orchestraMethodsB2B` (array di string; obbligatorio: No): Metodi ORCHESTRA consentiti in ambito B2B.
- `orchestraMethodsB2C` (array di string; obbligatorio: No): Metodi ORCHESTRA consentiti in ambito B2C (verificati, ad es., in fase di esecuzione pagamento).

**PaymentGatewayResponse**

- `exitUrl` (string; obbligatorio: No): URL di uscita/redirect verso il gateway di pagamento.
- `paymentGatewayStatus` (string; obbligatorio: No): Stato restituito dal gateway (es. AUTHORIZED, ERROR).
- `error` (string; obbligatorio: No): Eventuale messaggio di errore del gateway.
- `transactionId` (string; obbligatorio: No): Identificativo della transazione lato gateway.

**PaymentSubjectDTO**

- `id` (string; obbligatorio: No): Identificativo interno del soggetto.
- `xid` (string; obbligatorio: No): Identificativo esterno del soggetto.
- `name` (string; obbligatorio: No): Ragione sociale (persona giuridica).
- `firstName` (string; obbligatorio: No): Nome (persona fisica).
- `lastName` (string; obbligatorio: No): Cognome (persona fisica).
- `email` (string; obbligatorio: No): Indirizzo email.
- `phoneNumber` (string; obbligatorio: No): Numero di telefono.

**Enum PaymentMethod**

Valori ammessi: SDD, CASH, CHEQUE, SMARTPOS, INSURANCE_CREDIT, BANCOMATPAY, FBKR2P, EXTERNAL, CREDITCARD, SCT, MYBANK, PAYPAL, SATISPAY, SDD_CBI, KLARNA, ORCHESTRA. In assenza di indicazione esplicita, il metodo di default utilizzato dalla piattaforma è ORCHESTRA.

**MandateSubject / MandateSubjectResponse**

- `name` (string; obbligatorio: No): Ragione sociale del soggetto titolare del mandato.
- `firstName` (string; obbligatorio: No): Nome.
- `lastName` (string; obbligatorio: No): Cognome.
- `email` (string; obbligatorio: No): Indirizzo email.
- `phoneNumber` (string; obbligatorio: No): Numero di telefono.
- `ccu` (string; obbligatorio: No): Codice cliente univoco (CCU) del soggetto.
- `legalInformation` (LegalInformation; obbligatorio: No): Dati legali del soggetto — vedi sotto.
- `registryInformation` (RegistryInformation; obbligatorio: No): Dati anagrafici/indirizzo del soggetto — vedi sotto.

**LegalInformation / LegalInformationResponse**

- `type` (string; obbligatorio: No): Tipologia di soggetto (es. PF = persona fisica, PG = persona giuridica).
- `taxCode` (string; obbligatorio: No): Codice fiscale.
- `vatNumber` (string; obbligatorio: No): Partita IVA.

**RegistryInformation / RegistryInformationResponse**

- `address` (string; obbligatorio: No): Indirizzo (via e numero civico).
- `city` (string; obbligatorio: No): Città.
- `region` (string; obbligatorio: No): Provincia/regione.
- `zipCode` (string; obbligatorio: No): CAP.

**PaymentInstrumentData (dati mandato SDD)**

- `xId` (string; obbligatorio: Sì): Identificativo esterno dello strumento di pagamento (deve essere univoco per merchant).
- `iban` (string; obbligatorio: Sì): IBAN del conto addebitato.
- `signatureDate` (string (date); obbligatorio: Sì): Data di firma del mandato SDD; determina anche la data di scadenza dello strumento (anno-mese).
- `signaturePlace` (string; obbligatorio: No): Luogo di firma del mandato.
- `contractId` (string; obbligatorio: No): Identificativo del contratto sottostante; le ultime cifre sono usate per generare l'alias dello strumento.
- `contractDescription` (string; obbligatorio: No): Descrizione del contratto sottostante.

## Payments — /back/payments

Endpoint relativi al ciclo di vita del pagamento (bill): creazione, lettura, cancellazione, aggiornamento tag/scadenza, esecuzione delle transazioni (autorizzazione, cattura, pagamento con token salvato) e rimborsi.

### Creazione di un pagamento (bill)

**POST** `/api/fabrick/pace/v4.0/mods/payment/v2.0/back/payments`

**Descrizione funzionale**

Crea un nuovo bill. È il principale punto di ingresso per la creazione di un pagamento.

**Note e regole di business**

- Se il merchant è di tipo PSP "BILLING", il campo pagoPa.pspId è obbligatorio e deve corrispondere (case-insensitive) al pspId configurato per il merchant; se il merchant è "SPENDING", il campo non deve essere valorizzato.

- Se paymentConfiguration.mandateCreation è true, il merchant deve avere l'opzione enableMandate abilitata, altrimenti l'operazione è rifiutata (403).

- Con mandateCreation=true gli importi (bill e items) possono essere >= 0 (anche zero); con mandateCreation=false devono essere strettamente > 0.

- Se sono presenti items, la somma dei relativi importi deve coincidere esattamente con l'importo del bill.

**Campi del body della richiesta (PaymentCoreCreateRequestDTO)**

- `merchantId` (string; obbligatorio: Sì): Identificativo del merchant.
- `externalId` (string; obbligatorio: Sì): Riferimento esterno assegnato dal chiamante.
- `paymentConfiguration` (object; obbligatorio: No): Configurazione del pagamento — vedi PaymentConfigurationPaymentCoreDTO in "Tipi condivisi".
- `bill` (object; obbligatorio: Sì): Dettaglio del bill — vedi BillPaymentCoreRequestDTO in "Tipi condivisi".
- `pagoPa` (object; obbligatorio: No): Configurazione specifica PagoPA (campo pspId), obbligatoria solo per merchant di tipo BILLING.

***Esempio di richiesta (JSON):***

```json
{
  "merchantId": "MERCH-00012345",
  "externalId": "ORD-2026-000789",
  "paymentConfiguration": {
    "expirationDate": "2026-09-15T23:59:59.000Z",
    "manualExecution": false,
    "mandateCreation": false
  },
  "bill": {
    "externalId": "BILL-2026-000789",
    "amount": 150,
    "currency": "EUR",
    "description": "Fattura energia elettrica settembre 2026",
    "items": [
      {
        "externalId": "ITEM-000001",
        "amount": 150,
        "currency": "EUR",
        "description": "Consumo energia elettrica"
      }
    ]
  }
}
```

**Risposta — 200 OK (PaymentCoreResponse)**

***Esempio di risposta (JSON):***

```json
{
  "status": "OK",
  "errors": [],
  "payload": {
    "externalId": "ORD-2026-000789",
    "tenantId": "TENANT-PACE",
    "paymentId": "PAY-2026-000789",
    "merchantId": "MERCH-00012345",
    "paymentPageUrl": "https://pay.fabrick.com/checkout/PAY-2026-000789",
    "paymentPageAuthUrl": "https://pay.fabrick.com/checkout/PAY-2026-000789/auth",
    "shortPaymentPageUrl": "https://pay.fbk.it/s/ab12cd",
    "qrCodePayment": "https://pay.fabrick.com/qr/PAY-2026-000789.png",
    "qrCodeAuth": "https://pay.fabrick.com/qr/PAY-2026-000789-auth.png",
    "coupon": null,
    "description": "Fattura energia elettrica settembre 2026"
  }
}
```

**Principali codici di errore**

- **400 PAYM-REQUIRED-400**: Campo obbligatorio mancante (es. bill.amount).
- **403 PAYM-FORBIDDEN-403**: Merchant non abilitato a operare.
- **422 PAYM-INVALID-PAYLOAD**: Payload non valido (es. bill.amount diverso dalla somma degli items).
- **500 TECH-500**: Errore tecnico imprevisto.

### Lettura di un pagamento

**GET** `/api/fabrick/pace/v4.0/mods/payment/v2.0/back/payments/{paymentId}`

**Descrizione funzionale**

Restituisce i dettagli completi del pagamento richiesto (dati bill, transazioni, mandato di creazione, importi).

**Note e regole di business**

- L'header opzionale x-terminalId è accettato ma non influisce sull'elaborazione della risposta.

- Se la data di scadenza del pagamento è assente o già trascorsa, l'endpoint risponde comunque con esito 404 ("non trovato"), anche se concettualmente il pagamento esiste ma è scaduto.

**Parametri path**

- `paymentId` (string; obbligatorio: Sì): Identificativo del pagamento.

**Header specifici**

- `x-terminalId` (obbligatorio: No): Identificativo terminale, opzionale e non utilizzato ai fini del calcolo della risposta.

**Risposta — 200 OK (PaymentDTO)**

***Esempio di risposta (JSON):***

```json
{
  "status": "OK",
  "payload": {
    "id": "PAY123456789",
    "creationDate": "2026-09-01T10:15:30.000Z",
    "expirationDate": "2026-09-08T23:59:59.000Z",
    "shortCode": "AB12CD",
    "merchant": {
      "id": "MERCH001",
      "xid": "X-MERCH-001",
      "name": "Acme Store Srl",
      "email": "merchant@acme.it",
      "phoneNumber": "+390212345678"
    },
    "customer": {
      "id": "CUST987",
      "xid": "X-CUST-987",
      "firstName": "Mario",
      "lastName": "Rossi",
      "email": "mario.rossi@example.com",
      "phoneNumber": "+393331234567"
    },
    "allowedPaymentMethods": {
      "customerMethods": [
        "CARD",
        "BANK_TRANSFER"
      ],
      "businessMethods": [
        "CARD"
      ],
      "orchestraMethodsB2B": [],
      "orchestraMethodsB2C": [
        "CARD"
      ]
    },
    "residualAmount": {
      "amount": 0,
      "currency": "EUR"
    },
    "paidAmount": {
      "amount": 150,
      "currency": "EUR"
    },
    "money": {
      "amount": 150,
      "currency": "EUR"
    },
    "bill": {
      "id": "BILL5678",
      "status": "CREATED",
      "description": "Order #5678",
      "money": {
        "amount": 150,
        "currency": "EUR"
      },
      "tag": "order-5678"
    },
    "manualExecution": false
  }
}
```

**Principali codici di errore**

- **404 PAYM-NOTFOUND-404**: Pagamento non trovato oppure scaduto.

### Cancellazione di un pagamento

**DELETE** `/api/fabrick/pace/v4.0/mods/payment/v2.0/back/payments/{paymentId}`

**Descrizione funzionale**

Annulla il pagamento indicato.

**Parametri path**

- `paymentId` (string; obbligatorio: Sì): Identificativo del pagamento.

**Risposta — 200 OK (BillCancelResult)**

***Esempio di risposta (JSON):***

```json
{
  "status": "OK",
  "payload": {
    "paymentId": "PAY123456789",
    "billId": "BILL5678",
    "status": "CANCELLED",
    "executed": false
  }
}
```

**Principali codici di errore**

- **400 PAYM-REQUIRED-400**: Campo obbligatorio mancante.
- **404 PAYM-NOTFOUND-404**: Pagamento non trovato.
- **500 TECH-500**: Errore tecnico imprevisto.

### Aggiornamento dei tag del pagamento

**PUT** `/api/fabrick/pace/v4.0/mods/payment/v2.0/back/payments/{paymentId}/tag`

**Descrizione funzionale**

Aggiorna i campi tag, tag2, tag3 (etichette libere) associati al bill.

**Note e regole di business**

- Almeno uno tra tag, tag2, tag3 deve essere valorizzato, altrimenti la richiesta è rifiutata.

- Il merchant della sessione personificata deve corrispondere al merchant proprietario del bill.

- L'aggiornamento genera un evento di dominio e una notifica al merchant; un eventuale fallimento della notifica produce comunque un errore 500, anche se il tag è già stato aggiornato internamente.

**Parametri path**

- `paymentId` (string; obbligatorio: Sì): Identificativo del pagamento.

**Campi del body della richiesta (BillUpdateTagRequestDTO)**

- `tag` (string; obbligatorio: No): Prima etichetta libera.
- `tag2` (string; obbligatorio: No): Seconda etichetta libera.
- `tag3` (string; obbligatorio: No): Terza etichetta libera.

***Esempio di richiesta (JSON):***

```json
{
  "tag": "order-5678",
  "tag2": "campaign-summer",
  "tag3": "channel-web"
}
```

**Risposta — 200 OK (ResponseDto)**

***Esempio di risposta (JSON):***

```json
{
  "status": "OK"
}
```

**Principali codici di errore**

- **400 PAYM-REQUIRED-400**: Payload non valido o sconosciuto (nessun tag valorizzato).
- **404 PAYM-NOTFOUND-404**: Pagamento non trovato.
- **401 AUTH-401**: Non autorizzato.

### Aggiornamento della data di scadenza

**PUT** `/api/fabrick/pace/v4.0/mods/payment/v2.0/back/payments/expirationDate`

**Descrizione funzionale**

Modifica la data di scadenza di un bill/pagamento.

**Note e regole di business**

- Consentito solo se il bill si trova in stato READY, PAYMENT_STARTED o CANC; qualunque altro stato produce un errore.

- Il campo newExpirationDate viene interpretato con pattern "yyyy-MM-dd HH:mm:ss" nel fuso orario di default del server, non in UTC come le altre date della piattaforma — da tenere presente in fase di integrazione.

**Campi del body della richiesta (ChangeExpirationDto)**

- `paymentId` (string; obbligatorio: Sì): Identificativo del pagamento da aggiornare.
- `newExpirationDate` (string; obbligatorio: Sì): Nuova data di scadenza.

***Esempio di richiesta (JSON):***

```json
{
  "paymentId": "PAY-2026-000789",
  "newExpirationDate": "2026-10-15T23:59:59.000Z"
}
```

**Risposta — 200 OK (ExpirationDateDto)**

***Esempio di risposta (JSON):***

```json
{
  "status": "OK",
  "errors": [],
  "payload": {
    "id": "PAY-2026-000789",
    "creationDate": "2026-09-01T09:00:00.000Z",
    "expirationDate": "2026-10-15T23:59:59.000Z",
    "xId": "EXT-2026-000789"
  }
}
```

**Principali codici di errore**

- **400 PAYM-REQUIRED-400**: Campo obbligatorio mancante (es. newExpirationDate).
- **500 TECH-500**: Errore tecnico imprevisto.

### Esecuzione pagamento (inizializzazione + autorizzazione)

**POST** `/api/fabrick/pace/v4.0/mods/payment/v2.0/back/payments/{paymentId}/transaction`

**Descrizione funzionale**

Inizializza e autorizza in un'unica chiamata sincrona una transazione di pagamento sul gateway Axerve per il pagamento indicato.

**Note e regole di business**

- Prima dell'esecuzione viene verificato che il bill esista, non sia scaduto, che l'importo richiesto sia coerente con quello del bill e che il paymentMethod richiesto sia tra i metodi ORCHESTRA consentiti lato B2C per quel pagamento.

- In caso di esito negativo dell'autorizzazione sul gateway, viene registrato un evento di fallimento e il pagamento risulta annullato (stato CANC) prima che l'errore venga restituito al chiamante.

- Concettualmente distinto da "execution" (che effettua la sola cattura di una transazione già autorizzata) e da "updateandexecution" (cattura di un importo specifico su una transazione preautorizzata).

**Parametri path**

- `paymentId` (string; obbligatorio: Sì): Identificativo del pagamento.

**Campi del body della richiesta (ExecutePaymentRequest)**

- `paymentMethod` (string (enum); obbligatorio: Sì): Metodo di pagamento — vedi enum PaymentMethod in "Tipi condivisi".
- `money` (MoneyDTO; obbligatorio: Sì): Importo e valuta — vedi MoneyDTO in "Tipi condivisi".

***Esempio di richiesta (JSON):***

```json
{
  "paymentMethod": "CREDITCARD",
  "money": {
    "amount": 49.9,
    "currency": "EUR"
  }
}
```

**Risposta — 200 OK (ExecutePaymentResponse)**

***Esempio di risposta (JSON):***

```json
{
  "status": "OK",
  "errors": [],
  "payload": {
    "status": "OK",
    "transactionId": "TRX-2026-000456",
    "paymentGatewayResponse": {
      "exitUrl": "https://pay.axerve.com/checkout/TRX-2026-000456",
      "paymentGatewayStatus": "AUTHORIZED",
      "error": null,
      "transactionId": "TRX-2026-000456"
    }
  }
}
```

**Principali codici di errore**

- **400 PAYM-REQUIRED-400**: Campo obbligatorio mancante (es. money.amount).
- **404 PAYM-NOTFOUND-404**: Pagamento non trovato.
- **409 PAYM-INVALID-409**: Pagamento già eseguito o non eseguibile nello stato corrente.
- **500 PAYM-GATEWAY-000**: Errore del gateway/core di pagamento.

### Cattura (execution) di una transazione preautorizzata

**POST** `/api/fabrick/pace/v4.0/mods/payment/v2.0/back/payments/{paymentId}/execution`

**Descrizione funzionale**

Esegue la cattura ("execution") di una transazione precedentemente autorizzata e non ancora catturata, associata al pagamento indicato.

**Note e regole di business**

- Supporta esclusivamente il metodo di pagamento CREDITCARD: qualsiasi altro metodo viene rifiutato con esito 422.

- La transazione target deve trovarsi in stato IN_PRGS; in caso contrario l'operazione è rifiutata con esito 409 ("già eseguita").

- Prima della cattura, lo stato della transazione viene riallineato con il gateway: se risulta già liquidata ("settled"), l'endpoint restituisce l'esito corrente senza ritentare la cattura.

- In caso di timeout o errore interno del gateway durante la cattura, l'endpoint non propaga l'errore ma risponde comunque 200 OK con lo stato corrente della transazione, per favorire la gestione di eventuali retry idempotenti.

**Parametri path**

- `paymentId` (string; obbligatorio: Sì): Identificativo del pagamento.

**Risposta — 200 OK (PaymentResponse)**

***Esempio di risposta (JSON):***

```json
{
  "status": "OK",
  "payload": {
    "transactionId": "TXN445566",
    "transactionDateTime": "2026-09-08T09:45:00.000Z",
    "amount": 150,
    "currency": "EUR",
    "gatewayId": "GW-01",
    "acquirerId": "ACQ-01",
    "status": "AUTHORIZED",
    "paymentMethod": "CARD",
    "scaRequired": false,
    "scaUrl": null
  }
}
```

**Principali codici di errore**

- **401 AUTH-401**: Non autorizzato.
- **422 PAYM-INVALID-PAYLOAD**: Metodo di pagamento non supportato per l'esecuzione (diverso da CREDITCARD).
- **409 PAYM-INVALID-409**: Pagamento già eseguito.
- **500 PAYM-GATEWAY-000**: Errore bloccante sulla cattura lato gateway.

### Movimentazione dell'importo reale su un pagamento preautorizzato

**POST** `/api/fabrick/pace/v4.0/mods/payment/v2.0/back/payments/{paymentId}/updateandexecution`

**Descrizione funzionale**

Utilizzato per movimentare (catturare) il reale importo di un pagamento preautorizzato, quando l'importo da catturare è diverso da quello originariamente autorizzato (es. pre-autorizzazione per importo massimo, cattura dell'importo realmente consumato).

**Note e regole di business**

- Richiede che il bill sia configurato con manualExecution = true, altrimenti l'operazione è rifiutata.

- L'importo richiesto non può superare l'importo complessivo del bill.

- Deve esistere almeno una transazione in stato IN_PRGS per il pagamento indicato.

- A differenza di "execution", questo endpoint richiede sempre manualExecution=true e accetta un importo esplicito nel corpo della richiesta.

**Parametri path**

- `paymentId` (string; obbligatorio: Sì): Identificativo del pagamento.

**Campi del body della richiesta (MoneyDTO)**

- `amount` (number; obbligatorio: Sì): Importo da movimentare (non può superare l'importo del bill) — vedi MoneyDTO in "Tipi condivisi".
- `currency` (string; obbligatorio: Sì): Valuta (ISO 4217).

***Esempio di richiesta (JSON):***

```json
{
  "amount": 99.9,
  "currency": "EUR"
}
```

**Risposta — 200 OK (PaymentResponse)**

***Esempio di risposta (JSON):***

```json
{
  "status": "OK",
  "errors": [],
  "payload": {
    "transactionId": "TRX-2026-000456",
    "transactionDateTime": "2026-09-08T10:15:30.000Z",
    "amount": 99.9,
    "currency": "EUR",
    "gatewayId": "AXERVE",
    "acquirerId": "ACQ-001",
    "status": "OK",
    "paymentMethod": "CREDITCARD",
    "scaRequired": false,
    "scaUrl": null
  }
}
```

**Principali codici di errore**

- **400 PAYM-REQUIRED-400**: Campo obbligatorio mancante (es. amount).
- **404 PAYM-NOTFOUND-404**: Pagamento non trovato.
- **409 PAYM-INVALID-409**: Pagamento già eseguito o non eseguibile nello stato corrente.
- **500 TECH-500**: Errore tecnico imprevisto.

### Pagamento con strumento di pagamento salvato (token)

**POST** `/api/fabrick/pace/v4.0/mods/payment/v2.0/back/payments/{paymentId}/payWithToken`

**Descrizione funzionale**

Esegue il pagamento sul pagamento indicato utilizzando uno strumento di pagamento (token) precedentemente salvato, identificato dal proprio xid.

**Note e regole di business**

- Il bill deve trovarsi in stato READY.

- Lo strumento di pagamento deve appartenere al merchant della sessione, essere in stato ACTIVE ed essere di tipo CREDITCARD, SEPA o SDD (il tipo SEPA è trattato internamente come alias storico di SDD).

- Non devono esistere altre transazioni in stato INIT o IN_PRGS per lo stesso pagamento, per evitare pagamenti concorrenti/duplicati.

- L'importo pagato non è quello indicato nel body ma corrisponde sempre all'intero importo del bill.

**Parametri path**

- `paymentId` (string; obbligatorio: Sì): Identificativo del pagamento.

**Campi del body della richiesta (PayWithTokenRequest)**

- `paymentInstrumentXid` (string; obbligatorio: Sì): Xid dello strumento di pagamento salvato da utilizzare.

***Esempio di richiesta (JSON):***

```json
{
  "paymentInstrumentXid": "PI-2026-000123"
}
```

**Risposta — 200 OK (PayWithTokenResponse)**

***Esempio di risposta (JSON):***

```json
{
  "status": "OK",
  "errors": [],
  "payload": {
    "id": "PAY-2026-000789",
    "expirationDate": "2026-09-20T23:59:59.000Z",
    "importo": {
      "amount": 99.9,
      "currency": "EUR"
    },
    "creationDate": "2026-09-08T10:15:30.000Z",
    "status": "OK",
    "paymentMethod": "CREDITCARD"
  }
}
```

**Principali codici di errore**

- **401 AUTH-401**: Header di autenticazione mancanti o non validi.
- **404 INSTR-NOTFOUND-404**: Strumento di pagamento non trovato.
- **409 PAYM-INVALID-409**: Pagamento già eseguito o non eseguibile nello stato corrente.
- **500 TECH-500**: Errore tecnico imprevisto.

### Autorizzazione con strumento di pagamento salvato (token)

**POST** `/api/fabrick/pace/v4.0/mods/payment/v2.0/back/payments/{paymentId}/authWithToken`

**Descrizione funzionale**

Autorizza (senza catturare) un pagamento sul pagamento indicato utilizzando uno strumento di pagamento a carta salvato, identificato dal proprio xid. Restituisce un esito PENDING (202) quando il gateway richiede un'elaborazione aggiuntiva (es. 3DS/SCA).

**Note e regole di business**

- Il bill deve trovarsi in stato READY ed essere configurato con manualExecution = true: l'endpoint è pensato per flussi di pre-autorizzazione con cattura manuale successiva (tramite "execution" o "updateandexecution").

- Supporta esclusivamente strumenti di pagamento di tipo CREDITCARD.

- Se è richiesta un'autenticazione forte (3DS/SCA), la risposta ha status HTTP 202 e status logico PENDING, con scaRedirectUrl valorizzato; altrimenti la risposta è 200 OK.

- Anche qui l'importo autorizzato è quello del bill, non un valore passato nel body; viene inoltre verificata l'assenza di transazioni concorrenti in stato INIT o IN_PRGS.

**Parametri path**

- `paymentId` (string; obbligatorio: Sì): Identificativo del pagamento.

**Campi del body della richiesta (AuthWithTokenRequest)**

- `paymentInstrumentXid` (string; obbligatorio: Sì): Xid dello strumento di pagamento a carta salvato da utilizzare.

***Esempio di richiesta (JSON):***

```json
{
  "paymentInstrumentXid": "PI-2026-000123"
}
```

**Risposta — 200 OK / 202 Accepted (SCA richiesta) (AuthWithTokenResponse)**

***Esempio di risposta (JSON):***

```json
{
  "status": "PENDING",
  "errors": [],
  "payload": {
    "id": "PAY-2026-000789",
    "expirationDate": "2026-09-20T23:59:59.000Z",
    "money": {
      "amount": 99.9,
      "currency": "EUR"
    },
    "creationDate": "2026-09-08T10:15:30.000Z",
    "status": "PMT_IN_PRGS",
    "paymentMethod": "CREDITCARD",
    "code": "3DS_REQUIRED",
    "scaRedirectUrl": "https://pay.axerve.com/3ds/PAY-2026-000789"
  }
}
```

**Principali codici di errore**

- **400 INSTR-REQUIRED-400**: Campo obbligatorio mancante (es. paymentInstrumentXid).
- **404 INSTR-NOTFOUND-404**: Strumento di pagamento non trovato.
- **401 AUTH-401**: Header di autenticazione mancanti o non validi.
- **500 TECH-500**: Errore tecnico imprevisto.

### Rimborso di una transazione

**POST** `/api/fabrick/pace/v4.0/mods/payment/v2.0/back/payments/{paymentId}/transactions/{transactionId}/refund`

**Descrizione funzionale**

Esegue il rimborso, totale o parziale, di una specifica transazione associata al pagamento indicato.

**Note e regole di business**

- Il merchant deve avere il rimborso abilitato in configurazione, altrimenti la richiesta è rifiutata.

- La transazione target deve essere in stato OK e non già interamente rimborsata; l'importo cumulato dei rimborsi (già effettuati + richiesto) non può superare l'importo della transazione.

- Il rimborso deve avvenire entro il periodo configurato per il merchant, calcolato a partire dalla data di creazione della transazione.

- Un rimborso parziale (inferiore all'importo totale) è ammesso solo se esplicitamente abilitato in configurazione per il merchant.

- Il metodo di pagamento della transazione deve corrispondere a quello configurato per il merchant ai fini del rimborso.

**Parametri path**

- `paymentId` (string; obbligatorio: Sì): Identificativo del pagamento.
- `transactionId` (string; obbligatorio: Sì): Identificativo della transazione da rimborsare.

**Campi del body della richiesta (RefundRequest)**

- `amountToRefund` (MoneyDTO; obbligatorio: No): Importo da rimborsare — vedi MoneyDTO in "Tipi condivisi". Se omesso o pari all'intero importo, il rimborso è totale.
- `refundReason` (string; obbligatorio: No): Motivazione del rimborso.
- `merchantId` (string; obbligatorio: No): Ignorato: viene sempre sovrascritto con il merchant della sessione autenticata.

***Esempio di richiesta (JSON):***

```json
{
  "amountToRefund": {
    "amount": 50,
    "currency": "EUR"
  },
  "refundReason": "Customer requested partial refund"
}
```

**Risposta — 200 OK (RefundResponse)**

***Esempio di risposta (JSON):***

```json
{
  "status": "OK",
  "payload": {
    "id": "REF001122",
    "creationDate": "2026-09-08T09:30:00.000Z",
    "transactionId": "TXN998877",
    "status": "IN_PROGRESS",
    "reason": "Customer request",
    "amount": 50,
    "currency": "EUR"
  }
}
```

**Principali codici di errore**

- **401 AUTH-401**: Header di autenticazione mancanti o non validi.
- **400 PAYM-REQUIRED-400**: Verifica di rimborso fallita (configurazione merchant non valida o transazione non idonea).
- **500 TECH-500**: Errore tecnico imprevisto.

### Creazione di un mandato per il pagamento

**POST** `/api/fabrick/pace/v4.0/mods/payment/v2.0/back/payments/{idPayment}/doMandate`

**Descrizione funzionale**

Crea un mandato per il pagamento indicato, sulla base dei dati di transazione forniti. La presenza dell'header di autenticazione abilita il flusso di creazione mandato B2B (in assenza, il flusso è B2C).

**Note e regole di business**

- Il campo tokenCart determina se il mandato utilizzerà il "carrello token" (utile per pagamenti ricorrenti/tokenizzati con più mandati che condividono un token cart).

- I campi redirect / redirectTo / redirectLabel definiscono l'URL e l'etichetta di ritorno lato gateway al termine del flusso di sottoscrizione del mandato.

- Se il mandato è già in stato ATTEMPTING o IN_PROGRESS (e non è un mandato di tipo "orchestra"), l'operazione è bloccata per evitare duplicazioni/concorrenza.

- Attualmente è implementato l'executor solo per il metodo di pagamento CREDITCARD; altri metodi potrebbero non essere supportati.

- In caso di errore durante l'esecuzione, viene comunque registrato un evento di fallimento del mandato prima di restituire l'errore al chiamante.

**Parametri path**

- `idPayment` (string; obbligatorio: Sì): Identificativo del pagamento per cui creare il mandato.

**Header specifici**

- `Auth-Token` (obbligatorio: No): Se presente, abilita il flusso di creazione mandato B2B (validato contro l'IDP).

**Campi del body della richiesta (Input (TransactionDTO))**

- `expirationDate` (string (date-time); obbligatorio: No): Data di scadenza del mandato.
- `rate` (number; obbligatorio: Sì): Rata/importo di riferimento del mandato.
- `paymentMethod` (string (enum); obbligatorio: No): Metodo di pagamento — vedi enum PaymentMethod in "Tipi condivisi".
- `money` (Money; obbligatorio: No): Importo e valuta — vedi MoneyDTO in "Tipi condivisi".
- `redirect` (boolean; obbligatorio: No): Abilita il redirect verso l'URL indicato al termine del flusso.
- `redirectTo` (string; obbligatorio: No): URL di ritorno al termine del flusso di sottoscrizione mandato.
- `redirectLabel` (string; obbligatorio: No): Etichetta mostrata per il link di ritorno.
- `tokenCart` (boolean; obbligatorio: No): Abilita l'uso del carrello token per il mandato (default: false).

***Esempio di richiesta (JSON):***

```json
{
  "expirationDate": "2026-09-20T23:59:59.000Z",
  "rate": 1,
  "paymentMethod": "CREDITCARD",
  "money": {
    "amount": 99.9,
    "currency": "EUR"
  },
  "redirect": true,
  "redirectTo": "https://merchant.example.com/thank-you",
  "redirectLabel": "Torna al negozio",
  "tokenCart": false
}
```

**Risposta — 200 OK (MandateResponseDto)**

***Esempio di risposta (JSON):***

```json
{
  "status": "OK",
  "errors": [],
  "payload": {
    "exitUrl": "https://pay.fabrick.com/mandate/PAY-2026-000789/exit",
    "gatewayError": null
  }
}
```

**Principali codici di errore**

- **400 PAYM-REQUIRED-400**: Campo obbligatorio mancante.
- **500 TECH-500**: Errore tecnico imprevisto.

## Payment Instrument — /back/payment-instrument

Endpoint back-channel per la gestione degli strumenti di pagamento salvati (token carta, mandati SDD): creazione, lettura, aggiornamento, cancellazione e ricerca per merchant/soggetto/token.

### Creazione di uno strumento di pagamento

**POST** `/api/fabrick/pace/v4.0/mods/payment/v2.0/back/payment-instrument`

**Descrizione funzionale**

Crea un nuovo strumento di pagamento con mandato già tokenizzato sul gateway. Il merchant richiedente è ricavato dalla sessione autenticata; la combinazione di xid, subject xid e merchant deve essere univoca.

**Note e regole di business**

- La data di scadenza deve essere in formato anno-mese ed essere futura.

- È previsto un numero massimo configurabile di strumenti di pagamento per soggetto/merchant.

- La combinazione xid + subject_xid + merchantId deve essere univoca.

- Il primo strumento creato per un soggetto diventa automaticamente quello predefinito (is_default = true).

**Campi del body della richiesta (PaymentInstrumentCreateRequest)**

- `alias` (string; obbligatorio: Sì): Etichetta descrittiva dello strumento.
- `description` (string; obbligatorio: No): Descrizione estesa.
- `type` (string (enum); obbligatorio: Sì): Tipo di strumento: CREDITCARD, PAYPAL, SATISPAY, SDD, SEPA.
- `xid` (string; obbligatorio: Sì): Token identificativo assegnato dal gateway.
- `subject_xid` (string; obbligatorio: Sì): Identificativo esterno del soggetto titolare.
- `expiration_date` (string; obbligatorio: Sì): Data di scadenza (formato anno-mese).
- `card_country` (string; obbligatorio: No): Paese di emissione della carta.
- `card_type` (string; obbligatorio: No): Tipo di carta (es. VISA).
- `card_company` (string; obbligatorio: No): Circuito/brand della carta.
- `commercial` (string \[Y/N]; obbligatorio: No): Indica se la carta è di tipo commerciale.
- `prepaid` (string \[Y/N]; obbligatorio: No): Indica se la carta è prepagata.
- `cardHolderName` (string; obbligatorio: No): Nome dell'intestatario carta.

***Esempio di richiesta (JSON):***

```json
{
  "alias": "Carta Visa personale",
  "description": "Carta Visa principale",
  "expiration_date": "12/28",
  "type": "CREDITCARD",
  "xid": "tok-2026-abc123",
  "subject_xid": "X-SUBJ-001",
  "card_country": "IT",
  "card_type": "VISA",
  "card_company": "VISA",
  "commercial": "N",
  "prepaid": "N",
  "cardHolderName": "Mario Rossi"
}
```

**Risposta — 200 OK (PaymentInstrumentCreateResponse)**

***Esempio di risposta (JSON):***

```json
{
  "status": "OK",
  "errors": [],
  "payload": {
    "id": "PI-2026-000123",
    "xid": "tok-2026-abc123",
    "type": "CREDITCARD",
    "subject_id": "3f2a9e10-8b1a-4c2e-9d55-1a2b3c4d5e6f",
    "subject_xid": "X-SUBJ-001",
    "alias": "Carta Visa personale",
    "description": "Carta Visa principale",
    "expiration_date": "12/28",
    "card_country": "IT",
    "card_type": "VISA",
    "card_company": "VISA",
    "is_default": true,
    "status": "ACTIVE",
    "prepaid": "N",
    "cardHolderName": "Mario Rossi"
  }
}
```

**Principali codici di errore**

- **401 AUTH-401**: Header di autenticazione mancanti o non validi.
- **409 INSTR-INVALID-409**: Strumento di pagamento già esistente con lo stesso xid.
- **400 INSTR-REQUIRED-400 / INSTR-INVALID-PAYLOAD**: Campo obbligatorio mancante, data di scadenza non futura, oppure limite massimo strumenti raggiunto.
- **500 TECH-500**: Errore tecnico imprevisto.

### Creazione di mandato SDD esterno e strumento di pagamento

**POST** `/api/fabrick/pace/v4.0/mods/payment/v2.0/back/payment-instrument/full`

**Descrizione funzionale**

Crea un mandato SDD esterno sul gateway e registra contestualmente lo strumento di pagamento corrispondente, in un'unica chiamata sincrona e transazionale.

**Note e regole di business**

- Il merchant deve avere il metodo SDD abilitato (B2B o B2C) in configurazione.

- L'xId dello strumento di pagamento deve essere univoco per merchant.

- L'alias viene generato automaticamente a partire dalle ultime cifre del contractId.

- La data di scadenza dello strumento è derivata dalla data di firma del mandato (anno-mese), non da un valore esplicito.

**Campi del body della richiesta (SddExternalPaymentInstrumentRequest)**

- `merchantId` (string; obbligatorio: Sì): Identificativo del merchant (deve coincidere con quello della sessione autenticata).
- `subjectXId` (string; obbligatorio: Sì): Identificativo esterno del soggetto titolare del mandato.
- `mandateSubject` (object; obbligatorio: Sì): Anagrafica del soggetto — vedi MandateSubject in "Tipi condivisi".
- `paymentInstrument` (object; obbligatorio: Sì): Dati del mandato SDD (IBAN, firma, contratto) — vedi PaymentInstrumentData in "Tipi condivisi".

***Esempio di richiesta (JSON):***

```json
{
  "merchantId": "MERCH001",
  "subjectXId": "X-SUBJ-001",
  "mandateSubject": {
    "name": "Mario Rossi Srl",
    "firstName": "Mario",
    "lastName": "Rossi",
    "email": "mario.rossi@example.com",
    "phoneNumber": "+393331234567",
    "ccu": "CCU00123456",
    "legalInformation": {
      "type": "PF",
      "taxCode": "RSSMRA80A01H501U",
      "vatNumber": "IT01234567890"
    },
    "registryInformation": {
      "address": "Via Roma 1",
      "city": "Milano",
      "region": "MI",
      "zipCode": "20100"
    }
  },
  "paymentInstrument": {
    "xId": "SDD-INSTR-2026-001",
    "iban": "IT60X0542811101000000123456",
    "signatureDate": "2026-09-01",
    "signaturePlace": "Milano",
    "contractId": "CTR-9988",
    "contractDescription": "Fornitura energia elettrica"
  }
}
```

**Risposta — 200 OK (SddExternalPaymentInstrumentResponse)**

***Esempio di risposta (JSON):***

```json
{
  "status": "OK",
  "errors": [],
  "payload": {
    "id": "MND-2026-000456",
    "xId": "SDD-INSTR-2026-001",
    "type": "SDD",
    "alias": "SDD ****-9988",
    "description": "Fornitura energia elettrica",
    "status": "ACTIVE",
    "subjectId": "3f2a9e10-8b1a-4c2e-9d55-1a2b3c4d5e6f",
    "subjectXId": "X-SUBJ-001",
    "merchantId": "MERCH001",
    "expirationDate": "2026-09",
    "isDefault": true,
    "mandateSubject": {
      "ccu": "CCU00123456",
      "email": "mario.rossi@example.com",
      "firstName": "Mario",
      "lastName": "Rossi",
      "name": "Mario Rossi Srl",
      "phoneNumber": "+393331234567"
    },
    "sddMandate": {
      "iban": "IT60X0542811101000000123456",
      "signatureDate": "2026-09-01",
      "signaturePlace": "Milano",
      "contractId": "CTR-9988",
      "contractDescription": "Fornitura energia elettrica"
    }
  }
}
```

**Principali codici di errore**

- **401 AUTH-401**: Header di autenticazione mancanti o non validi.
- **403 INSTR-FORBIDDEN-403**: Merchant non abilitato a operare.
- **400 INSTR-REQUIRED-400**: Campo obbligatorio mancante (es. signatureDate).
- **409 INSTR-INVALID-409**: Conflitto con lo stato corrente della risorsa (xId non univoco).
- **500 TECH-500**: Errore tecnico imprevisto.

### Lettura di uno strumento di pagamento per id interno

**GET** `/api/fabrick/pace/v4.0/mods/payment/v2.0/back/payment-instrument/{id}`

**Descrizione funzionale**

Restituisce il dettaglio di uno strumento di pagamento identificato dal proprio id interno.

**Parametri path**

- `id` (string; obbligatorio: Sì): Identificativo interno dello strumento di pagamento.

**Risposta — 200 OK (PaymentInstrumentCreateResponse)**

***Esempio di risposta (JSON):***

```json
{
  "status": "OK",
  "errors": [],
  "payload": {
    "id": "PI-2026-000123",
    "xid": "tok-2026-abc123",
    "type": "CREDITCARD",
    "subject_id": "SUBJ-001",
    "subject_xid": "X-SUBJ-001",
    "alias": "Carta Visa personale",
    "description": "Carta Visa principale",
    "expiration_date": "12/28",
    "card_country": "IT",
    "card_type": "VISA",
    "card_company": "VISA",
    "is_default": true,
    "status": "ACTIVE",
    "prepaid": "N",
    "cardHolderName": "Mario Rossi"
  }
}
```

**Principali codici di errore**

- **404 INSTR-NOTFOUND-404**: Strumento di pagamento non trovato (anche in caso di merchant non corrispondente).
- **403 INSTR-FORBIDDEN-403**: Merchant non abilitato a operare.
- **500 TECH-500**: Errore tecnico imprevisto.

### Aggiornamento di uno strumento di pagamento

**PUT** `/api/fabrick/pace/v4.0/mods/payment/v2.0/back/payment-instrument/{id}`

**Descrizione funzionale**

Aggiorna alias, descrizione, stato o flag di default di uno strumento di pagamento esistente.

**Note e regole di business**

- Non è consentito impostare esplicitamente is_default a false: il flag può solo essere impostato a true oppure omesso.

- Non è consentito modificare contemporaneamente status a INACTIVE e il flag is_default nella stessa richiesta.

**Parametri path**

- `id` (string; obbligatorio: Sì): Identificativo interno dello strumento di pagamento.

**Campi del body della richiesta (PaymentInstrumentUpdateRequest)**

- `alias` (string; obbligatorio: No): Nuova etichetta descrittiva.
- `description` (string; obbligatorio: No): Nuova descrizione.
- `status` (string (enum); obbligatorio: No): Nuovo stato: ACTIVE o INACTIVE (non combinabile con is_default nella stessa richiesta).
- `is_default` (boolean; obbligatorio: No): Impostazione a strumento predefinito (può essere impostato solo a true).

***Esempio di richiesta (JSON):***

```json
{
  "alias": "La mia carta principale",
  "description": "Carta Visa principale",
  "is_default": true,
  "status": "ACTIVE"
}
```

**Risposta — 200 OK (PaymentInstrumentCreateResponse)**

***Esempio di risposta (JSON):***

```json
{
  "status": "OK",
  "errors": [],
  "payload": {
    "id": "PI-2026-000123",
    "xid": "tok-2026-abc123",
    "type": "CREDITCARD",
    "alias": "La mia carta principale",
    "description": "Carta Visa principale",
    "is_default": true,
    "status": "ACTIVE"
  }
}
```

**Principali codici di errore**

- **400 INSTR-REQUIRED-400**: Campo obbligatorio mancante o combinazione non valida di campi (es. alias, status+is_default).
- **403 INSTR-FORBIDDEN-403**: Merchant non abilitato a operare su questo strumento.
- **404**: Strumento di pagamento non trovato.
- **500 TECH-500**: Errore tecnico imprevisto.

### Ricerca strumenti di pagamento per merchant e soggetto

**GET** `/api/fabrick/pace/v4.0/mods/payment/v2.0/back/payment-instrument/{merchantId}/subject/{subjectXid}`

**Descrizione funzionale**

Restituisce gli strumenti di pagamento appartenenti a un soggetto per un dato merchant, con filtro opzionale per stato.

**Parametri path**

- `merchantId` (string; obbligatorio: Sì): Identificativo del merchant.
- `subjectXid` (string; obbligatorio: Sì): Identificativo esterno del soggetto.

**Parametri query**

- `status` (string; obbligatorio: No): Filtro opzionale sullo stato dello strumento (es. ACTIVE, INACTIVE).

**Risposta — 200 OK (PaymentInstrumentCreateResponse (array))**

***Esempio di risposta (JSON):***

```json
{
  "status": "OK",
  "errors": [],
  "payload": [
    {
      "id": "PI-2026-000123",
      "xid": "tok-2026-abc123",
      "type": "CREDITCARD",
      "subject_id": "SUBJ-001",
      "subject_xid": "X-SUBJ-001",
      "alias": "Carta Visa personale",
      "is_default": true,
      "status": "ACTIVE"
    }
  ]
}
```

**Principali codici di errore**

- **500 TECH-500**: Errore tecnico imprevisto.

### Ricerca strumenti di pagamento per soggetto

**GET** `/api/fabrick/pace/v4.0/mods/payment/v2.0/back/payment-instrument/subject/{subjectXid}`

**Descrizione funzionale**

Restituisce gli strumenti di pagamento appartenenti a un soggetto, con filtro opzionale per stato.

**Parametri path**

- `subjectXid` (string; obbligatorio: Sì): Identificativo esterno del soggetto.

**Parametri query**

- `status` (string; obbligatorio: No): Filtro opzionale sullo stato dello strumento.

**Risposta — 200 OK (PaymentInstrumentCreateResponse (array))**

***Esempio di risposta (JSON):***

```json
{
  "status": "OK",
  "errors": [],
  "payload": [
    {
      "id": "PI-2026-000123",
      "xid": "tok-2026-abc123",
      "type": "CREDITCARD",
      "subject_id": "SUBJ-001",
      "subject_xid": "X-SUBJ-001",
      "alias": "Carta Visa personale",
      "is_default": true,
      "status": "ACTIVE"
    }
  ]
}
```

**Principali codici di errore**

- **401 AUTH-401**: Header di autenticazione mancanti o non validi.
- **403 INSTR-FORBIDDEN-403**: Merchant non abilitato a operare.
- **500 TECH-500**: Errore tecnico imprevisto.

### Ricerca strumenti di pagamento per token del gateway

**GET** `/api/fabrick/pace/v4.0/mods/payment/v2.0/back/payment-instrument/token/{xid}`

**Descrizione funzionale**

Restituisce gli strumenti di pagamento corrispondenti al token (xid) assegnato dal gateway.

**Parametri path**

- `xid` (string; obbligatorio: Sì): Token identificativo assegnato dal gateway.

**Risposta — 200 OK (PaymentInstrumentCreateResponse (array))**

***Esempio di risposta (JSON):***

```json
{
  "status": "OK",
  "errors": [],
  "payload": [
    {
      "id": "PI-2026-000123",
      "xid": "tok-2026-abc123",
      "type": "CREDITCARD",
      "subject_id": "SUBJ-001",
      "subject_xid": "X-SUBJ-001",
      "alias": "Carta Visa personale",
      "is_default": true,
      "status": "ACTIVE"
    }
  ]
}
```

**Principali codici di errore**

- **403**: Merchant non abilitato a operare.
- **500 TECH-500**: Errore tecnico imprevisto.

### Cancellazione di uno strumento di pagamento SDD

**DELETE** `/api/fabrick/pace/v4.0/mods/payment/v2.0/back/payment-instrument/{paymentInstrumentId}`

**Descrizione funzionale**

Cancella uno strumento di pagamento SDD insieme al relativo mandato sul gateway esterno. Possono essere cancellati solo strumenti di tipo SDD.

**Note e regole di business**

- Un tentativo di cancellazione su uno strumento di tipo diverso da SDD viene rifiutato.

- La cancellazione del mandato lato gateway esterno avviene prima di qualunque modifica ai dati locali: se il gateway fallisce, l'intera operazione fallisce.

**Parametri path**

- `paymentInstrumentId` (string; obbligatorio: Sì): Identificativo dello strumento di pagamento SDD da cancellare.

**Risposta — 200 OK (ResponseDto)**

***Esempio di risposta (JSON):***

```json
{
  "status": "OK",
  "errors": [],
  "payload": null
}
```

**Principali codici di errore**

- **401**: Header di autenticazione mancanti/non validi, oppure tentativo di cancellare uno strumento non SDD.
- **404 INSTR-NOTFOUND-404**: Strumento di pagamento non trovato.
- **500 INSTR-GATEWAY-000**: Errore del gateway/core dello strumento.