- Linee guida per l'integrazione
- Funzionalità supportate (modalità di pagamento)
- Automated Clearing House Pagamenti
Pagamenti Automated Clearing House
Automated Clearing House è una rete elettronica per l'elaborazione di batch di transazioni di addebito e di credito tra gli istituti finanziari negli Stati Uniti. È gestita dalla National Clearing House Association (NACHA).
La rete può essere utilizzata per il trasferimento elettronico di fondi tra conti. Viene utilizzata per Direct Payment mediante Automated Clearing House (ad esempio i pagamenti periodici di crediti ipotecari o un acquisto online) e il deposito diretto mediante Automated Clearing House (ad esempio pagamenti di salari, un rimborso per un acquisto online o un pagamento B2B).
Il gateway consente di elaborare i pagamenti diretti (pagamenti) e i depositi diretti (rimborsi) mediante Automated Clearing House.
In questa pagina vengono descritti i requisiti necessari per l'elaborazione dei pagamenti Automated Clearing House mediante il Mastercard Gateway, viene presentata una panoramica del flusso di pagamento e vengono forniti dettagli sulle operazioni DirectAPI supportate per i pagamenti Automated Clearing House.
Prerequisiti
È necessario disporre di un conto Automated Clearing House configurato con un acquirer Automated Clearing House.
- È necessario ottenere l'autorizzazione esplicita del cliente prima di poter eseguire il trasferimento fondi Automated Clearing House.
- Dal momento che Automated Clearing House non è una rete in tempo reale, possono verificarsi restituzioni anche dopo che la richiesta di pagamento è stata inviata al Mastercard Gateway.
- È necessario rispettare le normative NACHA. Errori di conformità possono comportare penali consistenti. Per restare aggiornati sulle normative correnti, visitare il sito https://www.nacha.org/
- È necessario stabilire, implementare e aggiornare politiche, procedure e sistemi correlati all'avvio, all'elaborazione e all'archiviazione delle voci al fine di:
- Garantire la riservatezza delle informazioni.
- Proteggere dalle minacce la sicurezza delle informazioni.
- Proteggere le informazioni dall'uso non autorizzato.
Flusso di dati Automated Clearing House
- Il pagante autorizza il pagamento o il deposito.
I codici SEC (Standard Entry Codes) consentiti da NACHA sono:
TEL
. Immissione tramite telefono.WEB
. Immissione tramite WebPPD
. Pagamenti e depositi preordinati.
- L'esercente invia una richiesta di transazione al Mastercard Gateway.
Le richieste possono essere
PAY
,REFUND
oVOID
. - Mastercard Gateway emette una risposta contenente informazioni sullo stato (ad esempio
APPROVED_PENDING_SETTLEMENT
).La transazione viene aggiunta al batch corrente per il trasferimento fondi.
Il batch delle transazioni viene chiuso in uno dei due modi seguenti:
- Una volta al giorno all'orario configurato.
- Dall'esercente, chiudendo il batch attualmente aperto inviando una richiesta DirectAPI
CLOSE_BATCH
. Le transazioni successive verranno aggiunte a un nuovo batch.
Alla fine della giornata, tutti i batch chiusi che non sono stati inviati vengono raccolti in un file di trasferimento fondi e trasmessi all'acquirer Automated Clearing House.
- L'acquirer Automated Clearing House emette una risposta immediata contenente il risultato della validazione dei dati trasmessi (ad esempio
APPROVED
oDECLINED
) e invia le richieste di pagamento alla rete Automated Clearing House per l'elaborazione.Note:
- L'esito
APPROVED
emesso dall'acquirer Automated Clearing House implica semplicemente l'accettazione convalidata della trasmissione per ulteriore elaborazione; non l'approvazione effettiva della transazione finanziaria. - Per ricevere notifica della risposta dell'acquirer Automated Clearing House, effettuare la sottoscrizione alle notifiche Webhook.
- L'esito
- La rete Automated Clearing House gestisce le transazioni di pagamento tra gli istituti finanziari applicabili.
- Dopo un ritardo di un massimo di 3 giorni, la rete Automated Clearing House invia un report delle eccezioni delle richieste di pagamento non approvate all'acquirer Automated Clearing House che, a sua volta, le fornisce all'esercente.
Integrazione dei pagamenti Automated Clearing House
Sono disponibili tre opzioni che consentono di integrare i pagamenti Automated Clearing House nella pagina di pagamento:
Se si dispone di un'integrazione Hosted Checkout, è possibile utilizzare Hosted Checkout per verificare i dettagli di pagamento di Automated Clearing House.
È possibile eseguire questa operazione impostando interaction.operation=VERIFY
nella richiesta Create Checkout Session. Hosted Checkout visualizza i pagamenti Automated Clearing House come opzione di pagamento per il pagante. I dati immessi dal pagante vengono verificati utilizzando i metodi di verifica supportati dall'acquirer configurato.
È possibile verificare se l'operazione di verifica ha avuto esito positivo confrontando i parametri resultIndicator
e successIndicator
. Se l'interazione non è riuscita, Hosted Checkout visualizza un messaggio per comunicare l'esito negativo della verifica e chiedere al pagante di riprovare l'operazione.
Se si dispone di una pagina di pagamento personale, è possibile scegliere l'opzione di integrazione Hosted Session per consentire a Mastercard Gateway di acquisire in modo sicuro i dettagli di pagamento Automated Clearing House e archiviarli in una sessione di pagamento.
<html> <head> <!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY --> <script src="https://eu-gateway.mastercard.com/form/version/72/merchant/<MERCHANTID>/session.js"></script> <!-- APPLY CLICK-JACKING STYLING AND HIDE CONTENTS OF THE PAGE --> <style id="antiClickjack">body{display:none !important;}</style> </head> <body> <!-- CREATE THE HTML FOR THE PAYMENT PAGE --> <div>Please enter your Automated Clearing House details:</div> <div> <label class="control-label" id="ach-account-type-label">Account Type:</label> <select class="form-control col-sm-6" name="ach-account-type" id="ach-account-type"> <option value="CONSUMER_SAVINGS">Consumer Savings Account</option> <option value="CONSUMER_CHECKING" selected>Consumer Checking Account</option> <option value="CORPORATE_CHECKING">Business Checking Account</option> </select> </div> <div>Bank Account Holder: <input type="text" id="ach-account-holder" class="input-field" value="" readonly></div> <div>Bank Account Number:<input type="text" id="ach-account-number" class="input-field" value="" readonly></div> <div>Routing Number:<input type="text" id="ach-routing-number" class="input-field" value="" readonly></div> <div><button id="payButton" onclick="pay();">Pay Now</button></div> <!-- JAVASCRIPT FRAME-BREAKER CODE TO PROVIDE PROTECTION AGAINST IFRAME CLICK-JACKING --> <script type="text/javascript"> if (self === top) { var antiClickjack = document.getElementById("antiClickjack"); antiClickjack.parentNode.removeChild(antiClickjack); } else { top.location = self.location; } PaymentSession.configure({ fields: { // ATTACH HOSTED FIELDS TO YOUR PAYMENT PAGE FOR ACH ach: { accountType: "#ach-account-type", bankAccountHolder: "#ach-account-holder", bankAccountNumber: "#ach-account-number", routingNumber: "#ach-routing-number" } }, //SPECIFY YOUR MITIGATION OPTION HERE frameEmbeddingMitigation: ["javascript"], callbacks: { initialized: function(response) { // HANDLE INITIALIZATION RESPONSE }, formSessionUpdate: function(response) { // HANDLE RESPONSE FOR UPDATE SESSION if (response.status) { if ("ok" == response.status) { console.log("Session updated with data: " + response.session.id); } else if ("fields_in_error" == response.status) { console.log("Session update failed with field errors."); if (response.errors.bankAccountHolder) { console.log("Bank account holder invalid."); } if (response.errors.bankAccountNummber) { console.log("Bank account number invalid."); } if (response.errors.routingNumber) { console.log("Routing number invalid."); } } else if ("request_timeout" == response.status) { console.log("Session update failed with request timeout: " + response.errors.message); } else if ("system_error" == response.status) { console.log("Session update failed with system error: " + response.errors.message); } } else { console.log("Session update failed: " + response); } } } }); function pay() { // UPDATE THE SESSION WITH THE INPUT FROM HOSTED FIELDS PaymentSession.updateSessionFromForm('ach'); } </script> </body> </html>
- Includere nella pagina di pagamento la libreria Javascript lato client
session.js
ospitata dal gateway. Il percorso di questo file include sia la versione api sia l'identificativo esercente per la sessione. - Creare il file HTML per la pagina di pagamento contenente i campi di pagamento Automated Clearing House.
Per evitare l'invio di dati sensibili al server, verificare che i campi relativi sianoreadonly
e che NON presentino l'attributoname
. - Richiamare la funzione
PaymentSession.configure(configuration)
.
L'oggetto
configuration
consente di allegare campi ospitati alla pagina di pagamento. È necessario specificare le seguenti informazioni:
- Sessione (facoltativo). Se non si specifica, la libreria di client crea una sessione di pagamento.
- Selettori di campi per i campi di pagamento Automated Clearing House che, se forniti, vengono sostituiti dai campi proxy corrispondenti incorporati in iFrame ospitati da Mastercard Gateway. I campi proxy avranno lo stesso aspetto di quelli sostituiti.
-
Opzioni di mitigazione per la prevenzione del clickjacking
Il clickjacking, noto anche come "rapimento del clic", si verifica quando l'autore dell'attacco usa più livelli trasparenti o opachi per indurre un utente a fare clic su un pulsante o su un collegamento di una pagina credendo di fare clic sulla pagina del livello principale. Per utilizzare Hosted Session, è necessario implementare una o più difese contro gli attacchi di clickjacking tra quelle indicate di seguito.
Opzione di mitigazione dei frame Implementazione javascript
Includere il JavaScript "frame-breaker" nella pagina di pagamento. x-frame-options
Il server deve restituire un'intestazione della risposta HTTP X-Frame Options. csp
Il server deve restituire l'intestazione della risposta HTTP Content-Security-Policy contenente una direttiva frame-ancestors. È necessario specificare le difese implementate mediante il parametro
frameEmbeddingMitigation
nella chiamataPaymentSession.configure(configuration)
. Per informazioni su come difendersi dagli attacchi di clickjacking, vedere Clickjacking Defense Cheat Sheet nel sito Web OWASP esterno. -
Callback per la gestione di vari eventi durante l'interazione di Hosted Session
initialized( )
: richiamata quando vengono allegati i campi ospitati alla pagina di pagamento.formSessionUpdate( )
: richiamata in risposta alla funzionePaymentSession.updateSessionFromForm('ach')
(vedere il passaggio successivo)
- Richiamare
PaymentSession.updateSessionFromForm('ach')
per archiviare in una sessione di pagamento i dettagli Automated Clearing House raccolti. Una volta completata l'operazione, viene richiamato il callbackformSessionUpdate( )
con un parametro dei risultati. È necessario verificare il valoreresult.status
per stabilire se l'operazione è riuscita. Vedere Gestione delle risposte di callback. - È possibile utilizzare la sessione di pagamento restituita (session.id) per eseguire una tokenizzazione o una transazione di pagamento quando richiesto. Per ulteriori informazioni, vedere Eseguire un'operazione usando la sessione
Riferimento per session.js[JavaScript]
È possibile inviare i dettagli di pagamento Automated Clearing House direttamente a Mastercard Gateway utilizzando le operazioni indicate di seguito.
È possibile avviare un pagamento Automated Clearing House inviando una richiesta DirectAPIPAY
e un rimborso inviando una richiesta DirectAPIREFUND
.
Assicurarsi di includere le seguenti informazioni nella richiesta:
sourceOfFunds.type = ACH.
sourceOfFunds.provided.ach.routingNumber
: Le coordinate bancarie del pagante.sourceOfFunds.provided.ach.bankAccountNumber
: Il numero di conto corrente bancario del pagante.sourceOfFunds.provided.ach.bankAccountHolder
: Il nome del titolare del conto del pagante.sourceOfFunds.provided.ach.accountType
: Il tipo di conto corrente bancario del pagante.sourceOfFunds.provided.ach.secCode
: Il codice SEC per il pagamento Automated Clearing House applicabile a questa transazione.Il codice SEC deve essere uno dei valori seguenti:
TEL
: Una voce di addebito Automated Clearing House per un pagamento B2C autorizzato dal cliente tramite telefono. TEL può essere utilizzato solo quando già esiste un accordo tra l'esercente e il pagante oppure, in assenza di un accordo tra l'esercente e il pagante, quando il pagante avvia il contatto con l'esercente.WEB
: Una voce di addebito Automated Clearing House per un pagamento B2C autorizzato via Internet o mediante una rete wireless.PPD
: Una voce di addebito o di credito Automated Clearing House basata su un'autorizzazione di autenticazione fornita da un pagante. Il PPD viene utilizzato per i pagamenti B2C (ad esempio salari dei dipendenti, pagamenti di crediti ipotecari o rimborsi spese).
È possibile annullare la transazione precedente in un ordine inviando una richiesta DirectAPIVOID
per l'ordine con il parametro ID transazione di destinazione che fa riferimento alla richiesta PAY
o REFUND
.
Per una richiesta DirectAPIVOID
con esito positivo, la transazione di destinazione di riferimento viene rimossa dal batch, pertanto non verrà inviata all'acquirer Automated Clearing House.
Una volta che è stato chiuso il batch contenente la transazione di destinazione di riferimento per il trasferimento fondi (ad esempio il trasferimento fondi è in corso) o il trasferimento fondi è stato già completato, non è più possibile annullare le transazioni.
È possibile verificare i dettagli di pagamento di Automated Clearing House inviando una richiesta DirectAPIVERIFY
.
Attualmente Mastercard Gateway supporta solo la verifica semantica dei dettagli di pagamento ACH, ma non verifica la validità del conto bancario e la partecipazione della banca in Automated Clearing House.
Gestione e trasferimento fondi batch
È possibile controllare la chiusura del batch inviando una richiesta DirectAPICLOSE_BATCH
con l'ID acquirer per l'acquirer Automated Clearing House. L'ID acquirer viene fornito in transaction.acquirer.id
nella risposta di transazione.
Di conseguenza, il batch dell'acquirer Automated Clearing House corrente in Mastercard Gateway verrà chiuso. Le transazioni Automated Clearing House successive verranno aggiunte a un nuovo batch di Mastercard Gateway interno.
Riconciliazione
La risposta dell'operazione Retrieve Transaction per le transazioni Automated Clearing House eseguite correttamente contiene l'identificativo per la transazione utilizzata dall'acquirer in transaction.receipt
.
Tale identificativo verrà utilizzato nel report dei dettagli dell'eccezione fornito dall'acquirer Automated Clearing House Paymentech Salem. Contiene tutte le transazioni Automated Clearing House non riuscite e può essere utilizzato per riconciliare i pagamenti.
Il codice (response.gatewayCode
) dell'esito della transazione fornito dal gateway non viene aggiornato con la risposta corrente della rete Automated Clearing House.
Test delle transazioni Automated Clearing House
È possibile testare l'integrazione utilizzando il profilo esercente di TEST.
Il Mastercard Gateway fornisce un simulatore che restituisce una risposta con response.gatewayCode=APPROVED
per tutte le richieste valide per i pagamenti Automated Clearing House.