ACH Internet Payment Guide using Transaction Processing - For Online Payment Websites

Introduction

In this guide we will be walking you through how to create single and recurring ACH payments initiated by an end user through the internet using the Transaction Processing web service. Our objective will be to establish the basics by using specific ACH payment type examples, however the examples should provide you with the information needed to customize to your specific needs.
Internet Payments are initiated and authorized via the internet by the end-user. ACH payments are those payments against a Checking or Savings bank account. If you have a customer facing online platform where users can login and initiate payments from their bank accounts, you will want to follow this guide for proper payment routing.

Getting Started

Here's what you'll do in this guide

Create a single ACH payment with custom data and customer data.
Create a recurring ACH payment resulting from user-initiated payment schedules in your platform.

note

How to determine when to use Single vs Recurring?

The best way to determine this is to consider how you are obtaining the on-screen ACH authorization from the user. If the user is authorizing each payment individually, then AuthorizeTransaction should be used. If the user is authorizing a payment once for the initial payment as well as future payments which will be made on a cadence by your system (monthly, quarterly, annually, etc), then AuthorizeRecurringTransaction should be used.

Prerequisites needed before continuing

You will want to obtain your test credentials in order to try any of the examples in this guide. You should have received these from your Implementation Coordinator.
Review the Authentication guide for an understanding on how to authenticate to the EPS web service. This guide will walk you through sending a test connection and test credentials to ensure you are able to authenticate before moving forward.
Download the Transaction Processing WSDL file from the Downloads menu

Create a single ACH payment with custom data workflow guide

For this guide we will walk through a hypothetical example where a customer is making a one-time payment of 25 dollars for purchasing a product that they have initiated through a customer facing website. We have given the product an ID of A1234 which we will track with the transaction. The customer is supplying their bank account information for the ACH payment and we will also capture the user's address information as part of the payment.

Step 1 The first thing that will need to occur is to capture the required payment information needed to build the web request. For this example, we will say the customer has entered the following on the website.
- Name: Test User
- Address: 1234 Avenue, Allen TX, 75050
- Routing/Account: 111000025/56789
- Amount: 25.00 purchase amount.
- Product ID: A1234 from product selection
Step 2 Using the collected information, we will populate an AuthorizeTransaction request in order to process this payment.
- Since we have specific user information, we want to add that to the various customer fields.
- We will also add the productid they purchased to Field1 so it will be stored with the transaction and can be reported on in Transaction Reporting.
- Since this is an internet payment, we need to specify “Internet” as the “PaymentOrigin”.
- Since this user is making a payment, we will specific “Sale” as the “OperationType”.
- Lastly, we will specify “ACH” as the “SettlementType”.

Here is what our completed AuthorizeTransaction request will look like for this example.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pv="https://ssl.selectpayment.com/PV">
    <soapenv:Header/>
    <soapenv:Body>
        <pv:AuthorizeTransaction>
            <pv:storeId>Your StoreID</pv:storeId>
            <pv:storeKey>Your StoreKey</pv:storeKey>
            <pv:transaction>
                <pv:EntityId>Your EntityID</pv:EntityId>
                <pv:LocationId>Your LocationID</pv:LocationId>
                <pv:PaymentOrigin>Internet</pv:PaymentOrigin>
                <pv:AccountType>Checking</pv:AccountType>
                <pv:OperationType>Sale</pv:OperationType>
                <pv:SettlementType>ACH</pv:SettlementType>
                <pv:EffectiveDate>2020-12-14</pv:EffectiveDate>
                <pv:TotalAmount>25.00</pv:TotalAmount>
                <pv:TerminalNumber>__Webservice</pv:TerminalNumber>
                <pv:TransactionNumber>1234567890</pv:TransactionNumber>
                <pv:Field1>A1234</pv:Field1>
                <pv:RoutingNumber>111000025</pv:RoutingNumber>
                <pv:AccountNumber>56789</pv:AccountNumber>
                <pv:IsBusinessPayment>0</pv:IsBusinessPayment>
                <pv:NameOnAccount>Test User</pv:NameOnAccount>
                <pv:BillingAddress1>1234 Avenue</pv:BillingAddress1>
                <pv:BillingCity>Allen</pv:BillingCity>
                <pv:BillingStateRegion>TX</pv:BillingStateRegion>
                <pv:BillingPostalCode>75050</pv:BillingPostalCode>
                <pv:BillingCountry>US</pv:BillingCountry>
            </pv:transaction>
            <pv:ownerApplication>Web_Service</pv:ownerApplication>
        </pv:AuthorizeTransaction>
    </soapenv:Body>
</soapenv:Envelope>

Step 3 Once this request is sent to the endpoint, we should get a successful response and there are a few key items that are important to log with this response.
- ReferenceNumber - EPS generates this value for you to use for pulling reporting information on the transaction later. You will want to store this number with the transaction in your database.
- Success - indicates a successful transaction.
- Error - indicates if an error has occurred.
- ResponseCode - EPS code signifying result of the request.
- ActualDate - when the transaction was created in EPS.
- ResponseMessage - detailed description for the response code when applicable.

Here is what our successful response looks like for this example.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body>
        <AuthorizeTransactionResponse xmlns="https://ssl.selectpayment.com/PV">
            <AuthorizeTransactionResult>
                <ReferenceNumber>T:STHB8B2MLA1</ReferenceNumber>
                <Success>true</Success>
                <Error>false</Error>
                <ResponseCode>Success</ResponseCode>
                <ActualDate>2020-12-14T00:00:00-06:00</ActualDate>
                <ResponseMessage/>
                <OriginatedAs>ACH</OriginatedAs>
            </AuthorizeTransactionResult>
        </AuthorizeTransactionResponse>
    </soap:Body>
</soap:Envelope>

Here is how the single payment example looks represented as a complete workflow diagram. Click on the method boxes to be taken to the specific API reference.

	Integrator Payment Flow	EPS Web Service Flow

	EPS Web Service

1.	Gather payment information from user online.
2.	Initiate the payment with AuthorizeTransaction using payment information gathered from user.
		Successful payment Key Data Elements: AuthorizeTransactionResponse ReferenceNumber = Unique number assigned to transaction by EPS Success = true Error = false ResponseCode = Success ResponseMessage = Additional information for response code if applicable
3.	For successful payments: store the ReferenceNumber along with your TransactionNumber from AuthorizeTransaction in your database display and log any results.
		Unsuccessful Payment Key Data Elements: AuthorizeTransactionResponse Success = false Error = true or false ResponseCode = See API Reference ResponseMessage = Additional information for response code if applicable
4	For Unsuccessful payments: display and log the error and responsecode as needed

Create a recurring ACH payment workflow guide

For this guide we will walk through a hypothetical example where a customer has setup a monthly recurring payment of 5 dollars for a service that they have initiated through a customer facing website. We will track the payment month and occurrence along with the invoice ID in custom fields. The customer has supplied their bank account information for the recurring ACH payment when they initially setup the schedule in the customer facing website. We will also capture the user's address information as part of the payment.

Step 1 The first thing that will need to occur is to use the payment information generated by the recurring payment schedule required to build the web request. For this example, we will say the recurring schedule has generated a payment for October invoice ID RP1234 which is payment 10 of 12.
- Name: Test User
- Address: 1234 Avenue, Allen TX, 75050
- Routing/Account: 111000025/56789
- Amount: 5.00 monthly payment.
- InvoiceID: RP1234
- Recurring information: October 10/12
Step 2 Using the collected information, we will populate a AuthorizeRecurringTransaction request in order to process this payment.
- Since we have specific user information, we want to add that to the appropriate fields in the WSCustomer object.
- We will also add the invoiceID RP123 to Field1 and recurring information October 10/12 to Field2 so it will be stored with the transaction and can be reported on in Transaction Reporting. These are the fields within the WSRecurringTransaction object.
- Since this is an internet payment, we need to specify “Internet” as the “RecurringPaymentOrigin”.
- The nature of the AuthorizeRecurringTransaction method automatically creates a “Sale” transaction that is ACH. We cannot alter the “OperationType” or “SettlementType” on this method.

note

Please note that CustomerNumber is not required but highly recommended you assign your own value to facilitate managing your customers information in the EPS platform.

Here is what our completed AuthorizeRecurringTransaction request will look like for this example.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pv="https://ssl.selectpayment.com/PV">
<soapenv:Header/>
<soapenv:Body>
    <pv:AuthorizeRecurringTransaction>
        <pv:storeId>your storeid</pv:storeId>
        <pv:storeKey>your storekey</pv:storeKey>
        <pv:customer>
            <pv:EntityId>your entityid</pv:EntityId>
            <pv:IsCompany>0</pv:IsCompany>
            <pv:CustomerNumber>010612</pv:CustomerNumber>
            <pv:FirstName>Test</pv:FirstName>
            <pv:LastName>User</pv:LastName>
            <pv:Address1>1234 Avenue</pv:Address1>
            <pv:City>Allen</pv:City>
            <pv:StateRegion>TX</pv:StateRegion>
            <pv:PostalCode>75050</pv:PostalCode>
            <pv:Country>US</pv:Country>
        </pv:customer>
        <pv:createCustomerIfDoesNotExists>1</pv:createCustomerIfDoesNotExists>
        <pv:updateCustomerIfExists>0</pv:updateCustomerIfExists>
        <pv:recurringTransaction>
            <pv:EntityId>your entityid</pv:EntityId>
            <pv:LocationId>your locationid</pv:LocationId>
            <pv:RecurringPaymentOrigin>Internet</pv:RecurringPaymentOrigin>
            <pv:EffectiveDate>2012-01-06</pv:EffectiveDate>
            <pv:Description>Recurring</pv:Description>
            <pv:TotalAmount>5.00</pv:TotalAmount>
            <pv:TransactionNumber>010612</pv:TransactionNumber>
            <pv:Field1>RP1234</pv:Field1>
            <pv:Field2>October 10/12</pv:Field2>
            <pv:RoutingNumber>111000025</pv:RoutingNumber>
            <pv:AccountNumber>56789</pv:AccountNumber>
            <pv:IsBusinessPayment>0</pv:IsBusinessPayment>
            <pv:NameOnAccount>Test User</pv:NameOnAccount>
        </pv:recurringTransaction>
    </pv:AuthorizeRecurringTransaction>
</soapenv:Body>
</soapenv:Envelope>

Step 3 Once this request is sent to the endpoint, we should get a successful response and there are a few key items that are important to log with this response.
- ReferenceNumber - EPS generates this value for you to use for pulling reporting information on the transaction later. You will want to store this number with the transaction in your database.
- Success - indicates a successful transaction.
- Error - indicates if an error has occurred.
- ResponseCode - EPS code signifying result of the request.
- ActualDate - when the transaction was created in EPS.
- ResponseMessage - detailed description for the response code when applicable.

Here is what our successful response looks like for this example.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body>
        <AuthorizeRecurringTransactionResponse xmlns="https://ssl.selectpayment.com/PV">
            <AuthorizeRecurringTransactionResult>
                <ReferenceNumber>T:R9388BX8A1</ReferenceNumber>
                <Success>true</Success>
                <Error>false</Error>
                <ResponseCode>Success</ResponseCode>
                <ActualDate>2012-01-06T00:00:00-06:00</ActualDate>
                <ResponseMessage/>
                <OriginatedAs>ACH</OriginatedAs>
            </AuthorizeRecurringTransactionResult>
        </AuthorizeRecurringTransactionResponse>
    </soap:Body>
</soap:Envelope>

Here is how the recurring payment example looks represented as a complete workflow diagram. Click on the method boxes to be taken to the specific API reference.

	Integrator Payment Flow	EPS Web Service Flow

	EPS Web Service

1.	Gather payment information generated from the recurring schedule.
2.	Initiate the payment with AuthorizeRecurringTransaction using payment information gathered from user.
		Successful payment Key Data Elements: AuthorizeRecurringTransactionResponse ReferenceNumber = Unique number assigned to transaction by EPS Success = true Error = false ResponseCode = Success ResponseMessage = Additional information for response code if applicable
3.	For Successful payments: store the ReferenceNumber along with your TransactionNumber from AuthorizeRecurringTransaction in your database display and log any results.
		Unsuccessful Payment Key Data Elements: AuthorizeRecurringTransactionResponse Success = false Error = true or false ResponseCode = See API Reference ResponseMessage = Additional information for response code if applicable
4	For Unsuccessful payments: display and log the error and responsecode as needed

Handling Errors and Failed Requests

Not all requests will be successful, so we will need to run through a few common errors you should be ready to handle.

Velocity error- Velocity declines will happen when one of the payment amount or count limits are exceeded by the transaction. It is important not to automatically retry the transaction as it will not succeed without being under the current limits. To handle this situation, store the velocity decline response with transaction details. Reach out through your normal support channels to discuss your velocity limits further.
Invalid routing number - Invalid routing number declines for ACH transactions will occur when the value does not pass a routing number checksum formula. When this occurs, it is important not to automatically retry the transaction. The routing number value will need to be verified and corrected before resubmitting the transaction.
Duplicate transaction - Duplicate transactions will be declined. Transactions are checked against our duplicate table which is a rolling 75 days of history and is checked against other transactions for the same merchant (entityID). It is important that transactions that receive a duplicate error are not automatically retried and there are two ways to handle it.
- The transaction is a true duplicate and will not need another attempt. Record the response and no further action is needed.
- You are certain that the transaction is not really a duplicate and need it to process. For WEB payments a duplicate is flagged when the Transaction Number is not unique. This means the Transaction Number value will need to change to something unique and resubmit the request.
Timeout waiting for response - Systems should be designed to wait 5 seconds for ACH transactions to receive a response before timing out. If a timeout occurs, you can attempt to query the system with one of the GetTransaction methods to verify if the transaction was received. If it was not the transaction can be resubmitted.

Next Steps

Customize the workflows to fit your specific business needs.
- You can apply the principles shown in these examples and customize the requests using the API Reference to suit your needs. You can also substitute these other methods in place of AuthorizeTransaction when appropriate.
  - AuthorizeTransactionWithAddenda - used to send additional information with the ACH payment.
  - AuthorizeTransactionWithCustomer - used to associate a new or previously created customer record with the transaction. (see guide for storing customer records)
Review the API Reference
- This guide is just a starting point to show a common use case scenario for making internet payments. Please review the API Reference to see all APIs and their technical specifications.
Explore other guides
- We have other guides to show how to leverage our APIs in other common use cases so if this one doesn't cover what you are looking for, give another guide a try.
Get certified and move into production
- Ready to put your new code into production use? Refer to this process guide that explains our certification steps and how to contact us to get started.

Introduction​

Getting Started​

Create a single ACH payment with custom data workflow guide​

Create a recurring ACH payment workflow guide​

Handling Errors and Failed Requests​

Next Steps​