Implementation Guide for Oracle Self-Service E-Billing > Customizing Payment >
Customizing Oracle Self-Service E-Billing Payment Template Files
Oracle Self-Service E-Billing provides a template engine to generate text messages, such as email, ACH files, and A/R files. This topic describes how to use Oracle Self-Service E-Billing Payment templates to customize those text messages. Oracle Self-Service E-Billing Payment Template Engine
The Oracle Self-Service E-Billing Payment templates provide a generic template mechanism based on Java reflection. The template engine generates custom text output based on the templates. Similar to JSP, the template engine replaces the special placeholders inserted into the text file with the values of Java objects. For more detailed API documentation, see Accessing Oracle Self-Service E-Billing Javadoc for details on accessing Oracle Self-Service E-Billing Javadoc. The Template engine hosts a pool of objects in its context in the form of a hash table. You can refer to the variables in that context by their names. For example, there is a Check object whose name is check. You can refer to that object as %check%. This means replace %check% with the string returned from check.toString(). This is true for all Java objects except java.util.Date, where getTime() is called and inserts a long value that is the number of milliseconds since January 1, 1970, 00:00:00 GMT. If a method returns void, then nothing prints. The content of the message consists of text plus resolved placeholders. Placeholders are Java variables, which are Payment hosted objects including their attributes and methods. Enclose all template variables with two percent signs (%%). To escape %, use %%. For example, %%40 means %40. In addition to referring to variables, you can also access an object's public fields and methods. The valid reference is %name.field%, %name.method(param1, param2, ...)% , where each parameter to a method can be name, name.field, or name.method(param1, param2, ,,,) . The number of parameters is unlimited and an arbitrary level of method nesting is allowed (nesting means that a method's return value is used as a parameter when calling another method). For example, suppose there are two objects in contexts: buf which is a StringBuffer, and str which is a String. The following references are valid: %buf%, %buf.append(str)%, %buf.append(str.toString())% . A static field or method can be accessed directly without instantiating an object. For example, java.lang.Integer has a static field called MIN_VALUE and a static method called parseInt. You can refer to them as %java.lang.Integer.MIN_VALUE% or %java.lang.Integer.parseInt("12.34")%. All variables must be preset by calling putToContext on the Template class. Some variables are already set by Oracle Self-Service E-Billing Payment which you can use directly. But you can also put your own variables into the context: %template.putToContext("buf", new java.lang.StringBuffer())%
This means to put a new StringBuffer object called buf into the template context. You can then refer to this object by its name: %buf.append("abc")%
This appends "abc" to the end of the StringBuffer's value. The current Oracle Self-Service E-Billing Payment engine has some limitations. It cannot do math operations, such as x plus y. You must call a Java method to do math operations. Another limitation is that it does not allow you to concatenate method calls, for example: %variable.method().method() %. You must write your own Java method to do method concatenation. Included with the Oracle Self-Service E-Billing Payment package, there are a few utility classes to help you overcome the weakness of Oracle Self-Service E-Billing Payment Template Engine. These classes are: com.edocs.payment.util.DecimalUtil com.edocs.payment.util.DateUtil com.edocs.payment.util.StringUtil.
One useful method in StringUtil is concat, which you declare and use as follows: public static String concat(String s1, String s2, String s3) %com.edocs.payment.util.StringUtil.concat(s1,s2,s3)%
Remember, you cannot do %s1.concat(s2).concat(s3)% inside a template, instead, you must call this function from template: %com.edocs.payment.util.StringUtil.concat(s1,s2,s3)%.
Another useful method is format() from DateUtil class. This method helps format a Date object into different display formats. For example: %com.edocs.payment.util.DateUtil.format("MMM dd, yyyy", check.getPayDate())% formats a check's pay date to display as "Jan 01, 2000." For a complete list of possible date formats, please check the JDK document about java.text.SimpleDateFormat. When writing customized Java code, it is strongly recommended that you use static methods as frequently as possible, so you can call them directly from a template without creating an instance of that object first. For example, by default, the individual ID field of an ACH entry detail field is populated with the customer's account number using %check.getPayerAcctNumber()%. The returned result is 16 bytes long, but the account number is 15 bytes, so you must truncate the retrieved value. To create a java class to do truncation and enable it in the Oracle Self-Service E-Billing Payment Template Engine
- Write a Java class:
package com.edocs.ps; public class MyUtil { public static String truncate(String s){ return s.substring(1); } }
- Compile the class and put it into Payment_custom.jar of each EAR file, then redeploy the EAR files.
- Refer to this class in a template as follows:
%com.edocs.ps.MyUtil.truncate(check.getPayerAcctNumber())%
Customizing Email Templates
The Payment module uses template files to generate customized text that will be sent in a notification email. The email templates can be customized for you by Oracle Professional Services, or you can customize them yourself. Table 70 describes the email notification templates used in Payment.
Table 70. Email Notification Templates
|
Name of the Task that Uses the Notification |
|
Reminder to pay bills and the status of the checks |
pmtPaymentReminder |
paymentReminder.txt |
Enrollment status |
pmtNotifyEnroll |
modifyEnroll.txt |
Recurring payment was scheduled |
pmtRecurPayment |
recurringNotify.txt |
Payment Command Center job status |
All Payment jobs |
notifyPaymentTask.txt |
Credit card expiration |
pmtCreditCardExpNotify |
CCExpNotify.txt |
For UNIX, the default path to the email template files is the EDX_HOME /payment/lib/payment_resources / directory (the EDX_HOME \payment\lib\payment_resources directory on Windows). In the path, EDX_HOME is the directory where you installed Oracle Self-Service E-Billing. The email templates use a programming structure that works similar to JSP (but is not JSP). The template language includes a list of placeholders that refers to Java objects, which are hosted by Payment. It also includes some logic control directives such as IF and LOOP. For more information about template classes, see Accessing Oracle Self-Service E-Billing Javadoc for details on accessing Oracle Self-Service E-Billing Javadoc. Oracle Self-Service E-Billing Payment Reminder Template
Oracle Self-Service E-Billing Payment reminder messages are generated based on PaymentReminder.txt, which resides in the EDX_HOME /payment/lib/payment_resources / directory (the EDX_HOME \payment\lib\payment_resources directory on Windows). In the path, EDX_HOME is the directory where you installed Oracle Self-Service E-Billing. This template is used for regular payment reminder and email notifications for processed, returned or failed payments. Table 71 describes the Oracle Self-Service E-Billing Payment reminder template variables.
Table 71. Payment Reminder Template Variables
|
|
|
check |
ICheck |
The ICheck object being notified, valid only when isCheck is true. |
creditcard |
ICreditCard |
The ICreditCard object being notified, valid only when isCCard is true. |
isCCard |
Boolean |
True means this is for credit card status notification. |
isCheck |
Boolean |
True means this is for check status notification. |
isFailed |
Boolean |
True means the payment has failed to process (isFailedAuthorize). |
isPaid |
Boolean |
True means the check has been paid or cleared. |
isProcessed |
Boolean |
True means the check has been processed. |
isReminded |
Boolean |
True means this is for regular payment reminders. |
isReturned |
Boolean |
True means the check has been returned. |
isSettled |
Boolean |
True means the credit card has been settled. |
isSystemFailure |
Boolean |
True means there has been a system error. For example, a network failure. |
reminder |
IPaymentReminder |
The IPaymentReminder object being reminded, valid only when isReminded is true. |
Enrollment Notification Template
The enrollment notification template notifies customers about active and bad-active payment accounts and NOC returns. Enrollment reminder messages are generated based on enrollNotify.txt. This template is used for ACH. The text between %<IF isACH>% and the corresponding %</IF>% is for ACH. If there are no payment gateways for ACH, you can remove that topic from the template file. Each Oracle Self-Service E-Billing Payment account will be sent an individual email. Oracle Self-Service E-Billing Payment supports multiple payment accounts. If a customer has multiple payment accounts, there could be more than one email message sent for each customer. Table 72 list the variables available for use in the Enrollment Notification email template. The variables described in Table 72 apply to all cases.
Table 72. Enrollment Notification Template Variables
|
|
|
checkAccount |
ICheckAccount |
The current check account being notified. |
template |
Template |
The Payment Template Engine, which is used to declare new variables for the template. |
config |
IPaymentConfig |
Payment setting information, as configured in the Command Center. |
The variables described in Table 73 apply to ACH.
Table 73. ACH Variables
|
|
|
isACH |
Boolean |
True indicates this is an ACH notification. |
success |
Boolean |
Success means this account has been activated successfully. |
errCode |
String |
ACH return code, if the transaction failed. |
The variables described in Table 74 apply to ACH NOC returns.
Table 74. ACH NOC Return Variables
|
|
|
isNOC |
Boolean |
True indicates this is an NOC return. |
isC01, isC02, isC03, isC05, isC06, isC07 |
Boolean |
True indicates the returned NOC codes. |
isAutoUpdate |
Boolean |
Returns the state of the com.edocs.payment.cassette.ach.autoUpdatNOC flag, which is configured on the Payment Settings page from the Command Center. |
newPaymentAccount |
String |
New payment account number. |
oldPaymentAccount |
String |
Old payment account number. |
newRouting |
String |
New payment routing number. |
oldRouting |
String |
Old payment routing number. |
newPaymentType |
String |
New payment account type. |
oldPaymentType |
String |
Old payment account type. |
Recurring Payment Schedule Notification Template
When recurring payment schedules a payment, email notification messages are generated from the template file recurringNotify.txt. Table 75 describes the recurring notification template variables.
Table 75. Recurring Notification Template Variables
|
|
|
recurringPayment |
IRecurringPayment |
Contains recurring payment information and current bill information paid by this recurring payment, when applicable. Bill information is null if the amount and pay date are both fixed. |
isPaymentScheduled |
Boolean |
True if a payment has been scheduled. |
isCheck |
Boolean |
True if the payment scheduled is a check. |
isCCard |
Boolean |
True if the payment scheduled is a credit card. |
payment |
IPaymentTransaction |
ICheck if isCheck is true or ICreditCard if isCCard is true. This is the payment being scheduled. |
isPaymentNotScheduled |
Boolean |
True if the payment is not scheduled for some reason. Usually this is because a payment job plug-in rejected the payment based on a customer business rule. |
isLessPayment |
Boolean |
True if the amount due is less than a certain amount, but the amount due is more than that. Notify the customer to pay manually. |
isAlreadyPaid |
Boolean |
True when Oracle Self-Service E-Billing finds a DuplicateBillIdException during the insertion of a payment into database. |
isLastRecurringPayment |
Boolean |
True if this is the last payment. |
isRecurringPaymentCancelled |
Boolean |
True if the recurring payment is cancelled. For example, if the payment account is cancelled. See the job configuration for details. |
Payment Notification Template
This template controls the format of email that are sent to the administrator by each job. The template file is notifyPaymentTask.txt. pmtCreditCardExpNotify Variables
Table 76 describes the payment notification template variables related to pmtCreditCardExpNotifiy.
Table 76. pmtCreditCardExpNotifiy Variables
|
|
|
CreditCardExpNotifyTask |
String |
Identifies the credit card expiration notification task. |
isDone |
Boolean (true or false) |
Identifies the job had done. |
jobName |
String |
Identifies the job name. |
ccexpNotifyCount |
int |
Total number of notifications to be made. |
ccexpNotifySuccessCount |
int |
Successful number of accounts. |
ccexpNotifyFailureCount |
int |
Failed number of accounts. |
goodCCAccountCount |
int |
Number of good credit card accounts (due to decryption). |
badCCAccountCount |
int |
Number of bad credit card accounts (due to decryption). |
pmtRecurringPayment Variables
Table 77 describes the recurring notification template variables for the synchronization task.
Table 77. Synchronization Task Variables
Recurring Synchronization Variable |
|
|
skipSynchronization |
Boolean (true or false) |
True enables the skip synchronization option. |
recurringPmtSyncTask |
Boolean (true or false) |
True identifies this as the recurring payment task. |
isDone |
Boolean (true or false) |
True indicates that the job is done. |
jobName |
String |
The job name. |
syncCount |
int |
Total number of accounts to be synchronized. |
syncSuccessCount |
int |
Successful number of synchronized accounts. |
syncFailureCount |
int |
Number of failed of synchronized accounts. |
Table 78 describes the recurring notification template variables for the scheduler task.
Table 78. scheduler Task Variables
Recurring Scheduler Variable |
|
|
recurringPmtSchedulerTask |
String |
Identifies the scheduler task. |
isDone |
Boolean (true or false) |
To identify the job had done. |
jobName |
String |
To identify the job name. |
scheduleCount |
Int |
Total number of accounts to be scheduled. |
scheduleSuccessCount |
Int |
Successful number of scheduled accounts. |
scheduleFailureCount |
Int |
Failed number of scheduled accounts. |
CancelCount |
Int |
Cancelled number of scheduled accounts. |
isDecryptFailed |
Boolean value (true or false) |
To identify whether there were any decryption failures. |
pmtPaymentReminder Variables
Table 79 describes the pmtPaymentReminder variables.
Table 79. pmtPaymentReminder Task Variables
|
|
|
paymentReminderTask |
String |
Identifies the payment reminder task |
isDone |
Boolean (true or false) |
Identifies the job is done |
jobName |
String |
Identifies the job name |
goodCheckPaymentsCount |
Int |
Number of successful check accounts |
badCheckPaymentsCount |
Int |
Number of failed check accounts |
goodCCPaymentsCount |
Int |
Number of successful credit card accounts |
badCCPaymentsCount |
Int |
Number of failed credit card accounts |
pmtCreditCardExpNotify Variables
Table 80 describes the pmtCreditCardExpNotify variables.
Table 80. pmtCreditCardExpNotify Variables
|
|
|
CreditCardExpNotifyTask |
String |
Identifies the credit card expiration notification task |
isDone |
Boolean (true or false) |
Identifies the job is done |
jobName |
String |
Identifies the job name |
ccexpNotifyCoun |
int |
Total number of notifications to be made |
ccexpNotifySuccessCount |
int |
Number of successful accounts |
ccexpNotifyFailureCount |
int |
Number of failed accounts |
goodCCAccountCount |
int |
Number of good credit card accounts (due to successful decryption) |
badCCAccountCount |
int |
Number of bad credit card accounts (due to unsuccessful decryption) |
pmtCheckSubmit Variables
Table 81 describes the pmtCheckSubmit variables.
Table 81. pmtCheckSubmit Variables
|
|
|
CheckSubmitTask |
Boolean value (true or false) |
Identifies the check submit task. |
isDone |
Boolean (true or false) |
Identifies the job done. |
jobName |
String |
Identifies the job name. |
isHoliday |
Boolean value (true or false) |
Identifies a holiday. |
dateUtil |
DateUtil object |
Format of the expiration date. |
isDecryptFailed |
Boolean value (true or false) |
Identifies whether there were any decryption failures. |
pmtSubmitEnroll
Table 82 describes the pmtSubmitEnroll variables.
Table 82. pmtSubmitEnroll Variables
|
|
|
SubmitEnrollTask |
String |
Identifies the submit enroll task. |
isDone |
Boolean (true or false) |
Identifies the job had done. |
jobName |
String |
Identifies the job name. |
sHoliday |
Boolean value (true or false) |
Identifies a holiday. |
isDecryptFailed |
Boolean value (true or false) |
Identifies whether there were any decryption failures. |
Credit Card Expiration Notification Template
When a credit card is about to expire, email notification messages are generated from the template file CCExpNotify.txt. Table 83 describes the credit card expiration notification template variables.
Table 83. Credit Card Expiration Notification Template Variables
|
|
|
accExpired |
Boolean value (true or false) |
Identify whether the account is expired or not |
account |
ICreditCardAccount object |
Object of ICreditCardAccount that has the information about the account |
Customizing ACH Templates
The ACH records of interest are in File Header, Batch Header, Entry Detail for PPD, Addenda and return for PPD, Batch Trailer and File Trailer. ACH fields can be mandatory, required, or optional. The contents of mandatory fields are fixed and must not be customized. Required fields are usually defined by the receiving bank, and can be customized for different banks. Optional fields can be customized, also. By default, secCode is set to WEB to be compliant with the ACH 2001 format. However, you can change the SEC code based on the requirements of a biller's bank by editing the batchHeader_template.xml file. Table 84 describes some ACH fields. These fields can be customized upon a biller's request. The pmtCheckSubmit jobs running date is referred to as Today.
Table 84. ACH Fields
|
|
|
Company Descriptive Date |
8th field in batch header, optional |
Default set to Today; the date pmtCheckSubmit is running. |
Effective Entry Date |
9th field in batch, required |
The date when checks in the batches are to be cleared. This is a suggested date from ACH, but the date that checks are cleared can vary. All checks with the same pay date will be put into one batch. The effective entry date might not always be the pay date. The default setting for effective entry date is: If the pay date is tomorrow or earlier, then it is the earliest business date after today. If the pay date is after tomorrow, then it is the earliest business date after the pay date (including the pay date). |
Individual ID |
7th field in PPD entry detail, optional or required |
By default set to the customer's account with the biller. Because this field is 15 bytes, the length of customer's account must not exceed 15 bytes. If the customer account is longer than 15 bytes, either the field will not be populated, or you must truncate this field using Java code or the Java classes provided by Oracle Self-Service E-Billing. |
Individual Name |
8th field in PPD entry detail. Required |
By default set to the check's payment ID. Payment ID is the primary key on the check_payments table. It can be used to map a returned check back to the one in Oracle Self-Service E-Billing Payment database. |
The templates for ACH are XML files, which describe the format of each ACH record, such as the start position, length, and so on. There are two sets of templates: one to generate ACH files, and another to parse ACH return files. The first set of templates is used to generate the following ACH files:
- fileHeader_template.xml
- batchHeader_template.xml
- entryDetail_template.xml
- batchTrailer_template.xml
- Trailer_template.xml
When an ACH file is generated, check information is pulled from the database and then populated into the content of the XML files by replacing the template variables. The resulting XML file is transferred into an ACH file according to the format specified by the XML tags. The generic format of an XML tag is: <amount pos="30 " len=" 10 " fmt=" N " fract=" 2 "> %
where:
- amount is the name of the tag
- pos="30" is the start position
- len="10" is the length of the field
- fmt="N" is the format of the field
- fract="2" is the number of digits after the decimal point if the format (fmt) is N (numerical)
Table 85 through Table 89 list the template variables that are predefined in the Oracle Self-Service E-Billing Payment Template Engine. These variables are used to populate the content of the templates. Table 85 describes the template variables that all templates use.
Table 85. Global Template Variables
|
|
|
template |
com.edocs.util.template. Template |
The template engine. |
stringUtil |
com.edocs.payment. util.StringUtil |
Makes calling the static methods of StringUtil easier. Instead of using: %com.edocs.payment.util. StringUtil.concat("a","b","c")% use: %stringUtil.concat("a", "b", "c")% |
decimalUtil |
com.edocs.payment. util.DecimalUtil |
Provides decimal number manipulations. |
dateUtil |
com.edocs.payment. util.DateUtil |
Provides date manipulation methods Also a calendar, which includes all U.S. holidays. |
batch |
com.edocs.payment. IPaymentBatch |
The payment summary report, which you can view through the Command Center. |
config |
com.edocs.payment. config.IPaymentConfig |
Payment setting information. |
attributeName |
com.edocs.payment. config.AttributeName |
Payment setting parameter names, Use it with the variable config to get payment setting information. |
Table 86 describes the template variables that File Header uses.
Table 86. File Header Variables
|
|
|
fileCreateDate |
java.util.Date |
Creation date of the ACH file. |
fileCreateTime |
java.util.Date |
Creation time of the ACH file. |
fileIdModifier |
java.lang.String |
ACH file modifier, A to Z and 0 to 9. |
Table 87 describes the template variables that Batch Header uses.
Table 87. Batch Header Variables
|
|
|
curPayDate |
java.util.Date |
The pay date of checks in the batch. All the checks in the same batch have the same pay date. |
companyDescData |
String |
From Payment Settings. |
companyDescDate |
Date |
Defaults to Today. To use another date, you must call a static Java method. |
batchNumber |
int |
Starts from 1; identifies the batches in the ACH. |
batchEffectiveEntryDate |
Date |
Identifies the batches in the ACH. |
Table 88 describes the template variables that Entry Detail uses.
Table 88. Entry Detail Variables
|
|
|
check |
com.edocs. payment.ICheck |
All check payment information, including the trace number. |
addenda Record Indicator |
int |
Indicates whether there is addenda record for entry detail. 0=No; 1=Yes. |
Table 89 describes the template variables that Batch Trailer uses.
Table 89. Batch Trailer Variables
|
|
|
batchEntryHash |
String |
See the ACH documentation. |
batchEntryAddendaCount |
int |
Number of entries in the batch. |
batchDebitAmount |
String |
Total debit amount in the batch. |
batchCreditAmount |
String |
Always zero. |
blockCount |
int |
See the ACH documentation. |
totalEntryHash |
String |
See the ACH documentation. |
totalEntryAddendaCount |
int |
Total number of entries in the file. |
totalDebitAmount |
String |
Total debit amount in the file. |
Matching a Check in the ACH Return to the Database
Return files are parsed by the return templates:
- fileHeader_return_template.xml
- batchHeader_return_template.xml
- entryDetail_return_template.xml
- addenda_return_template.xml
- batchTrailer_return_template.xml
- fileTrailer_return_template.xml
The format of these files is similar to the format of the submit template. For example: <individualName pos="55" len="22" fmt="AN" target="%check.setPaymentId(?)%"></individualName>
This code retrieves the part of the text from positions 55 to 77, puts it into a variable called ? and then calls check.setPaymentId() to set payment_id for the check. The template executes the template statement specified by XML tag "target" only. When a check is returned from the ACH network, Oracle Self-Service E-Billing Payment matches it to that check in the database and marks it as returned. ACH modifies several fields in the return file. Oracle Self-Service E-Billing Payment populates one or more unchanged fields with identification information to help in matching them with a check in the database. Consult the ACH documentation for information about which fields are not changed. The return template retrieves the error return code from the addenda record and then tries to reconstruct the payment ID or gateway payment ID to match a check in the database. If Oracle Self-Service E-Billing Payment cannot populate the payment ID into the ACH file, it uses the gateway payment ID, which is a concatenation of a few check payment fields that can identify a check. By default, Oracle Self-Service E-Billing Payment populates the payment_id of the check into the individual name field to create the ACH file. The following line in the entryDetail_template.xml file populates the payment ID into an individual name: <individualName pos="55" len="22" fmt="AN">%check.getPaymentId()%</individualName>
The following line in the entryDetail_return_template.xml file extracts the payment ID: < individualName pos="55" len="22" fmt="AN" target="%check.setPaymentId(?)%"></individualName >
The following line in the addenda_return_template.xml file extracts the return error code: <returnReasonCode pos="4" len="3" target="%check.setTxnErrMsg(?)%"></returnReasonCode>
Payment then changes the status of the check to returned and updates this check in the database using its payment_id. If the individual name is required for another task, for example, the check account name (which is the first 22 bytes), then follow these steps to use gateway payment ID. To use the gateway payment ID
- Modify the entryDetail_template.xml file to populate individual name with account name. Change:
<individualName pos="55" len="22" fmt="AN">%check.getPaymentId()%</individualName>
to:
<individualName pos="55" len="22" fmt="AN">%stringUtil.substring(check.getAccountName(), 0, 22)%</individualName>
- Modify the entryDetail_return_template.xml file so that payment ID will not be set for a returned check. Change:
<individualName pos="55" len="22" fmt="AN" target='%check.setPaymenId(?)%'></individualName>
to:
<individualName pos="55" len="22" fmt="AN"></individualName>
- Because payment ID cannot be used to match checks, use the gateway payment ID instead. Gateway payment ID is the ID generated by the template that submitted the ACH file to ACH. This template generates a unique ID based on the information submitted to ACH. This ID must contain information that will not be changed by ACH in the return file. The Oracle Self-Service E-Billing engine uses the gateway payment ID to find a match in the database.
In very rare circumstances, more than one match might be found. In that case, the match with the latest creation time is used. The following example discusses several ways to generate the gateway payment ID. Oracle Self-Service E-Billing Payment generates a trace number and puts that into the entry detail record. By default, the trace number starts at 0000000 and increases by one for each check until it reaches 9999999. After this point, the numbering restarts at 0000000. It is possible to get a duplicate trace number (after 10 million checks). However, because the Oracle Self-Service E-Billing Payment engine always chooses the payment with the latest date, the correct check will be matched. You can use both the trace number and individual ID (customer account number) to identify a payment and use them for the gateway payment ID. Example 1: Unchanged ACH Trace Number
In the following example, it is assumed that the ACH or Bank will return both the original trace number and individual ID to Oracle Self-Service E-Billing:
- At the beginning of the entryDetail_template.xml file, see the following code:
<ACH_6> %<*>% %check.setGatewayPaymentId(com.edocs.payment.util.StringUtil.concat(check.getPayerAcctNumber(), "_", check.getTxnNumber()))%
%</*>%
This statement is commented out in the template, using %<*>% and %</*>%. Removing the comment tags enables the statement.
The trace number is stored as txnNumber in the check object. This statement concatenates the customer account number, a "_", and trace number as the gateway payment ID. The setGatewayPaymentId method returns void, so nothing will print out. (If it did return a value, then that would print, which would ruin the format of the XML file.) After running pmtCheckSubmit, check the gateway payment ID in the check_payments table, which is the concatenation of the individual ID and the trace number that are written into the entry detail record.
- Next, Payment retrieves the original trace number from the return file, and sets it as the gateway payment ID. In the addenda_return_template.xm, find this code:
<traceNumber pos="80" len="15" fmt="N" target1='%check.setGatewayPaymentId(txnNumber)%' target2='%check.setGatewayPaymentId(stringUtil.concat(payerAcctNumber, "_", txnNumber))%'></traceNumber>
Rename target2= to target, which will reconstruct the gateway payment ID based on the returned customer account number and trace number. Template variable payerAcctNumber has been set in the entryDetail_return_template.xml file and txnNumber has been set before this line in the addenda_return_template.xml file by calling template.putToContext.
- Now you are all set. Test this setting using a real return file and verify that the check's status has been updated to -4 in the check_payments table.
Example 2: Modified ACH Trace Number
If the individual ID is not returned as it was set, you can try to use other information, such as individual name combined with trace number. If only the trace number can be used for gateway payment ID, use that as follows. To use only the trace number for gateway payment ID
- At the beginning of the entryDetail_template.xml file, see the following code:
%<*/>%
%check.setGatewayPaymentId(check.getTxnNumber())%
%</*>%
Remove the comment tags to enable the statement.
- In the addenda_return_template.xml file, rename target1 to target to enable using trace number as gateway payment ID:
<traceNumber pos="80" len="15" fmt="N" target1='%check.setGatewayPaymentId(txnNumber)%' target2='%check.setGatewayPaymentId(stringUtil.concat(payerAcctNumber, "_", txnNumber))%'></traceNumber>
|