ElicshtxService
This web service provides methods related to cash receipt transactions, including:
- ViewOpenItems
- AddCashTrx
- ViewCashTrx
- DeleteCashTrx
This method returns a customer’s open items, including Invoices, Payments, Credit Memos, Debit Memos and Financial Charges. This is similar to Elliott “Customer Account Inquiry” or “Customer Account Summary Inquiry.” One additional feature this method provides is the option to show Pending Cash Receipt.
The current implementation can return up
to 2,000 rows of an A/R open item table. If you have any customer that has over
2,000 rows in an A/R open item table, then you should consider one or both of the
following strategies:
1. Do not return the fully paid A/R Open Item Records.
2. Purge Fully Paid A/R Open Item Records.
Usage:
ViewOpenItemsResult = A.ViewOpenItems(UserName, UserPassword, ViewOpenItemsInput)
Parameters UserID and Password are not used at this moment.
ViewOpenItemsInput
Structure
|
Property Name |
Length |
Type |
Upper |
Detail |
|
CustomerNo |
6 |
String |
|
Required. This is the customer number to view open items. |
|
IncludeFullyPaidItems |
1 |
String |
Y |
“Y” or “N” (Default). If this field is “Y,” this method will include fully paid items in the returned record. |
|
IncludePendingCashReceipts |
1 |
String |
Y |
“Y” or “N” (Default). If this field is “Y,” this method will include on-hold ACH accounts in the returned record. |
|
IncludeHistory |
1 |
String |
Y |
“Y” or “N” (Default). If this field is “Y,” this method will include records from the A/R History File that have a document date on or after the CutOffDate in the returned record. |
|
CutOffDate |
8 |
Date |
|
If not supplied, the field will default to 3 years from the current system date. Note the CutOffDate refers to the invoice cutoff date, not the payment cutoff date. This cutoff date applies to the the data in the A/R Open Item File as well as the A/R History File. |
* Upper = Y indicates the value of the property will be converted to uppercase.
ViewOpenItemsResult Structure
|
Property |
Type |
Detail |
|
ReturnCode |
Integer |
Zero means OK. For other return codes, please refer to the “Return Code” section. |
|
ReturnMsg |
String |
This is the explaination of return code. |
|
ArApplyTo() |
ArApplyToSumRecord |
These are the records in AROPNFIL for the corresponding customer, in the Apply-To summary format. If IncludePendingCashReceipts is set to “Y,” then the information in ARCSHTRX and ARCSHAPL will be merged into this array. The array is displayed by the Apply-To sequence. As a result, the open payments/credits (0 apply to) will be displayed first, including ARCSHTRX with no apply-to record. The 0 apply to will be displayed individually without being consolidated. |
ArApplyToSumRecord Structure
|
Property |
Type |
Detail |
|
ArApplyToDocDate |
Date |
Document date |
|
ArApplyToDocNo |
Prior to V8.5: Integer V8.5 and Above: String |
Document number |
|
ArApplyToDocType |
String |
“P”: Payment “C”: Credit “D”: Debit “I”: Invoice “F”: Finance Charge “B”: Balance Forward |
|
ArApplyToApplyToNo |
Prior to V8.5: Integer V8.5 and Above: String |
If zeroes, then this is either the open payment or credit on the account. |
|
ArApplyToDocDueDate |
Date |
|
|
ArApplyToReference |
String |
|
|
ArApplyToAmount1 |
Double |
For invoice type record, amount1 is the sales amount. For payment type record, it is the received payment amount. |
|
ArApplyToAmount2 |
Double |
For invoice type record, amount2 is the freight, misc. charges and sales tax. For payment type record, it is the discount or allowance amount. |
|
ArApplyToTotalAmount |
Double |
Generally speaking, this is the invoice record’s amount1 + amount2 |
|
ArApplyToPaymentAmount |
Double |
This amount includes all payments of this apply-to. |
|
ArApplyToAdjustAmount |
Double |
This amount includes all credit, debit memo, and finance charge of this apply-to. |
|
ArApplyToBalance |
Double |
This field = TotalAmount + PaymentAmount + AdjustmentAmount. (since PaymentAmount is expressed in negative value). |
|
ArApplyToAge |
Integer |
Number of days past due. This value can be negative, which means the invoice is paid before due date. Please refer to A/R Account Summary Inquiry for more examples. |
|
ArApplyToPaymentPending |
String |
This value can be “Y,” “N” or blank. If ShowPendingCashReceipt is set to “Y,” then this value is either “Y” or “N.” “Y” means there’s pending payment in A/R Cash Receipt for this apply-to. Vice versa for “N.” If ShowPendingCashReceipt is set to “N," then the value will be blank since we do not check whether pending payments exist. |
|
ARApplyToOpenItems() |
ARApplyToOpenItem |
This array contains the detail records of the apply-to. For example, if an apply-to consists of one invoice, one credit memo and one payment, then the invoice record will be displayed in the ARApplyTo(). All three records, including the invoice, credit memo and payment will be displayed in ARApplyToOpenItem(). |
ARApplyToOpenItem Structure
|
Property |
Type |
Detail |
|
ArOpenDocDate |
Date |
Document date |
|
ArOpenDocNo |
Prior to V8.5: Integer V8.5 and Above: String |
Document number |
|
ArOpenDocType |
String |
See “ArApplyToSumRecord Structure” for detail. |
|
ArOpenApplyToNo |
Prior to V8.5: Integer V8.5 and Above: String |
Apply-to number |
|
ArOpenDocDueDate |
Date |
Document due date |
|
ArOpenReference |
String |
Reference |
|
ArOpenAmount1 |
Double |
Amount 1 |
|
ArOpenAmount2 |
Double |
Amount 2 |
|
ArOpenApplyAmount |
Double |
Apply amount |
|
ArOpenTermsCode |
String |
Terms code |
|
ArOpenSalesmanNo |
String |
Salesman number |
|
ArOpenOrigInvoiceNo |
String |
Original invoice number for charge back |
|
ArOpenReasonCode |
String |
Reason code for charge back |
|
ArOpenPaymentType |
String |
Payment type can be: CK=Check, CS=Cash, GC=Gift Cert., CC=Credit Card, WR=Wired, AC=ACH. |
|
ArOpenACHTrxNo |
Integer |
ACH transaction number |
|
ArOpenFiller |
String |
Normally this field is blank |
|
AROpenPaymentPending |
String |
If this is a pending cash receipt, this flag will be “Y'; otherwise this flag will be “N” |
|
AROpenPaymentBatchID |
String |
If this is a pending cash receipt, this field will contain the batch ID for the cash transaction; otherwise this field will be blank. A batchID in the format of YYYYMMDD implies a scheduled ACH payment. For example, batchID 20160630 means this ACH payment will be posted on 6/30/2016. |
Code Example (VB)
The following sample codes return open item summary for customer “000044,” including pending cash payments and excluding fully paid items.
Dim Service As New webServicesCash.ElicshtxService
Dim Input As New webServicesCash.ViewOpenItemsInput
Dim Result As New webServicesCash.ViewOpenItemsResult
Input.CustomerNo = “000044”
Input.IncludePendingCashReceipts = “Y”
Result = Service.ViewOpenItems(“”, “”, Input)
If Result.ReturnCode = 0
If Result.ArApplyTo IsNot Nothing AndAlso _
Result.ArApplyTo.Count > 0 Then
lblResult.Text = “The first open item’s apply-to number is: ” + _
Result.ArApplyTo(0).ArApplyToApplyToNo.ToString
Else
lblResult.Text = “No open items for this customer.”
End If
Else
lblResult.Text = “Error Code: ” + Result.ReturnCode.ToString + _
“ . Message: ” + Result.ReturnMsg
End If
This method creates one or more pending cash receipts. If this is a web application, you can use this method to allow your users to schedule ACH payments.
Transaction Consolidation
Cash Receipts for ACH may result in duplicate check number. This can happen because ACH check number by default = (Last 4 digits of Check Account Number) + (Last 2 digits of Total ACH payments + 1). For example, a check account ending with ***5720, that has processed 69 payments so far, the next check number assigned will be 572070. Web services will consolidate duplicate check number for the same receipt date is already on file in the Cash Transaction table (ARCSHTRX).
- For example, if customer 000001 pays $100.00 on invoice# 123456 on 12/14/20. The check number is sequentially assigned as 572070.
- Customer 000001 pays $200.00 on invoice 123457 and it is scheduled for 12/31/20. The check number is sequentially assigned as 572070 again because the previous cash receipt had not been posted yet. But that is acceptable because the receipt date is 12/31/20. No consolidation will take place.
- On the other hand, if customer 0000001 pays $300.00 on invoice 123458 on 12/14/20. If the previous cash transaction was not posted yet, then the check number is sequentially assigned as 572070. This transaction will be consolidated with the previous payment record on 12/14/20 make it total $400 because they fall on the same date.
If you do not want to consolidate the duplicate ACH check numbers, you can set the value of the key AddCashTrxConsolidateDupCheckNo in the ElliottService.custom.config to N. The default value is Y.
<!-- ElicshtxService CONFIGURATION -->
<!-- Specifies if ACH duplicate service will consolidate duplicate cash transactions -->
<add key="AddCashTrxConsolidateDupCheckNo" value="Y"/>
Usage:
AddCashTrxResult = A.AddCashTrx(UserName, UserPassword, AddCashTrxInput)
Parameters UserID and Password are not used at this moment.
AddCashTrxInput Structure
|
Property Name |
Length |
Type |
Detail |
|
CashTrx() |
6 |
CashTrxForAdd |
Each element in the array creates one pending cash receipt. |
CashTrxForAdd Structure
|
Property Name |
Length |
Type |
Detail |
|
CashAccountNo |
24 |
String |
24-digit cash account number. If this is not provided, it will default to the default cash account number in Elliott A/R Setup. |
|
BatchID |
8 |
String |
Blank BatchID is allowed. If BatchID is provided, this could be a new batch id, or an existing one. If it is an existing one, the PaymentType must match. We suggest you adopt a convention for Batch ID. For example, you can use the Payment Type + YYMMDD. In that case, if this is an ACH batch for 08/19/2015. The Batch ID will be AC150819. To schedule an ACH payment in the future, specify the BatchID in YYYYMMDD format. For example, a BatchID of 20160630 means the ACH payment in this batch will be posted on or after 6/30/2016. |
|
PaymentType |
2 |
String |
Default to “CK” if not provided. CK=Check, CS=Cash, GC=Gift Cert., CC=Credit Card, WR=Wired, AC=ACH. |
|
CustomerNo |
6 |
String |
Required. |
|
CheckNo |
6 |
Prior to V8.5: Integer V8.5 and Above: String |
For ACH payment type, do not pass anything to this field. The system will automatically make this field value something like XXXX99, where XXXX is the last 4 digits of the bank account number and 99 is the sequentially incremented transaction number for the bank account. |
|
ReceiptDate |
8 |
Integer |
Default to system date. |
|
ReceiptAmount |
7.2 |
Double |
Normally, this value should be greater than zero. However, a negative cash receipt is also supported. |
|
CreditARFlag |
1 |
String |
“Y” (Default) or “N.” |
|
CreditAccountNo |
24 |
String |
You will be required to provide a valid account if CreditARFlag is set to “N.” |
|
CashACHAcctKey |
32 |
String |
This field is required for ACH payment type. This is the ACH Account selected for this cash transaction. You can find a list of ACH accounts for the customer by using the ViewACHAccts method in EliarachService web service. |
|
CashACHReference |
30 |
String |
This field is only valid for ACH payment type. As an example, this value can be “AUTHORIZED BY JOE” or “CHECK# 1234.” Depending on Elliott's Global Setup, this field may be required. |
|
AutoApply |
1 |
String |
Default “Y” and the CashReceiptApplyTo() will be ignored. This is the case when you let users pay a certain amount and the system automatically applies the outstanding invoice sequentially. If you wish to determine the specific invoice(s) to be paid off, you will set this flag to “N” and provide CashReceiptApplyTo() info. |
|
CashReceiptApplyTo() |
|
CashReceiptApplyToForAdd |
The elements in this array will only be used if you set AutoApply to “N.” The total AmountApplied must equal the ReceiptAmount. Otherwise, you will get error code 19. |
CashReceiptApplyToForAdd Structure
|
Property Name |
Length |
Type |
Detail |
|
ApplyToNo |
6 |
Prior to V8.5: Integer V8.5 and Above: String |
The 6 digits apply to must not be fully paid yet. It is possible the ApplyToNo may not exist if (1) Elliott Global Setup allows; or (2) ApplyToAmountApplied is negative, which will result in creating a debit memo (charge back handling.) |
|
ApplyToAmountApplied |
7.2 |
Double |
The amount can not cause the apply-to (i.e., the invoice or debit memo number) to become over paid. You will get error code 14 if over paid. |
|
ApplyToDiscAmount |
6.2 |
Double |
This amount will go to A/R Open Item Amount2. |
|
ApplyToAllowAmount |
6.2 |
Double |
This amount will go to A/R Open Item Amount2. |
|
ApplyToAllowAcctNo |
24 |
String |
If ApplyToAllowAmount is not zero, you can provide the account number here, or leave it blank to use the default allowance account in A/R Setup. |
|
ApplyToReference |
30 |
String |
If not provided, this method will create a default value by the following logic. If payment type is “AC,” and CashACHReference is not empty, it will use the value in CashACHReference. Otherwise it will create a sentence such as “Cust#123456 Check# 123456” |
|
ApplyToOrigInvNo |
6 |
String |
This field is only applicable for charge-back situations (i.e., apply-to does not exist, and AmountApplied < zero). |
|
ApplyToReasonCode |
3 |
String |
This field is only applicable for charge-back situations. |
AddCashTrxResult Structure
|
Property |
Type |
Detail |
|
ReturnCode |
Integer |
Zero means OK. For other return codes, please refer to “Return Code” section. |
|
ReturnMsg |
String |
This is the explaination of return code. |
Code Example (VB)
The following sample codes create one pending ACH payment of 1,000.00 for customer 123456 and lets the system automatically apply the payment to outstanding invoices sequentially.
Dim Service As New webServicesCash.ElicshtxService
Dim Input As New webServicesCash.AddCashTrxInput
Dim Result As New webServicesCash.AddCashTrxResult
Redim Input.CashTrx(0)
Input.CashTrx(0) = New webServicesCash.CashTrxForAdd
Input.CashTrx(0).BatchID = “AC150915”
Input.CashTrx(0).PaymentType = “AC”
Input.CashTrx(0).CustomerNo = “123456”
Input.CashTrx(0).CashACHReference = "AUTHORIZED BY JOE" Input.CashTrx(0).ReceiptAmount = 1000
Input.CashTrx(0).CashACHAcctKey = “ARCUSFIL1234560001201412280812”
Result = Service.AddCashTrx(“”, “”, Input)
If Result.ReturnCode = 0 Then
lblResult.Text = “Cash Receipt Created.”
Else
lblResult.Text = “Error Code: ” + Result.ReturnCode.ToString + _
“ . Message: ” + Result.ReturnMsg
End If
This method returns a customer’s pending cash receipts in the A/R Cash Receipt Trx File.
Usage:
ViewCashTrxResult = A.ViewCashTrx(UserName, UserPassword, ViewCashTrxInput)
Parameters UserID and Password are not used at this moment.
ViewCashTrxInput Structure
|
Property Name |
Length |
Type |
Detail |
|
CustomerNo |
6 |
String |
Required. This is the customer number to view pending cash receipts. |
ViewCashTrxResult Structure
|
Property |
Type |
Detail |
|
ReturnCode |
Integer |
Zero means OK. For other return codes, please refer to “Return Code” section. |
|
ReturnMsg |
String |
This is the explaination of return code. |
|
CashTrxDataSet |
DataSet |
This data set includes two data tables, ARCSHTRX and ARCSHAPL. For fields of each data set, please see the following sections. |
Fields in ARCSHTRX Data Table
|
Property |
Length |
Type |
Detail |
|
CSH_CUS_NO |
6 |
String |
Customer no. |
|
CSH_CK_NO |
6 |
Prior to V8.5: Integer V8.5 and Above: String |
Check no. |
|
CSH_TIME_STAMP |
6 |
Integer |
Time stamp |
|
CSH_RCPT_DATE |
8 |
Integer |
Receipt Date |
|
CSH_AMT_RECD |
7.2 |
Double |
Amount received |
|
CSH_CR_AR_FG |
1 |
String |
Credit AR Flag |
|
CSH_CR_ACCT_NO |
24 |
String |
Credit account no. |
|
CSH_CUS_NAME |
30 |
String |
Customer name |
|
CSH_CUS_BAL_METH |
1 |
String |
Customer balance method |
|
CSH_TM_CD |
2 |
String |
Terms code |
|
CSH_TM_CD_DESC |
15 |
String |
Terms code description |
|
CSH_TM_CD_DSC_DAYS |
3 |
Integer |
Terms code discount days |
|
CSH_TM_CD_DSC_PCT |
2.2 |
Double |
Terms code discount percent |
|
CSH_ACCT_NO |
24 |
String |
Cash account no. |
|
CSH_BATCH_ID |
8 |
String |
Batch ID |
|
CSH_PMT_TYPE |
2 |
String |
Payment type can be: CK=Check, CS=Cash, GC=Gift Cert., CC=Credit Card, WR=Wired, AC=ACH. |
|
CSH_ACH_FILE_NAME |
8 |
String |
ACH account file name. Could be “ARCUSFIL” for customer or “CPSHPFIL” for ship-to. |
|
CSH_ACH_CUST_NO |
6 |
String |
ACH account customer no. |
|
CSH_ACH_SHIP_TO |
4 |
String |
ACH account ship-to no. |
|
CSH_ACH_CR_DATE |
8 |
Integer |
ACH account create date |
|
CSH_ACH_CR_TIME |
6 |
Integer |
ACH account create time |
|
CSH_ACH_REFERENCE |
30 |
String |
ACH reference for this cash transaction |
|
ARCSHTRX_FILLER_0001 |
28 |
String |
This field should be blank. |
Fields in ARCSHAPL Data Table
|
Property |
Length |
Type |
Detail |
|
CSH_APL_CUS_NO |
6 |
String |
Customer no. |
|
CSH_APL_CK_NO |
6 |
Prior to V8.5: Integer V8.5 and Above: String |
Check no. |
|
CSH_APL_TIME_STAMP |
6 |
Integer |
Time stamp |
|
CSH_APL_APPLY_TO |
6 |
Prior to V8.5: Integer V8.5 and Above: String |
Apply-to no. |
|
CSH_APL_OPEN_CR_FG |
1 |
String |
Open credit flag. “C” indicates this is an open credit. |
|
CSH_APL_AMT_APPLIED |
7.2 |
Double |
Amount applied |
|
CSH_APL_DSC_AMT |
6.2 |
Double |
Discount amount |
|
CSH_APL_ALLOW_AMT |
6.2 |
Double |
Allowance amount |
|
CSH_APL_TM_CD |
2 |
String |
Terms code |
|
CSH_APL_TM_CD_DESC |
15 |
String |
Terms code description |
|
CSH_APL_TM_CD_DSC_DA |
3 |
Integer |
Terms code discount days |
|
CSH_APL_TM_CD_DSC_PC |
2.2 |
Double |
Terms code discount percent |
|
ALLOW_ACCT_NO |
24 |
String |
Allowance account no. |
|
CSH_APL_REF |
30 |
String |
Reference of this cash application. |
|
CSH_APL_ORIG_INV_NO |
6 |
String |
Original invoice number. This field is only applicable for charge-back situations (i.e., Apply-to does not exist, and AmountApplied < zero.) |
|
CSH_APL_REASON_CD |
3 |
String |
Reason Code. This field is only applicable for charge-back situations. |
|
CSH_APL_FILLER |
91 |
String |
This field should be blank. |
Code Example (VB)
The following sample codes return a pending cash receipt for customer “000044.”
Dim Service As New webServicesCash.ElicshtxService
Dim Input As New webServicesCash.ViewCashTrxInput
Dim Result As New webServicesCash.ViewCashTrxResult
Input.CustomerNo = “000044”
Result = Service.ViewCashTrx(“”, “”, Input)
If Result.CashTrxDataSet IsNot Nothing AndAlso _
Result.CashTrxDataSet.Tables("ARCSHTRX").Rows.Count > 0 Then
ResultTable1 = Result.CashTrxDataSet.Tables("ARCSHTRX")
lblResult.Text = "The first check number is: " + _
ResultTable1.Rows(0).Item("CSH_CK_NO").ToString
Else
lblResult.Text = "No record found"
End If
This method deletes one pending cash receipt. For example, you may use this method if the user decides to cancel a scheduled ACH payment in the A/R Cash Receipt Trx File.
Usage:
DeleteCashTrxResult = A.DeleteCashTrx(UserName, UserPassword, DeleteCashTrxInput)
Parameters UserID and Password are not used at this moment.
DeleteCashTrxInput Structure
|
Property Name |
Length |
Type |
Detail |
|
CustomerNo |
6 |
String |
Required. |
|
CheckNo |
6 |
Prior to V8.5: Integer V8.5 and Above: String |
Required. You will find out this information from ViewCashTrx method. |
|
TimeStamp |
6 |
Integer |
Required.. You will find out this information from ViewCashTrx method. |
DeleteCashTrxResult Structure
|
Property |
Type |
Detail |
|
ReturnCode |
Integer |
Zero means OK. For other return codes, please refer to “Return Code” section. |
|
ReturnMsg |
String |
This is the explaination of return code. |
Code Example (VB)
The following sample codes delete one pending cash receipt.
Dim Service As New webServicesCash.ElicshtxService
Dim Input As New webServicesCash.DeleteCashTrxInput
Dim Result As New webServicesCash.DeleteCashTrxResult
Input.CustomerNo = “000044”
Input.CheckNo = 123456
Input.TimeStamp = 163801
Result = Service.DeleteCashTrx(“”, “”, Input)
If Result.ReturnCode <> 0 Then
lblResult.Text = “Record Deleted.”
Else
lblResult.Text = “Error Code: ” + Result.ReturnCode.ToString + _
“ . Message: ” + Result.ReturnMsg
End If
0 = OK
1 = File Error
2 = IncludeFullyPaidItems Must Be "Y", "N", or Blank (ViewOpenItems)
3 = IncludePendingCashReceipts Must Be "Y", "N", or Blank (ViewOpenItems)
4 = Too Many Records, Only The First 2000 Trx Returned (ViewOpenItems)
5 = CustomerNo, CheckNo, and TimeStamp Are Required (DeleteCashTrx)
6 = Cash Trx Record Locked (DeleteCashTrx)
7 = Cash Appl Record Locked (DeleteCashTrx)
8 = CreditARFlag Must Be "Y", "N", or Blank (AddCashTrx)
9 = A Vaild CreditAccountNo Is Required When CreditARFlag = "N" (AddCashTrx)
10 = Invaild CashAccountNo (AddCashTrx)
11 = Invaild ApplyToAllowAcctNo (AddCashTrx)
12 = AutoApply Must Be "Y", "N", or Blank (AddCashTrx)
13 = ApplyToNo Is Already Fully Paid (AddCashTrx)
14 = Entered Amount Will Make The Apply-To Become Over Paid (AddCashTrx)
15 = ApplyToAmountApplied Must Be Positive (AddCashTrx)
16 = ApplyToAmountApplied Must Be Negative For Charge Back (AddCashTrx)
17 = CashACHReference Required (AddCashTrx)
18 = Invaild CashACHAcctKey (AddCashTrx)
19 = Total of ApplyToAmountApplied Not Equal To ReceiptAmount (AddCashTrx)
20 = PaymentType Must Be "CK" "CS" "GC" "CC" "WR" "AC" or Blank (AddCashTrx)
21 = PaymentType Does Not Match BatchID's payment type (AddCashTrx)
22 = To Auto Apply Trx, AmountReceived Must Greater Than Zero (AddCashTrx)
23 = PaymentType "AC" Is Not Enabled in Elliott (AddCashTrx)
24 = CheckNo Cannot Be Zero (AddCashTrx)
25 = ACH Account Belongs to Different Customer (AddCashTrx)
26 = Must Use PaymentType "AC" for Scheduled Batch (AddCashTrx)
27 = Receipt Date Must Match Scheduled Post Date (AddCashTrx)
28 = IncludeHistory Must Be “Y”, “N” or Blank (ViewOpenItems)
29 = IncludeFullyPaidItems Must Be “Y” if IncludeHistory Is “Y” (ViewOpenItems)
30 = Customer Not On File (ViewOpenItems, AddCashTrx)
10001 = Missing Customer No.
CLS