<<ach2>> Payments

<<ach2>> is an electronic network for processing batches of debit and credit transactions between financial institutions in the USA. It is administered by the National Clearing House Association (NACHA).

The network can be used for the electronic transfer of funds between accounts. It is used for Direct Payment via <<ach2>> (e.g. a recurring mortgage payments or an online consumer purchase) and Direct Deposit via <<ach2>> (e.g. payroll payments, a refund made for an online purchase or a B2B payment).

The gateway allows you to process Direct Payments (payments) and Direct Deposits (refunds) via <<ach2>>.

This page describes the requirements for processing <<ach2>> payments via the Tyro eCommerce Payment Gateway and provides an overview of the payment flow and details about the supported Web Services Integration operations for <<ach2>> payments.

Tyro eCommerce Payment Gateway supports <<ach2>> Payments in Web Services Integration version 26 and later.

Prerequisites

You must have an <<ach2>> account configured with an <<ach2>> acquirer.

NACHA imposes a range of requirements on merchants; over and above those applicable to other payment methods, such as cards.
  1. You must obtain explicit customer authorization before <<ach2>> settlement can take place.
  2. Since <<ach2>> is not a real-time network, returns can still take place even after the payment request has been submitted to the Tyro eCommerce Payment Gateway.
  3. You must adhere to NACHA regulations. Compliance failure can carry substantial penalties. To keep up to date with current regulations, visit https://www.nacha.org/
  4. You must establish, implement and update policies, procedures and systems related to the initiation, processing and storage of entries, in order to:

    • Ensure information confidentiality.
    • Protect against threats to information security.
    • Protect against unauthorized information use.

<<ach2>> Data Flow

ACH Payment Flow

  1. The payer authorizes the payment or deposit.

    NACHA-permitted Standard Entry Codes (SEC) are:

    • TEL. Telephone-initiated entry.
    • WEB. Web-initiated entry.
    • PPD. Prearranged payment and deposits.
  2. The merchant sends a transaction request to the Tyro eCommerce Payment Gateway.

    Requests may be PAY, REFUND or VOID.

  3. Tyro eCommerce Payment Gateway issues a response containing status information (e.g. APPROVED_PENDING_SETTLEMENT).

    The transaction is added to the current batch for settlement.

    The batch of transactions is closed in one of two ways:

    • Once per day at the configured time.
    • By you closing the currently-open batch by submitting an Web Services IntegrationCLOSE_BATCH request. Any subsequent transactions will be added to a new batch.

    At the end of the day, all closed batches that have not yet been submitted are collected into a settlement file and transmitted to the <<ach2>> Acquirer.

  4. The <<ach2>> Acquirer issues an immediate response, containing the validation result of the transmitted data (e.g. APPROVED or DECLINED), and submits the payment requests to the <<ach2>> network for processing.

    Notes:

    • An APPROVED status issued by the <<ach2>> Acquirer merely implies validated acceptance of the transmission for further processing; not an actual approval of the financial transaction.
    • To be notified of the <<ach2>> Acquirer response, subscribe to Webhook Notifications.
      •
  5. The <<ach2>> network manages the payment transactions between the applicable fincancial institutions.
  6. After a delay of up to 3 days, the <<ach2>> Network sends an exception report of unapproved payment requests to the <<ach2>> Acquirer, who will provide it for you .

Integrating <<ach2>> Payments

There are three options to integrate <<ach2>> payments into your payment page:

<<ach2>> via Hosted Checkout

If you have an existing Hosted Checkout integration, you can use Hosted Checkout to verify the <<ach2>> payment details.

You can do this by setting interaction.operation=VERIFY in the Create Checkout Session request. Hosted Checkout displays <<ach2>> payments as a payment option to the payer. The data entered by the payer is verified using the verification methods supported by the configured acquirer.

You can determine the success of the verification operation by comparing resultIndicator to successIndicator. If the interaction was not successful, Hosted Checkout displays a message indicating that verification has failed and prompts the payer to try again.

<<ach2>> via Hosted Session

If you have your own payment page then you can choose the Hosted Session integration option to have the Tyro eCommerce Payment Gateway securely capture the <<ach2>> payment details and store them into a payment session.

Sample Code to Collect <<ach2>> Payment Details
<html>
<head>
<!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY -->
<script src="https://tyro.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. Include the session.js client JavaScript library hosted by the gateway in your payment page. The path to this file includes both the api version and the merchant identifier for the session.
  2. Create the HTML for the payment page containing the <<ach2>> payment fields.
    To prevent submission of sensitive data to the server, ensure the sensitive data fields are readonly and do NOT have the name attribute.
  3. Invoke PaymentSession.configure(configuration) function.

    The configuration object allows you to attach hosted fields to your payment page. You need to provide the following:

    • session(optional), if you do not provide one, the client library creates a payment session.
    • field selectors for <<ach2>> payment fields, which when provided are replaced with corresponding proxy fields embedded in iFrames hosted by the Tyro eCommerce Payment Gateway. The proxy fields will have the same look and feel as the replaced fields.
    • mitigation option(s) for clickjacking prevention

      Clickjacking, also known as a "UI redress attack", is when an attacker uses multiple transparent or opaque layers to trick a user into clicking on a button or link on another page when they were intending to click on the top level page. To use Hosted Session, you must implement one or more of the following defenses against clickjacking attacks.

      Frame Mitigation Option Implementation
      javascript include "frame-breaker" JavaScript in your payment page.
      x-frame-options your server should return an X-Frame Options HTTP response header.
      csp your server should return Content-Security-Policy HTTP response header containing a frame-ancestors directive.

      You must specify which defenses are implemented via the frameEmbeddingMitigation parameter in the PaymentSession.configure(configuration) call. For information on defending against clickjacking attacks, see Clickjacking Defense Cheat Sheet on the OWASP External Website.

    • callbacks for handling various events during the Hosted Session interaction
      • initialized( ): invoked when the hosted fields attach to your payment page.
      • formSessionUpdate( ): invoked in response to the PaymentSession.updateSessionFromForm('ach') function (see next step)

  4. Invoke PaymentSession.updateSessionFromForm('ach') to store the collected <<ach2>> details into a payment session. Once the operation completes, formSessionUpdate( ) callback is invoked with a result parameter. You must check the result.status value to determine if the operation was successful. See Handle Callback Responses.
  5. You can use the returned payment session (session.id) to perform a tokenization or a payment transaction when required. For more information, see Perform an Operation Using the Session.

session.js Reference[JavaScript]

<<ach2>> via Direct Payment

You can submit <<ach2>> payment details directly to the Tyro eCommerce Payment Gateway using the following operations.

Payments and Refunds

You initiate an <<ach2>> payment by submitting an Web Services IntegrationPAY request, and a refund by submitting an Web Services IntegrationREFUND request.

Ensure that you include the following information in your request:

  • sourceOfFunds.type = ACH.
  • sourceOfFunds.provided.ach.routingNumber: The payer's bank routing number.
  • sourceOfFunds.provided.ach.bankAccountNumber: The payer's bank account number.
  • sourceOfFunds.provided.ach.bankAccountHolder: The payer's account holder name.
  • sourceOfFunds.provided.ach.accountType: The payer's bank account type.
  • sourceOfFunds.provided.ach.secCode: The SEC code for the <<ach2>> payment applicable to this transaction.

    The SEC code must be one of:

    • TEL: An <<ach2>> Debit entry for a B2C payment authorized by the customer via the telephone. TEL may only be used when a relationship already exists between you and the payer or, when there is not an existing relationship, the payer initiates the contact with you.
    • WEB: An <<ach2>> Debit entry for a B2C payment authorized via the internet or a wireless network.
    • PPD: An <<ach2>> Debit or Credit entry based on an authenticated authorization provided by a payer. PPD is used for B2C payments (e.g. employee payroll, mortgage payments, or expense reimbursement).

Pay API Reference [REST][NVP]

Refund API Reference [REST][NVP]

Void

You can void the previous transaction on an order by submitting an Web Services IntegrationVOID request for the order with the target transaction ID parameter referencing the PAY or REFUND request.

For a successful Web Services IntegrationVOID request, the referenced target transaction is removed from the batch and therefore will not be submitted to the <<ach2>> Acquirer.

Transactions can no longer be voided once the batch containing the referenced target transaction has been closed for settlement (i.e. settlement is in progress) or has already been settled.

Void API Reference [REST][NVP]

Verify

You can verify the payment details for an <<ach2>> payment by submitting an Web Services IntegrationVERIFY request.

Currently, the Tyro eCommerce Payment Gateway only supports semantic verification of the ACH payment details, but does not verify that the account is a valid bank account and the bank participates in <<ach2>>.

Verify API Reference [REST][NVP]

Batch Management and Settlement

You can control batch closure by submitting an Web Services IntegrationCLOSE_BATCH request with the acquirer ID for your <<ach2>> acquirer. The acquirer ID is provided in transaction.acquirer.id in the transaction response.

As a result, the current <<ach2>> Acquirer batch in the Tyro eCommerce Payment Gateway will be closed. Subsequent <<ach2>> transactions will be added to a new the Tyro eCommerce Payment Gateway-internal batch.

Reconciliation

The Retrieve Transaction response for successful <<ach2>> transactions contains the identifier for the transaction that the acquirer uses in transaction.receipt.

The Paymentech Salem <<ach2>> acquirer uses the same transaction identifier for all transactions of an order.

This identifier will be used in the Exception Detail Report provided by the Paymentech Salem <<ach2>> acquirer. This contains all unsuccessful <<ach2>> transactions and can be used to reconcile your payments.

The transaction status provided by the gateway (response.gatewayCode) is not updated with the actual response from the <<ach2>> network.

Testing <<ach2>> Transactions

You can test your integration using your TEST merchant profile.

The Tyro eCommerce Payment Gateway provides an emulator that will return a response with response.gatewayCode=APPROVED for all valid requests for <<ach2>> payments.

Copyright © 2023 Tyro Payments