--- title: "API" description: "In questo documento puoi trovare la descrizione degli endpoint del prodotto Money Transfer." url: "https://docs.fabrick.com/payment-institution/banking-as-a-service/payments/dev/api/" language: "it" --- # API In questo documento puoi trovare la descrizione degli endpoint del prodotto Money Transfer. ## Flusso ![moneyTransferFlow](https://docs.fabrick.com/img/payment-institution/banking-as-a-service/payments/money-transfer-flow.png) ## Create Money Transfer Consente di disporre un trasferimento di denaro verso un beneficiario. È l’azione con cui si avvia il pagamento: si definiscono il destinatario, l’importo, la valuta, la descrizione e – se necessario – si può impostare urgenza o istantaneità. È pensato per gestire anche casi in cui l’operazione richiede più tempo: in caso di esito incerto è previsto un controllo successivo per capire se il pagamento sia stato eseguito o vada ripetuto. Questo endpoint consente di creare un nuovo bonifico (SCT, Swift o SCT‑Inst). Permette l’invio immediato o la prenotazione per una data futura, supporta l’esecuzione opzionale della Verification of Payee (VoP) e consente l’inserimento di eventuali agevolazioni fiscali. È necessario prestare attenzione ai timeout lato client, poiché l’elaborazione può richiedere diversi secondi (consigliato un timeout pari a 100 s). In caso di errore 500 o 504 è consigliato verificare se il bonifico sia stato comunque eseguito tramite ricerca. Esempio di richiesta ```text POST /api/gbs/banking/v4.1/accounts/{accountId}/payments/money-transfers ``` ```json { "creditor": { "name": "John Doe", "account": { "accountCode": "IT23A0336844430152923804660", "bicCode": "SELBIT2BXXX" }, "address": { "address": null, "city": null, "countryCode": null } }, "executionDate": "2019-04-01", "uri": "REMITTANCE_INFORMATION", "description": "Payment invoice 75/2017", "amount": 800, "currency": "EUR", "isUrgent": false, "isInstant": false, "feeType": "SHA", "feeAccountId": "45685475", "taxRelief": { "taxReliefId": "L449", "isCondoUpgrade": false, "creditorFiscalCode": "56258745832", "beneficiaryType": "NATURAL_PERSON", "naturalPersonBeneficiary": { "fiscalCode1": "MRLFNC81L04A859L", "fiscalCode2": null, "fiscalCode3": null, "fiscalCode4": null, "fiscalCode5": null }, "legalPersonBeneficiary": { "fiscalCode": null, "legalRepresentativeFiscalCode": null } } } ``` Parametri della richiesta: - *creditor* contiene i dati del beneficiario. - *creditor.name* nome del beneficiario (max 70 caratteri). - *creditor.account.accountCode* IBAN o conto SWIFT del beneficiario. - *creditor.account.bicCode* codice BIC della banca del beneficiario (obbligatorio se accountCode è SWIFT). - *creditor.address* indirizzo del beneficiario, richiesto per banche non italiane. - *executionDate* data di esecuzione del bonifico; obbligatoria salvo bonifico istantaneo. - *uri* informativa di rimessa facoltativa. - *description* descrizione del bonifico (max 140 caratteri). - *amount* importo del bonifico. - *currency* valuta del bonifico. - *isUrgent* indica se il bonifico è urgente. - *isInstant* indica se è un bonifico istantaneo SCT‑Inst. - *feeType* schema commissionale (SHA, OUR, BEN). - *feeAccountId* conto su cui addebitare le commissioni. - *taxRelief* contiene le informazioni opzionali per agevolazioni fiscali. - *taxRelief.taxReliefId* tipologia di agevolazione (L449, L296, DL50, ecc.). - *taxRelief.isCondoUpgrade* indica se l’intervento riguarda parti condominiali. - *taxRelief.creditorFiscalCode* codice fiscale o P.IVA del beneficiario del bonifico. - *taxRelief.beneficiaryType* tipologia beneficiario (NATURAL_PERSON, LEGAL_PERSON). - *taxRelief.naturalPersonBeneficiary.fiscalCode1* CF del primo beneficiario (obbligatorio per persona fisica). - *taxRelief.legalPersonBeneficiary.fiscalCode* P.IVA del beneficiario persona giuridica. Esempio di risposta ```json { "moneyTransferId": "452516859427", "status": "EXECUTED", "direction": "OUTGOING", "creditor": { "name": "John Doe", "account": { "accountCode": "IT23A0336844430152923804660", "bicCode": "SELBIT2BXXX" }, "address": { "address": null, "city": null, "countryCode": null } }, "debtor": { "name": "", "account": { "accountCode": "IT61F0326802230280596327270", "bicCode": null } }, "cro": "1234566788907", "uri": "REMITTANCE_INFORMATION", "trn": "AJFSAD1234566788907CCSFDGTGVGV", "description": "Description", "createdDatetime": "2019-04-10T10:38:55.949+0200", "accountedDatetime": "2019-04-10T10:38:56.000+0200", "debtorValueDate": "2019-04-10", "creditorValueDate": "2019-04-10", "amount": { "debtorAmount": 800, "debtorCurrency": "EUR", "creditorAmount": 800, "creditorCurrency": "EUR", "creditorCurrencyDate": "2019-04-10", "exchangeRate": 1 }, "isUrgent": false, "isInstant": false, "feeType": "SHA", "feeAccountId": "12345678", "fees": [ { "feeCode": "MK001", "description": "Money transfer execution fee", "amount": 0.25, "currency": "EUR" }, { "feeCode": "MK003", "description": "Currency exchange fee", "amount": 3.5, "currency": "EUR" } ], "hasTaxRelief": true, "vopResult": { "requestCode": "5977d0d6-22cc-4852-a994-25b13cf8015b", "operationCode": "12345678", "ownerName": "TEST", "matchedName": null, "iban": "IT23A0336844430152923804660", "description": null, "matchType": "MTCH", "respondingBic": "SELBIT2BXXX", "id": "a897b2e2-2936-4159-af6a-5b4ea52abdc7", "requestDateTime": "2025-11-10T16:16:42Z" } } ``` Parametri della risposta: - *moneyTransferId* identificativo univoco del bonifico creato. - *status* stato del bonifico (EXECUTED, BOOKED, REJECTED, ecc.). - *direction* direzione del trasferimento (INCOMING o OUTGOING). - *creditor* dati del beneficiario. - *creditor.name* nome del beneficiario. - *creditor.account.accountCode* conto del beneficiario. - *creditor.account.bicCode* BIC della banca del beneficiario. - *debtor* dati dell’ordinante. - *debtor.account.accountCode* conto dell’ordinante. - *cro* codice CRO. - *uri* remittance information. - *trn* codice TRN del bonifico. - *description* descrizione del bonifico. - *createdDatetime* data e ora di creazione. - *accountedDatetime* data e ora di contabilizzazione. - *debtorValueDate* data valuta ordinante. - *creditorValueDate* data valuta beneficiario. - *amount.debtorAmount* importo addebitato. - *amount.creditorAmount* importo accreditato. - *isUrgent* indica se il bonifico è urgente. - *isInstant* indica se è SCT‑Inst. - *feeType* schema commissionale applicato. - *feeAccountId* conto delle commissioni. - *fees* elenco delle commissioni applicate. - *hasTaxRelief* indica la presenza di agevolazioni fiscali. - *vopResult* contiene l’esito della Verification of Payee. - *vopResult.matchType* esito del match (MTCH, CMTC, NMTC, NOAP). ## Validate Money Transfer Permette di verificare in anticipo che un trasferimento sia correttamente impostato prima dell’esecuzione. È utile per ridurre errori, duplicazioni e rilanci non necessari, soprattutto quando si gestiscono volumi elevati o pagamenti sensibili. L’endpoint permette quindi di validare un ordine di bonifico SCT o SCT‑Inst, verificando che tutti i dati forniti siano corretti e che l’operazione possa essere eseguita. L’endpoint controlla completezza, coerenza dei campi, disponibilità dei dati necessari e applicazione di eventuali regole di dominio come istantaneità, urgenza, indirizzi e agevolazioni fiscali. Esempio di richiesta: ```text POST /api/gbs/banking/v4.0/accounts/{accountId}/payments/money-transfers/validate ``` ```json { "creditor": { "name": "John Doe", "account": { "accountCode": "IT23A0336844430152923804660", "bicCode": "SELBIT2BXXX" }, "address": { "address": null, "city": null, "countryCode": null } }, "executionDate": "2019-04-01", "uri": "REMITTANCE_INFORMATION", "description": "Payment invoice 75/2017", "amount": 800, "currency": "EUR", "isUrgent": false, "isInstant": false, "feeType": "SHA", "feeAccountId": "45685475", "taxRelief": { "taxReliefId": "L449", "isCondoUpgrade": false, "creditorFiscalCode": "56258745832", "beneficiaryType": "NATURAL_PERSON", "naturalPersonBeneficiary": { "fiscalCode1": "MRLFNC81L04A859L", "fiscalCode2": null, "fiscalCode3": null, "fiscalCode4": null, "fiscalCode5": null }, "legalPersonBeneficiary": { "fiscalCode": null, "legalRepresentativeFiscalCode": null } } } ``` Parametri della richiesta: - *creditor*: oggetto che contiene le informazioni del creditore. - *creditor.name*: nome del creditore. - *creditor.account*: dati del conto del creditore. - *creditor.account.accountCode*: IBAN o conto SWIFT del creditore. - *creditor.account.bicCode*: codice BIC della banca del creditore. - *creditor.address*: eventuale indirizzo del creditore per conti non‑SEPA. - *creditor.address.address*: via e numero civico. - *creditor.address.city*: città del creditore. - *creditor.address.countryCode*: codice paese ISO 3166‑1 alfa‑2. - *executionDate*: data di esecuzione del bonifico. - *uri*: remittance information verso il creditore. - *description*: descrizione testuale del bonifico. - *amount*: importo del bonifico. - *currency*: valuta utilizzata per l'accredito. - *isUrgent*: indica se il bonifico è urgente. - *isInstant*: indica se il bonifico è istantaneo. - *feeType*: schema delle commissioni (SHA, OUR, BEN). - *feeAccountId*: conto di addebito delle commissioni. - *taxRelief*: informazioni sull’agevolazione fiscale. - *taxRelief.taxReliefId*: identificativo dell’agevolazione. - *taxRelief.isCondoUpgrade*: indica se riguarda parti condominiali. - *taxRelief.creditorFiscalCode*: codice fiscale/partita IVA del creditore. - *taxRelief.beneficiaryType*: tipo di beneficiario. - *taxRelief.naturalPersonBeneficiary*: eventuali beneficiari persone fisiche. - *taxRelief.legalPersonBeneficiary*: eventuale beneficiario persona giuridica. Esempio di risposta: ```text { "creditor": { "name": "John Doe", "account": { "accountCode": "IT23A0336844430152923804660", "bicCode": "SELBIT2BXXX" } }, "debtor": { "name": "", "account": { "accountCode": "IT61F0326802230280596327270", "bicCode": null } }, "description": "Description", "executionDate": "2019-04-01", "feeType": "SHA", "feeAccountId": "12345678", "fees": [ { "feeCode": "MK001", "description": "Money transfer execution fee", "amount": 0.25, "currency": "EUR" }, { "feeCode": "MK003", "description": "Currency exchange fee", "amount": 3.5, "currency": "EUR" } ], "taxRelief": { "taxReliefId": "L449", "description": "Description", "isCondoUpgrade": false, "creditorFiscalCode": "56258745832", "beneficiaryType": "NATURAL_PERSON", "naturalPersonBeneficiary": {}, "legalPersonBeneficiary": {} } } ``` Parametri della risposta: - *creditor*: dati del creditore validati. - *creditor.name*: nome del creditore. - *creditor.account*: dati del conto del creditore. - *creditor.account.accountCode*: IBAN/conto del creditore. - *creditor.account.bicCode*: codice BIC del creditore. - *debtor*: dati del debitore. - *debtor.name*: nome del debitore. - *debtor.account*: informazioni del conto del debitore. - *debtor.account.accountCode*: IBAN del debitore. - *debtor.account.bicCode*: codice BIC del debitore. - *description*: descrizione validata. - *executionDate*: data di esecuzione confermata. - *feeType*: schema delle commissioni applicato. - *feeAccountId*: conto usato per le commissioni. - *fees*: elenco delle commissioni. - *fees\[i].feeCode*: codice della commissione. - *fees\[i].description*: descrizione della commissione. - *fees\[i].amount*: importo della commissione. - *fees\[i].currency*: valuta della commissione. - *taxRelief*: dati dell’agevolazione fiscale. - *taxRelief.taxReliefId*: identificativo dell’agevolazione. - *taxRelief.description*: descrizione dell’agevolazione. - *taxRelief.isCondoUpgrade*: indicazione su parti condominiali. - *taxRelief.creditorFiscalCode*: codice fiscale del creditore. - *taxRelief.beneficiaryType*: tipo di beneficiario. - *taxRelief.naturalPersonBeneficiary*: beneficiari persone fisiche. - *taxRelief.legalPersonBeneficiary*: beneficiario persona giuridica. ## Get Money Transfer Consente di consultare i dettagli di un trasferimento (per esempio, stato dell’operazione, direzione in uscita o in entrata, identificativi di riferimento, importi e valute, eventuali commissioni). È lo strumento per avere visibilità puntuale su una singola operazione già effettuata o programmata. Questo endpoint consente di recuperare tutti i dettagli di un bonifico già creato. È utilizzato per verificare lo stato dell’operazione, ottenere informazioni su importi, valute, soggetti coinvolti, riferimenti CRO/TRN e consultare eventuali commissioni applicate. È utile per attività di riconciliazione contabile, controllo esecuzioni e verifica dell’avvenuto accredito o addebito. Esempio di richiesta: ```text GET /api/gbs/banking/v4.0/accounts/{accountId}/payments/money-transfers/{moneyTransferId} ``` Parametri della richiesta: - *accountId* identificativo del conto da cui è stato eseguito il bonifico. - *moneyTransferId* identificativo univoco del bonifico da recuperare. Esempio di risposta: ```json { "moneyTransferId": "452516859427", "status": "EXECUTED", "direction": "OUTGOING", "creditor": { "name": "John Doe", "account": { "accountCode": "IT23A0336844430152923804660", "bicCode": "SELBIT2BXXX" }, "address": { "address": null, "city": null, "countryCode": null } }, "debtor": { "name": "", "account": { "accountCode": "IT61F0326802230280596327270", "bicCode": null } }, "cro": "1234566788907", "uri": "REMITTANCE_INFORMATION", "trn": "AJFSAD1234566788907CCSFDGTGVGV", "description": "Description", "createdDatetime": "2019-04-10T10:38:55.949+0200", "accountedDatetime": "2019-04-10T10:38:56.000+0200", "debtorValueDate": "2019-04-10", "creditorValueDate": "2019-04-10", "amount": { "debtorAmount": 800, "debtorCurrency": "EUR", "creditorAmount": 800, "creditorCurrency": "EUR", "creditorCurrencyDate": "2019-04-10", "exchangeRate": 1 }, "isUrgent": false, "isInstant": false, "feeType": "SHA", "feeAccountId": "12345678", "fees": [ { "feeCode": "MK001", "description": "Money transfer execution fee", "amount": 0.25, "currency": "EUR" }, { "feeCode": "MK003", "description": "Currency exchange fee", "amount": 3.5, "currency": "EUR" } ], "hasTaxRelief": true } ``` Parametri della risposta: - *moneyTransferId* identificatore del bonifico. - *status* stato dell’operazione (EXECUTED, BOOKED, WORK_IN_PROGRESS, CANCELLED, REJECTED). - *direction* direzione del bonifico (INCOMING o OUTGOING). - *creditor* dati del beneficiario del bonifico. - *creditor.name* nome del beneficiario. - *creditor.account.accountCode* IBAN o conto del beneficiario. - *creditor.account.bicCode* BIC della banca del beneficiario. - *creditor.address.address* indirizzo del beneficiario. - *creditor.address.city* città del beneficiario. - *creditor.address.countryCode* paese del beneficiario (ISO 3166-1 alfa 2). - *debtor* dati dell’ordinante. - *debtor.name* nome dell’ordinante. - *debtor.account.accountCode* IBAN o conto dell’ordinante. - *debtor.account.bicCode* BIC della banca dell’ordinante. - *cro* codice CRO dell’operazione. - *trn* codice TRN dell’operazione. - *uri* informativa di rimessa. - *description* descrizione o causale del bonifico. - *createdDatetime* data/ora di creazione dell’operazione. - *accountedDatetime* data/ora di contabilizzazione. - *debtorValueDate* data valuta per l’ordinante. - *creditorValueDate* data valuta per il beneficiario. - *amount.debtorAmount* importo addebitato all’ordinante. - *amount.debtorCurrency* valuta dell’importo addebitato. - *amount.creditorAmount* importo accreditato al beneficiario. - *amount.creditorCurrency* valuta dell’importo accreditato. - *amount.creditorCurrencyDate* data valuta della valuta del beneficiario. - *amount.exchangeRate* tasso di cambio applicato. - *isUrgent* indica se il bonifico è urgente. - *isInstant* indica se è un bonifico istantaneo SCT-Inst. - *feeType* tipologia di commissione (SHA, OUR, BEN). - *feeAccountId* conto su cui sono addebitate le commissioni. - *fees* elenco delle commissioni applicate. - *hasTaxRelief* indica se è presente agevolazione fiscale. ## Get Money Transfer Accounting Proof Fornisce la prova contabile dell’operazione (una ricevuta/pezza giustificativa utilizzabile ai fini amministrativi). Serve a documentare che il trasferimento è stato contabilizzato, semplificando riconciliazioni e archiviazione. Questo endpoint permette di recuperare la *quietanza contabile* relativa a un bonifico già effettuato. È utile per ottenere una prova ufficiale dell’operazione, da utilizzare per riconciliazioni, verifiche interne o come documento da condividere con terze parti. Esempio di richiesta ```text GET /api/gbs/banking/v4.0/accounts/{accountId}/payments/money-transfers/{moneyTransferId}/accounting-proof ``` Parametri della richiesta: - *accountId* identificativo del conto da cui è partito il bonifico. - *moneyTransferId* identificativo del trasferimento di denaro di cui si vuole recuperare la quietanza. Esempio di risposta (HTTP 200) ```json {} ``` Parametri della risposta: - *(payload vuoto)* l’endpoint restituisce un corpo vuoto in caso di esito positivo, mentre le informazioni rilevanti sono incluse nei metadati o nei documenti scaricabili associati all’operazione. Esempio di risposta (HTTP 400) ```json { "errors": [ { "code": "SZBO-0040", "description": "Superato il range delle date", "params": "" } ] } ``` Parametri della risposta di errore: - *errors* elenco degli errori riscontrati. - *code* codice identificativo dell’errore. - *description* descrizione testuale del problema. - *params* eventuali parametri aggiuntivi utili alla diagnosi. ## Delete Booked Money Transfer Permette di annullare un trasferimento prenotato (cioè programmato per una data futura e non ancora eseguito). È utile quando cambiano le condizioni o si commette un errore prima della data di esecuzione. Questo endpoint consente di eliminare un bonifico precedentemente contabilizzato (booked money transfer). È utile quando occorre revocare un trasferimento di denaro già registrato sul conto, purché le condizioni operative della banca lo permettano. L’endpoint non restituisce un payload specifico, ma conferma l’esito dell’operazione tramite la risposta standard della piattaforma. ```text DELETE /api/gbs/banking/v4.0/accounts/{accountId}/payments/money-transfers/{moneyTransferId} ``` Esempio di richiesta e parametri: ```text DELETE /api/gbs/banking/v4.0/accounts/123456/payments/money-transfers/MT987654 ``` - *accountId* identificativo del conto su cui è stato contabilizzato il bonifico da eliminare - *moneyTransferId* identificativo del bonifico contabilizzato da eliminare Esempio di risposta e parametri: ```json { "status": "OK", "errors": [], "payload": null } ``` - *status* indica l’esito dell’operazione (ad esempio OK in caso di successo) - *errors* contiene eventuali errori restituiti dal sistema, rappresentati come lista - *payload* valore nullo in quanto l’operazione non restituisce un contenuto specifico ## Search Money Transfer Consente di ricercare operazioni già eseguite o programmate in base a criteri come beneficiario, IBAN, importo, valuta e descrizione. È lo strumento per trovare rapidamente pagamenti e verificarne l’esito, anche per concludere controlli a valle di errori o timeout. Questo endpoint consente di cercare i bonifici effettuati o ricevuti su un determinato conto, permettendo di filtrare per direzione, date, importi, controparti, stato e altri criteri. Restituisce l’elenco delle operazioni che soddisfano i parametri impostati. ```text POST /api/gbs/banking/v4.0/accounts/{accountId}/payments/money-transfers/search ``` ```json { "direction": "OUTGOING", "accountedDatetime": { "from": "2019-01-01", "to": "2019-01-31" }, "createdDatetime": { "from": "2019-01-01", "to": "2019-01-31" }, "pagination": { "offset": 0, "limit": 20 }, "status": "EXECUTED", "amount": { "from": 500, "to": 1000 }, "currency": "EUR", "isUrgent": false, "isInstant": false, "counterpartAccount": "string", "counterpartName": "string", "feeType": "SHA", "trn": "string", "cro": "string", "description": "string", "isTaxAdvantage": false } ``` - *direction* direzione del bonifico (INCOMING/OUTGOING). - *accountedDatetime* intervallo delle date di contabilizzazione. - *createdDatetime* intervallo delle date di creazione. - *pagination* indice iniziale e numero massimo di elementi. - *status* stato del bonifico. - *amount* intervallo dell’importo. - *currency* valuta dell’operazione. - *isUrgent* filtro per bonifici urgenti. - *isInstant* filtro per bonifici istantanei. - *counterpartAccount* conto della controparte. - *counterpartName* nome della controparte. - *feeType* tipologia delle commissioni. - *trn* codice TRN dell’operazione. - *cro* codice CRO dell’operazione. - *description* descrizione inserita nel bonifico. - *isTaxAdvantage* indica se è presente agevolazione fiscale. ```json { "list": [ { "moneyTransferId": "452516859427", "status": "EXECUTED", "direction": "OUTGOING", "creditor": { "name": "John Doe", "account": { "account": "IT23A0336844430152923804660", "bicCode": "SELBIT2BXXX" }, "address": { "address": null, "city": null, "countryCode": null } }, "debtor": { "name": "", "account": { "accountCode": "IT61F0326802230280596327270", "bicCode": null } }, "uri": "REMITTANCE_INFORMATION", "trn": "AJFSAD1234566788907CCSFDGTGVGV", "cro": null, "description": "Description", "createdDatetime": "2019-04-10T10:38:55.949+0200", "accountedDatetime": "2019-04-10T10:38:56.000+0200", "debtorValueDate": "2019-04-10", "creditorValueDate": "2019-04-10", "amount": { "debtorAmount": 800, "debtorCurrency": "EUR", "creditorAmount": 800, "creditorCurrency": "EUR", "creditorCurrencyDate": "2019-04-10", "exchangeRate": 1 }, "isUrgent": false, "isInstant": false, "feeType": "SHA", "feeAccountId": "12345678", "fees": [ { "feeCode": "MK001", "description": "Money transfer execution fee", "amount": 0.25, "currency": "EUR" }, { "feeCode": "MK003", "description": "Currency exchange fee", "amount": 3.5, "currency": "EUR" } ], "hasTaxRelief": true } ] } ``` - *moneyTransferId* identificativo dell’operazione. - *status* stato del bonifico. - *direction* direzione dell’operazione. - *creditor* informazioni sul beneficiario. - *debtor* informazioni sull’ordinante. - *uri* informazioni di rimessa. - *trn* codice TRN dell’operazione. - *cro* codice CRO. - *description* descrizione del bonifico. - *createdDatetime* data di creazione. - *accountedDatetime* data di contabilizzazione. - *debtorValueDate* data valuta per il debitore. - *creditorValueDate* data valuta per il creditore. - *amount* valori relativi agli importi e alle valute. - *isUrgent* indica se il bonifico era urgente. - *isInstant* indica se era istantaneo. - *feeType* tipologia delle commissioni. - *feeAccountId* conto da cui sono state prelevate le commissioni. - *fees* lista delle commissioni applicate. - *hasTaxRelief* indica se è presente agevolazione fiscale. ## Revert Money Transfer Avvia una richiesta di annullamento/riaccredito per un trasferimento già impartito, quando il contesto lo consente. È il primo passo del processo di “reversal”, attivato in casi specifici (per esempio un pagamento da stornare). Questo endpoint permette di effettuare il reversal di un bonifico ricevuto. L’operazione crea automaticamente un nuovo bonifico verso il mittente originale, utilizzando in modo vincolante i dati del trasferimento ricevuto (beneficiario, valuta e descrizione). L’utente può solo modificare elementi come data di esecuzione, urgenza, modalità instant, fee e importo da restituire. L’operazione è idempotente, quindi può essere effettuata una sola volta per ciascun bonifico ricevuto. Esempio di request: ```text POST /api/gbs/banking/v4.0/accounts/{accountId}/payments/money-transfers/{moneyTransferId}/revert ``` ```json { "descriptionHeading": "UNDO ", "executionDate": "2020-06-26", "isUrgent": false, "isInstant": false, "feeType": "SHA", "amount": 800 } ``` - *accountId* identificativo del conto sul quale è stato ricevuto il bonifico da stornare. - *moneyTransferId* identificativo del bonifico originale da restituire. - *X-Time-Zone* fuso orario utilizzato per interpretare le date della richiesta. - *descriptionHeading* testo opzionale da anteporre alla descrizione del bonifico originale. - *executionDate* data di esecuzione del bonifico di ritorno; non utilizzabile insieme ai flag urgent o instant. - *isUrgent* indica se il bonifico di ritorno deve essere urgente; incompatibile con executionDate e instant. - *isInstant* indica se il bonifico deve essere istantaneo; incompatibile con executionDate e urgent. - *feeType* modalità di gestione delle commissioni (SHA/OUR/BEN). - *amount* importo da restituire; se omesso viene restituito l’importo totale del bonifico originale. Esempio di risposta ```json { "revertedMoneyTransferId": "452516859427", "moneyTransferId": "452516859428", "status": "EXECUTED", "direction": "OUTGOING", "creditor": { "name": "John Doe", "account": { "accountCode": "IT23A0336844430152923804660", "bicCode": "SELBIT2BXXX" }, "address": { "address": null, "city": null, "countryCode": null } }, "debtor": { "name": "Jane Doe", "account": { "accountCode": "IT61F0326802230280596327270", "bicCode": null }, "feeAccountId": "12345678" }, "cro": "1234566788907", "uri": "REMITTANCE_INFORMATION", "trn": "AJFSAD1234566788907CCSFDGTGVGV", "description": "UNDO Description", "createdDatetime": "2020-06-26T10:38:55.949+0200", "accountedDatetime": "2020-06-26T10:38:56.000+0200", "debtorValueDate": "2020-06-26", "creditorValueDate": "2020-06-26", "amount": { "debtorAmount": 800, "debtorCurrency": "EUR", "creditorAmount": 800, "creditorCurrency": "EUR", "creditorCurrencyDate": "2020-06-26", "exchangeRate": 1 }, "isUrgent": false, "isInstant": false, "feeType": "SHA", "fees": [ { "feeCode": "MK001", "description": "Money transfer execution fee", "amount": 0.25, "currency": "EUR" } ] } ``` - *revertedMoneyTransferId* identificativo del bonifico originale che è stato stornato. - *moneyTransferId* identificativo del nuovo bonifico creato come restituzione. - *status* stato del bonifico (EXECUTED, BOOKED, ecc.). - *direction* direzione del trasferimento (INCOMING/OUTGOING). - *creditor* informazioni sul creditore del bonifico di ritorno. - *debtor* informazioni sul debitore del bonifico di ritorno. - *cro* codice CRO del bonifico. - *trn* codice TRN del bonifico. - *uri* informazioni di rimessa. - *description* descrizione del bonifico risultante. - *createdDatetime* data e ora di creazione del bonifico di ritorno. - *accountedDatetime* data e ora di contabilizzazione. - *debtorValueDate* data valuta debitore. - *creditorValueDate* data valuta creditore. - *amount* dettagli relativi all’importo e alla valuta. - *isUrgent* indica se il bonifico è urgente. - *isInstant* indica se il bonifico è instant. - *feeType* tipologia di commissioni applicata. - *fees* elenco delle commissioni applicate. ## Get Revert Money Transfer Consente di verificare lo stato di una richiesta di annullamento/riaccredito precedentemente avviata, monitorando l’avanzamento fino alla chiusura. Questo endpoint consente di ottenere i dettagli completi relativi a un trasferimento di denaro che è stato stornato. È pensato per permettere ai sistemi client di verificare lo stato dell’operazione, comprendere le motivazioni dello storno e recuperare tutte le informazioni utili per la riconciliazione contabile o la gestione operativa. Esempio di richiesta: ```text GET /api/v1/money-transfer/reverted/{transferId} ``` Parametri della richiesta: - *transferId* identificativo univoco del trasferimento di denaro di cui si desiderano recuperare i dettagli Esempio di risposta: ```json { "transferId": "MT-9845321", "originalAmount": 250.00, "currency": "EUR", "revertedAt": "2026-01-28T14:55:00Z", "reason": "IBAN non valido", "status": "reverted", "beneficiary": { "name": "Mario Rossi", "account": "IT60X0542811101000000123456" } } ``` Parametri della risposta: - *transferId* identificativo del trasferimento stornato - *originalAmount* importo originale del trasferimento - *currency* valuta dell’importo trasferito - *revertedAt* data e ora in cui il trasferimento è stato stornato - *reason* motivazione dello storno, così come registrata dal sistema - *status* stato del trasferimento, valorizzato come "reverted" per indicare l’avvenuto storno - *beneficiary* oggetto contenente le informazioni sul beneficiario originario del trasferimento - *name* nome del beneficiario (all’interno di *beneficiary*) - *account* conto del beneficiario (all’interno di *beneficiary*) ## Challenge Response Completa un passaggio di conferma richiesto in alcuni flussi (per esempio una sfida/approvazione addizionale). In pratica, serve a fornire la risposta alla richiesta di conferma, così che l’operazione possa proseguire e concludersi correttamente. L’endpoint consente di confermare una richiesta di bonifico sospesa a seguito di una challenge di sicurezza. L’endpoint riceve il canale tramite cui è stata inviata la challenge e il codice di risposta fornito dall’utente, e restituisce i dettagli aggiornati del bonifico. Esempio di richiesta ```text PUT /api/gbs/banking/v4.0/accounts/{accountId}/payments/money-transfers/challenges/{challengeId} ``` ```json { "channel": "SMS", "response": "123456" } ``` Parametri della richiesta: - *channel* indica il canale tramite cui la challenge è stata inviata all’utente. Valori ammessi: SMS, RSA. - *response* rappresenta il codice di risposta alla challenge fornito dall’utente. Esempio di risposta ```json { "moneyTransferId": "452516859427", "status": "EXECUTED", "direction": "OUTGOING", "creditor": { "name": "John Doe", "account": { "account": "IT23A0336844430152923804660", "bicCode": "SELBIT2BXXX" }, "address": { "address": null, "city": null, "countryCode": null } }, "debtor": { "name": "", "account": { "accountCode": "IT61F0326802230280596327270", "bicCode": null } }, "cro": "1234566788907", "uri": "REMITTANCE_INFORMATION", "trn": "AJFSAD1234566788907CCSFDGTGVGV", "description": "Description", "createdDatetime": "2019-04-10T10:38:55.949+0200", "accountedDatetime": "2019-04-10T10:38:56.000+0200", "debtorValueDate": "2019-04-10", "creditorValueDate": "2019-04-10", "amount": { "debtorAmount": 800, "debtorCurrency": "EUR", "creditorAmount": 800, "creditorCurrency": "EUR", "creditorCurrencyDate": "2019-04-10", "exchangeRate": 1 }, "isUrgent": false, "isInstant": false, "feeType": "SHA", "feeAccountId": "12345678", "fees": [ { "feeCode": "MK001", "description": "Money transfer execution fee", "amount": 0.25, "currency": "EUR" }, { "feeCode": "MK003", "description": "Currency exchange fee", "amount": 3.5, "currency": "EUR" } ], "hasTaxRelief": true } ``` Parametri della risposta: - *moneyTransferId* identifica univocamente il bonifico confermato. - *status* indica lo stato aggiornato del bonifico (EXECUTED, BOOKED, REJECTED, ecc.). - *direction* indica la direzione del trasferimento (INCOMING o OUTGOING). - *creditor* contiene i dati del beneficiario. - *creditor.name* nome del beneficiario. - *creditor.account.accountCode* numero di conto del beneficiario (IBAN o SWIFT). - *creditor.account.bicCode* codice BIC della banca del beneficiario. - *debtor* contiene i dati dell’ordinante. - *debtor.account.accountCode* numero del conto dell’ordinante. - *cro* codice CRO del bonifico. - *uri* informazioni di rimessa. - *trn* codice TRN assegnato al bonifico. - *description* descrizione fornita durante l’operazione. - *createdDatetime* data e ora di creazione. - *accountedDatetime* data e ora di contabilizzazione. - *debtorValueDate* data valuta per l’ordinante. - *creditorValueDate* data valuta per il beneficiario. - *amount.debtorAmount* importo addebitato all’ordinante. - *amount.creditorAmount* importo accreditato al beneficiario. - *isUrgent* indica se il bonifico è urgente. - *isInstant* indica se è un bonifico istantaneo SCT‑Inst. - *feeType* modalità di gestione delle commissioni (SHA, OUR, BEN). - *feeAccountId* conto su cui vengono addebitate le commissioni. - *fees* elenco delle commissioni applicate. - *hasTaxRelief* indica se sono presenti dati per agevolazioni fiscali.