Payment Hub

Visualizza come Markdown

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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

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

Risposta — 200 OK (ResponseDto)

Esempio di risposta (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):

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

Risposta — 200 OK (ExpirationDateDto)

Esempio di risposta (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):

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

Risposta — 200 OK (ExecutePaymentResponse)

Esempio di risposta (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):

{
  "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):

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

Risposta — 200 OK (PaymentResponse)

Esempio di risposta (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):

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

Risposta — 200 OK (PayWithTokenResponse)

Esempio di risposta (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):

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

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

Esempio di risposta (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):

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

Risposta — 200 OK (RefundResponse)

Esempio di risposta (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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

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

Risposta — 200 OK (PaymentInstrumentCreateResponse)

Esempio di risposta (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):

{
  "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):

{
  "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):

{
  "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):

{
  "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.