EliarachService
This web service provides methods related to ACH transactions, including:
- ViewACHAccts
- ViewOrderACHAcct
- AssignOrderACHAcct
- AddACHAcct
- ChangeACHAcct
ViewACHAccts
This method returns ACH accounts for a customer. It is typically used on a web page to display and choose the ACH account for the order.
Usage:
ViewACHAcctsResult = A.ViewACHAccts(UserName, UserPassword, ViewACHAcctsInput)
Parameters UserID and Password are not used at this moment.
ViewACHAcctsInput Structure
|
Property Name |
Length |
Type |
Upper |
Detail |
|
CustomerNo |
6 |
String |
|
Required. This is the customer number for the ACH accounts. |
|
ShipToNo |
4 |
String |
|
If you provide a value in this field, only the ACH accounts of the matching ship-to number will be returned. If you do no provide a value in this field, all ACH accounts, including those at the ship-to level, for the customer will be returned. |
|
IncludeTerminateAcct |
1 |
String |
Y |
“Y” or “N” (Default). If this field is “Y," this method will return terminated ACH accounts. |
|
IncludeHoldAcct |
1 |
String |
Y |
“Y” or “N” (Default). If this field is “Y,” this method will return on-hold ACH accounts. |
* Upper = Y indicates the value of the property will be converted to uppercase.
ViewACHAcctsResult Structure
|
Property Name |
Type |
Detail |
|
ReturnCode |
Integer |
0=OK (No Error), 10001 = Missing Customer Number, 30000 = Database Error, 30001 = No Record Found, 30002 = General Error |
|
ReturnMsg |
String |
This is the explaination of ReturnCode. |
|
ACHAcctRecord |
DataSet |
This data set has one data table “SYACHACT,” which includes the information of ACH accounts. Please refer to the following section for the fields in the data table. |
Fields in “SYACHACT” Data Table
|
Name |
Detail |
|
ACHAcctKey |
This is a 32-digit key from file name + customer no. + ship-to no. + create date + create time. We are providing this as a separate field because other ACH or payment-related web services may require this as an input field. |
|
SYACHACT_FILE_NAME |
File name of the ACH account. “ARCUSFIL” indicates this account is for customer, and “CPSHPFIL” indicates this account is for ship-to. |
|
SYACHACT_CUST_NO |
Customer number. |
|
SYACHACT_SHIP_TO_NO |
Ship-to number. |
|
SYACHACT_CREATE_DATE |
Create date of this account. |
|
SYACHACT_CREATE_TIME |
Create time of this account. |
|
SYACHACT_BANK_RTG_NO |
Bank routing number. |
|
SYACHACT_BANK_ACCTNO |
Bank account number. |
|
SYACHACT_ACCT_NNAME |
Account nickname. |
|
SYACHACT_MAIN_ACCT |
“Y”or “N.” “Y” indicates this is the main ACH account for this customer/ ship-to. |
|
SYACHACT_STATUS |
Blank: This account is not on-hold or terminated. “T”: This account is terminated. “H”: This account is on-hold. |
|
SYACHACT_STS_REASON |
The reason the account was terminated or put on hold. |
|
SYACHACT_STS_DATE |
Date of the account status change. |
|
SYACHACT_STS_TIME |
Time of the account status change. |
|
SYACHACT_STS_BY_USER |
Account status change by user. |
|
SYACHACT_STS_BY_WRKS |
Account status change by work station. |
|
SYACHACT_LST_TRX_DT |
Last transaction date for this ACH account. |
|
SYACHACT_LST_TRX_AMT |
Last transaction time for this ACH account. |
|
SYACHACT_TRX_SNC_CR |
Number of transactions of this account since created. |
|
SYACHACT_AMT_SNC_CR |
Total amount of this account since created. |
|
SYACHACT_NO_TRX_YTD |
Number of transactions of this account year-to-date. |
|
SYACHACT_AMT_YTD |
Total amount of this account year-to-date. |
|
SYACHACT_TRX_LSTYR |
Number of transactions of this account last year. |
|
SYACHACT_AMT_LSTYR |
Total amount of this account last year. |
|
SYACHACT_TRX_2_YR |
Number of transactions of this account the year before last year. |
|
SYACHACT_AMT_2_YR |
Total amount of this account the year before last year. |
|
SYACHACT_FILLER |
Not used for now. |
Code Example (VB)
The following sample codes return all ACH accounts for customer “000044,” including all ship-to ACH accounts. We did not set input parameters “IncludeTerminateAcct” and “IncludeHoldAcct,” so the terminated and on-hold accounts will not be returned.
Dim Service As New webServicesACH.EliarachService
Dim Input As New webServicesACH.ViewACHAcctsInput
Dim Result As New webServicesACH.ViewACHAcctsResult
Input.CustomerNo = “000044”
Result = Service.ViewACHAccts(“”, “”, Input)
If Result.ReturnCode = 0 Then
If Result.ACHAcctRecord.Tables(0).Rows.Count = 0 Then
lblResult.Text = "No record found"
Else
lblResult.Text = "ACH account’s key for the customer is: " + _
Result.ACHAcctRecord.Tables(0).Rows(0).Item("ACHAcctKey").ToString
End If
Else
lblResult.Text = “Error code:” + Result.ReturnCode.ToString
End If
This method returns the ACH account that is assigned to an order. It is typically used on a web page to display the ACH account that’s assigned to the order, or on the page that allows users to change the ACH account assigned to the order.
Usage:
ViewOrderACHAcctResult = A.ViewOrderACHAcct(UserName, UserPassword, ViewOrderACHAcctInput)
Parameters UserID and Password are not used at this moment.
ViewOrderACHAcctInput
Structure
|
Property Name |
Length |
Type |
Detail |
|
OrderNo |
6 |
Prior to V8.5: Integer V8.5 and Above: String |
Required. This is the order number. |
ViewOrderACHAcctResult Structure
|
Property Name |
Type |
Detail |
|
ReturnCode |
Integer |
0=OK (No Error) , 10002 = Missing Order Number, 30000 = Database Error, 30001 = No Record Found, 30002 = General Error |
|
ReturnMsg |
String |
This is the explaination of ReturnCode. |
|
ACHAcctRecord |
DataSet |
This data set has one data table “SYACHACT,” which includes the information of ACH accounts. Please refer “ViewACHAccts” method for the fields in the data table. |
Code Example (VB)
The following sample codes return the ACH account for order number “123456.”
Dim Service As New webServicesACH.EliarachService
Dim Input As New webServicesACH.ViewOrderACHAcctInput
Dim Result As New webServicesACH.ViewOrderACHAcctResult
Input.OrderNo = 123456
Result = Service.ViewOrderACHAcct(“”, “”, Input)
If Result.ReturnCode = 0 Then
If Result.ACHAcctRecord.Tables(0).Rows.Count = 0 Then
lblResult.Text = "No record found"
Else
lblResult.Text = "ACH account’s key for the order is: " + _
Result.ACHAcctRecord.Tables(0).Rows(0).Item("ACHAcctKey").ToString
End If
Else
lblResult.Text = “Error code:” + Result.ReturnCode.ToString
End If
This method assigns an ACH payment to the order. If there is already an ACH account assigned to the order, the new ACH account will replace the old ACH account.
Usage:
AssignOrderACHAcctResult = A.AssignOrderACHAcct(UserName, UserPassword, AssignOrderACHAcctInput)
Parameters UserID and Password are not used at this moment.
AssignOrderACHAcctInput Structure
|
Property Name |
Length |
Type |
Detail |
|
OrderNo |
6 |
Prior to V8.5: Integer V8.5 and Above: String |
Required. This is the order number. |
|
Reference |
30 |
String |
This can be anything you wish to show on your customer’s bank statement. Like “AUTHORIZED BY JOE” or “CHECK# 1234.” This field may be required depending on the setting in Elliott’s ACH processing Global Setup. |
|
PaymentACHAcct() |
|
PaymentACHAcct |
Although this is an array, currently Elliott only supports one ACH account per order. That is to say, only the first element of this array will be used. |
PaymentACHAcct Structure
|
Property Name |
Length |
Type |
Detail |
|
PaymentACHKey |
32 |
String |
This is a 32-digit key from file name + customer no. + ship-to no. + create date + create time.
You can assign a valid ACH account key in this field. If this field is blank, the system will use the primary ACH account based on the order’s customer number and ship-to.
For example, if this field is blank, and the order has customer number “000001” ship-to “1234,” this method will first look for the primary ACH account of cust# “000001” and ship-to “1234.” If this does not exist, it will look for the primary ACH account of cust# “000001.” If this does not exist either, then it is an error condition. |
|
PaymentACHAmount |
30 |
Double |
This field is not used for now. This method will automatically calculate the payment amount by order total amount and deduct other payments that already exist for the order. |
AssignOrderACHAcctResult Structure
|
Property Name |
Type |
Detail |
|
ReturnCode |
Integer |
Zero means OK. For other return codes, please see the following section. |
|
ReturnMsg |
String |
This is the explaination of return code. |
|
ACHAmount |
Double |
This is the calculated ACH payment amount. |
Code Example (VB)
The following sample codes will assign an ACH payment for order number “123456,” which is for customer “000100” and ship to “0001.”
Dim Service As New webServicesACH.EliarachService
Dim Input As New webServicesACH.AssignOrderACHAcctInput
Dim Result As New webServicesACH.AssignOrderACHAcctResult
Dim PaymentACHAcct As New webServicesACH.PaymentACHAcct
ReDim Input.PaymentACHAcct(0)
Input.PaymentACHAcct(0) = New webServicesACH.PaymentACHAcct
Input.OrderNo = 123456
Input.PaymentACHAcct(0).PaymentACHKey = "CPSHPFIL000100000120141228081200"
Result = Service.AssignOrderACHAcct("", "", Input)
If Result.ReturnCode = 0 Then
lblResult.Text = "ACH account assigned. Payment amount: " + _
Result.ACHAmount
Else
lblResult.Text = "Error Code: " + Result.ReturnCode.ToString + _
" . Message: " + Result.ReturnMsg
End If
AddACHAcct
This method adds an ACH account.
Usage:
AddACHAcctResult = A.AddACHAcct(UserName, UserPassword,AddACHAcctInput )
Parameters UserName and Password are not used at this moment.
AddACHAcctInput Structure
|
Property Name |
Length |
Type |
Upper |
Detail |
|
CustomerNo |
6 |
String |
Y |
Required. This is the customer number for the ACH accounts. |
|
ShipToNo |
4 |
String |
Y |
If you provide a value in this field, then the corresponding ship-to must exist for the customer. The ACH accounts will be added to the ship-to, instead of customer. |
|
BankRoutingNo |
9 |
String |
|
Bank routing number. Provided value must be all numeric. |
|
BankAccountNo |
17 |
String |
|
Bank account number. Provided value must be all numeric. |
|
NickName |
20 |
String |
Y |
Account nickname. |
|
MainAccount |
1 |
String |
Y |
“Y”or “N.” “Y” indicates this is the main ACH account for this customer/ ship-to. If this is the first account user added for this customer or ship-to, then the value will become “Y” regardless the value user provided here. If this customer already has a main account, then adding a record with “Y” here will cause that account to become not the main account. |
|
AccountStatus |
1 |
String |
Y |
Blank: This account is not on-hold or terminated. (Default) “T”: This account is terminated. “H”: This account is on-hold. Under most situations, you should leave this field blank. But it is possible for users to add an ACH account that’s on hold or terminated |
|
StatusReason |
30 |
String |
Y |
The reason for the account was terminated or put on hold. |
|
AccountName |
16 |
String |
Y |
This is the account name. If left blank, then the system will use the customer or ship-to name when the NACHA file is created. If not blank, then it will override the customer or ship-to name when the NACHA file is created. Under most situations, you should leave this field blank unless it is known that the name on the ACH account does not match the customer or ship-to name. |
* Upper = Y indicates the value of the property will be converted to uppercase.
AddACHAcctResult Structure
|
Property Name |
Type |
Detail |
|
ReturnCode |
Integer |
0=OK (No Error), |
|
ReturnMsg |
String |
This is the explaination of ReturnCode. |
|
AchKey |
String |
This is a 32-digit key from file name + customer no. + ship-to no. + create date + create time. We are providing this as a separate field because other ACH or payment related web services may require this as an input field. |
ACHCreate Email
This method support sending an email to admin users so the added ACH bank account can be sent to, say, accounting to verified the added bank account for validity. To do so, you will need to add the following key in ElliottService.custom.config file.
<add key="ACHCreateSendAdminEmail" value="Y"/>
By default, this email function is turned off. Also, you should specify the from and to email address. If there should be multiple recepients for this email address, separate them with a ";" (semicolom) symbol. See sample below:
<add key="ACHCreateFromEmail" value="admin@netcellent.com"/>
<add key="ACHCreateAdminEmail" value="accounting@netcellent.com;emk@netcellent.com"/>
The following is the default email content:
Subject: Bank Account Added through Web Services
Bank Account Info was added for customer number 368121 on 12/28/2017 at 6:11 PM from Web Services. The following information was entered.Customer Number: 368121
Bank Routing Number: 122000121
Bank Account Number: ****8240
Account Name: Landy Lee
Nickname: BOA MM
Main Account: Y
You could modify the default Subject line by adding the following key to ElliottService.custom.config file.
<add key="ACHCreateEmailSubject" value="Bank Account Added through Web Services"/>
If you want to modify the content of the email, you can copy the ACHCreate.template.html file from web services MailMergeTemplate\Default folder to MailMergeTemplate\Custom folder. Then modify the file in Custom folder to the way you want it. Note that you need to have HTML knowledge to modify the format of this email.
ChangeACHAcct
This method allows for changes to the ACH account information.
Usage:
ChangeACHAcctResult = A.ChangeACHAcct(UserName, UserPassword,ChangeACHAcctInput )
Parameters UserName and Password are not used at this moment.
ChangeACHAcctInput Structure
|
Property Name |
Length |
Type |
Upper |
Detail |
|
AchKey |
32 |
String |
|
This is a 32-digit key from file name + customer no. + ship-to no. + create date + create time. |
|
BankRoutingNo |
9 |
String |
|
Default blank, which means no change. If provided, change bank routing number. Provided value must be all numeric. |
|
BankAccountNo |
17 |
String |
|
Default blank which means no change. If provided, change bank account number. Provided value must be all numeric. |
|
NickName |
20 |
String |
Y |
Default blank which means no change, If provided, change account nickname. |
|
MainAccount |
1 |
String |
Y |
Default blank, which means no change. If provided, must be “Y”or “N.” If changed, then another account will either become the main account, or not become main account. If this is the only account for customer or ship- to, the user can’t change it to a non-main account. |
|
AccountStatus |
1 |
String |
Y |
Default blank, which means no change. “B”: Change the account status to blank value, which means this account is not on hold or terminated. “T”: Change account to terminated. “H”: Change account to on-hold. If you terminate or put account on hold, then you should provide the reason in the StatusReason field. |
|
StatusReason |
30 |
String |
Y |
Default blank, which means no change. This is the reason the account was terminated or put on hold. |
|
AccountName |
16 |
String |
Y |
Default blank, which means no change. This is the account name. If account name is blank, then it is assumed to be the same as the customer or ship-to name. If not blank, then it overrides the customer or ship-to name. |
ChangeACHAcctResult Structure
|
Property Name |
Type |
Detail |
|
ReturnCode |
Integer |
0=OK (No Error) |
|
ReturnMsg |
String |
This is the explaination of ReturnCode. |
0 = OK
1 = File Error
2 = Reference Is Required (AddOrderACHPayment)
3 = Invalid Order Number (AddOrderACHPayment)
4 = Invalid ACH Key (AddOrderACHPayment, ChangeACHAcct)
5 = ACH Payment Record For The Order Is Locked (AddOrderACHPayment)
6 = Primary ACH Account Not Found (AddOrderACHPayment, ChangeACHAcct)
7 = ACH Account Belongs to Different Customer or Ship To (AddOrderACHPayment)
8 = ACH Processing Is Not Enabled In Elliott (AddOrderACHPayment)
9 = Customer Number Is Required (AddACHAcct)
10 = Customer Number Is Not On File (AddACHAcct)
11 = Ship-To Number Is Not On File (AddACHAcct)
12 = Bank Routing Number Must Be Numeric (AddACHAcct)
13 = Bank Account Number Must Be Numeric (AddACHAcct)
14 = Bank Account Number Already On File For Customer (AddACHAcct)
15 = Bank Account Number Already On File For Ship-To (AddACHAcct)
16 = Invalid Main Account (AddACHAcct, ChangeACTAcct)
17 = Invalid Account Status (AddACHAcct, ChangeACTAcct)
CLS