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 Payment Gateway, viene presentata una panoramica del flusso di pagamento e vengono forniti dettagli sulle operazioni API supportate per i pagamenti Automated Clearing House.

MasterCard Payment Gateway supporta i pagamenti Automated Clearing House in API versione 26 e successive.

Prerequisiti

È necessario disporre di un conto Automated Clearing House configurato con un acquirer Automated Clearing House.

NACHA impone una gamma di requisiti per gli esercenti, oltre a quelli applicabili alle altre modalità di pagamento, come le carte di credito.
  1. È necessario ottenere l'autorizzazione esplicita del cliente prima di poter eseguire il trasferimento fondi Automated Clearing House.
  2. 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 Payment Gateway.
  3. È 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/
  4. È 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

Flusso di pagamento ACH

  1. 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 Web
    • PPD. Pagamenti e depositi preordinati.
  2. L'esercente invia una richiesta di transazione al MasterCard Payment Gateway.

    Le richieste possono essere PAY, REFUND o VOID.

  3. MasterCard Payment 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 APICLOSE_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.

  4. L'acquirer Automated Clearing House emette una risposta immediata contenente il risultato della validazione dei dati trasmessi (ad esempio APPROVED o DECLINED) 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.
  5. La rete Automated Clearing House gestisce le transazioni di pagamento tra gli istituti finanziari applicabili.
  6. 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:

Automated Clearing House mediante Hosted Checkout

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.

Automated Clearing House mediante Hosted Session

Se si dispone di una pagina di pagamento personale, è possibile scegliere l'opzione di integrazione Hosted Session per consentire a MasterCard Payment Gateway di acquisire in modo sicuro i dettagli di pagamento Automated Clearing House e archiviarli in una sessione di pagamento.

Codice di esempio per raccogliere dettagli di pagamento Automated Clearing House
<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>
   
  1. 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.
  2. 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 siano readonly e che NON presentino l'attributo name .
  3. 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 Payment 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 chiamata PaymentSession.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 funzione PaymentSession.updateSessionFromForm('ach') (vedere il passaggio successivo)

  4. 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 callback formSessionUpdate( ) con un parametro dei risultati. È necessario verificare il valore result.status per stabilire se l'operazione è riuscita. Vedere Gestione delle risposte di callback.
  5. È 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]

Automated Clearing House mediante Direct Payment

È possibile inviare i dettagli di pagamento Automated Clearing House direttamente a MasterCard Payment Gateway utilizzando le operazioni indicate di seguito.

Pagamenti e rimborsi

È possibile avviare un pagamento Automated Clearing House inviando una richiesta APIPAY e un rimborso inviando una richiesta APIREFUND.

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

Riferimento API per Pay [REST][NVP]

Riferimento API per Refund [REST][NVP]

Void

È possibile annullare la transazione precedente in un ordine inviando una richiesta APIVOID per l'ordine con il parametro ID transazione di destinazione che fa riferimento alla richiesta PAY o REFUND.

Per una richiesta APIVOID 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.

Riferimento API per Void [REST][NVP]

Verify

È possibile verificare i dettagli di pagamento di Automated Clearing House inviando una richiesta APIVERIFY.

Attualmente MasterCard Payment 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.

Riferimento API per Verify [REST][NVP]

Gestione e trasferimento fondi batch

È possibile controllare la chiusura del batch inviando una richiesta APICLOSE_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 Payment Gateway verrà chiuso. Le transazioni Automated Clearing House successive verranno aggiunte a un nuovo batch di MasterCard Payment 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.

L'acquirer Automated Clearing House Paymentech Salem usa lo stesso identificativo di transazione per tutte le transazioni di un ordine.

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 Payment Gateway fornisce un simulatore che restituisce una risposta con response.gatewayCode=APPROVED per tutte le richieste valide per i pagamenti Automated Clearing House.

Copyright © 2023 MasterCard