ACH
Automated Clearing House (ACH) transactions allow the Merchant to
accept payment from or make a payment to the Customer’s Bank
Account.
Version: 1.11
Published: 7 April 2017
ACH
Table of Contents
1
Introduction ...................................................................................................................................... 3
1.1
1.2
1.3
2
Overview .................................................................................................................................... 3
Account Configuration ................................................................................................................ 3
Chargebacks .............................................................................................................................. 3
Process overview ............................................................................................................................. 4
2.1
2.2
2.3
2.4
2.5
2.6
2.7
3
Summary .................................................................................................................................... 4
Account Check ........................................................................................................................... 6
Authorisation Request ................................................................................................................ 8
Settlement .................................................................................................................................. 9
Confirmation ............................................................................................................................. 10
Settle Status ............................................................................................................................. 11
Refunds .................................................................................................................................... 12
ACH Account Check ...................................................................................................................... 13
3.1
3.2
4
XML ACH Account Check Request ......................................................................................... 13
XML ACH Account Check Response ....................................................................................... 18
ACH Authorisation ......................................................................................................................... 23
4.1
4.2
5
XML ACH Authorisation Request ............................................................................................. 23
XML ACH Authorisation Response .......................................................................................... 27
ACH Authorisation with Account Check ..................................................................................... 31
5.1
5.2
6
XML ACH Authorisation with Account Check Request ............................................................ 31
XML ACH Authorisation with Account Check Response ......................................................... 34
ACH Refund .................................................................................................................................... 37
6.1
6.2
7
XML ACH Refund Request ...................................................................................................... 37
XML ACH Refund Response ................................................................................................... 40
ACH Transaction Query................................................................................................................. 42
7.1
7.2
8
XML ACH Transaction Query Request .................................................................................... 42
XML ACH Transaction Query Response ................................................................................. 42
ACH Transaction Update ............................................................................................................... 43
8.1
8.2
9
XML Transaction Update Request Example ............................................................................ 43
XML Transaction Update Response Example ......................................................................... 43
Additional Notes ............................................................................................................................. 44
9.1
9.2
9.3
9.4
9.5
10
10.1
10.2
11
11.1
11.2
11.3
11.4
12
System Limitations ................................................................................................................... 44
Card Store ................................................................................................................................ 44
Subscriptions and Tokenisation ............................................................................................... 44
Supported Currencies .............................................................................................................. 44
Mail or Telephone Order .......................................................................................................... 44
Testing......................................................................................................................................... 45
Account Check Requests (ACCOUNTCHECK) ....................................................................... 45
Authorisation Requests (AUTH) and Chargebacks (CHARGEBACK) .................................... 45
Further Information and Support ............................................................................................. 48
Secure Trading Support ........................................................................................................... 48
Secure Trading Sales ............................................................................................................... 48
Useful Documents .................................................................................................................... 48
Frequently Asked Questions .................................................................................................... 48
Appendix ..................................................................................................................................... 49
© Secure Trading Limited 2017
7 April 2017
Page 2 / 51
ACH
1
Introduction
Automated Clearing House (ACH) bank transfers allow the merchant to accept payment directly
from a customer’s bank account. The merchant can also transfer money directly to a customer’s
bank account, either by refunding a previous transaction, or by performing a Cardholder Funds
Transfer (CFT) Request.
1.1
Overview
This document describes processing ACH Bank Transfers using the Secure Trading Payment
Platform (STPP). It pays specific attention to the XML fields used to create ACH Requests and
the information returned in the Response.
The examples specified may include other fields not covered in this document. Details of these
fields are available in the STPP XML Specification (see section 11.3 Useful Documents on
page 48).
Of the fields outlined within this document, Secure Trading may add
additional fields and tags in the future; we would therefore recommend that
you do not build your application to only accept these tags.
Please note the order of the tags cannot be guaranteed. Some tags may be
returned in a different order to the examples in this document.
1.2
Account Configuration
There are a few steps the merchant needs to have considered to begin processing ACH bank
transfers. The merchant may require new accounts with different providers.
1.2.1
Acquiring Bank
The merchant must have an account with an acquirer that supports ACH bank transfers and is
integrated with Secure Trading.
1.2.2
Secure Trading
The merchant will need to have an account with Secure Trading. For more information, contact
Secure Trading Sales (see section 11.2 Secure Trading Sales on page 48).
The merchant will need to provide the support team with their ACH account details to allow
them to enable ACH on their Secure Trading account (see section 11.1 Secure Trading
Support on page 48).
1.2.3
Notifications
Secure Trading recommends that all merchants implementing ACH bank transfers configure
URL notifications to be kept informed of when ACH transfers have been updated/completed on
their accounts. For more information, please refer to the Notifications documentation (see
section 11.3 Useful Documents on page 48).
1.3
Chargebacks
ACH transactions may be subject to Chargebacks. An ACH Chargeback is a payment that is
initiated when a customer successfully disputes an item on their bank account statement. The
full amount is transferred back to the customer’s account from the merchant’s, on request of the
customer’s bank. It is strongly recommended that all merchants with ACH accounts read Secure
Trading’s Chargeback documentation (see section 11.3 Useful Documents on page 48) so
that they are fully aware of the Chargeback process and how to manage them.
© Secure Trading Limited 2017
7 April 2017
Page 3 / 51
ACH
2
Process overview
2.1
Summary
There are a number of different parties involved in Automated Clearing House (ACH) bank
transfers. These are listed, below:
The Customer - The purchaser of goods or services. They will process a payment by
supplying their ACH bank details to the merchant.
The Merchant – The seller of goods or services. They will need to have an account with
Secure Trading.
Secure Trading – The Payment Service Provider. They facilitate the transaction, by
securely contacting the merchant’s acquiring bank.
The Merchant’s Bank – Performs checks on the customer’s bank account details and
authorises transfers.
Below is a summary of the process of a typical ACH bank transfer:
Sending the XML Request
In a typical transaction where the customer is paying the merchant, the customer sends their
bank details directly to the merchant, who then constructs an Account Check and Authorisation
(AUTH) XML Request and submits it to Secure Trading’s Payment Gateway.
Account Check
Secure Trading then securely contacts the merchant’s acquirer, which carries out checks on the
payment details provided by the customer and returns the results of these checks back to
Secure Trading. The merchant may decide to not proceed with the processing of further
transactions, if the Account Check Response does not match a certain criteria, by establishing
rules with the Secure Trading support team. Otherwise, Secure Trading will securely contact the
merchant’s acquirer to seek authorisation for the bank transfer.
Authorisation
Secure Trading will contact the merchant’s acquiring bank to arrange for Authorisation. Secure
Trading will automatically schedule settlement on all recently authorised payments.
Transfers that have been declined by the merchant’s acquirer are cancelled immediately.
Settlement
Secure Trading checks for confirmation that the transfer was settled, daily. After a holding
period defined by the merchant’s acquirer, the acquirer informs Secure Trading that the transfer
was either settled or cancelled, and they update their records respectively.
© Secure Trading Limited 2017
7 April 2017
Page 4 / 51
ACH
Diagram of Entire Process Overview – Combined Account Check with Authorisation Request
Account Check
Step 1) The Customer
opts to make an ACH
Bank Transfer on the
merchant’s website.
Step 2) The Merchant
submits an XML Request
to Secure Trading.
Step 3) Secure Trading
validates the Request
and sends the
Customer’s bank details
to the Merchant’s Bank.
Step 4) Merchant Bank
processes the Account
Check request received and
returns a response.
Step 5) Secure Trading
receives results of the
checks from the
Merchant’s Bank.
Step 6) If the Account Check returns a
NOT MATCHED response, the Merchant
will receive an XML Response and the
Authorisation will NOT proceed.
NOT MATCHED – (4)
Bank concludes Customer’s
account is high risk.
MATCHED – (2)
Bank concludes Customer’s
account is low risk.
NOT CHECKED – (1)
Bank undecided or unable
to complete checks.
Authorisation
Step 7) Secure Trading sends
details to the Merchant’s Bank to
authorise the transfer.
Step 9) The Merchant receives an XML
Response from Secure Trading
containing results of Account Check and
Authorisation.
Step 8) The Merchant’s
Bank processes the
request and updates their
records.


DECLINED
AUTHORISED
Settlement
Step 10) Secure Trading sends
details to the Merchant’s Bank to
settle the transfer.
Step 12) Any settlement notifications that
have been configured would be sent once
transactions have been officially
confirmed to be cancelled or settled.

Step 11) Secure Trading
regularly checks for
confirmation from the
Merchant’s Bank.

SETTLED
CANCELLED
The Merchant’s Bank
The Merchant’s Bank
informs Secure Trading that informs Secure Trading that
the funds were not
the funds have been settled.
transferred.
© Secure Trading Limited 2017
7 April 2017
Page 5 / 51
ACH
2.2
Account Check
An Account Check is an optional request that allows payment details to be validated by
checking the account’s status. No funds will be reserved or transferred by the Account Check
Request. Secure Trading allows Account Checks to be carried out on ACH accounts for select
acquirers. Please contact support for information on which Acquirers support Account Check
(see section 11.1 Secure Trading Support).
The merchant may decide to not proceed with the processing of further transactions, if the
Account Check Response does not match a certain criteria. This is achieved by contacting the
support team and setting up rules that act on the security response field.
The following steps outline the process of sending an Account Check Request to Secure
Trading:
Step 1) The Merchant
submits an XML Request
to Secure Trading.
Step 2) Secure Trading
validates the Request
and sends the
Customer’s bank details
to the Merchant’s Bank.
Step 3) The Bank
performs verification
checks; is the Customer’s
account valid and in good
standing?
Step 5) Secure Trading
receives the results of
these checks from the
Merchant’s Bank.
Step 4) The Bank checks
the Customer’s details
against a National
negative database.
Step 6) The Merchant
receives an XML
Response from Secure
Trading with results of
the checks.
NOT CHECKED – (1)
Bank undecided or unable
to complete checks.
MATCHED – (2)
Bank concludes Customer’s
account is low risk.
NOT MATCHED – (4)
Bank concludes Customer’s
account is high risk.
Figure 1 - Process Overview of Account Check for ACH
© Secure Trading Limited 2017
7 April 2017
Page 6 / 51
ACH
2.2.1
Account Verification Check
The merchant’s acquirer will perform checks to verify that the customer’s account is valid and in
good standing. The response returned following these checks can either be ‘2 – Matched’ (low
risk), ‘4 – Not Matched’ (high risk) or ‘1 – Not Checked’. Transactions that do not receive a
definitive response may be checked against the negative database (see section 2.2.2 Negative
Database). Secure Trading recommends against proceeding with further transactions using
payment details that return the ‘4 – Not Matched’ response. For further details, please see
section 3.2.4 <security> on page 20.
2.2.2
Negative Database Check
The merchant’s acquirer may also search a large National database for negative reports against
the payment details submitted in the XML Request. This database contains information on over
150 million accounts. Checks against the negative database can only return a ‘2 – Matched’ or
‘4 – Not Matched’ response. Secure Trading recommends against proceeding with further
transactions using payment details that return the ‘4 – Not Matched’ response. For further
details, please see section 3.2.4 <security> on page 20.
Please note that the Negative Database check may need to be enabled by your
acquirer before it can be used as part of Account Check Requests. Please contact
your acquiring bank for further information.
Please note that Secure Trading allows Account Checks to be combined with an
Authorisation in the same request. A summary of an Authorisation Request can
be found in section 2.3 Authorisation Request.
2.2.3
Security Response
After performing an Account Check, you are returned a security response from the acquiring
bank, in the form of a number, which indicates the result of the checks performed on the
customer’s bank account details. A detailed XML specification of the security response can be
found in section 3.2.4 <security> on page 20.
When performing combined ACH Account Check and Authorisation
Requests, it is recommended that you contact support in order to set up
rules, which use the results of the Account Check carried out by the
acquiring bank to either allow or prevent future authorisations.
2.2.4
Rules
Rules can be assigned on your account by the Secure Trading support team, which will use the
results of the Account Check to decide whether or not to process an associated Authorisation
transaction. The recommended process flow is as follows:
1. If the Account Check returns a ‘Matched’ or ‘Not Checked’ response, then process the
Authorisation.
2. If the Account Check returns a ‘Not Matched’ response, then do NOT process an
Authorisation.
Please note the default process flow can be customised. For more information,
please contact Secure Trading support (see section 11.1 Secure Trading Support
on page 48).
An alternative to having rules set up is that your system has this logic present which determines
whether or not to submit an Authorisation Request based on the Account Check Response.
© Secure Trading Limited 2017
7 April 2017
Page 7 / 51
ACH
2.3
Authorisation Request
Step 1) The Merchant
submits an XML Request
to Secure Trading.
Step 2) Secure Trading
validates the request and
sends the details to the
Merchant’s Bank.
Step 3) The Merchant’s
Bank processes the
request.
Step 4) Secure Trading
returns an XML
Response to the
Merchant.


The Merchant’s Bank has
authorised the transfer
request.
The Merchant’s Bank has
declined the transfer request
or the request failed.
settlestatus is set to
“0” - Automatic
settlestatus is set to
“3” - Cancelled
Figure 2 - Process Overview of Authorisation
Please note that after an ACH bank transfer request has been authorised, it is
possible for you to update some of the details or cancel the transfer altogether, by
following the steps outlined in section 8 ACH Transaction Update.
Please note that Secure Trading allows Authorisations to be combined with an
Account Check in the same request. A summary of an Account Check Request
can be found in section 2.2 Account Check.
Please note that ACH transactions are cancelled by Secure Trading if they have
not been settled within 7 days of being authorised.
© Secure Trading Limited 2017
7 April 2017
Page 8 / 51
ACH
2.4
Settlement
Merchants can be informed on transactions that are settled, through the use of Notifications. For
more information, please refer to the Notifications documentation (see section 11.3 Useful
Documents on page 48).
Secure Trading will contact the
Merchant’s Bank daily to start the
settlement process for recently
authorised ACH transactions.

The settlestatus is set to
“10” - Settling,
and remains this way until
the Merchant’s Bank
confirms the settlement is
complete via confirmation.
Figure 3 - Process Overview of Settlement
Please note that after Secure Trading starts the settlement procedure on an
authorised ACH bank transfer request, you will no longer be able to update or
cancel the transaction. If you would like to stop the transfer at this stage, you will
need to contact your acquirer.
Please note that the time between a transaction being sent for settlement and
receiving confirmation of settlement depends on the holding day period defined by
your acquirer. For more information on holding days, please contact your acquirer.
© Secure Trading Limited 2017
7 April 2017
Page 9 / 51
ACH
2.5
Confirmation
Secure Trading will contact the
Merchant’s Bank daily to check if
any outstanding ACH
transactions have been settled.

The settlestatus is set to
“100” - Settled,
if the transaction has been
confirmed as settled by the
Merchant’s Bank.
The settlestatus is set to
“3” - Cancelled,
if the transaction has been
confirmed to be cancelled
by the Merchant’s Bank.
Figure 4 - Process Overview of Confirmation
Once details of the transaction have been sent to the merchant’s acquirer to be settled, Secure
Trading will check for confirmation from the acquirer on a daily basis. Funds can be captured at
any time between the settlement request and receiving confirmation from the acquirer. When
Secure Trading finally receives this confirmation, the settlestatus is updated to a final
value:
If the transaction has been confirmed to be successful and the funds have been
transferred, the settlestatus is set to 100.
If the transaction has failed, and no funds have been transferred, the settlestatus is
set to 3
Please note that it is possible to set up custom notifications on ACH transactions
processed through the Secure Trading system. For more information, please refer
to the Notifications documentation (see section 11.3 Useful Documents on page
48).
© Secure Trading Limited 2017
7 April 2017
Page 10 / 51
ACH
2.6
Settle Status
Every Authorisation transaction in the Secure Trading system is assigned a settlestatus.
This can be used to establish where the transaction is along the settlement process. There are
four important settlestatus fields:
‘0’ – Transaction has been authorised by the acquirer, and is awaiting settlement. At
this stage, some updates can be made to the transaction, and you can cancel it (see
section 8 ACH Transaction Update).
‘3’ – Transaction has been cancelled.
‘10’ – Transaction has been sent to be settled, and is awaiting confirmation from the
acquiring bank.
‘100’ – Confirmation has been received that the transaction has been settled by the
acquiring bank.
The following table shows the progression of the settlestatus of a transaction as an ACH
transaction is authorised (assuming each step is successfully processed), sent to be settled and
confirmed to be settled.
settlestatus
Successful ACH Authorisation
Transaction:
After Authorisation
processed
After Settlement
processed
After Confirmation
processed
0
10
100
Successful ACH Authorisation
Transaction (sent for settlement
immediately)
Declined or Cancelled ACH
Authorisation Transaction
3
ACH Authorisation Transaction
Cancelled by the bank
0
© Secure Trading Limited 2017
100
10
7 April 2017
(Not sent for settlement)
10
3
Page 11 / 51
ACH
2.7
Refunds
To perform a refund or make a payment to the customer, the merchant needs to submit a CFT
(Cardholder Funds Transfer) Refund XML Request. CFT Refunds allow merchants to perform
refunds on transactions before they have been settled. CFT Refunds can be for any amount
and do not require a parent Authorisation. Please refer to section 6.1 XML ACH Refund
Request for an XML Example.
If you have not yet received confirmation that the original Authorisation has
been settled, it is possible that the funds have not been transferred. When
performing a CFT Refund in such circumstances, please ensure you have
received the payment before processing a Refund Request.
Step 1 – XML Request Submitted to Secure Trading
The merchant submits an CFT Refund XML Request to the Secure Trading system.
Step 2 – Secure Trading contact Acquirer
Once the merchant’s XML Request has been validated, Secure Trading will securely contact the
customer’s bank to seek an authorisation for the transfer.
Step 3 – Acquirer Responds to Secure Trading
The customer’s bank responds to Secure Trading. Secure Trading interprets this Response and
stores the details in their system.
Step 4 – Secure Trading Returns XML Response
Secure Trading will return an XML Response to the merchant, with details of whether or not the
transaction was successful:
If the payment details were declined by the acquirer, the settlestatus is set to 3 and
the request does not continue.
If the transaction was authorised by the acquirer, the settlestatus is set to 10.
Step 5 – Acquirer Confirms Refund
Secure Trading will check for confirmation from the acquiring bank on a daily basis. When
Secure Trading receives this confirmation:
If the CFT Refund has been confirmed to be successful and the funds have been
transferred, the settlestatus is set to 100,
If it has failed, and no funds have been transferred, the settlestatus is set to 3.
© Secure Trading Limited 2017
7 April 2017
Page 12 / 51
ACH
3
ACH Account Check
3.1
XML ACH Account Check Request
This section describes the XML Request that needs to be sent in order to process a single
Account Check on a customer’s account. It is possible to combine this Request with an
Authorisation Request, by following the steps outlined in 5.1 XML ACH Authorisation with
Account Check Request, but it is not required that you do so.
Please note that no funds will be reserved or transferred by the Account Check
Request.
Please note that an example ACH ACCOUNTCHECK XML Request can be
found in the STAPI client files, within the ACCOUNTCHECK_ACH folder, which
can be downloaded from our website:
http://webapp.securetrading.net/examples/STAPI_JAVA1.6.zip
3.1.1
XML Overview
The XML Request for an ACH Account Check is similar to a normal Authorisation Request, as
outlined in the STPP XML Specification document (see section 11.3 Useful Documents),
except for the differences outlined in this section of the document.
Before submitting an Account Check Request, as outlined in this section, it
is imperative that you read section 2.2 Account Check and consider setting
up rules that will prevent AUTHs from being processed from payment
details that fail an Account Check.
Other fields that can be included within the request are covered in the STPP XML
Specification document (see section 11.3 Useful Documents).
operation
merchant
alias
billing
customer
request type =
“ACCOUNTCHECK”
settlement
+
+
+
+
+
name
amount currencycode
= ”USD”
payment type=”ACH”
+
socialsecuritynumber
+
Figure 5 - ACH Account Check XML Request
© Secure Trading Limited 2017
7 April 2017
Page 13 / 51
ACH
3.1.2
<request type=”ACCOUNTCHECK”>
The request type for an Account Check Request is “ACCOUNTCHECK”.
3.1.3
<billing>
3.1.3.1 <socialsecuritynumber>
The socialsecuritynumber element can be submitted within the billing tag, for ACH
transactions.
Tag
socialsecurity
number
Type
Length
Required
n
9
N
Comment
The customer’s social security
number. Numbers only.
3.1.3.2 <name>
prefix
first
alias
middle
+
billing
name
request type =
“ACCOUNTCHECK”
last
suffix
Figure 6 - ACH Account Check XML Request <name> tag
The name tag is mandatory and is submitted within the billing tag. A billing name must be
submitted for every ACH Request.
Tag
name
Type
Length
Required
Y
prefix
an
25
N
first
an
25
Y
middle
an
25
N
last
an
25
Y
suffix
an
25
N
© Secure Trading Limited 2017
7 April 2017
Comment
The prefix of the customer’s billing
name (e.g. Mr,Miss,Dr).
The customer’s billing first name.
The customer’s billing middle
name(s).
The customer’s billing last name.
The customer’s suffix of the billing
name (e.g. Bsc).
Page 14 / 51
ACH
3.1.3.3 <amount>
alias
+
billing
amount currencycode =
”USD”
request type =
“ACCOUNTCHECK”
Figure 7 - ACH Account Check XML Request <amount> tag
The amount tag for an Account Check can have a value of 0. If the value of the amount tag is
set to a non-zero value, this can be inherited as the amount in any subsequent transactions that
pass through the reference to this Account Check. For example, an Account Check with an
amount of $100 will not reserve any funds, but an Authorisation Request which inherits from
this Account Check, without passing through a new amount, will reserve $100 on the
customer’s account.
Please note that no funds will ever be reserved or transferred by the Account
Check Request.
The currency must be “USD”.
Tag
Type
Length
Required
amount
currencycode=””
an
3
Y
amount
n
13
Y
© Secure Trading Limited 2017
7 April 2017
Comment
The currency that the transaction will
be processed in. For ACH bank
transfers, the currency must be
“USD”.
For Account Checks, this field can be
set to 0. Non-zero values can be
inherited in subsequent requests.
Page 15 / 51
ACH
3.1.3.4 <payment>
achtype
alias
+
billing
achchecknumber
payment type = “ACH”
request type =
“ACCOUNTCHECK”
achaccountnumber
achaba
Figure 8 - ACH Account Check XML Request <payment> tag
Tag
payment
type = “ACH”
Type
Length
Required
an
20
Y
achtype
an
10
Y
achchecknumber
n
10
N
n
17
Y
Account number
n
9
Y
Transit routing number
achaccount
number
achaba
3.1.4
Comment
Payment type is submitted as “ACH”
Account type. Either “SAVINGS”,
“CHECKING” or “BUSINESSCK”
Check number for Point of Sale
transactions. Length can be between
1 and 10.
<settlement>
The value of the settlestatus tag is returned in the XML Response, allowing it be inherited
in any subsequent requests, such as an Authorisation Request.
Tag
settlement
settlestatus
© Secure Trading Limited 2017
Type
n
Length
3
Required
N
7 April 2017
Comment
This value relates to the status you
would like to be inherited by
subsequent transactions.
The possible values are:
0 – Pending Settlement
2 – Suspended.
100 – Settled (this is only available
for certain acquirers).
If this is not set, status is
automatically set to 0.
Page 16 / 51
ACH
3.1.5
ACH Account Check XML Request Example
Please find below an example of an ACH ACCOUNTCHECK XML Request to be submitted to
Secure Trading’s systems (fields of interest for ACH are highlighted in bold):
<?xml version='1.0' encoding='utf-8'?>
<requestblock version="3.67">
<alias>test_example40000</alias>
<request type="ACCOUNTCHECK">
<merchant>
<orderreference>ACCOUNTCHECK_ACH</orderreference>
</merchant>
<customer>
<town>Bangor</town>
<name>
<middle>Mary</middle>
<prefix>Miss</prefix>
<last>Smith</last>
<first>Joanne</first>
</name>
<ip>1.2.3.4</ip>
<telephone type="H">1111111111</telephone>
<street>Second Street</street>
<postcode>CU888ST</postcode>
<premise>111</premise>
</customer>
<billing>
<town>Bangor</town>
<name>
<middle>joe</middle>
<prefix>Dr</prefix>
<last>Smith</last>
<suffix>Jr.</suffix>
<first>John</first>
</name>
<country>GB</country>
<email>[email protected]</email>
<telephone type="M">0777777777</telephone>
<county>Gwynedd</county>
<amount currencycode="USD">0</amount>
<street>Test Street</street>
<postcode>TE45 6ST</postcode>
<premise>789</premise>
<payment type="ACH">
<achaba>987654321</achaba>
<achaccountnumber>123456781</achaccountnumber>
<achchecknumber>123456</achchecknumber>
<achtype>SAVINGS</achtype>
</payment>
<socialsecuritynumber>123456789</socialsecuritynumber>
</billing>
<operation>
<accounttypedescription>ECOM</accounttypedescription>
<sitereference>test_example40000</sitereference>
</operation>
</request>
</requestblock>
© Secure Trading Limited 2017
7 April 2017
Page 17 / 51
ACH
3.2
XML ACH Account Check Response
This section describes the XML Response returned from Secure Trading after you send an ACH
Account Check XML Request (as in section 3.1 XML ACH Account Check Request).
Please note that an example ACH ACCOUNTCHECK XML Response can be
found in the STAPI client files, within the ACCOUNTCHECK_ACH folder, which
can be downloaded from our website:
http://webapp.securetrading.net/examples/STAPI_JAVA1.6.zip
3.2.1
XML Overview
The XML Response for an ACH Account Check is similar to a regular Authorisation XML
Response, except for the differences outlined in this section of the document.
Other fields that can be included within the response are covered in the STPP XML
Specification document (see section 11.3 Useful Documents).
The diagram below shows an ACH Account Check Response.
authcode
timestamp
live
response type =
“ACCOUNTCHECK”
transactionreference
merchant
address
+
security
settlement
billing
operation
error
+
+
+
postcode
achtype
securitycode
achchecknumber
amount currencycode =
“USD”
achaccountnumber
payment type = “ACH”
achaba
socialsecuritynumber
+
acquirerresponsecode
acquirerresponsemessage
Figure 9 - ACH Account Check XML Response
© Secure Trading Limited 2017
7 April 2017
Page 18 / 51
ACH
3.2.2
<request type=”ACCOUNTCHECK”>
The request type for an Account Check Request is “ACCOUNTCHECK”.
3.2.3
<billing>
3.2.3.1 <socialsecuritynumber>
If the customer’s social security number was submitted in the XML Request, a masked version
is returned in the billing tag of the XML Response.
Tag
socialsecurity
number
Type
Length
Required
n
9
N
Comment
The customer’s social security
number. All numbers except the last
four are masked. (e.g. “#####6789”)
3.2.3.2 <amount>
alias
+
billing
amount currencycode
= ”USD”
response type =
“ACCOUNTCHECK”
Figure 10 - ACH Account Check XML Response <amount> tag
The amount tag for an Account Check can be 0. The currency must be “USD”. This is returned
in the billing tag of the XML Response.
3.2.3.3 <payment>
achtype
alias
+
billing
achchecknumber
payment type = “ACH”
response type =
“ACCOUNTCHECK”
achaccountnumber
achaba
Figure 11 - ACH Account Check XML Response <payment> tag
Tag
payment
type = “ACH”
Type
Length
Required
an
20
Y
achtype
an
10
Y
achchecknumber
n
10
N
n
17
Y
Account number
n
9
Y
Transit routing number
achaccount
number
achaba
© Secure Trading Limited 2017
7 April 2017
Comment
Payment type is returned as “ACH”
Account type. Either “SAVINGS”,
“CHECKING” or “BUSINESSCK”
Check number for Point of Sale
transactions. Length can be between
1 and 10.
Page 19 / 51
ACH
3.2.4
<security>
address
response type =
“ACCOUNTCHECK”
postcode
security
securitycode
Figure 12 - ACH Account Check XML Response <security> tag
The <securitycode> tag within the XML Response provides the results of checks performed
by your acquiring bank on the customer’s payment details. For ACH Account Checks, the
address and postcode fields are not used as part of the check.
These are the child elements returned in the <security> tag, in the XML Response:
Tag
security
Type
Length
Required
address
n
1
Y
postcode
n
1
Y
securitycode
n
1
Y
Comment
This field will always have the value
‘1’.
This field will always have the value
‘1’.
The result of the Account Checks.
See section 2.2.3 Response for
more information on this field.
The table below lists all of the possible security responses that can be returned in the
securitycode field:
securitycode
Description
Definition
1
“Not
Checked”
The acquiring bank was unable to complete checks on the
information you provided in the request.
2
“Matched”
The information you provided in the request is deemed low
or medium risk by the acquiring bank and is therefore
considered acceptable for further transactions.
4
“Not
Matched”
The information you provided in the request is deemed high
risk by the acquiring bank and is therefore considered
inappropriate for further transactions.
When performing combined ACH Account Check and Authorisation
Requests, it is recommended that you contact support in order to set up
rules, which use the results of the Account Check carried out by the
acquiring bank to either allow or prevent future authorisations. Please refer
to section 2.2.4 Rules on page 7 for further information.
© Secure Trading Limited 2017
7 April 2017
Page 20 / 51
ACH
3.2.5
<settlement>
The value of the settlestatus in the Response will remain the same as the value in the
Request and does not represent the state of the Account Check. This is to allow you to inherit
this value in subsequent child transactions, such as an Authorisation Request.
The settlestatus of the Account Check is not updated after completion of the Account
Check Request.
Please note that the results of the Account Check returned by the acquiring bank
can be found in the security tag (see section 3.2.4 <security>).
3.2.6
<acquirerresponsecode> and <acquirerresponsemessage>
The acquirerresponsecode and acquirerresponsemessage elements contain a
response message from the acquiring bank. For more information, please contact your acquirer.
Please see the section 12 Appendix for further information.
Tag
acquirerresponse
code
acquirerresponse
message
© Secure Trading Limited 2017
Type
Length
Required
an
255
N
an
255
N
7 April 2017
Comment
Response code returned from the
acquiring bank.
Message, associated with the
response code, returned from the
acquiring bank.
Page 21 / 51
ACH
3.2.7
ACH Account Check XML Response Example
Please find below an example of an ACH ACCOUNTCHECK XML Response received from
Secure Trading’s systems (fields of interest for ACH are highlighted in bold):
It is strongly recommended that you check the <security> fields returned in
the XML Response, and discontinue further transactions with the customer, if
the security response indicates high risk (securitycode is 4). See section
3.2.4 <security> for more information.
<?xml version='1.0' encoding='utf-8'?>
<responseblock version="3.67">
<requestreference>X538749002</requestreference>
<response type="ACCOUNTCHECK">
<merchant>
<merchantname>example UNICODE merchantname</merchantname>
<orderreference>ACCOUNTCHECK_ACH</orderreference>
<operatorname>test_example40000</operatorname>
</merchant>
<transactionreference>15-69-1</transactionreference>
<billing>
<amount currencycode="USD">0</amount>
<socialsecuritynumber>#####6789</socialsecuritynumber>
<payment type="ACH">
<achaccountnumber>12#####81</achaccountnumber>
<achchecknumber>123456</achchecknumber>
<achtype>SAVINGS</achtype>
<achaba>98#####21</achaba>
</payment>
</billing>
<authcode>TEST</authcode>
<live>0</live>
<error>
<message>Ok</message>
<code>0</code>
</error>
<timestamp>2013-04-09 08:33:07</timestamp>
<acquirerresponsecode>P70</acquirerresponsecode>
<security>
<address>1</address>
<postcode>1</postcode>
<securitycode>2</securitycode>
</security>
<settlement>
<settleduedate>2013-04-09</settleduedate>
<settlestatus>0</settlestatus>
</settlement>
<operation>
<accounttypedescription>ECOM</accounttypedescription>
</operation>
<acquirerresponsemessage>VALIDATED</acquirerresponsemessage>
</response>
</responseblock>
© Secure Trading Limited 2017
7 April 2017
Page 22 / 51
ACH
4
ACH Authorisation
4.1
XML ACH Authorisation Request
This section of the document describes the XML structure of an ACH Authorisation (AUTH)
Request. The Request described in this section of the document does not perform an Account
Check. It is possible to combine an Account Check Request with an Authorisation, by sending
an XML Request with the structure described in section 5.1 XML ACH Authorisation with
Account Check Request.
Please note that it is also possible to process an ACH Authorisation by inheriting
the transaction details (including amount) from a previous Account Check
transaction.
This
is
achieved
by
passing
through
the
parenttransactionreference of the Account Check transaction within the
<operation> tag of the Authorisation Request.
Please note that an example ACH AUTHORISATION XML Request can be
found in the STAPI client files, within the AUTH_ACH folder, which can be
downloaded from our website:
http://webapp.securetrading.net/examples/STAPI_JAVA1.6.zip
4.1.1
XML Overview
The XML Request for an ACH payment is similar to a standard Authorisation (AUTH) Request,
except for the differences outlined in this section of the document. Other fields that can be
included within the request are covered in the STPP XML Specification document (see section
11.3 Useful Documents).
The diagram below shows an ACH Authorisation Request. The <payment> tag will need to
include elements specific to ACH transactions.
operation
merchant
alias
billing
customer
+
+
+
+
+
name
amount currencycode
= ”USD”
payment type = ”ACH”
+
socialsecuritynumber
request type = “AUTH”
settlement
+
settlestatus
Figure 13 - ACH AUTH XML Request
© Secure Trading Limited 2017
7 April 2017
Page 23 / 51
ACH
4.1.2
<billing>
4.1.2.1 <socialsecuritynumber>
The socialsecuritynumber element can be submitted within the billing tag, for ACH
transactions. If you are inheriting details from a previous Account Check transaction, the
socialsecuritynumber will be inherited.
Tag
socialsecurity
number
Type
Length
Required
n
9
N
Comment
The customer’s social security
number. Numbers only.
4.1.2.2 <name>
prefix
first
alias
billing
middle
+
name
last
request type = “AUTH”
suffix
Figure 14 - ACH AUTH XML Request <name> tag
The name tag is mandatory. A billing name must be submitted for every ACH Request.
Tag
name
Type
Length
Required
prefix
an
25
N
first
an
25
Y
middle
an
25
N
last
an
25
Y
suffix
an
25
N
Comment
The prefix of the Customer’s billing
name (e.g. Mr,Miss,Dr).
The Customer’s billing first name.
The Customer’s billing middle
name(s).
The Customer’s billing last name.
The Customer’s suffix of the billing
name (e.g. Bsc).
4.1.2.3 <amount>
The currency must be “USD”. If you are inheriting details from a previous Account Check
transaction, the amount will be inherited, unless you specify a new amount in the <amount>
tag.
© Secure Trading Limited 2017
7 April 2017
Page 24 / 51
ACH
4.1.2.4 <payment>
achtype
alias
achchecknumber
+
billing
payment type = “ACH”
achaccountnumber
request type = “AUTH”
achaba
Figure 15 - ACH AUTH XML Request <payment> tag
Tag
payment
type = “ACH”
Type
Length
Required
an
20
Y
achtype
an
10
Y
achchecknumber
n
10
N
n
17
Y
Account number
n
9
Y
Transit routing number
achaccount
number
achaba
4.1.3
Comment
Payment type is submitted as “ACH”
Account type. Either “SAVINGS”,
“CHECKING” or “BUSINESSCK”
Check number for Point of Sale
transactions. Length can be between
1 and 10.
<settlement>
alias
settlement
+
settlestatus
request type = “AUTH”
Figure 16 - ACH AUTH XML Request <settlement> tag
In the settlement tag, the settlestatus tag can be set to ‘100’ to send an ACH payment to
be settled after it is authorised by the acquiring bank.
ACH bank transfers do not settle immediately, and for this reason, the settlestatus of the
transaction will initially be shown as ‘10’, representing a transaction that has been sent for
settlement, but has not yet received confirmation.
If you do not include a settlestatus tag in the request, the transaction is scheduled for
settlement in the next settlement run (normally the next day).
Tag
settlement
settlestatus
© Secure Trading Limited 2017
Type
n
Length
3
Required
N
7 April 2017
Comment
This value relates to the status you
would like to set the transaction.
The possible values are:
0 – Pending Settlement
100 – Settled (this is only available
for certain acquirers).
If this is not set, status is
automatically set to 0.
Page 25 / 51
ACH
4.1.4
ACH Authorisation XML Request Example
Please find below an example of an ACH AUTH XML Request to be submitted to Secure
Trading’s systems (fields of interest for ACH are highlighted in bold):
<?xml version='1.0' encoding='utf-8'?>
<requestblock version="3.67">
<alias>test_example40000</alias>
<request type="AUTH">
<merchant>
<orderreference>AUTH_ACH</orderreference>
</merchant>
<customer>
<town>Bangor</town>
<name>
<middle>Mary</middle>
<prefix>Miss</prefix>
<last>Smith</last>
<first>Joanne</first>
</name>
<ip>1.2.3.4</ip>
<telephone type="H">1111111111</telephone>
<street>Second Street</street>
<postcode>CU888ST</postcode>
<premise>111</premise>
</customer>
<billing>
<telephone type="M">0777777777</telephone>
<county>Gwynedd</county>
<street>Test Street</street>
<postcode>TE45 6ST</postcode>
<premise>789</premise>
<payment type="ACH">
<achaba>987654321</achaba>
<achchecknumber>123456</achchecknumber>
<achaccountnumber>123456781</achaccountnumber>
<achtype>SAVINGS</achtype>
</payment>
<socialsecuritynumber>123456789</socialsecuritynumber>
<town>Bangor</town>
<name>
<middle>joe</middle>
<prefix>Dr</prefix>
<last>Smith</last>
<suffix>Jr.</suffix>
<first>John</first>
</name>
<country>GB</country>
<amount currencycode="USD">100</amount>
<email>[email protected]</email>
</billing>
<operation>
<sitereference>test_example40000</sitereference>
<accounttypedescription>ECOM</accounttypedescription>
</operation>
</request>
</requestblock>
© Secure Trading Limited 2017
7 April 2017
Page 26 / 51
ACH
4.2
XML ACH Authorisation Response
This section describes the XML Response that is returned by Secure Trading, after submitting
an ACH Authorisation Request.
Please note that an example ACH AUTHORISATION XML Response can be found
in the STAPI client files, within the AUTH_ACH folder, which can be downloaded
from our website:
http://webapp.securetrading.net/examples/STAPI_JAVA1.6.zip
4.2.1
XML Overview
The XML Response for an ACH Authorisation is similar to a standard Authorisation (AUTH)
Response. This section details the returned fields that are specific to ACH Authorisations.
Other fields that can be included within the response are covered in the STPP XML
Specification document (see section 11.3 Useful Documents).
The diagram below shows an ACH Authorisation Response. The <payment> tag contains the
relevant information for this payment type.
authcode
timestamp
live
transactionreference
response type = “AUTH”
merchant
security
+
+
settleduedate
achtype
settlestatus
settlement
billing
+
achchecknumber
payment type = “ACH”
achaccountnumber
operation
+
socialsecuritynumber
achaba
error
+
acquirerresponsecode
acquirerresponsemessage
Figure 17 - ACH AUTH XML Response
© Secure Trading Limited 2017
7 April 2017
Page 27 / 51
ACH
4.2.2
<billing>
4.2.2.1 <socialsecuritynumber>
If the customer’s social security number was submitted in the XML Request, a masked version
is returned in the billing tag of the XML Response.
Tag
socialsecurity
number
Type
Length
Required
n
9
N
Comment
The customer’s social security
number. All numbers except the last
four are masked. (e.g. “#####6789”)
4.2.2.2 <payment>
Within the <billing> tag, the <payment> tag contains the customer’s ACH details.
achtype
alias
billing
achchecknumber
+
payment type = “ACH”
achaccountnumber
response type = “AUTH”
achaba
Figure 18 - ACH AUTH XML Response <payment> tag
Tag
payment
type = “ACH”
Type
Length
Required
an
20
Y
achtype
an
10
Y
achchecknumber
n
10
N
n
17
Y
Account number
n
9
Y
Transit routing number
achaccount
number
achaba
© Secure Trading Limited 2017
7 April 2017
Comment
Payment type is returned as “ACH”
Account type. Either “SAVINGS”,
“CHECKING” or “BUSINESSCK”
Check number for Point of Sale
transactions. Length can be between
1 and 10.
Page 28 / 51
ACH
4.2.3
<error>
response type = “AUTH”
code
+
error
message
Figure 19 - ACH AUTH XML Response <error> tag
The error code should be used to determine if the request was successful or not.
If the error code is 0 then the transaction was successful.
If the error code is not 0 then the transaction was not successful.
An error code of 99999 represents an unknown error that can happen during
a request and requires manual investigation to determine the state of the
transaction. Please contact support (see section 11.1 Secure Trading
Support).
For a full list of error codes and error messages please see
http://webapp.securetrading.net/errorcodes.html
Tag
error
Type
Length
Required
code
n
5
Y
message
an
255
Y
Comment
The code will be 0 if the transaction
was successful.
This is the corresponding message to
the above code.
Please note that ACH transactions that are processed with invalid details (such
as an invalid field name), may be shown in MyST, with a given error message.
4.2.4
<acquirerresponsecode> and <acquirerresponsemessage>
The acquirerresponsecode and acquirerresponsemessage elements contain a
response message from the acquiring bank. For more information, please contact your acquirer.
Please see the section 12 Appendix for further information.
Tag
acquirerresponse
code
acquirerresponse
message
Type
Length
Required
an
255
N
an
255
N
Comment
Response code returned from the
acquiring bank.
Message, associated with the
response code, returned from the
acquiring bank.
Please note that the contents of the acquirer response code and message fields
may be updated after authorisation, either as part of confirmation or if a
chargeback occurs.
© Secure Trading Limited 2017
7 April 2017
Page 29 / 51
ACH
4.2.5
ACH Authorisation Response Example
Please find below an example of an ACH AUTH XML Response received from Secure Trading’s
systems (fields of interest for ACH are highlighted in bold):
<?xml version='1.0' encoding='utf-8'?>
<responseblock version="3.67">
<requestreference>X673033493</requestreference>
<response type="AUTH">
<merchant>
<merchantname>example UNICODE merchantname</merchantname>
<orderreference>AUTH_ACH</orderreference>
<operatorname>test_example40000</operatorname>
</merchant>
<transactionreference>15-69-2</transactionreference>
<security>
<postcode>1</postcode>
<securitycode>0</securitycode>
<address>1</address>
</security>
<billing>
<amount currencycode="USD">100</amount>
<socialsecuritynumber>#####6789</socialsecuritynumber>
<payment type="ACH">
<achaccountnumber>12#####81</achaccountnumber>
<achtype>SAVINGS</achtype>
<achaba>98#####21</achaba>
<achchecknumber>123456</achchecknumber>
</payment>
</billing>
<authcode>TEST</authcode>
<timestamp>2013-04-09 08:33:08</timestamp>
<settlement>
<settleduedate>2013-04-09</settleduedate>
<settlestatus>0</settlestatus>
</settlement>
<live>0</live>
<error>
<message>Ok</message>
<code>0</code>
</error>
<acquirerresponsecode>A01</acquirerresponsecode>
<operation>
<accounttypedescription>ECOM</accounttypedescription>
</operation>
<acquirerresponsemessage>APPROVED</acquirerresponsemessage>
</response>
</responseblock>
© Secure Trading Limited 2017
7 April 2017
Page 30 / 51
ACH
5
ACH Authorisation with Account Check
5.1
XML ACH Authorisation with Account Check Request
It is possible to send through an Account Check and an Authorisation (AUTH) in the same XML
Request. This section of the document describes the structure of this XML Request.
Before submitting an Account Check Request, as outlined in this section, it
is imperative that you read section 2.2 Account Check and consider setting
up rules that will prevent AUTHs from being processed from payment
details that fail an Account Check.
Secure Trading first processes the Account Check, and then if rules have been enabled on your
account, may or may not process the associated AUTH Request.
Please note that an example ACH AUTHORISATION WITH ACCOUNTCHECK
XML Request can be found in the STAPI client files, within the
ACH_ACCOUNTCHECK_WITH_AUTH_ACH folder, which can be downloaded
from our website:
http://webapp.securetrading.net/examples/STAPI_JAVA1.6.zip
© Secure Trading Limited 2017
7 April 2017
Page 31 / 51
ACH
5.1.1
XML Overview
The structure of the XML Request consists of two requests in a single request block. A single
XML Request is sent, containing both an “ACCOUNTCHECK” and an “AUTH” Request. The
structure of the Account Check section of the request is the same as an independent ACH
Account Check Request, as shown in section 3.1 XML ACH Account Check Request. The
structure of the AUTH section of the request can be the same as a regular ACH AUTH Request,
as outlined in section 4.1 XML ACH Authorisation Request, but can omit details already
submitted in the Account Check section of the request.
Please note that, as shown in the following XML example, the amount field can
only be omitted in the AUTH section of the request, if it is submitted in the
Account Check section of the request, as it is inherited from the parent Account
Check amount field.
operation
merchant
alias
billing
customer
request type =
“ACCOUNTCHECK”
settlement
request type = “AUTH”
operation
+
+
+
+
+
name
amount currencycode
= ”USD”
payment type= ”ACH”
+
socialsecuritynumber
+
settlestatus
+
Figure 20 - ACH AUTH with Account Check XML Request
© Secure Trading Limited 2017
7 April 2017
Page 32 / 51
ACH
5.1.2
ACH Authorisation with Account Check XML Request Example
Please find below an example of an ACH AUTH with ACCOUNTCHECK XML Request to be
submitted to Secure Trading’s systems (fields of interest for ACH are highlighted in bold):
<?xml version='1.0' encoding='utf-8'?>
<requestblock version="3.67">
<alias>test_example40000</alias>
<request type="ACCOUNTCHECK">
<merchant>
<orderreference>ach_accountcheck_with_auth</orderreference>
</merchant>
<customer>
<town>Bangor</town>
<name>
<middle>Mary</middle>
<prefix>Miss</prefix>
<last>Smith</last>
<first>Joanne</first>
</name>
<ip>1.2.3.4</ip>
<telephone type="H">1111111111</telephone>
<street>Second Street</street>
<postcode>CU888ST</postcode>
<premise>111</premise>
</customer>
<billing>
<town>Bangor</town>
<name>
<middle>joe</middle>
<prefix>Dr</prefix>
<last>bloggs</last>
<suffix>Jr.</suffix>
<first>fred</first>
</name>
<country>GB</country>
<email>[email protected]</email>
<telephone type="M">0777777777</telephone>
<county>Gwynedd</county>
<amount currencycode="USD">100</amount>
<street>Test Street</street>
<postcode>TE45 6ST</postcode>
<premise>789</premise>
<payment type="ACH">
<achaba>987654321</achaba>
<achaccountnumber>123456781</achaccountnumber>
<achchecknumber>123456</achchecknumber>
<achtype>SAVINGS</achtype>
</payment>
<socialsecuritynumber>123456789</socialsecuritynumber>
</billing>
<operation>
<accounttypedescription>ECOM</accounttypedescription>
<sitereference>test_example40000</sitereference>
</operation>
</request>
<request type="AUTH">
</request>
</requestblock>
© Secure Trading Limited 2017
7 April 2017
Page 33 / 51
ACH
5.2
XML ACH Authorisation with Account Check Response
This section outlines the XML Response received after sending an Authorisation (AUTH) with
Account Check XML Request.
Please note that an example ACH AUTHORISATION WITH ACCOUNTCHECK
XML Response can be found in the STAPI client files, within the
ACH_ACCOUNTCHECK_WITH_AUTH_ACH folder, which can be downloaded
from our website:
http://webapp.securetrading.net/examples/STAPI_JAVA1.6.zip
5.2.1
XML Overview
Below is a diagram of an ACH Authorisation with Account Check XML Response. The
<payment> tag contains the relevant information for this payment type.
Please note that an ACH Authorisation with Account Check XML Response
consists of two response tags, each with their own transactionreference
values.
address
alias
response type =
“ACCOUNTCHECK”
postcode
achtype
securitycode
achchecknumber
amount currencycode =
“USD”
achaccountnumber
payment type = “ACH”
achaba
security
billing
response type = “AUTH”
settlement
billing
+
+
socialsecuritynumber
payment type = “ACH”
+
Figure 21 - ACH AUTH with Account Check XML Response
5.2.2
ACH Authorisation with Account Check XML Response Example
Please find below an example of an ACH AUTH with ACCOUNTCHECK XML Response
received from Secure Trading’s systems (fields of interest for ACH are highlighted in bold):
Please note that the results of the Account Check will be in the securitycode
tag in the Account Check section of the response. The numbers shown in
security tag in the Authorisation section of the response should be ignored. For
information on the security response, see section 3.2.4 <security>.
© Secure Trading Limited 2017
7 April 2017
Page 34 / 51
ACH
<?xml version='1.0' encoding='utf-8'?>
<responseblock version="3.67">
<requestreference>X904343528</requestreference>
<response type="ACCOUNTCHECK">
<merchant>
<merchantname>example UNICODE merchantname </merchantname>
<orderreference>ach_accountcheck_with_auth</orderreference>
<operatorname>test_example40000</operatorname>
</merchant>
<transactionreference>15-69-3</transactionreference>
<billing>
<amount currencycode="USD">100</amount>
<socialsecuritynumber>#####6789</socialsecuritynumber>
<payment type="ACH">
<achaccountnumber>12#####81</achaccountnumber>
<achchecknumber>123456</achchecknumber>
<achtype>SAVINGS</achtype>
<achaba>98#####21</achaba>
</payment>
</billing>
<authcode>TEST</authcode>
<live>0</live>
<error>
<message>Ok</message>
<code>0</code>
</error>
<timestamp>2013-04-09 08:33:25</timestamp>
<acquirerresponsecode>P70</acquirerresponsecode>
<security>
<address>1</address>
<postcode>1</postcode>
<securitycode>2</securitycode>
</security>
<settlement>
<settleduedate>2013-04-09</settleduedate>
<settlestatus>0</settlestatus>
</settlement>
<operation>
<accounttypedescription>ECOM</accounttypedescription>
</operation>
<acquirerresponsemessage>VALIDATED</acquirerresponsemessage>
</response>
<response type="AUTH">
<merchant>
<merchantname>example UNICODE merchantname</merchantname>
<orderreference>ach_accountcheck_with_auth</orderreference>
</merchant>
<transactionreference>15-69-4</transactionreference>
<security>
<postcode>1</postcode>
<securitycode>0</securitycode>
<address>1</address>
</security>
<billing>
<amount currencycode="USD">100</amount>
<socialsecuritynumber>#####6789</socialsecuritynumber>
<payment type="ACH">
<achaccountnumber>12#####81</achaccountnumber>
<achtype>SAVINGS</achtype>
© Secure Trading Limited 2017
7 April 2017
Page 35 / 51
ACH
<achaba>98#####21</achaba>
<achchecknumber>123456</achchecknumber>
</payment>
</billing>
<authcode>TEST</authcode>
<timestamp>2013-04-09 08:33:25</timestamp>
<settlement>
<settleduedate>2013-04-09</settleduedate>
<settlestatus>0</settlestatus>
</settlement>
<live>0</live>
<error>
<message>Ok</message>
<code>0</code>
</error>
<acquirerresponsecode>A01</acquirerresponsecode>
<operation>
<parenttransactionreference>15-69-3</parenttransactionreference>
<accounttypedescription>ECOM</accounttypedescription>
</operation>
<acquirerresponsemessage>APPROVED</acquirerresponsemessage>
</response>
</responseblock>
© Secure Trading Limited 2017
7 April 2017
Page 36 / 51
ACH
6
ACH Refund
6.1
XML ACH Refund Request
In order to refund a transaction or make any other payment to the customer, you need to
perform a Cardholder Funds Transfer (CFT) Refund. CFT Refunds can be used to pay a
specified amount to the customer, without the need to refer to a pre-existing Authorisation
(AUTH).
The CFT refund amount can be different to the amount specified in the initial transaction, even
when referencing a parent transaction.
Please note that an example ACH REFUND XML Request can be found in the
STAPI client files, within the CFT_REFUND_ACH folder, which can be
downloaded from our website:
http://webapp.securetrading.net/examples/STAPI_JAVA1.6.zip
Please note that you can inherit details from a pre-existing ACH transaction, by
passing through the parenttransactionreference of the transaction.
If you wish to reference a previous transaction as part of a CFT transaction you
can include the tag <parenttransactionreference>
within the
<operation> tag of the request.
Please note that you cannot process a new CFT Refund by using the Virtual
Terminal feature of MyST. At this time, you can only perform a CFT Refund
Request by sending through an XML Request to the STPP gateway, as outlined
in this section of the document.
© Secure Trading Limited 2017
7 April 2017
Page 37 / 51
ACH
6.1.1
XML Overview
The XML structure for an ACH Refund Request is similar to an ACH AUTH Request (see
section 11.3 Useful Documents), with the following important differences:
The request type is “REFUND”.
The accounttypedescription is “CFT”.
operation
merchant
alias
billing
customer
+
+
accounttypedescription
+
name
+
amount currencycode
= ”USD”
+
payment type = ”ACH”
+
request type = “REFUND”
socialsecuritynumber
Figure 22 - ACH CFT Refund XML Request
© Secure Trading Limited 2017
7 April 2017
Page 38 / 51
ACH
6.1.2
ACH Refund XML Request Example
Please find below an example of an ACH REFUND XML Request to be submitted to Secure
Trading’s systems (fields of interest for ACH are highlighted in bold):
<?xml version='1.0' encoding='utf-8'?>
<requestblock version="3.67">
<alias>test_example40000</alias>
<request type="REFUND">
<merchant>
<orderreference>CFT_REFUND_ACH</orderreference>
</merchant>
<customer>
<town>Bangor</town>
<name>
<middle>Mary</middle>
<prefix>Miss</prefix>
<last>Smith</last>
<first>Joanne</first>
</name>
<ip>1.2.3.4</ip>
<telephone type="H">1111111111</telephone>
<street>Second Street</street>
<postcode>CU888ST</postcode>
<premise>111</premise>
</customer>
<billing>
<town>Bangor</town>
<name>
<middle>joe</middle>
<prefix>Dr</prefix>
<last>Smith</last>
<suffix>Jr.</suffix>
<first>John</first>
</name>
<country>GB</country>
<email>[email protected]</email>
<telephone type="M">0777777777</telephone>
<county>Gwynedd</county>
<amount currencycode="USD">100</amount>
<street>Test Street</street>
<postcode>TE45 6ST</postcode>
<premise>789</premise>
<socialsecuritynumber>123456789</socialsecuritynumber>
<payment type="ACH">
<achaba>987654321</achaba>
<achaccountnumber>123456781</achaccountnumber>
<achchecknumber>123456</achchecknumber>
<achtype>SAVINGS</achtype>
</payment>
</billing>
<operation>
<sitereference>test_example40000</sitereference>
<accounttypedescription>CFT</accounttypedescription>
</operation>
</request>
</requestblock>
© Secure Trading Limited 2017
7 April 2017
Page 39 / 51
ACH
6.2
XML ACH Refund Response
This section outlines the structure of the XML Response to an ACH Refund XML Request (see
section 6.1 XML ACH Refund Request for more information).
Please note that an example ACH REFUND XML Response can be found in the
STAPI client files, within the CFT_REFUND_ACH folder, which can be
downloaded from our website:
http://webapp.securetrading.net/examples/STAPI_JAVA1.6.zip
6.2.1
XML Overview
The XML structure for an ACH Refund Response is similar to an ACH AUTH Response (see
section 4.2 XML ACH Authorisation Response), with the following important differences:
The request type is “REFUND”.
The accounttypedescription is “CFT”.
authcode
timestamp
live
transactionreference
response type = “REFUND”
merchant
security
settlement
billing
+
+
+
+
operation
+
error
+
accounttypedescription
acquirerresponsecode
acquirerresponsemessage
Figure 23 - ACH CFT Refund XML Response
© Secure Trading Limited 2017
7 April 2017
Page 40 / 51
ACH
6.2.2
ACH Refund XML Response Example
Please find below an example of an ACH REFUND XML Response received from Secure
Trading’s systems (fields of interest for ACH are highlighted in bold):
<?xml version='1.0' encoding='utf-8'?>
<responseblock version="3.67">
<requestreference>X768881073</requestreference>
<response type="REFUND">
<merchant>
<merchantname>example merchantname</merchantname>
<orderreference>CFT_REFUND_ACH</orderreference>
<operatorname>test_example40000</operatorname>
</merchant>
<transactionreference>15-69-5</transactionreference>
<billing>
<amount currencycode="USD">100</amount>
<socialsecuritynumber>#####6789</socialsecuritynumber>
<payment type="ACH">
<achaccountnumber>12#####81</achaccountnumber>
<achchecknumber>123456</achchecknumber>
<achtype>SAVINGS</achtype>
<achaba>98#####21</achaba>
</payment>
</billing>
<authcode>TEST</authcode>
<live>0</live>
<error>
<message>Ok</message>
<code>0</code>
</error>
<timestamp>2013-04-09 08:33:33</timestamp>
<acquirerresponsecode>A01</acquirerresponsecode>
<security>
<address>1</address>
<postcode>1</postcode>
<securitycode>0</securitycode>
</security>
<settlement>
<settleduedate>2013-04-09</settleduedate>
<settlestatus>10</settlestatus>
</settlement>
<operation>
<accounttypedescription>CFT</accounttypedescription>
</operation>
<acquirerresponsemessage>APPROVED</acquirerresponsemessage>
</response>
</responseblock>
© Secure Trading Limited 2017
7 April 2017
Page 41 / 51
ACH
7
ACH Transaction Query
In order to view details of an Account Check, Authorisation or CFT Refund transaction that has
been processed through Secure Trading, you can send a Transaction Query Request,
containing the transactionreference of the transaction. An XML Response will be
returned, with information about the transaction.
7.1
XML ACH Transaction Query Request
The structure of the XML Request used in this case is the same as a regular Transaction Query
Request. Please refer to the STPP Transaction Query document for more information (see
section 11.3 Useful Documents).
7.1.1
XML Transaction Query Request Example
Please find below an example of a TRANSACTIONQUERY XML Request to be submitted to
Secure Trading’s systems.
<?xml version="1.0" encoding="utf-8"?>
<requestblock version="3.67">
<alias>site12345</alias>
<request type="TRANSACTIONQUERY">
<filter>
<sitereference>site12345</sitereference>
<transactionreference>50-2-2</transactionreference>
</filter>
</request>
</requestblock>
7.2
XML ACH Transaction Query Response
Once you have successfully submitted a Transaction Query Request through STPP, if no errors
were found, you will be returned an XML Response. The structure of the XML returned in the
response is similar to that of a normal Transaction Query Response, with fields returned in the
response that are unique to ACH transactions. These are outlined in detail in section 4.2.2.2
<payment>.
© Secure Trading Limited 2017
7 April 2017
Page 42 / 51
ACH
8
ACH Transaction Update
It is possible to update certain fields in an ACH payment after authorisation (but before it has
been
settled)
by sending
a
Transaction
Update
Request,
containing
the
transactionreference of the transaction and the desired changes. For further information,
please refer to the STPP Transaction Update document (see section 11.3 Useful
Documents).
Please note that transactions cannot be cancelled or updated after they have
been sent to be settled (when they have a settlestatus of 10). ACH
transactions can only be updated if they have a settlestatus of 0.
Please note that ACH transactions are cancelled by Secure Trading if they have
not been settled within 7 days of being authorised.
8.1
XML Transaction Update Request Example
Please find below an example of a TRANSACTIONUPDATE Request to be submitted to Secure
Trading’s systems.
<?xml version="1.0" encoding="utf-8"?>
<requestblock version="3.67">
<alias>site12345</alias>
<request type="TRANSACTIONUPDATE">
<filter>
<sitereference>site12345</sitereference>
<transactionreference>51-2-5</transactionreference>
</filter>
<updates>
<settlement>
<settlestatus>1</settlestatus>
</settlement>
</updates>
</request>
</requestblock>
8.2
XML Transaction Update Response Example
Please find below an example of a TRANSACTIONQUERY Response returned from Secure
Trading’s systems.
<?xml version="1.0" encoding="utf-8"?>
<responseblock version="3.67">
<requestreference>X675136983</requestreference>
<response type="TRANSACTIONUPDATE">
<timestamp>2010-03-11 16:38:47</timestamp>
<error>
<code>0</code>
</error>
</response>
</responseblock>
© Secure Trading Limited 2017
7 April 2017
Page 43 / 51
ACH
9
Additional Notes
9.1
System Limitations
The request types supported for ACH Bank Transfers are:
AUTH
ACCOUNTCHECK
TRANSACTIONQUERY
TRANSACTIONUPDATE
REFUND
CHARGEBACK*
* This request can only be generated by Secure Trading when the customer’s bank requests a
Chargeback and cannot be sent in a request by a merchant.
9.2
Card Store
It is not possible to use Card Store with ACH payment details.
9.3
Subscriptions and Tokenisation
It is not possible to set up recurring payments using ACH payment details.
9.4
Supported Currencies
ACH only supports transactions that use the currency USD.
9.5
Mail or Telephone Order
ACH does not support Mail or Telephone Order (MOTO) transactions.
© Secure Trading Limited 2017
7 April 2017
Page 44 / 51
ACH
10
Testing
ACH Bank Transfers can be tested using Secure Trading’s test system. Test transactions must
be processed using a test account. If you do not know your test account details, please contact
Secure Trading Support (see section 11.1 Secure Trading Support).
10.1
Account Check Requests (ACCOUNTCHECK)
To test Account Check Responses, please send through a valid ACH Account Check Request,
substituting the following values in the achaccountnumber field.
achaccountnumber
‘123456781’
‘123456783’
‘123456784’
10.2
Response from the test system
“VALIDATED” (2 Matched)
“HIGH RISK” (4 Not Matched)
“PREAUTH VENDOR
UNAVAIL” (1 Not Checked)
securitycode response value
2
4
1
Authorisation Requests (AUTH) and Chargebacks (CHARGEBACK)
The “Days” used in the following process overviews are used for demonstration purposes only
and the period between each step is dependent on the time the transaction was processed and
the settlement process is run.
Please note that for testing purposes, when processing ACH transactions on
your test site, you receive notification of Chargeback immediately after settlement
confirmation. With live accounts, it may take several weeks before a Chargeback
is processed against a settled ACH transaction.
10.2.1
Authorised and settled successfully by test bank
To simulate an ACH transaction that is authorised and settled by the test bank, submit a valid
ACH AUTH XML Request with the following fields:
achaccountnumber – “123456781”
amount – “1011”
Day One
Secure Trading interprets the
AUTH XML Request and contacts
a simulated test bank, which
authorises the transaction.
Day Two
Secure Trading sends details of
the transaction to the test bank for
settlement.
Day Three
Secure Trading checks for
confirmation of settlement from
the test bank, and updates the
transaction
accordingly.
The
transaction was confirmed as
settled by the bank.
settlestatus – 0
“Pending settlement”
settlestatus – 10
“Settling”
settlestatus – 100
“Settled”
(e.g.)
transactionreference – 1-1-1
XML Response received by merchant
(e.g.)
transactionreference – 1-1-1
(e.g.)
transactionreference – 1-1-1
Notification sent to merchant
© Secure Trading Limited 2017
7 April 2017
Page 45 / 51
ACH
10.2.2
Sent for settlement immediately after successful authorisation
To simulate an ACH transaction that is sent for settlement immediately after authorisation,
submit a valid ACH AUTH XML Request with the following fields:
achaccountnumber – “123456781”
amount – “1011”
settlestatus – “100”
Day One
Secure Trading interprets the
AUTH XML Request and contacts
a simulated test bank, which
authorises the transaction. Details
of the transaction are then sent to
the test bank for settlement.
Day Two
Secure Trading checks for
confirmation of settlement from
the test bank, and updates the
transaction
accordingly.
The
transaction was confirmed as
settled by the bank.
settlestatus – 10
“Settling”
settlestatus – 100
“Settled”
(e.g.)
transactionreference – 1-1-2
XML Response received by merchant
(e.g.)
transactionreference – 1-1-2
Notification sent to merchant
10.2.3
Authorised and settled successfully by test bank, then Chargeback generated
To simulate an ACH transaction that is authorised and settled by the test bank and then a
Chargeback is generated, submit a valid ACH AUTH XML Request with the following fields:
achaccountnumber – “123456781”
amount – “1044”, “820544” or “822944”
(the different amounts shown here simulate different response codes in the
Chargeback, following confirmation)
Day One
Secure Trading interprets the
AUTH XML Request and contacts
a simulated test bank, which
authorises the transaction.
Day Two
Secure Trading sends details of
the transaction to the test bank for
settlement.
Day Three
Secure Trading checks for
confirmation of settlement from
the test bank, and updates the
transaction accordingly. They
receive
information
of
a
Chargeback, which is recorded as
a separate transaction.
settlestatus – 0
“Pending settlement”
(e.g.)
transactionreference – 1-1-3
XML Response received by merchant
settlestatus – 10
“Settling”
settlestatus – 100
“Settled”
(e.g.)
transactionreference – 1-1-3
(e.g.)
transactionreference – 1-1-3
Notification sent to merchant
Simulates chargeback generation
settlestatus – 100
“Settled”
(e.g.)
transactionreference – 1-1-4
Notification sent to merchant
© Secure Trading Limited 2017
7 April 2017
Page 46 / 51
ACH
10.2.4
Authorised but cancelled by test bank
To simulate an ACH transaction that is authorised and cancelled by the test bank, submit a valid
ACH AUTH XML Request with the following fields:
achaccountnumber – “123456781”
amount – “1033”, “821633” or “823233”
(the different amounts shown here simulate different response codes in the AUTH
following confirmation)
Day One
Secure Trading interprets the
AUTH XML Request and contacts
a simulated test bank, which
authorises the transaction.
Day Two
Secure Trading sends details of
the transaction to the test bank for
settlement.
Day Three
Secure Trading checks for
confirmation of settlement from
the test bank, and updates the
transaction
accordingly.
The
transaction was cancelled by the
bank.
settlestatus – 0
“Pending settlement”
(e.g.)
transactionreference – 1-1-5
XML Response received by merchant
settlestatus – 10
“Settling”
settlestatus – 3
“Cancelled”
(e.g.)
transactionreference – 1-1-5
(e.g.)
transactionreference – 1-1-5
Notification sent to merchant
10.2.5
Declined by the test bank
To simulate an ACH transaction that is declined by the test bank, submit a valid ACH AUTH
XML Request with the following fields:
achaccountnumber – “123456782”
amount – “1011”
Day One
Secure Trading interprets the
AUTH XML Request and contacts
a simulated test bank, which
declines the transaction.
settlestatus – 3
“Declined”
(e.g.)
transactionreference – 1-1-6
XML Response received by merchant
© Secure Trading Limited 2017
7 April 2017
Page 47 / 51
ACH
11
Further Information and Support
This section provides useful information with regards to documentation and support for the
Merchant’s Secure Trading solution.
11.1
Secure Trading Support
If you have any questions regarding integration or maintenance of the system, please contact
our support team using one of the following methods.
Method
Telephone
Fax
Email
Website
11.2
Details
+44 (0) 1248 672 050
+44 (0) 1248 672 099
[email protected]
http://www.securetrading.com/support/support.html
Secure Trading Sales
If you do not have an account with Secure Trading, please contact our Sales team and they will
inform you of the benefits of a Secure Trading account.
Method
Telephone
Telephone (Int’l)
Fax
Email
Website
11.3
Details
0800 028 9151
+44 (0) 1248 672 070
+44 (0) 1248 672 079
[email protected]
http://www.securetrading.com
Useful Documents
The documents listed below should be read in conjunction with this document:
STPP XML Specification Documentation – This document outlines fields used in XML
Requests and Responses by Secure Trading.
STPP Notifications – This document outlines how to configure notifications for events
that occur on your Secure Trading account.
STPP Chargebacks – This document introduces the reader to Chargebacks and how
they are processed through STPP.
STAPI Setup Guide – This document outlines how to install a STAPI java client. This
client can be used to process XML Requests and Responses through Secure Trading.
XML Reference Transaction Query – This document outlines how to perform a
Transaction Query Request.
XML Reference Transaction Update – This document outlines how to perform a
Transaction Update Request.
Any other document regarding the STAPI system can be found on Secure Trading’s website
(http://www.securetrading.com). Alternatively, please contact our support team as outlined
above.
11.4
Frequently Asked Questions
Please visit the FAQ section on our website (http://www.securetrading.com/support/faq).
© Secure Trading Limited 2017
7 April 2017
Page 48 / 51
ACH
12
Appendix
12.1
ACH Response Codes
The following section outlines the response codes and messages that can be returned from
your acquiring bank in ACH transaction responses. These are correct at time of writing, but are
subject to change. For further information on ACH response codes (also referred to as “return
codes”), please contact your acquirer.
Response
Code
A01
P15
P40
P41
P50
P70
P71
P73
R01
R02
R03
R04
R05
R06
R07
R08
R09
R10
R11
R12
R13
R14
R15
R16
R17
R18
R19
R20
R21
R22
R23
R24
R25
R26
R27
R28
R29
R30
Response message
APPROVED
HIGH RISK
NO NEG INFO
NEGATIVE INFO
NO INFO
VALIDATED
LOW RISK APPROVAL
MEDIUM RISK APPROVAL
Insufficient Funds
Account Closed
No Account/Unable to Locate Account
Invalid Account Number
Reserved
Returned per ODFIs Request
Authorization Revoked by Customer
Payment Stopped or Stop Payment on Item
Uncollected Funds
Customer Advises Not Authorized
Check Truncation Entry Return
Branch sold to another DFI
RDFI not qualified to participate
Re-presentment payee deceased or unable to continue in that capacity
Beneficiary of account holder deceased
Account Frozen
File record edit criteria
Improper effective entry date
Amount field error
Non-Transaction Account
Invalid company identification
Invalid individual ID number
Credit entry refused by receiver
Duplicate entry
Addenda error
Mandatory field error
Trace number error
Routing number check digit error
Corporate customer advises not authorized
RDFI not participant in check truncation program
© Secure Trading Limited 2017
7 April 2017
Page 49 / 51
ACH
Response
Code
R31
R32
R33
R34
R35
R36
R40
R41
R42
R43
R44
R45
R46
R47
R50
R51
R52
R61
R62
R63
R64
R65
R66
R67
R68
R69
R70
R71
R72
R73
R74
R80
R81
R82
R83
U02
U10
U12
U13
U15
U18
U19
U25
U26
U27
U28
Response message
Permissible return entry
RDFI non-settlement
Return of XCK entry
Limited participation DFI
Return of improper debit entry
Return of improper credit entry
Return of ENR entry by Federal Government Agency (ENR Only)
Invalid transaction code (ENR Only)
Routing number/check digit error (ENR only)
Invalid DFI account number (ENR only)
Invalid individual ID number (ENR only)
Invalid individual name/company name (ENR only)
Invalid representative payee indicator (ENR only)
Duplicate enrollment
State Law Affecting RCK Acceptance
Item is Ineligible, Notice Not Provided, Signature not genuine
Stop Payment on Item
Misrouted return
Incorrect trace number
Incorrect dollar amount
Incorrect individual identification
Incorrect transaction code
Incorrect company identification
Duplicate return
Untimely Return
Multiple Errors
Permissible return entry not accepted
Misrouted dishonored return
Untimely dishonored return
Timely original return
Corrected return
Cross-Border Payment Coding Error
Non-Participant in Cross-Border Program
Invalid Foreign Receiving DFI Identification
Foreign Receiving DFI Unable to Settle
TRN NOT APPROVED
DUPLICATE TRANSACTION
UPDATE NOT ALLOWED
ORIG TRANS NOT FOUND
ALREADY VOIDED ALREADY CAPTURED
UPDATE FAILED
INVALID TRN
INVALID AMOUNT
INVALID DATA
CONV FEE NOT ALLOWED
CONV FEE INCORRECT
© Secure Trading Limited 2017
7 April 2017
Page 50 / 51
ACH
Response
Code
U29
U30
U51
U54
U80
U81
U82
U83
U84
U85
U88
U90
Response message
CONV FEE DECLINED
PRINCIPAL DECLINED
MERCHANT STATUS
INVALID MERCHANT CONFIG
PREAUTH DECLINE
PREAUTH TIMEOUT
PREAUTH ERROR
AUTH DECLINE
AUTH TIMEOUT
AUTH ERROR
PREAUTH BUSY
PREAUTH UNAVAIL
© Secure Trading Limited 2017
7 April 2017
Page 51 / 51