API

In questo documento puoi trovare la descrizione degli endpoint del prodotto Money Transfer.

Flusso

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

POST /api/gbs/banking/v4.1/accounts/{accountId}/payments/money-transfers

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

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

POST /api/gbs/banking/v4.0/accounts/{accountId}/payments/money-transfers/validate

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

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

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:

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

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)

{}

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)

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

DELETE /api/gbs/banking/v4.0/accounts/{accountId}/payments/money-transfers/{moneyTransferId}

Esempio di richiesta e parametri:

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:

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

POST /api/gbs/banking/v4.0/accounts/{accountId}/payments/money-transfers/search

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

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

POST /api/gbs/banking/v4.0/accounts/{accountId}/payments/money-transfers/{moneyTransferId}/revert

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

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

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:

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

PUT /api/gbs/banking/v4.0/accounts/{accountId}/payments/money-transfers/challenges/{challengeId}

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

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

Flusso​

Create Money Transfer​

Validate Money Transfer​

Get Money Transfer​

Get Money Transfer Accounting Proof​

Delete Booked Money Transfer​

Search Money Transfer​

Revert Money Transfer​

Get Revert Money Transfer​

Challenge Response​

Flusso

Create Money Transfer

Validate Money Transfer

Get Money Transfer

Get Money Transfer Accounting Proof

Delete Booked Money Transfer

Search Money Transfer

Revert Money Transfer

Get Revert Money Transfer

Challenge Response