Chapter 6 - SecureACH Storage | Nuvei Technologies

SecureACH Storage is the storage of sensitive account information in the Nuvei system for use at a later date. It is a requirement for ACH Subscription processing. It is useful for merchants that are required to perform regular payments without the accountholder entering their information.

6.1 SecureACH Registration and Updating From the Hosted Page link

SecureACH details can be registered or updated using the Nuvei hosted page by the account holder, account details will be

stored using Nuvei SecureACH Storage.

To initiate a SecureACH registration or update a POST must be made to the following URL:

https://testpayments.nuvei.com/merchant/securecardpage

The following table describes the form felds to be posted:

Field Name	Required	Description
ACTION	Y	registerAch updateAch
MERCHANTREF	Y	Unique Reference assigned by the merchants site/software to identify the stored account details. Length is limited to 48 chars.
DATETIME	Y	Format: DD-MM-YYYY:HH:MM:SS:SSS
TERMINALID		A Terminal ID provided by Nuvei. NB – Please contact Nuvei to be issued with a test terminal ID.
RECEIPTPAGEURL	N	Overrides “Secure Card URL” terminal setting if sent.
PERMITTEDTERMINALS	N	Terminals which are permitted to process the request. The PERMITTEDTERMINALS string should be a comma separated list of the permitted terminals
HASH	Y	An SHA-512 HASH. See Note 1 below.

Notes:

1. The SHA-512 HASH is generated using the following as an input string

TERMINALID:MERCHANTREF:DATETIME:ACTION:RECEIPTPAGEURL:secret

Below is an example HTML form to open account details registration page.

HTML

<html>
<body>
<form action="https://testpayments.nuvei.com/merchant/securecardpage" method="post">
	<input type="hidden" name="ACTION" value="registerAch" />
	<input type="hidden" name="TERMINALID" value="6491002" />
	<input type="hidden" name="MERCHANTREF" value="1234321" />
	<input type="hidden" name="DATETIME" value="15-03-2006:10:43:01:673" />
	<input type="hidden" name="HASH" value="d5d3441f0e8318ce6d03976c2e93749" />
	<input type="submit" value="Register" />
</form>
</body>
<html>

To initiate account details updating, the value of the ACTION parameter should be changed to “updateAch”. A SecureACH of MERCHANTREF 1234321 must be already existing under your account. Please note that the TERMINALID here is not valid and must be changed.

Assuming valid details were sent, the Hosted Registration or Update page will be displayed, clicking on “Register” or “Update” will save the account details, result GET parameters will be forwarded to the SecureACH URL that is confgured on the Terminal Setup page.

Following parameters will be sent to the SecureACH Receipt URL:

Field Name	Description
RESPONSECODE	Response Code “A” - Approval, check the Response Codes table below for a full list of all supported codes.
RESPONSETEXT	Response Text.
MERCHANTREF	Original Merchant Reference.
ACHREFERENCE	Generated globally unique numeric account reference.
DATETIME	Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH	An SHA-512 HASH. See Note 1 below.
MASKED_ACH_ACCOUNT	Masked ACH account number, shows ~60% of characters.

Notes:

The SHA-512 HASH is generated using the following as an input string:

TERMINALID:RESPONSECODE:RESPONSETEXT:MERCHANTREF:ACHREFERENCE:DATETIME:

secret

6.2 XML SecureACH Integration link

6.2.1 SecureACH Details Registration and Updating link

The following is an example of a SecureACH Registration request for a terminal. Note: The PERMITTEDTERMINALS string should be a comma separated list of the permitted terminals.

XML

<?xml version="1.0" encoding="UTF-8"?>
<ACHSECUREREGISTRATION>
	<MERCHANTREF>CSV_73443623</MERCHANTREF>
	<TERMINALID>2366006</TERMINALID>
	<DATETIME>22-02-2017:18:24:03:638</DATETIME>
	<ACCOUNT_TYPE>CHECKING</ACCOUNT_TYPE>
	<ACCOUNT_NUMBER>2387654376</ACCOUNT_NUMBER>
	<ROUTING_NUMBER>123103729</ROUTING_NUMBER>
	<ACCOUNT_NAME>Billy Joel</ACCOUNT_NAME>
	<ADDRESS1>7th Avenu, 77</ADDRESS1>
	<ADDRESS2>5th Avenu, 14</ADDRESS2>
	<CITY>New York</CITY>
	<REGION>A1</REGION>
	<POSTCODE>117898</POSTCODE>
	<COUNTRY>US</COUNTRY>
	<PHONE>9563343234</PHONE>
	<IPADDRESS>192.168.0.1</IPADDRESS>
	<EMAIL>asd@asd.org</EMAIL>
	<DL_STATE>NY</DL_STATE>
	<DL_NUMBER>4353446</DL_NUMBER>
	<PERMITTEDTERMINALS>
<TERMINALID>2366002</TERMINALID>
</PERMITTEDTERMINALS>
<HASH>ebdc9615f1c3e7ca3a01e28ad6ce04f4</HASH>
</ACHSECUREREGISTRATION>

The following is an example of a SecureACH Updating request:

XML

<?xml version="1.0" encoding="UTF-8"?>
<ACHSECUREUPDATE>
	<MERCHANTREF>CSV_73254705</MERCHANTREF>
	<TERMINALID>2366006</TERMINALID>
	<DATETIME>22-02-2017:18:50:51:008</DATETIME>
	<ACCOUNT_TYPE>SAVINGS</ACCOUNT_TYPE>
	<ACCOUNT_NUMBER>2387654376</ACCOUNT_NUMBER>
	<ROUTING_NUMBER>121122676</ROUTING_NUMBER>
	<ACCOUNT_NAME>Billy Joel</ACCOUNT_NAME>
	<ADDRESS1>7th Avenu, 77</ADDRESS1>
	<CITY>New York</CITY>
	<REGION>NY</REGION>
	<POSTCODE>-1</POSTCODE>
	<COUNTRY>US</COUNTRY>
	<PHONE>9563343234</PHONE>
	<IPADDRESS>192.168.0.2</IPADDRESS>
	<EMAIL>asd123@asd.org</EMAIL>
	<DL_STATE>NY</DL_STATE>
	<DL_NUMBER>4353446</DL_NUMBER>


<PERMITTEDTERMINALS>
<TERMINALID>2366002</TERMINALID>
</PERMITTEDTERMINALS>
<HASH>982f6c2b467401fccc765ebf4d16bd66</HASH>
</ACHSECUREUPDATE>

Fields description

Field Name		REQ Update	Description
TERMINALID	Y	Y	A TerminalID provided by Nuvei.
MERCHANTREF	Y	Y	Unique Merchant Reference. Length is limited to 48 chars..
ACCOUNT_NAME	Y	Y	The customers frst and last names.
ACCOUNT_TYPE	Y	Y	CHECKING or SAVINGS.
ACCOUNT_NUMBER	Y	Y	Customers ACH account number.
ROUTING_NUMBER	Y	Y	Customers ACH routing number.
DESCRIPTION	N	N	Optional Description.
ADDRESS1	N	N	First line of customers address. For updateAch actions only submit this parameter if you want to set a new value. ('REMOVE' value clear that feld)
ADDRESS2	N	N	Second line of customers address. For updateAch actions only submit this parameter if you want to set a new value. ('REMOVE' value clear that feld)
CITY	N	N	Customers home city. For updateAch actions only submit this parameter if you want to set a new value. ('REMOVE' value clear that feld)
REGION	N	N	Customers home state. For updateAch actions only submit this parameter if you want to set a new value. ('REMOVE' value clear that feld))
POSTCODE	N	N	Customers ZIP code. For updateAch actions only submit this parameter if you want to set a new value. ('-1' value clear that feld))
PHONE	N	N	Customers phone number. For updateAch actions only submit this parameter if you want to set a new value. ('REMOVE' value clear that feld)
COUNTRY	N	N	Customers country. ('REMOVE' value clear that feld)
IPADDRESS	N	N	Customer IP Address. ('REMOVE' value clear that feld)
EMAIL	N	N	Customers email address. ('REMOVE' value clear that feld)
DL_STATE	N	N	Customers driving licence state. ('-1' value clear that feld)
DL_NUMBER	N	N	Customers driving licence number. ('REMOVE' value clear that feld)
DATETIME	Y	Y	Format: DD-MM-YYYY:HH:MM:SS:SSS.
PERMITTED TERMINALS	Y	Y	Terminals which are permitted to process the request. The PERMITTEDTERMINALS string should be a comma separated list of the permitted terminals
HASH	Y	Y	An SHA-512 HASH. See note 1 below.

Field Name

REQ

Register

REQ

Update

Description

TERMINALID

Y

A TerminalID provided by Nuvei.

MERCHANTREF

Y

Unique Merchant Reference. Length is limited to 48 chars..

ACCOUNT_NAME

Y

The customers frst and last names.

ACCOUNT_TYPE

Y

CHECKING or SAVINGS.

ACCOUNT_NUMBER

Y

Customers ACH account number.

ROUTING_NUMBER

Y

Customers ACH routing number.

DESCRIPTION

N

Optional Description.

ADDRESS1

N

First line of customers address. For updateAch actions only submit this parameter if you want to set a new value. ('REMOVE' value clear that feld)

ADDRESS2

N

Second line of customers address. For updateAch actions only submit this parameter if you want to set a new value. ('REMOVE' value clear that feld)

CITY

N

Customers home city. For updateAch actions only submit this parameter if you want to set a new value. ('REMOVE' value clear that feld)

REGION

N

Customers home state. For updateAch actions only submit this parameter if you want to set a new value. ('REMOVE' value clear that feld))

POSTCODE

N

Customers ZIP code. For updateAch actions only submit this parameter if you want to set a new value. ('-1' value clear that feld))

PHONE

N

Customers phone number. For updateAch actions only submit this parameter if you want to set a new value. ('REMOVE' value clear that feld)

COUNTRY

N

Customers country. ('REMOVE' value clear that feld)

IPADDRESS

N

Customer IP Address. ('REMOVE' value clear that feld)

EMAIL

N

Customers email address. ('REMOVE' value clear that feld)

DL_STATE

N

Customers driving licence state. ('-1' value clear that feld)

DL_NUMBER

N

Customers driving licence number. ('REMOVE' value clear that feld)

DATETIME

Y

Format: DD-MM-YYYY:HH:MM:SS:SSS.

PERMITTED TERMINALS

Y

Terminals which are permitted to process the request. The PERMITTEDTERMINALS string should be a comma separated list of the permitted terminals

HASH

Y

An SHA-512 HASH. See note 1 below.

Notes:

The SHA-512 HASH is generated using the following as an input string:

TERMINALID:MERCHANTREF:DATETIME:ACCOUNT_NUMBER: ACCOUNT_NAME: ACCOUNT_TYPE:ROUTING_NUMBER:PERMITTEDTERMINALS : secret If the account details were successfully registered, response for registration request would be:

XML

<ACHSECUREREGISTRATIONRESPONSE>
	<MERCHANTREF>CSV_73443623</MERCHANTREF>
	<ACHREFERENCE>2967530237009546</ACHREFERENCE>
	<DATETIME>22-02-2017:17:24:05:894</DATETIME>
	<HASH>eb3c878e6c304c086dd7ca186406584a</HASH>
</ACHSECUREREGISTRATIONRESPONSE>

Example of a successful account details updating response:

XML

<ACHSECUREUPDATERESPONSE>
	<MERCHANTREF>CSV_73254705</MERCHANTREF>
	<ACHREFERENCE>2967539138333186</ACHREFERENCE>
	<DATETIME>22-02-2017:17:50:51:176</DATETIME>
	<HASH>4b8f045a2a5682a9af34ba4532e78dea</HASH>
</ACHSECUREUPDATERESPONSE>

The following felds will be returned in the response:

Field Name	Description
MERCHANTREF	Original Merchant Refernce sent in registration request.
ACHREFERENCE	Generated globally unique numeric account reference.
DATETIME	Generated globally unique numeric account reference.
HASH	An SHA-512 HASH. See Note 1 below.

Notes:

The SHA-512 HASH is generated using the following as an input string:

TERMINALID:MERCHANTREF:ACHREFERENCE:DATETIME:secret

Error handling

If ACH Secure Account was not registered or updated, error code and error message will be returned:

XML

<ERROR>
	<ERRORCODE>E21</ERRORCODE>
	<ERRORSTRING>Invalid First Name</ERRORSTRING>
</ERROR>

6.2.2 SecureACH Details Removal link

Note that SecureACH MerchantRef's cannot be re-used after deletion. This is because they are tied to existing transactions in our system and are retained internally for data integrity and future refund functionality. Card details removal request format:

XML

<?xml version="1.0" encoding="UTF-8"?>
<ACHSECUREREMOVAL>
	<MERCHANTREF>CSV_73254705</MERCHANTREF>
	<ACHREFERENCE>2967539138333186</ACHREFERENCE>
	<TERMINALID>2366006</TERMINALID>
	<DATETIME>22-02-2017:19:10:31:114</DATETIME>
	<HASH>e632813057b4b7d80fa3556f78e16983</HASH>
</ACHSECUREREMOVAL>

Fields description:

Field Name	Required	Description
TERMINALID	Y	A TerminalID provided by Nuvei.
MERCHANTREF	Y	Unique Merchant Reference. Length is limited to 48 chars.
ACHREFERENCE	Y	Generated globally unique numeric account reference.
DATETIME	Y	Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH	Y	An SHA-512 HASH. See note 1 below.

Field Name

Required

Description

TERMINALID

Y

A TerminalID provided by Nuvei.

MERCHANTREF

Y

Unique Merchant Reference. Length is limited to 48 chars.

ACHREFERENCE

Y

Generated globally unique numeric account reference.

DATETIME

Y

Format: DD-MM-YYYY:HH:MM:SS:SSS.

HASH

Y

An SHA-512 HASH. See note 1 below.

Notes:

1. The SHA-512 HASH is generated using the following as an input string:

TERMINALID:MERCHANTREF:DATETIME:ACHREFERENCE:secret

Account detail successful deletion response format:

XML

<SECUREACHDELETIONRESPONSE>
	<MERCHANTREF>werg456343wf34fe</MERCHANTREF>
	<DATETIME>31-12-2008:23:59:59:002</DATETIME>
	<HASH>d04c3bab519095ecb046ef91722e8df</HASH>
</SECUREACHDELETIONRESPONSE>

The following felds will be returned in the response:

Field Name	Description
MERCHANTREF	Original Merchant Refernce sent in registration request.
DATETIME	Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH	An SHA-512 HASH. See Note 1 below.

Notes:

The SHA-512 HASH is generated using the following as an input string:

TERMINALID:MERCHANTREF:DATETIME:secret

Errors handling

If request was not successful, error code and error message will be returned:

XML

<ERROR>
	<ERRORCODE>E08</ERRORCODE>
	<ERRORSTRING>INVALID MERCHANTREF</ERRORSTRING>
</ERROR>

6.2.3 SecureACH Details Search link

SecureACH search by Merchant Reference can be performed as needed:

XML

<?xml version="1.0" encoding="UTF-8"?>
<ACHSECURESEARCH>
	<MERCHANTREF>CSV_73254705</MERCHANTREF>
	<TERMINALID>2366006</TERMINALID>
	<PERMITTEDTERMINALSREQUIRED>Y</PERMITTEDTERMINALSREQUIRED>
	<DATETIME>22-02-2017:18:59:50:189</DATETIME>
	<HASH>efa7edfab30da38bdfea8c67cb324cd</HASH>
</ACHSECURESEARCH>

Fields description:

Field Name	Required	Description
MERCHANTREF	Y	Unique Merchant Reference. Length is limited to 48 chars.
ACHREFERENCE	Y	Generated globally unique numeric account reference.
TERMINALID	Y	A TerminalID provided by Nuvei.
DATETIME	Y	Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH	Y	An SHA-512 HASH. See note 1 below.

Field Name

Required

Description

MERCHANTREF

Y

Unique Merchant Reference. Length is limited to 48 chars.

ACHREFERENCE

Y

Generated globally unique numeric account reference.

TERMINALID

Y

A TerminalID provided by Nuvei.

DATETIME

Y

Format: DD-MM-YYYY:HH:MM:SS:SSS.

HASH

Y

An SHA-512 HASH. See note 1 below.

Note

The SHA-512 HASH is generated using the following as an input string:

TERMINALID:MERCHANTREF:DATETIME:secret

SecureACH detail successful deletion response format:

XML

<?xml version="1.0" encoding="UTF-8"?>
<ACHSECURESEARCHRESPONSE>
	<MERCHANTREF>CSV_73254705</MERCHANTREF>
	<ACHREFERENCE>2967539138333186</ACHREFERENCE>
	<ACCOUNT_NAME>Billy Joel</ACCOUNT_NAME>
	<PERMITTEDTERMINALS>
	<TERMINALID>2366002</TERMINALID>
	</PERMITTEDTERMINALS>
<DATETIME>22-02-2017:17:59:50:319</DATETIME>
<HASH>5ffb7b446ef9c9bcd94b1c3500157c82</HASH>
</ACHSECURESEARCHRESPONSE>

The following felds will be returned in the response:

Field Name	Description
MERCHANTREF	The Merchant Reference from the request.
ACHREFERENCE	The SecureACH Reference from the request
ACCOUNT_NAME	Customers name
PERMITTEDTERMINALS	Terminals which are permitted to process the request. The PERMITTEDTERMINALS string should be a comma separated list of the permitted terminals
TERMINALID	A TerminalID provided by Nuvei. NB – Please contact Nuvei to be issued with a test terminal ID.
DATETIME	Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH	An SHA-512 HASH. See note 1 below.

Notes:

The SHA-512 HASH is generated using the following as an input string:

TERMINALID:MERCHANTREF:ACHREFERENCE:ACCOUNT_NAMEDATETIME:secret

Errors handling

If request was not successful, error code and error message will be returned:

XML

<ERROR>
	<ERRORCODE>E04</ERRORCODE>
	<ERRORSTRING>INVALID REFERENCE DETAILS</ERRORSTRING>
</ERROR>

6.2.4 XML Payments Using SecureACH Details link

To send a payment transaction using stored ACH details, a standard ACHSALE request should be sent. The ACH_SECURE

feld should be set to 'Y' and the ACH_ACCOUNT feld should be populated with the ACHREFERENCE for the account. These felds

should then be ommitted from the request:

ACH_ACCOUNT_TYPE
ACH_FIRST_NAME
ACH_LAST_NAME
ACH_ADDRESS1
ACH_ADDRESS2
ACH_CITY
ACH_STATE
ACH_ZIP
ACH_PHONE_NUMBER

Developers

Chapter 6 - SecureACH Storage

6.1 SecureACH Registration and Updating From the Hosted Page link

6.2 XML SecureACH Integration link

6.2.1 SecureACH Details Registration and Updating link

6.2.2 SecureACH Details Removal link

6.2.3 SecureACH Details Search link

6.2.4 XML Payments Using SecureACH Details link

Need Help?