October 2019
JHA Payment Solutions
iPay Solutions™
Bill Pay Services API – User Guide
(For use with jXchange XSD Version R2018.7.07_XSD)
i
Bill Pay Services API – User Guide
iPay Solutions™
1999-2017 Jack Henry & Associates, Inc.®
Release 2018.7.07
List of Tables and Figures .............................................................................................. iii
Bill Pay Services API – User Guide ............................................................................................ 4
Document Tracking ........................................................................................................ 4
About this Guide ............................................................................................................14
After Reading This Document ............................................................................14
What is the Bill Pay Services API? .....................................................................15
Error Handling ...............................................................................................................15
Fault Behaviors ..................................................................................................15
Parallel/Serial Error Message Handling ..............................................................16
Serial Error Message Handling ...............................................................16
Parallel Error Message Handling ............................................................16
Authentication and Identification ....................................................................................16
Authentication ....................................................................................................16
Authorization ......................................................................................................16
Identification .......................................................................................................17
Service Behaviors .........................................................................................................18
Canonicals .........................................................................................................18
Nulls...................................................................................................................19
Nillable Attribute : ...............................................................................................20
Rstr Attribute : ....................................................................................................20
Search/Inquiry Behaviors ...................................................................................20
Modification Behaviors .......................................................................................22
Localization/Time Zones ....................................................................................22
Deprecation Policy .............................................................................................23
Business Service Operations .........................................................................................24
Business Service Operations – Updates ............................................................26
Release 2012.0.01 – Initial release .........................................................26
Release 2012.0.02 – (06.01.2013) .........................................................26
Release 2013.1.00 – (10.15.2013) .........................................................27
Release 2013.1.03 – (07.07.2014) .........................................................28
Release 2014.0.01 – (07.31.2014) .........................................................29
Release 2014.0.06 – (03.31.2015) .........................................................30
Release 2014.0.08 – (06.15.2015) .........................................................31
Release 2015.0.01 – (08.12.2015) .........................................................32
Release 2015.0.03 – (11.02.2015) .........................................................32
Release 2015.0.06 – (02.01.2016) .........................................................33
Release 2016.0.01 – (06.03.2016) .........................................................34
Release 2016.0.09 – (01.30.2017) .........................................................34
Release 2017.0.02 – (05.31.2017) .........................................................34
Release 2017.2.01 – (08.07.2017) .........................................................35
Release 2017.2.03 – (10.27.2017) .........................................................35
Release 2017.4.01 – (02.01.2018) .........................................................35
Release 2017.4.04 – (04.03.2018) .........................................................36
Release 2018.6.01 – (02.21.2019) .........................................................36
Release 2018.7.04 – (06.03.2019) .........................................................36
Release 2018.7.07 – (09.11.2019) .........................................................37
Business Service Operations – General Behaviors ............................................37
Institution Services .............................................................................................38
ii
Bill Pay Services API – User Guide
iPay Solutions™
1999-2017 Jack Henry & Associates, Inc.®
Release 2018.7.07
Service Dictionary Search ......................................................................38
Channel Inquiry ......................................................................................43
Subscriber Services ...........................................................................................51
Subscriber Lookup .................................................................................51
Subscriber Add .......................................................................................54
Subscriber Search ..................................................................................69
Subscriber Inquiry ..................................................................................77
Subscriber Modify ...................................................................................90
Payee Services ................................................................................................ 106
Payee Add ............................................................................................ 106
Payee Search ....................................................................................... 113
Payee Inquiry ....................................................................................... 122
Payee Modify ....................................................................................... 139
Payment Services ............................................................................................ 153
Payment Add ........................................................................................ 153
Scheduled Payment Search ................................................................. 164
Scheduled Payment Inquiry .................................................................. 171
Scheduled Payment Mod ..................................................................... 184
Scheduled Payment Approval .............................................................. 194
Payment History Search ....................................................................... 196
Payment History Inquiry ....................................................................... 203
eBill Services ................................................................................................... 217
eBill Search .......................................................................................... 217
eBill Inquiry ........................................................................................... 221
eBill Mod .............................................................................................. 226
Appendix A: Business Service Operation-to-Feature Mapping – Bill Pay Services
........................................................................................................................ 229
Appendix B: Subscriber’s Associated User – Permission/Caps specifications
example ........................................................................................................... 232
Appendix C: Payment Statuses and Definitions ............................................... 235
Appendix D: eBill Account Setup and Error Resolution Flows .......................... 236
eBill Account Setup Flow ...................................................................... 236
eBill Account Info/Error Resolution Flow ............................................... 237
Appendix E: eBill Account Errors – Subscriber remediation required ............... 238
Glossary .......................................................................................................... 239
Bibliography ................................................................................................................ 242
Index ........................................................................................................................... 243
iii
Bill Pay Services API – User Guide
iPay Solutions™
1999-2017 Jack Henry & Associates, Inc.®
Release 2018.7.07
List of Tables and Figures
Table 1 – UTC Time Adjustments .............................................................................................23
Table 2 – Bill Pay Services Operations List ...............................................................................24
Table 3 – eBill Account Eligibility Options – Payee Search ..................................................... 117
Table 4 – eBill Account Eligibility Options – Payee Inquiry ...................................................... 126
Table 5 - eBill Auto Payment Options - Payee Inquiry ............................................................. 134
Table 6 - eBill Auto Payment Options - Payee Mod ................................................................. 146
Bill Pay Services API – User Guide
iPay Solutions™
4
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Bill Pay Services API – User Guide
Additional documents related to this User Guide are included in the jXchange Vendor Packet
Document Tracking
Updates made to this document are outlined below.
Date
Section
Summary of Changes
11.29.2012
Version 2012.0.01
Initial Publication
12.20.2012
• Payment Services:
o Payment History Srch;
o Payment History Inquiry
• Add missed Payment Status of: Resubmitted
01.15.2013
o Identification
o Business Service
Operations:
o Subscriber Services
o Glossary
o Add reference to Subscriber Lookup service – which will
return the iPay Subscriber Identifier needed for all
subscriber-level service requests.
o New Subscriber Lookup service
o Two new subscriber identifier elements added to
BilPaySubInfo complex, associated with SubInq,
SubMod and [future] SubAdd messages.
o Remove ability to add new MobProvdCode; thus
elminating need for MobProvDom element altogether
(SubInq; SubMod services)
o New term added for Stand-Alone Bill Pay Services.
01.17.2013
o Business Service
Operations
o Payee Services
o The following Account Number elements will no longer
be masked in the service response:
o PayFromAcctId
o SubMerAcctId
04.16.2013
o Business Service
Operations:
o Payee Services
o Eliminate the word Individual from the definition for
PayeePmtMthd The Payment Method is applicable for all
Payees, not just individual.
05.15.2013
o Version 2012.0.02
o Service Behaviors:
o Nulls
o Modifications
o Business Service
Operations:
o Glossary
o New Document Version
o Added instructions on use of JHANull when deleting
elements within an array item, or the array item itself.
o Added instructions for modifying items or elements in an
array.
o Modifications to mulitple Business Service Operations
are detailed in Business Service Operations – Updates
section.
o Includes new Business Service Operation: Subscriber
Add
o New term added for Electronic Risk Limits
Bill Pay Services API – User Guide
iPay Solutions™
5
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
10.15.2013
o Version 2013.1.03
o Business Service
Operations:
o Glossary
o New Document Version
o Includes new functionality to expose Bill Pay Services
API for Business subscribers
▪ Includes the ability to add multiple users to the Bill
Pay account.
o Modifications to multiple Business Service Operations to
include Business subscribers are detailed in Business
Service Operations – Updates section.
o Includes new Business Service Operation:
Scheduled Payment Approval
o New terms added for:
o Primary Account Holder
o Subscriber’s Associated User (i.e., Sub user)
12.03.2013
o Behaviors
o Identification:
AuthenUsrCrd
o Corrected AuthenUsrCred’element to accurately reflect
code assertion using claim name of RequestingUsrID
(vs. SubAssocUsrId)
07.07.2014
o Version 2013.1.03
o Business Service
Operations:
o Channel Inquiry
o Subscriber Add,
Subscriber Inquiry,
Subscriber Mod
o User Guide updated to align with jX XSD Version
2013.1.03.
o New element added to BilPayProdTypeInfoArray:
o AlwSubType
o Corrected PmtApprvReq element name in the
BilPaySubInfo complex to accurately reflect XSD value.
o Corrected PersonName element name in the
SecdPersonArray within the BilPaySubInfo complex to
accurately reflect XSD value (‘AddlName’):
07.31.2014
o Version 2014.0.01
o Copyright page:
o About this Guide:
o Service Behaviors:
o Nillable attribute
o Rstr attribute
o Business Service
Operations:
o Service Dict Search
o Payee Inquiry
o Payee Add
o Scheduled Pmt Add
o New Document/XSD Version (R2014.0.01)
o Minimum jXchange contract version R2014.0.01
required.
o Added Copyright information.
o New email contact for documentation support.
o Added instructions on use of nillable attribute.
o Added instructions on use of Rstr attribute
o Added PhoneType, SvcFeeDesc and ElecMerAcctType
to list of Open Enums available.
o Clarification of value returned for SubMerAcctId element
when no value exists.
o Clarification of rules for submitting Payee FI Account
Information when adding a new Payee.
o Rule change: Payment Add no longer allowed for a non-
activated Payee
Bill Pay Services API – User Guide
iPay Solutions™
6
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
o Payment Search
o Multiple/Various
o New] eBill Search
o [New] eBill Inquiry
o [New] eBill Mod
o [New] Appendix C:
o [New] Appendix D:
o [New] Appendix E:
o Glossary:
o Corrected PmtStartDt details to denote this will always be
based on Process Date, regardless of Payment Date
Model.
o Modifications to multiple Business Service Operations to
include Payment Service Fee functionality as detailed in
Business Service Operations – Updates section.
o Modifications to multiple Business Service Operations to
include eBills/Bill Presentment functionality are detailed
in Business Service Operations – Updates section.
o Added list of Payment Status Definitions
o eBill account setup and account error resolution flows
o eBill account errors list
o New terms added for:
o eBill/eBiller
03.31.2015
o Version 2014.0.06
o List of Tables and Figures
o Business Service
Operations
o Payee Search
o Payee Inquiry
o Payee Add
o Payee Mod
o Subscriber Add
o Multiple/Various
o New Document/XSD Version (R2014.0.06)
o Minimum jXchange contract version R2014.0.06
required.
• New section.
o New elements added to Payee Search response:
o FirstAvlProcDt
o FirstAvlEstArvDt
o EstArvDay
o Corrected definition of NotAct Payee Status.
o Corrected definition of NotAct Payee Status.
o Add the following missed element:
o SubModMerAcctId
o Clarified PayeeEmailArray requirement details
o Added notes for the following elements to clarify that
entered values may not always be used for Company
Payees, if superceding information exists on the
matched Merchant record:
o PhoneNum
o EmailAddr
o Corrected element name from ElecMerPayeeAcctID to
ElecBilPayeeAcctID under eBill Account Set up
instructions.
o Added instructions for designation of default funding
account in Subscriber Add Behaviors section.
o Clarified example in PmtDayofMonth to include days (1-
31).
Bill Pay Services API – User Guide
iPay Solutions™
7
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
o Glossary
o Index
o New terms added for:
o Activation [Payee]
o Non-Activated Payee
o New section
06.15.2015
o Version 2014.0.08
o Business Service
Operations
o Subscriber Inquiry
o Payee Inquiry
o Payee Mod
o Scheduled Payment
Add/Inquiry/Mod
o Payment History
Inquiry
o eBill Search
o eBill Inquiry
o Appendix B - Subscriber’s
Associated User -
Permission/Caps
examples
o New Document/XSD Version (R2014.0.08)
o Minimum jXchange contract version R2014.0.08
required.
o Added note for the PayFromAcctInfoArray to clarify that
this array will be empty if the subscriber has no active
funding account at the time of the inquiry.
• Added note to element included in response
[AuthenQuesDesc] clarifying that element may include
HTML or other prohibited characters.
• New element added to Scheduled Payment Add and Mod
requests (including future payments for recurring series),
as well as Scheduled Payment Inquiry, Mod and Payment
History inquiry responses:
o SubCmntToPayee
o New element added to request and response (root):
o ElecBilPayeeAcctId
o New elements added to eBill Search complex in
response:
o ElecBilPayeeAcctId
o CurrBal
o MinPmtAmt
o New element added to eBill Inquiry complex in
response:
o ElecBilPayeeAcctId
o Corrected canonical value name for Sub user PerCode
from CanScheduleP2PPayments to
CanScheduleP2PPayment
08.18.2015
o Version 2015.0.01
o Business Service
Operations
o Channel Inquiry
o Payee Add
o New Document/XSD Version (R2015.0.01)
o Minimum jXchange contract version R2015.0.01
required.
o New payment feature added: Outbound Transfers
o New canonical value added to FeturType element:
o XferToSubFinInst (Outbound Transfers)
o New canonical value added to PayeeClsf element
(request and response):
o FinInst (Financial Institution)
Bill Pay Services API – User Guide
iPay Solutions™
8
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
o Payee Search
o Payee Inquiry
o Payee Mod
o Scheduled Payment
Search
o Scheduled Payment
Add
o Scheduled Payment
Mod
o Scheduled Payment
Inquiry
o Payment History
Inquiry
o Payment History
Search
o Appendix B: Subuser
Permissions/Caps
o Glossary
o New element added to BilPayPayeeInfo complex in
response:
o PmtIntentType (Payee level)
o New elements added to BilPayPayeeSrchInfo complex in
response:
o PmtIntentType (Payee level)
o SubMerAcctID
o New element added to BilPayPayeeInfo complex in
response:
o PmtIntentType (Payee level)
o New filter added to search request and response:
o XferFilter (Transfer filter)
o New element added to BilPaySchedPmtSrchInfo
complex (request and response):
o PmtIntentType (Payment Intention Type)
o New element added to BilPayPmtInfo complex in
request:
o PmtIntentType (for Payment)
o New element added to BilPayPmtPayeeInfo complex in
response:
o PmtIntentType (for Payee)
o New element added to BilPayPmtInfo complex in
response:
o PmtIntentType (for Payment)
o New filter added to search request and response:
o XferFilter (Transfer filter)
o New element added to BilPayPmtHistSrchInfo complex
(request and response):
o PmtIntentType (Payment Intention Type)
• New examples added for Transfer permissions and caps.
• New terms added for Transfer account types.
11.02.2015
o Version 2015.0.03
o Business Service
Operations
o Subscriber Search
o New Document/XSD Version (R2015.0.03)
o Minimum jXchange contract version R2015.0.03
required.
o New filters added to search request and response to
provide expanded filter options in order to enhance ability
to finite subscriber identification:
o PayFromAcctId
o TaxId
o EmailAddr
o PostalCode
o New elements added to BilPaySubSrchInfo complex (in
SubSrch response):
Bill Pay Services API – User Guide
iPay Solutions™
9
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
o Subscriber Inquiry
o Payee Search
o Subscriber Inquiry
o Payee Inquiry
o PayFromAcctId
o PayFromAcctType
o PayFromInstRtId
o PayFromAcctOwnName
o PayFromAcctOwnAddr
o TaxId
o EmailAddr (array)
o BirthDt
o New element added to BilPaySubInfo complex in
response:
o BirthDt
o New Note for Business subscribers regarding retrieval of
Payee information on behalf of sub users with limited
Payee permissions.
o New Note regarding Service Consumer’s need to support
the display and entry of a variable number of login
credentials attributes for eBill accounts.
02.01.2016
o Version 2015.0.06
o Service Behaviors:
o <Rstr> Attribute
o Deprecation Policy
o Business Service
Operations
o Subscriber Inquiry
o Subscriber Mod
o Subscriber Add
o Subscriber Inquiry (Rs)
o Subscriber Search
o SubConsmCustInq
o Subscriber Add
o Payee Inquiry
o Payee Mod
o Payee Search
o Sched Payment
Search
o New Document/XSD Version (R2015.0.06)
o Minimum jXchange contract version R2015.0.06
required.
o New parameter (ReadOnly) being used by Service
Provider (iPay Solutions).
o Added new section detailing deprecation policy.
o New elements added to BilPaySubInfo complex to
support ability to deactivate or reactivate subscriber:
o SubInActRsnType
o SubStat
o Scheduled for DEPRECATION:
o SubStat (encapsulated by BilPaySubInqRs_Mtype)
o New canonical value added to <SubStat> search filter
parameters to enable return of deactivated subscribers:
o InAct (returns only those eligible for reactivation)
o New element added to BilPaySubInfo complex:
o SubStat
o Add additional detail around password set up
requirements to the following element:
o TempPswd
o Add <Rstr> instructions to Payee Name and Payee
Phone Number for conditional edit availability (elements
are ReadOnly in some scenarios)
o New information added regarding the default sort order
applied to search results.
Bill Pay Services API – User Guide
iPay Solutions™
10
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
o Payment History
Search
o Scheduled Pmt Mod
o Glossary
o Additional information on how to specify desired
changes to currently scheduled payment [only] in a
recurring series added to the following element:
o FutPmtId
o New terms added for subscriber Deactivation and
Reactivation.
06.03.2016
o Version 2016.0.01
o Payee Search
o Service Behaviors:
Srch/Inquiry Behaviors
o New Document/XSD Version (R2016.0.01)
o Minimum jXchange contract version R2016.0.01
required to leverage updates.
o New array added to BilPayPayeeSrchInfo complex to
support expanded search results:
o RushOptArray
o Additional information on records management in Srch
requests and responses (e.g., MaxRec, Cursor, etc).
01.30.2017
o Version 2016.0.09
o Payee Add
o Payee Inquiry
o Payee Mod
o Scheduled Payment
Inquiry
o Payment History
Inquiry
o New Document/XSD Version (R2016.0.09)
o Minimum jXchange contract version R2016.0.09
required to leverage updates.
o New element added to BilPayPayeeinfo complex to
allow the consumer to select the communication method
with the P2P recipient:
o PayeeP2PType
o New canonical value added to [Payee] PhoneType
element:
o SMS
o New Payee Add behaviors added to provide guidance on
adding a P2P Payee and designating the desired
communication method (Email or SMS).
o New canonical value added to [Payee] PhoneType
element:
o SMS
05.31.2017
o Version 2017.0.02
o Payee Inquiry
o Payee Search
o New Document/XSD Version (R2017.0.02)
o Minimum jXchange contract version R2017.0.02
required to leverage updates.
o New element added to BilPayPayeeInfo complex to
allow the service consumer to determine the last date a
Payee was modfied:
o LastMainDt
o New element added to BilPayPayeeSrchInfo complex to
allow the service consumer to determine the last date a
Payee was modfied:
o LastMainDt
o New filter(s) added to search request and response to
provide expanded filter options in order to enhance ability
to finite Payee identification (use of these filters allows a
Service Consumer to include only those Payees that
were modified within the specified date range):
Bill Pay Services API – User Guide
iPay Solutions™
11
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
o ScheduledPmtAdd
o ScheduledPmtMod
o LastMainStartDt
o LastMainEndDt
o Add <Rstr> instructions to PayeeName for conditional
Hid value (The Payee should be hidden from the user in
some scenarios.)
o Clarified instructions for adding or modifying a recurring
payment or transfer series.
08.07.2017
o Version 2017.2.01
o Service Behaviors:
o Localization/Time
Zones
o Business Service
Operations
o Payee Add
o Payee Mod
o Payee Inq
o Payee Mod
o Payee Search
o Payee Inquiry
o New Document/XSD Version (R2017.2.01)
o Minimum jXchange contract version R2017.2.01
o New information to warn that if Service Consumer’s
servers are configured to auto-adjust any received
timestamps for local time zone, this must be taken into
account when converting UTC to local time.
o Change to Payee Address rules for Individual Payees
(where bank account information is known) – address is
now optional:
o PayeeAddressInfoArray
o Clarification of the Service Provider’s handling of
ongoing eBill activity when acceptance of a new eBiller
Terms of Service is required for an existing eBill
account:
o ElecMerPayeeToSStat
o New canonical value added to [Payee]
ElecBilPayeeType:
o EnrollPend
o New element added to BilPayPayeeSrchInfo and
BilPayPayeeInfo complexes to provide information of
the level of eBill detail information available for the
Payee’s eBill account:
o ElecBilPayeeCatType
o Table added to illustrate eBill account
enrollment/eligiblity options:
o Table 3 & 4 – eBill Account Eligibility Options
10.27.2017
o Version 2017.2.03
o Business Service
Operations
o eBill Inquiry
o New Document/XSD Version (R2017.2.03)
o Minimum jXchange contract version R2017.2.03
o New elements added to root request (and response) for
entry of mobile device information, if the end user is
requesting eBill information via their mobile device:
o MobDevType
o MobDevResoType
o Orientation
o New element added to BilPayElectBilSchedInqInfo
complex to return the web page URL to be used by the
Service Consumer to retrieve eBill detail information:
o WebPgURL
Bill Pay Services API – User Guide
iPay Solutions™
12
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
02.01.18
o Version 2017.4.01
o Business Service
Operations
o Channel Inquiry
o eBill Inquiry
o New Document/XSD Version (R2017.4.01)
o Minimum jXchange contract version R2017.4.01
o New elements added to BilPayProdTypeInfo complex in
response for new Individual Payee payment Caps:
o MaxIndvPmtAmt
o MaxIndvDlyAmt
o New elements added to BilPayElectBilSchedInqInfo
complex to return another version of the web page URL
WITHOUT an embedded security token (delivered
separately) as an alternate option to be used by the
Service Consumer to retrieve eBill detail information:
o WebPgURLNoToken
o WebPgToken
o TokenExpTimeDt
04.03.18
o Version 2017.4.04
o Business Service
Operations
o Payee Search
o Payee Inquiry
o Subscriber Inquiry (Rs)
o Subscriber Mod (Rq)
o New Document/XSD Version (R2017.4.04)
o Minimum jXchange contract version R2017.4.04
o New canonical value added to [Payee]
<ElecBilPayeeType>:
o EnrollAlw
o New canonical value added to <SubInActRsnType>:
o AdminFraudAct
02.21.19
o Version 2018.6.01
o Business Service
Operations
o Channel Inquiry (Rs)
o Payee Inquiry (Rq)
o Payee Inquiry (Rs)
o Appendix A: Business
Service Operation-to-
Feature Mapping
o New Document/XSD Version (R2018.6.01)
o Minimum jXchange contract version R2018.6.01
o Details for the following element were updated to clarify
the purpose of the element:
o ChkFundModel
o New canonical value added to <FeturType> element
within <BilPayFeturInfoArray>:
o PaybyCard
o New <XtendElem> request value added to
<IncXtendElemArray> array:
o x_CardFundedPayeeArray
o New element added to response root:
o AlwCardFundedType
o New optional array added to response root:
o x_CardFundedPayeeArray
o Added new Feature under Payee Inquiry:
o PaybyCard
o Removed obsolete payment statuses:
Bill Pay Services API – User Guide
iPay Solutions™
13
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
o Appendix C: Payment
Statuses and
Definitions
o Appendix E: eBill
Account Errors
o Returned
o Settled
o New eBill errors requiring subscriber action/remediation
added to Appendix E:
o E6570
o E6571
o E6572
06.03.19
o Version 2018.7.04
o Business Service
Operations
o Payee Search
o Document/XSD Version (R2018.7.04)
o Minimum jXchange contract version R2018.7.04
o New filter added to search request and response to
provide expanded filter options in order to enhance ability
to finite Payee identification (use of this filter allows a
Service Consumer to include only those Payees that
have ‘CardPay’ enabled)
o CardPayFilter
09.11.19
o Version 2018.7.07
o Business Service
Operations
o Payment History
Search
o Document/XSD Version (R2018.7.07)
o Minimum jXchange contract version R2018.7.07
o New filter added to search request and response
o CardPayFilter
Bill Pay Services API – User Guide
iPay Solutions™
14
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
About this Guide
The Bill Pay Services API – User Guide provides information about configuring and working with iPay
Solutions’ Bill Pay Services API.
The purpose of this document is to provide the implementation, standards and operations of iPay Solutions’
Bill Pay Services API. This information is instructional and designed for third-party vendors to evaluate the
interface using a web-based messaging system for connecting with iPay Solutions’ Bill Pay Services through
jXchange.
This document is not designed to be a primer for consuming web services, nor a programming teaching tool.
After Reading This Document
iPay Solutions welcomes your comments and suggestions on the quality and usefulness of this technical
document. Please share your feedback with the Documentation Team by submitting your input by email to
iPayIntegrationSupport@jackhenry.com.
Bill Pay Services API – User Guide
iPay Solutions™
15
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
What is the Bill Pay Services API?
iPay Solutions has created an iPay Service Bus (iSB), which exposes Bill Pay Services API services through
jXChange, allowing authorized external service consumers to request bill payment functionality via web
service requests for integration into any desired bill pay or other interface.
Error Handling
Error handling is covered in the jXchange Error Handling document that is included in the Vendor Packet.
Fault Behaviors
Error handling for errors has been designed in the messaging structure and involves notification through use
of codes, categories and descriptions, as well as options for error overrides for non-fatal errors.
It should be noted that warning and [override-able] fault message information is returned in the Message
Record Information Array, <MsgRecInfoArray> while all unhandled exceptions and errors are thrown as
SOAP faults in the Fault Record Information Array <FaultRecInfoArray>.
Bill Pay Services API – User Guide
iPay Solutions™
16
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
The error values specific to iPay Solutions’ Bill Pay Services API business operations can be found by
performing a Service Dictionary Search, which will return all fault codes by service operation.
Parallel/Serial Error Message Handling
The Bill Pay Services API uses Parallel Error Message handling, except for those types of critical validation
errors that would prevent any forward movement of the request. These Serial Error scenarios include:
• Invalid Institution Identifier
• Invalid Subscriber Identifier
• Insufficient permissions to access a Service Operation
• Invalid Payee ID (for a Payee Inquiry request)
• Invalid Payment ID (for a Payment Inquiry request)
Serial Error Message Handling
In Serial Error Message Handling, the service provider (iPay Solutions) will issue an error response message
when the first critical error is discovered in a consumer’s request. If the consumer resubmits the request with
corrected information, the service provider will attempt to process the new request. If a second critical error is
discovered, the service provider will return another error response message, which will require correction and
resubmission. Back-and-forth error messaging will continue until the message request can be processed
successfully.
Parallel Error Message Handling
In Parallel Error Message Handling, the service provider (iPay Solutions) will continue to process a request
message after detecting faults or certain types of errors in an attempt to identify all possible errors before
returning an error message to the Consumer. Once all errors have been detected that prevent successful
completion of a request, an error response message will be returned to the Consumer listing all the errors.
Authentication and Identification
Authentication
The Service Consumer is expected to perform all subscriber authentication, while jXchange performs the
Consumer-level (e.g., Channel- or Institution-level) authentication. As such, it is assumed that all unique
identifiers provided for the Financial Institution (FI) and subscriber have been authenticated prior to receipt of
the message request by iPay Solutions.
iPay Solutions’ Bill Pay Services API will, in turn, perform service authentication to ensure the service request
is called/passed by a valid source (e.g., jXchange).
Authorization
iPay Solutions will authorize the Service Consumer via a shared security token generated and passed by
jXchange, and will also ensure the Consumer (e.g., Channel) has a valid relationship with the FI identified in
Bill Pay Services API – User Guide
iPay Solutions™
17
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
the service request. In addition, the subscriber, if applicable for the request, must be associated with the
specified institution.
Finally, iPay Solutions will validate all message requests to ensure the requested service operation is
available for the institution and, if applicable, for the subscriber.
NOTE: A subscriber’s authorized set of Bill Pay Services API operations must not exceed the services
available from the subscriber’s web-based (iPay Solutions) Bill Pay product. For example, a subscriber who
does not have Email Payment capabilities via their iPay Solutions-hosted online Bill Pay will not be allowed to
add an Email Payee or an Email Payment via the Bill Pay Services API.
Identification
The Service Provider (iPay Solutions) will validate institution and, if applicable, subscriber identification for
each request message received.
Service Consumers must provide the unique iPay Solutions subscriber identifier required to return a specific
subscriber profile/account. If the Service Consumer does not possess the required iPay Solutions subscriber
identifier, the Subscriber Lookup service may be used to get it.
To ensure that all required information is included to enable iPay Solutions to validate each request message,
the following complex elements are required in the Message Request Header (MsgRqHdr), in addition to
those elements required by jXchange:
jXchangeHdr
The simple elements contained within the jXchangeHdr complex that are required by the Bill Pay
Services API(s) are listed below.
ConsumerName
This is the name of the service consumer (business name) for the Soap Header. Entries
must be in canonical form as defined by the Service Consumer.
ConsumerProd
This is the name of the product which is consuming the service (business product name) for
the Soap Header. Entries must be in canonical form as defined by the Service Consumer.
InstRtId
This is the identification of the entity of the submitted message. An FI entity uses the routing
transit or nine-digit number assigned to FIs for the purpose of routing as assigned by the
American Bankers Association. Any leading zeros must be provided for a complete routing
and transit number. A non-financial institution entity should use a mutually agreed upon
identification that contains at least one non-integer character.
When a record is for a specific FI within a holding company, the InstRtID is the specific FI
routing identification and not the holding company’s identification.
AuthenUsrCred
This optional complex element specifies the Service Provider’s (iPay Solutions) identifier
<SubAssocUsrId> for the requesting user (the subscriber’s associated user). This element is used
primarily when the requesting user is not the subscriber, and is necessary to determine the Bill Pay
permissions available to the requesting user.
Bill Pay Services API – User Guide
iPay Solutions™
18
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
If provided, the identifier must be embedded within this complex element, which must be delivered in
the form of a WS Security element that contains a single SAML V2.0 Assertion (see http://docs.oasis-
open.org/security/saml/v2.0/saml-core-2.0-os.pdf for more information on SAML V2.0). The Service
Provider will parse the SAML token to retrieve the requesting user’s identifier.
If no SubAssocUsrId is provided, the Service Provider will assume the request is from a user
who possesses full permissions access, such as a primary account holder or [Individual]
subscriber, etc.)
Example:
<AuthenUsrCred>
<Security xmlns="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext- 1.0.xsd">
<Assertion xmlns="urn:oasis:names:tc:SAML:2.0:assertion" ID="c563985c-c095-4bd0-b066-
e6a3ccda7855" IssueInstant="2013-01-02T16:30:16.328Z" Version="2.0">
<AttributeStatement>
<AttributeName="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/RequestingUsrID">
<AttributeValue>123456</AttributeValue>
</Attribute>
</AttributeStatement>
</Assertion>
</Security>
</AuthenUsrCred>
Service Behaviors
Canonicals
Where canonical values are required within the Bill Pay Services API operations, the value submitted must
match the expected canonical value exactly. Any invalid canonical value (as with any invalid data) will cause
an error, unless explicit behavior has been defined that indicates we will use a default value in the event of
invalid data.
The two types of canonicals utilized for all service operations in jXchange and, consequently, the Bill Pay
Services API, are:
1. ClosedEnums – There is a definite set of values and only those values are to be used on the
request and response messages between a consumer and provider.
The Closed Enumerated values are defined in the jXchange XSD contract in the form of
annotations. The fixed values are the only data set that a consumer of these elements needs to
understand. An error will be returned when a value is delivered in a message that iPay Solutions’ Bill
Pay Services API services do not understand.
The Closed enumeration values will be used by the Bill Pay Services API in accordance with the
existing jXchange framework to determine how to invoke an operation. Some behaviors that go along
with this are;
• if the element is not sent or sent empty, and it is required, a fault error will be returned;
• if the element is not sent or sent empty, and it is optional, a default will be used and;
• if the element is sent with an incorrect value, a fault error could be returned.
Bill Pay Services API – User Guide
iPay Solutions™
19
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
The web service call – Service Dictionary Search (SvcDictSrchRq_MType) provides the means for a
consumer to query for iPay Solutions’ closed enumerated values within the Bill Pay Services API. The
details for using this request message can be found in the Service Dictionary Search section below.
2. OpenEnums – There is a definite set of values, but those values are not represented (annotated) in
the contract. These values have the potential to change over time. If a defined value is sent on the
request or response, it will be used. However, if a value that is not defined is sent, then it should be
passed as is and the provider or consumer receiving that value would be responsible for
understanding it.
Open enumeration elements are generally suffixed with Code. The element that is suffixed with Code
has a mate element that is suffixed with Desc. This is because often a Service Provider field is
represented as a code that does not convey its representation thereby the Service Provider returns
the description of the code that is a literal value that can be understood by the consumer.
The web service call – Service Dictionary Search (SvcDictSrchRq) provides the means for a
consumer to query for iPay Solutions’ open enumerated values within the Bill Pay Services API. The
details for using this request message can be found in the Service Dictionary Search section below.
Nulls
iPay Solutions requires an explicit declaration of a null value in order to specify when an element needs to be
modified to a null value, and therefore not modify an existing element if this null value is missing.
The WC3 XML Schema standard mechanism, xsi:nil= true, can be used to explicitly assign a value of null to
an element rather than using an empty element to implicitly assign a value to null.
The use of jXchange’s JHANull attribute notifies the business service to not set (on Add) or delete (on Mod)
the specified element. JHANull must be utilized for all add and modification requests within the Bill Pay
Services API.
JHANull Attribute:
• The behavior expectation for XML elements in a modification service:
o If the element is not sent at all, is empty, or is sent as xsi:‘nil = true, this will convey to the Service
Provider (iPay Solutions) to do nothing.
o If the element is sent with JHANull=true, this will convey to the Service Provider (iPay Solutions)
to clear the stored value and set the element to a null value.
• The behavior expectation for XML elements in an addition service:
o If the element is not sent, is empty, or sent as xsi:nil=true, this will convey to the Service Provider
(iPay Solutions) to set a default value.
o If the element is sent with JHANull=true, this will convey to the Service Provider (iPay Solutions)
to set the element to a null value.
• The behavior expectation for deleting XML elements in an array in a modification service:
o If the array element is not sent, is empty, or sent as xsi:nil=true, this will convey to the Service
Provider (iPay Solutions) to do nothing.
Bill Pay Services API – User Guide
iPay Solutions™
20
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
o If the array element key identifier is sent with JHANull=true, this will convey to the Service
Provider (iPay Solutions) to set the entire array item to null values (i.e., delete the array item).
o If a [non-key] element of the array item is sent with JHANull=true, this will convey to the Service
Provider to clear the stored value and set that element only in the array item to a null value.
o If every element in the array item is sent with JHANull=true, this will also convey to the Service
Provider to set the entire array item to null values (i.e., delete the array item).
Nillable Attribute :
The nillable attribute is used in jXchange to specify whether an element will be returned in the event there is
no value for that element. If the element is specified with the nillable attribute = true, the element will be
returned with no value (i.e., blank). If the element does not include the nillable attribute, the element will not
be returned if the value is not set or is set to null.
Rstr Attribute :
The ‘Rstr’ attribute is used in jXchange to specify the level of restriction(s) that exist at a parent or child node.
The full list of canonical values are:
• ReadWrite (default)
• ReadWritePart
• ReadOnly
• ReadOnlyPart
• NoAccess
• NoAccessPart
• Hid
iPay Solutions currently uses only the implied default (ReadWrite), as well as the ReadOnly, NoAccess and
Hid values.
• The ReadWrite value indicates there are no restrictions on the specified element.
• The ReadOnly value indicates the Service Consumer can allow the end user to view the specified
element, but updates are not allowed.
• The No Access value indicates the Service Consumer should ensure the end user has no access to the
specified element.
• The Hid value indicates the Service Consumer should ensure the specified element value is hidden from
the end user.
Search/Inquiry Behaviors
The Search/Inquiry process is a basic process in jXchange, and is how all data is retrieved:
• [object] Search – This search is performed by the Service Consumer to get a subset list of the
desired object (e.g., subscribers, payees, payments, etc.), based on client-specific search criteria.
• [object] Inquiry – Once the Service Consumer has the desired list of specific Payee(s), Payment(s),
etc., identified, they send the corresponding Inquiry message to get detailed information on an
individual payee, payment, subscriber, etc.
If the required individual identifier for an entity is already known (e.g., Subscriber ID or Payee ID), it is not
necessary to perform the search service prior to requesting the inquiry service for the given entity.
The Bill Pay Services API uses the following fault responses for search and inquiry requests:
• All search and inquiry requests will return an Error when the request contains an Identifier (e.g.,
institution, subscriber, etc.) that does not exist. The message will indicate which element is invalid
(e.g., Invalid Subscriber ID, etc.)
Bill Pay Services API – User Guide
iPay Solutions™
21
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
• All search and inquiry requests will return a Warning when the institution and/or subscriber identifiers
are valid, but the information requested (e.g., scheduled payments in a certain date range, specific
Payee Name, etc.) does not exist. The message will indicate that no records match the selection
criteria.
Searches: Record Request/Response Behaviors:
Elements are available with the <SrchMsgRqHdr> and <SrchMsgRsHdr> that pertain strictly to search
operations, and are used to control the records, as well as the number of those records that are returned to
the Service Consumer.
• Srch Request:
o MaxRec – Tells the Service Provider the maximum number of records to return in the
response. If no number, or an invalid number, is provided in the search request, the Service
Provider (iPay Solutions) will default this value to 50, and return a maximum of 50 records in
the response.
o Cursor – Tells the Service Provider at which record (as a number) to begin returning the
results. If no number, or an invalid number, is provided in the search request, the Service
Provider (iPay Solutions) will default this value to 1. (Records will be returned, starting with
the first record available.)
• Srch Response:
o SentRec – Tells the Service Consumer how many records were returned in the response
(may or may not be equal to the maximum number requested).
o MoreRec (True/False) – Tells the Service Consumer if there are more records available
than what was returned.
o Cursor – Tells the Service Consumer which record (as a number) would be next to be
returned.
o TotRec – Tells the Service Consumer the total number of records that exist in the file that
meet the criteria of the request. (It is not returned if Cursor was included with the request.)
Example:
Subscriber account 1234 has 145 transaction records that could be returned using Payment History
Search. The Service Consumer does not know how many records there are, but knows they only want to
receive 50 records at a time.
First Call Second Call Third Call
Request
Cursor = left blank
MaxRec = 50
Response
SentRec = 50
MoreRec = True
Cursor = 51
TotRec = 145
Request
Cursor = 51
MaxRec = 50
Response
SentRec = 50
MoreRec = True
Cursor = 101
TotRec is not
returned
Request
Cursor = 101
MaxRec = 50
Response
SentRec = 45
MoreRec = False
Cursor is not
returned
TotRec is not
returned
Bill Pay Services API – User Guide
iPay Solutions™
22
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Modification Behaviors
The Modification process is a basic process in jXchange, and is how all eligible data is updated or deleted.
The Activity Intention Key <ActIntentKey>, provided by the Service Provider, is required for every Mod
request. Therefore, an Inquiry request for the desired data set must always be performed prior to the
modification request in order to retrieve the Activity Intent Key necessary for modification processes.
Not all available objects and/or elements within the Bill Pay Services API are eligible for update or delete. An
element that is required can be updated, but cannot be deleted. An optional element is eligible for either
update or delete. For each Mod service operation detailed in the Business Service Operations section below,
only those elements that are eligible for update will be detailed in the Mod service operation, and each of
those elements will be designated as required or optional.
The use of JHANull is expected in a modification request to explicitly indicate whether an element is intended
to be deleted or is simply not included in the modification request.
Modification of individual elements within an array item, or update of the array item itself, must be indicated as
follows:
• If a new array item is received for an array, it will be inserted into the array.
o If a new element within an [existing] array item is received, it will be inserted into that array
item.
• If an [existing] array item is included in the modification request, and no changes to the [entire] item
are evident, no updates will be made to that item in the existing array.
• If an [existing] array item is included in the modification request, and one or more changes are noted
for individual elements within the array item, updates will be made to only those elements.
• If an [existing] array item is received that indicates a delete of an element within the array item, or
delete of the array item itself, the use of JHANull is expected in order to explicitly indicate the delete
intent.
• If an [existing] array item is not explicitly specified in the modification request, no updates will be
made to that array item.
NOTE: jXchange’s concurrency model is not currently supported within the Bill Pay Services API. However,
the Activity Intent Key will be provided by iPay Solutions in response to every Inquiry request that is intended
for other than read-only activity.
Localization/Time Zones
The Bill Pay Services API services are localized services, based on the English culture (IETF language tag:
en-US) and the Eastern time zone.
Handling Time Zones
Since the time zone of the service consumer or end user may differ from the Bill Pay Services API localized
time zone (Eastern), all time elements included in the service operations are required to be converted to
Universal Time Coordinates (UTC) – formerly known as Greenwich Mean Time, or GMT– in order to
neutralize these time zone differences.
For example, a Service Consumer’s Bill Pay application might allow an end user to select their desired time
zone. Any service transactions originated in the chosen time zone must be converted to UTC before the
request message is sent. For example:
Bill Pay Services API – User Guide
iPay Solutions™
23
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
1. Subscriber picks Central time zone and 9 a.m.
2. Service Consumer converts to UTC (9 a.m. + 6 hours =1500 UTC) and sends request message
3. Service Provider in Eastern time zone converts UTC time to local time zone (1500 – 5 hrs = 10 a.m.)
To convert local time to UTC time, you will need to add hours to the local time to get the UTC. To convert
UTC to local time, these hours must be subtracted from UTC. The following is a table showing the time
adjustments required for both Standard Time and Daylight Saving:
Table 1 – UTC Time Adjustments
Local Time Zone
Add or Subtract from UTC:
Standard
Daylight
Atlantic
Four hours
Three hours
Eastern
Five hours
Four hours
Central
Six hours
Five hours
Mountain
Seven hours
Six hours
Pacific
Eight hours
Seven hours
Alaskan
Nine hours
Eight hours
Hawaiian
Ten hours
Not observed
NOTE: Some servers are configured to auto-adjust any received timestamps to the time zone that is local to
the server. If your server is configured to perform this action, your local offset from the Eastern time zone
must be taken into account when converting UTC to local time.
Deprecation Policy
Deprecation is the future removal of XSD object(s). Objects to be deprecated are clearly marked as obsolete
to warn consumers and providers that the object will be phased out. The features of deprecation provide
backwards compatibility and give consumers time to bring affected code into compliance with the new
standard.
Elements scheduled for deprecation will remain in use for at least three (3) years from the time of the XSD
contract change. Any element(s) scheduled for deprecation will be clearly annotated in the XSD contracts, as
well as this User Guide. The date of the scheduled deprecation will also be noted.
Bill Pay Services API – User Guide
iPay Solutions™
24
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Business Service Operations
The Bill Pay Services API supports messaging for the following Business service operations:
Table 2 – Bill Pay Services Operations List
Service Operation
Description
Institution
Service Dictionary Search
<SvcDictSrchRq_MType>
Allows a client to request closed- and open-enumerated
canonical element values based on client-specified dictionary
criteria, as well as fault codes by service operation.
Channel Inquiry
<BilPayChanInq>
Allows a client to retrieve general reference information for the
FI and its Bill Pay services.
Subscriber
Subscriber Lookup
<BilPaySubConsmCustInq>
Allows a client to retrieve the iPay Solutions subscriber ID for a
specific subscriber.
Subscriber Add
<BilPaySubAdd>
Allows a client to add (enroll) a new subscriber
Subscriber Search
<BilPaySubSrch>
Allows a client to retrieve reference information for subscribers
meeting client-specified search criteria.
Subscriber Inquiry
<BilPaySubInq>
Allows a client to retrieve current information about a specific
subscriber’s profile, including all available Pay-FroFA
information.
Subscriber Modification
<BilPaySubMod>
Allows a client to modify/change fields within a subscriber’s
profile.
Bill Pay Services API – User Guide
iPay Solutions™
25
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Payee
Payee Add
<BilPayPayeeAdd>
Allows a client to add a new Payee for a subscriber.
Payee Search
<BilPayPayeeSrch>
Allows a client to retrieve a list of Payees for a subscriber
based on client-specified search criteria.
Payee Inquiry
<BilPayPayeeInq>
Allows a client to retrieve current information about a specific
Payee for a subscriber.
Payee Modification
<BilPayPayeeMod>
Allows a client to modify/change fields for a specific Payee, or
delete a specific Payee for a subscriber.
Payment
Payment Add
<BilPaySchedPmtAdd>
Allows a client to schedule a single or recurring payment for a
subscriber.
Scheduled Payment Search
<BilPaySchedPmtSrch>
Allows a client to retrieve Scheduled Payment information for a
subscriber based on client-specified search criteria.
Scheduled Payment Inquiry
<BilPaySchedPmtInq>
Allows a client to retrieve current information about a specific
scheduled payment for a subscriber.
Scheduled Payment Modification
<BilPaySchedPmtMod>
Allows a client to modify/change fields for a specific Scheduled
Payment, or stop a Scheduled Payment for a subscriber.
Scheduled Payment Approval
<BilPaySchedPmtApprv>
Allows a client to provide a payment approval from an
authorized approver for a scheduled payment that requires
additional approval.
Payment History Search
<BilPayPmtHistSrch>
Allows a client to retrieve Payment History information for a
subscriber based on client-specified search criteria.
Payment History Inquiry
<BilPayPmtHistInq>
Allows a client to retrieve current information about a specific
processed payment for a subscriber.
eBills
eBill [History] Search
<BilPayElecBilSchedSrch>
Allows a client to retrieve current and historical information
about eBills for a subscriber (for one or multiple Payees).
eBill Inquiry
<BilPayElecBilSchedInq>
Allows a client to retrieve information about a specific eBill for
a subscriber’s Payee.
eBill Modification
<BilPayElecBilSchedMod>
Allows a client to file a specific eBill for a subscriber’s Payee.
Bill Pay Services API – User Guide
iPay Solutions™
26
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Business Service Operations – Updates
Release 2012.0.01 – Initial release
o The following messages were created for Subscriber Lookup service:
▪ BilPaySubConsmCustInqRq_MType
▪ BilPaySubConsmCustInqRs_MType
o The following subscriber identifier elements added to BilPaySubInfo complex, associated with
SubInq, SubMod and [future] SubAdd services:
▪ SubConsmCustId
▪ SubComId
o Remove ability to add new MobProvdCode, eliminating need for MobProvDom element (SubInq;
SubMod services)
o The following service operations were revised to remove account masking requirements for service
responses:
▪ Subscriber Inquiry
▪ Payee Search
▪ Payee Inquiry
▪ Scheduled Payment Search
▪ Scheduled Payment Inquiry
▪ Payment History Search
▪ Payment History Inquiry
The following service operations were updated to reflect the corrected definition of the PayeePmtMthd
element:
▪ Payee Search
▪ Payee Inquiry
Release 2012.0.02 – (06.01.2013)
o New service operation added to the available list of Business Service Operations
▪ Subscriber Add
o The following service operation was updated to include the PayeeEmailSharedSecret element in
the response:
▪ Payee Inquiry
o The following service operation was updated to clarify that Payee Address is an optional entry for
Email Payees:
▪ Payee Add
Bill Pay Services API – User Guide
iPay Solutions™
27
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
o The following service operation was updated to include the newly added ability to edit the [Primary]
Payee Address:
▪ Payee Modification
o The following service operations were updated to include the newly added ability to schedule and
manage a recurring payment series, as well as view recurring series information:
▪ Scheduled Payment Add
▪ Scheduled Payment Inquiry
▪ Scheduled Payment Mod
▪ Payment History Inquiry
o The following service operations were updated to reflect the corrected element name for the Date
Range filter option (by Process Date or Due Date), as well as the inclusion of two new elements
and new search filter options to support Recurring Payments:
▪ Scheduled Payments Search
▪ Payment History Search
o The following service operation was updated to include two new elements to provide information on
Electronic Risk Limits,as well as several new elements needed to assist in the Subscriber Add
process:
▪ Channel Inquiry
o The following service operation was updated to include a new value within the SvcDictName
element needed to request dictionary information for the new Subscriber Add process:
▪ Service Dictionary Search
o The following service operations were updated to include new elements, including funding account
elements, needed to assist in the Subscriber Add and ongoing subscriber management processes:
▪ Subscriber Inquiry
▪ Subscriber Mod
▪ Payee Search
▪ Payee Inquiry
▪ Scheduled Payment Search
▪ Scheduled Payment Inquiry
▪ Payment History Search
▪ Payment History Inquiry
Release 2013.1.00 – (10.15.2013)
o New service operation added to the available list of Business Service Operations
▪ BilPaySchedPmtApprv
o The following service operation was updated to include new product configuration elements to
support Business Subscribers, where applicable:
▪ Channel Inquiry
o The following service operations were updated to include new elements needed to assist in the
Subscriber Add and ongoing subscriber management processes for Business subscribers,
including funding account (‘pay from account’) owner information, as well as adding and/or
managing multiple users – i.e., subscriber’s associated users – within the Business subscriber’s
account:
▪ Subscriber Add
▪ Subscriber Search
Bill Pay Services API – User Guide
iPay Solutions™
28
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
▪ Subscriber Inquiry
▪ Subscriber Mod
▪ Payee Search
▪ Payee Inquiry
▪ Scheduled Payment Search
▪ Scheduled Payment Inquiry
▪ Payment History Search
▪ Payment History Inquiry
o The following service operations were updated to add new RetroToOrigPmtDt and InvoiceInfoArray
information into the BilPayPmtInfo complex element:
▪ Scheduled Payment Add
▪ Scheduled Payment Inquiry
▪ Scheduled Payment Mod
▪ Payment History Inquiry
o The following service operations were updated to reflect the correct canonical value for the
PmtMthd element (from Elect to Elec):
▪ Payee Search – PayeePmtMthd
▪ Payee Inquiry – PayeePmtMthd
▪ Scheduled Payment Search – PayeePmtMthd & PmtMthd
▪ Scheduled Payment Inquiry – PayeePmtMthd & PmtMthd
▪ Payment History Search – PayeePmtMthd & PmtMthd
▪ Payment History Inquiry – PayeePmtMthd & PmtMthd
o The following service operations were updated to reflect the correct canonical value for the
PayeeClsf element (from Indiv to Indv):
▪ Payee Add
▪ Payee Search
▪ Payee Inquiry
▪ Scheduled Payment Inquiry
▪ Payment History Inquiry
o The following service operation was updated to include a new value within the SvcDictName
element needed to request dictionary information for the new Scheduled Payment Approval
process, as well as two new open enumerated elements:
▪ Service Dictionary Search
o Two new canonical values have been added to the PmtStat element to support Business
subscribers who require payment approval for scheduled payments:
▪ PmtApprvReq – Payment Approval Required
• Added to Scheduled Payment Search, Scheduled Payment Inquiry
▪ PmtApprv – Payment Approved (for processed payment that required Payment Approval)
• Added to Payment History Search, Payment History Inquiry
Release 2013.1.03 – (07.07.2014)
o This version to be used in conjunction with jXchange XSD release version R2013.1.03_XSD.
Bill Pay Services API – User Guide
iPay Solutions™
29
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
o The following service operation was updated to include a new element (AlwSubType) to provide
information about what subscriber types are allowed for the listed product:
▪ Channel Inquiry
o The following service operations were updated to reflect the corrected element name for
PmtApprvReq (initially listed incorrectly as PmtApprvReqd):
▪ BilPaySubAdd
▪ BilPaySubInq
▪ BilPaySubMod
o The following service operations were updated to accurately reflect the element name associated
with the Secondary Account Holder Name (AddlName vs. PersonName) within the
SecdPersonArray array:
▪ BilPaySubAdd
▪ BilPaySubInq
▪ BilPaySubMod
o The following service operations were updated to correct the canonical value for the
PmtDayofWeek element (from Thurs to Thur) within the RecurPmtInfo complex:
▪ BilPaySchedPmtAdd
▪ BilPaySchedPmtInq
▪ BilPaySchedPmtMod
▪ BilPayPmtHistInq
Release 2014.0.01 – (07.31.2014)
o This version to be used in conjunction with jXchange XSD release version R2014.0.01_XSD.
o The following service operation was updated to include PhoneType, SvcFeeDesc and
ElecMerAcctType in the list of open enums which can be requested:
▪ SvcDictSrch
o The following service operation was updated to include an additional Note for the TempPswd
element:
▪ BilPaySubAdd
o The following service operations were updated to clarify the value returned for the SubMerAcctId
element within the BilPayPayeeInfo complex when no Payee Account ID exists for the subscriber:
▪ BilPayPayeeAdd
▪ BilPayPayeeInq
▪ BilPaySchedPmtInq
▪ BilPayPmtHistInq
o The following service operations were updated to clarify the rules for allowing Payee FI Account
Information to be added:
▪ BilPayPayeeAdd
▪ BilPayPayeeMod
o The following service operation was updated to indicate the rule change regarding Payment Adds
for non-activated Payees (no longer allowed):
Bill Pay Services API – User Guide
iPay Solutions™
30
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
▪ BilPaySchedPmtAdd
o The following service operations were updated to correct PmtStartDt details to denote that this will
always be based on Process Date, regardless of Payment Date model:
▪ BilPaySchedPmtSrch
▪ BilPayPmtHistSrch
o The following service operations were updated to include new elements needed to support
Payment Service Fee functionality, where applicable:
▪ BilPayPayeeInq
▪ BilPaySchedPmtInq
▪ BilPayPmtHistInq
o The following service operations were updated to include new elements needed to support
eBills/Bill Presentment functionality:
▪ SvcDictSrch
▪ BilPayChanInq
▪ BilPayPayeeSrch
▪ BilPayPayeeInq
▪ BilPayPayeeMod
▪ BilPaySchedPmtSrch
▪ BilPaySchedPmtInq
▪ BilPayPmtHistSrch
▪ BilPayPmtHistInq
o New service operations added to the available list of Business Service Operations to support
eBills/Bill Presentment functionality:
▪ BilPayElecBillSchedSrch
▪ BilPayElecBillSchedInq
▪ BilPayElecBillSchedMod
Release 2014.0.06 – (03.31.2015)
o This version to be used in conjunction with jXchange XSD release version R2014.0.06_XSD.
o The following service operation was updated to include FirstAvlProcDt, FirstAvlEstArvDt and
EstArvDay elements in the response message:
▪ BilPayPayeeSrch
o The following service operations were updated to correct the definition of the NotAct canonical
value for the PayeeStat element:
▪ BilPayPayeeSrch
▪ BilPayPayeeInq
o The following service operation was updated to include the missed element SubModMerAcctId:
▪ BilPayPayeeInq
o The following service operation was updated to include additional Notes for the Payee PhoneNum
and EmailAddr elements:
▪ BilPayPayeeAdd
Bill Pay Services API – User Guide
iPay Solutions™
31
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
o The following service operation was updated to correct the element name under the eBill Account
Set up instructions:
▪ BilPayPayeeMod
o The following service operation was updated to include additional instructions for designating a
default funding account in the Subscriber Add Behaviors section:
▪ BilPaySubAdd
o The following service operations wer updated to clarify the example for accepted values for the
PmtDayofMonth element within the PmtDayInfoArray :
▪ BilPaySchedPmtAdd
▪ BilPaySchedPmtInq
▪ BilPaySchedPmtMod
▪ BilPayPmtHistInq
Release 2014.0.08 – (06.15.2015)
o This version to be used in conjunction with jXchange XSD release version R2014.0.08_XSD.
o The following service operations were updated to include SubCmntToPayee element in the request
and/or response messages:
▪ BilPaySchedPmtAdd (request and response)
▪ BilPaySchedPmtInq (response message only)
▪ BilPaySchedPmtMod (request and response)
▪ BilPayPmtHistInq (response message only)
o The following service operation was updated to include ElecBilPayeeAcctId element in the request
message:
▪ BilPayElecBilSchedSrch
o The following service operation was updated to include ElecBilPayeeAcctId, CurBal and
MinPmtAmt elements in the response message:
▪ BilPayElecBilSchedSrch
o The following service operation was updated to include ElecBilPayeeAcctId element in the
response message:
▪ BilPayElecBilSchedInq
o The following service operation was updated to include additional Note regarding the possibility that
no active funding accounts may exist for an active subscriber:
▪ BilPaySubscriberInq
o The following service operations were updated to include Note regarding the AuthenQuesDesc
element being returned as a CDATA section, as it may contain HTML and other non-permitted XML
characters:
▪ BilPayPayeeInq
▪ BilPayPayeeMod
Bill Pay Services API – User Guide
iPay Solutions™
32
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Release 2015.0.01 – (08.12.2015)
o This version to be used in conjunction with jXchange XSD release version R2015.0.01_XSD.
o The following service operation was updated to include the new XferToSubFinInst canonical value
for the FeturType element:
▪ BilPayChanInq (response)
o The following service operations were updated to include the new FinInst canonical value for the
PayeeClsf element:
▪ BilPayPayeeAdd (request)
▪ BilPayPayeeSrch (response)
▪ BilPayPayeeInq (response)
▪ BilPaySchedPmtInq (response)
▪ BilPayPmtHistInq (response)
o The following service operations were updated to include PmtIntentType element (for the Payee, as
well as for the Payment) in the request and/or response messages:
▪ BilPayPayeeAdd
▪ BilPayPayeeSrch
▪ BilPayPayeeInquiry
▪ BilPayPayeeMod
▪ BilPaySchedPmtAdd
▪ BilPaySchedPmtSrch
▪ BilPaySchedPmtInq
▪ BilPaySchedPmtMod
▪ BilPayPmtHistSrch
▪ BilPayPmtHistInq
o The following service operation was updated to include SubMerAcctID element in the response
message:
▪ BilPayPayeeSrch
o The following service operations were updated to include add and /or mod behaviors for Outbound
Transfer Payees and Payments:
▪ BilPayPayeeAdd
▪ BilPayPayeeMod
▪ BilPaySchedPmtAdd
▪ BilPaySchedPmtMod
Release 2015.0.03 – (11.02.2015)
o This version to be used in conjunction with jXchange XSD release version R2015.0.03_XSD.
o The following service operation was updated to include additional filter criteria (PayFromAcctId,
TaxId, EmailAddr, PostalCode) in the request and response messages:
▪ BilPaySubSrch
o The following service operation was updated to include additional identifying elements (funding
account information, TaxId, EmailAddr (array), BirthDt) in the response message:
▪ BilPaySubSrch
o The following service operation was updated to include BirthDt element in the response message:
Bill Pay Services API – User Guide
iPay Solutions™
33
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
▪ BilPaySubInquiry
o The following service operations were updated to include new Note regarding retrieval of Payee
information for Business subscribers on behalf of sub users with limited Payee permissions:
▪ BilPayPayeeSrch
▪ BilPaySubInq
o The following service operation was updated to include new Note regarding Service Consumer’s
need to support the display (and user entry) of a variable number of login credential attributes for
eBill accounts:
▪ BilPayPayeeInq
Release 2015.0.06 – (02.01.2016)
o This version to be used in conjunction with jXchange XSD release version R2015.0.06_XSD.
o The following service operations were updated to include new elements (<SubStat>,
<SubInActRsnType>) within the <BilPaySubInfo_CType> complex to enable a Consumer to
deactivate or reactivate a subscriber’s status:
▪ BilPaySubInq (response)
▪ BilPaySubMod (request)
o The following service operation was updated to indicate the <SubStat> element encapsulated by
the Bill Pay Subscriber Inquiry Response (<BilPaySubInqRs_MType>) has been scheduled for
deprecation:
▪ BilPaySubInq (response)
o The following service operation was updated to include a new canonical value for the <SubStat>
search filter parameter to enable return of deactivated subscribers who are eligible for reactivation:
▪ BilPaySubSrch (request)
o The following service operation was updated to include the <SubStat> element in to determine a
subscriber’s status (required to determine if a deactivated subscriber is eligible for reactivation):
▪ BilPaySubConsmCustInq (response)
o The following service operation was updated to include additional detail around <TempPswd> set-
up requirements:
▪ BilPaySubAdd
o The following service operations were updated to include information about evaluation of the
<Rstr> attribute for the <PayeeName> and Payee <PhoneNumber> elements:
▪ BilPayPayeeInquiry
▪ BilPayPayeeMod
o The following service operations were updated to include additional information about the default
sort order applied to search results returned in the response:
▪ BilPayPayeeSrch
▪ BilPaySchedPaymentSrch
▪ BilPayPaymentHistSrch
o The following service operation was updated to include additional information on the value needed
in the <FutPmtId> element to specify that changes should be applied to the currently scheduled
payment in a recurring series only:
▪ SchedPmtMod (request)
Bill Pay Services API – User Guide
iPay Solutions™
34
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Release 2016.0.01 – (06.03.2016)
o This version to be used in conjunction with jXchange XSD release version R2016.0.01 XSD.
o The following service operation was updated to include new array (<RushOptArray>) within the
<BilPayPayeeSrchInfo_CType> complex to enable a Consumer to view Rush Options (if available)
for a Payee without requiring a Payee Inquiry:
▪ BilPayPayeeSrch (response)
Release 2016.0.09 – (01.30.2017)
o This version to be used in conjunction with jXchange XSD release version R2016.0.09 XSD.
o The following service operations were updated to include new element <PayeeP2PType> within the
<BilPayPayeeInfo_CType> complex to enable a Consumer to select the desired communication
method with the P2P recipient:
▪ BilPayPayeeAdd (request)
▪ BilPayPayeeInquiry (response)
▪ BilPayPayeeMod (request)
o The following service operations were updated to include the new SMS canonical value for
<PhoneType> within the <PayeePhoneArray> to enable a Consumer to specify a SMS (Mobile)
number for Individual Payees.
▪ BilPayPayeeAdd (request)
▪ BilPayPayeeInquiry (response)
▪ BilPayPayeeMod (request)
▪ BilPaySchedPmtInq (response)
▪ BilPayPmtHistInq (response)
o The following service operation was updated to include new Payee Add Behaviors guidance on
adding a P2P Payee and designating the desired communication method (Email or SMS):
▪ BilPayPayeeAdd (request)
Release 2017.0.02 – (05.31.2017)
o This version to be used in conjunction with jXchange XSD release version R2017.0.02 XSD.
o The following service operation was updated to include new element <LastMainDt> within the
<BilPayPayeeInfo_CType> complex to enable a Service Consumer to determine the last date a
Payee was modified:
▪ BilPayPayeeInquiry (response)
o The following service operation was updated to include new element <LastMainDt> within the
<BilPayPayeeSrchInfo_CType> complex to enable a Service Consumer to determine the last date
a Payee was modified:
▪ BilPayPayeeSrch (response)
o The following service operation was updated to include additional filter criteria (LastMainStartDt,
LastMainEndDt) in the request and response messages:
▪ BilPayPayeeSrch
Bill Pay Services API – User Guide
iPay Solutions™
35
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
o The following service operation was updated to include instructions about evaluation of the <Rstr>
attribute for the <PayeeName> element:
▪ BilPayPayeeSrch (response)
Release 2017.2.01 – (08.07.2017)
o This version to be used in conjunction with jXchange XSD release version R2017.2.01 XSD.
o The following service operations were updated to include a new rule making completion of the
<PayeeAddress> within the <BilPayPayeeInfo_CType> complex optional for Individual, Electronic
Payees:
▪ BilPayPayeeAdd (request)
▪ BilPayPayeeMod (request)
o The following service operations were updated to clarify the Service Provider’s handling of ongoing
eBill activity when acceptance of a new eBiller Terms of Service is required for an existing eBill
account (<ElecMerPayeeToSStat> within the <ElecMerPayeeInfoRec_CType> complex):
▪ BilPayPayeeInq (response)
▪ BilPayPayeeMod (request)
o The following service operations were updated to updated to include the new EnrollPend canonical
value for <ElecBilPayeeType> within the <BilPayPayeeSrchInfo_CType> and
<BilPayPayeeInfo_CType> complexes to indicate a requested eBill registration is being processed,
but not yet complete:
▪ BilPayPayeeSrch (response)
▪ BilPayPayeeInq (response)
o The following service operations were updated to updated to include a new element
<ElecBilPayeeCatType> within the <BilPayPayeeSrchInfo_CType> and <BilPayPayeeInfo_CType)
complexes to indicate the level of eBill detail information that is available for the eBill account:
▪ BilPayPayeeSrch (response)
▪ BilPayPayeeInq (response)
Release 2017.2.03 – (10.27.2017)
o This version to be used in conjunction with jXchange XSD release version R2017.2.03 XSD.
o The following service operation was updated to include new elements <MobDevType>,
<MobDevResoType> and <Orientation> in the root level request (to provide needed mobile device
information so that the correct sizing of media can be delivered for the eBill detail); plus a new
element <WebPgURL> within the <BilPayElecBilSchedInqInfo> complex of the response (provides
the URL to view full electronic eBill statement and detail for a given eBill):
▪ BilPayElecBilSchedInq (request/response)
Release 2017.4.01 – (02.01.2018)
o This version to be used in conjunction with jXchange XSD release version R2017.4.01 XSD.
o The following service operation was updated to include new elements <MaxIndvPmtAmt> and
<MaxIndvDlyAmt> in the BilPayProdTypeInfo complex to provide information about new payment
caps for Individual Payees:
▪ BilPayChanInq (response)
Bill Pay Services API – User Guide
iPay Solutions™
36
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
o The following service operation was updated to include new elements <WebPgURLNoToken>,
<WebPgToken> and <TokenExpTimeDt> in a new ‘Ver_3’ complex element in the root level
response (to provide an alternate version of the WebPgURL that does NOT include an embedded
security token, but rather sends it separately) within the <BilPayElecBilSchedInqInfo> complex of
the response:
▪ BilPayElecBilSchedInq (response)
Release 2017.4.04 – (04.03.2018)
o This version to be used in conjunction with jXchange XSD release version R2017.4.04 XSD.
o The following service operations were updated to include the new EnrollAlw canonical value for
<ElecBilPayeeType> within the <BilPayPayeeSrchInfo_CType> and <BilPayPayeeInfo_CType>
complexes to indicate a Payee currently registered for eBills (summary information) is eligible for
detailed eBill information (subject to re-enrollment by the Subscriber):
▪ BilPayPayeeSrch (response)
▪ BilPayPayeeInq (response)
o The following service operations were updated to include the new AdminFraudAct canonical value
for <SubInActRsnType>) within the <BilPaySubInfo_CType> complex to enable a Consumer to
indicate the reason for Subscriber account deactivation is due to potential or confirmed fraudulent
activity:
▪ BilPaySubInq (response)
▪ BilPaySubMod (request)
Release 2018.6.01 – (02.21.2019)
o This version to be used in conjunction with jXchange XSD release version R2018.6.01.
o The following service operation was updated to include the new <PaybyCard> canonical value for
the FeturType element:
▪ BilPayChanInq (response)
o The following service operation was updated to include the new <AlwCardFundedType> element
to indicate if the allows card funded payments:
▪ BilPayPayeeInq (response) – within the root response
o The following service operation was updated to include a new optional
<x_CardFundedPayeeArray> array which encapsulates the new <CardFundedPayeeInfo_CType>
complex that includes the Payee’s (biller’s) URL for the card funded payment:
▪ BilPayPayeeInq (request and response)
Release 2018.7.04 – (06.03.2019)
o This version is to be used in conjunction with jXChange XSD release version R2018.7.04
o The following service operation was updated to include additional filter criteria (CardPayFilter) in
the request and response messages:
▪ BilPayPayeeSrch
Bill Pay Services API – User Guide
iPay Solutions™
37
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Release 2018.7.07 – (09.11.2019)
o This version is to be used in conjunction with jXChange XSD release version R2018.7.07
o The following service operation was updated to include additional filter criteria (CardPayFilter) in
the request and response messages:
▪ BilPayPmtHistSrch
Business Service Operations – General Behaviors
The jXchange messaging structures and protocols for general utilization of jXchange web services are
provided in the documentation included in the Vendor Packet. The Service Consumer is expected to adhere
to these messaging structures and protocols for all Bill Pay Services API service operations.
The service operation information that follows provides detailed information about expected behaviors
specific to each iPay Solutions Bill Pay Service API business service operation. As such, this document
addresses only those elements and/or protocols that are required for use within the Bill Pay Services API. It
can be assumed that any elements that exist in a given message schema that are not referenced in this
document are not required within the Bill Pay Services API services.
For all elements with closed enumerated canonical values of True and False, the default value will always be
False.
Bill Pay Services API – User Guide
iPay Solutions™
38
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Institution Services
Service Dictionary Search
Container: TPG_CustomerMaster.xsd
Message: SvcDictSrch
The Service Dictionary Search is a jXchange messaging service designed to provide the Service Consumer
with a service that can convey a Service Provider's elements, XSD path, requirements, default values, open
and closed enumerated canonical values, help/knowledge content, and fault codes per operation.
The Service Dictionary service is covered in detail in the jXchange Service Dictionary Service document
included in the Vendor Packet.
iPay Solutions’ Bill Pay Services API supports Service Dictionary search requests for the following:
• Closed enumerated canonical values (available for all closed enumerated elements)
• Open enumerated canonical values (limited to specific elements)
• Fault codes per [service] operation (Service Provider Error Array)
The elements at the root request message will be echoed back at the root response, regardless if those same
elements exist in the repeating complex.
Message Flow
Message flow involves the exchange of MType messages between the third-party consumer and the Service
Provider.
Request
The third-party consumer forwards the SvcDictSrchRq_MType request message containing:
• SvcDictName (Required)
• SvcDictType (Required)
• ElemName (Optional)
• SvcDictFilterArray (Optional)
• IncXtendElemArray (Not currently utilized by Bill Pay Services API)
The SvcDictSrchRq request message requires valid SvcDictName and SvcDictType elements. The simple
elements contained within the SvcDictSrchRq message request are listed below. They are a part of a
documented filter statement. Any or all of the following simple elements can be sent.
Bill Pay Services API – User Guide
iPay Solutions™
39
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
SvcDictName
This represents the operations that can be queried to obtain data dictionary definitions. The service
operations that are applicable to the Bill Pay Services API are:
• BilPayPayeeSrch
• BilPayPayeeInq
• BilPayPayeeAdd
• BilPayPayeeMod
• BilPaySchedPmtSrch
• BilPaySchedPmtInq
• BilPaySchedPmtAdd
• BilPaySchedPmtMod
• BilPaySchedPmtApprv
• BilPayPmtHistSrch
• BilPayPmtHistInq
• BilPaySubSrch
• BilPaySubInq
• BilPaySubAdd
• BilPaySubMod
• BilPaySubConsmCustInq
• BilPayChanInq
• BilPayElecBilSchedSrch
• BilPayElecBilSchedInq
• BilPayElecBilSchedMod
The SvcDictName must be specified to receive the list of enumerated canonical values for the desired
service operation. The ability to receive a global list of enumerated values for all elements within the Bill
Pay Services API by leaving the SvcDictName filter blank is not available.
SvcDictType
This represents the desired service dictionary operation type. Canonical values are:
• Request ~Rq~
• Response ~Rs~
If the value is set to “Rq,” the response message will return the enumerated (open and closed) values
required for the Service Consumer’s request specified by the SvcDictName. If the value is set to “Rs,” the
response message will return the enumerated (open and closed) values that would be returned in the
Service Provider’s response message specified by the SvcDictName.
NOTES:
1) Enumerated elements with True/False values will not be returned, as these are covered in the
Business Service Operations section below.
a. All enumerated True/False elements will default to False if not specified in the request.
2) Error values would not be sent if the SvcDictName is set to “Rs” (Response), as errors are applicable
only to service requests.
ElemName
The request also includes the optional simple element ElemName, so a consumer could query for the
canonical values as related to a specific element. Canonical values can be requested for all closed
enumerated elements required for the Bill Pay Services API.
Bill Pay Services API – User Guide
iPay Solutions™
40
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
The open enumerated elements available within the Bill Pay Services API are:
• MobPrvdCode
This is the list of mobile phone providers available within the Bill Pay Services API. It is located in
the BilPaySubAdd, BilPaySubInq and BilPaySubMod service operations.
• PerCode
This is the list of permissions that may be applied to subscriber’s associated users. It is located in
the BilPaySubAdd, BilPaySubInq and BilPaySubMod service operations.
• CapCode
This is the list of payment caps that may be applied to a subscriber’s associated users. It is
located in the BilPaySubAdd, BilPaySubInq and BilPaySubMod service operations.
• PhoneType
This is the list of phone types supported within the Bill Pay Services API. It is located in the
BilPayPayeeAdd, BilPayPayeeInq, BilPaySubSrch, BillPaySubAdd, BilPaySubInq,
BilPaySubMod, BilPaySchedPmtInq and BilPayPmtHistInq service operations.
• SvcFeeDesc
This is the list of payment-level service fee types supported within the Bill Pay Services API. It is
located in the BilPayPayeeInq, BilPaySchedPmtInq and BilPayPmtHistInq service operations.
• ElecMerAcctType
This is the list of eBiller account types (returned as a matched pair value including code and
corresponding description) supported within the Bill Pay Services API. It is located in the
BilPayPayeeInq and BilPayeeMod service operations.
Array(s)
SvcDictFilterArray
The request also includes the optional array SvcDictFilterArray, containing the SvcDictFilterInfo complex
element, which includes the SvcDictFilterCode and SvcDictFilterVal elements. These two simple
elements present a matched pair that provides canonical value(s) that allow a consumer to restrict a
query for specific values that have a correlation to an operation.
The only SvcDictFilterCode values currently supported for the Bill Pay Services API are:
• <BilPaySubInq>MobPrvdCode
• <BilPaySubMod>MobPrvdCode
Use of these Filter Codes limits the result set to the supporting information for the MobPrvdCode element
only.
IncXtendElemArray
The optional IncXtendElemArray array lists the x_ elements by name which are to be included in the
response. This array is required if the consumer would like to have the Service Provider's Field
Information or Service Provider Error Array returned for a specific element.
Bill Pay Services API – User Guide
iPay Solutions™
41
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Response
The Service Provider (iPay Solutions) returns the SvcDictSrchRs response message to the service consumer,
which returns the following:
• Closed enumerated canonical values (available for all closed enumerated elements)
• Open enumerated canonical values (limited to specific elements)
• Fault codes per operation (Service Provider Error Array)
The arrays within the SvcDictSrchRs response message applicable for the Bill Pay Services API are:
x_SvcPrvdErrArray
The x_SvcPrvdErrArray array included at the root response level provides the consumer with all the
fault/errors that can exist for the named SvcDictName submitted in the request. This root-level array
of errors will be provided with every SvcDictSrchRs message returned by the Bill Pay Services API.
SvcDictInfoArray
This array provides dictionary information for the named service (SvcDictName) and includes the
SvcDictInfoRec complex, which contains dictionary information for each enumerated element in the
service. The Bill Pay Services API returns the following for each enumerated element in this array:
ElemName
This is the name provided to the specified element.
ElemCanocType
This is the Service Provider’s canonical type for the specified element. Canonical values are:
• Open
• Closed
• NA
ElemCanocArray
This array includes the ElemCanocRec for each element, which provides the list of canonical
values and corresponding descriptions.
ElemCanocVal
This is the canonical value for the specific element.
ElemCanocValDesc
This is the description of the canonical value for the specific element.
CanocValInfoArray
This optional array includes additional information, if applicable, for each canonical
value and includes the following complex element:
CanocValInfo
CanocValDetail
The Service Provider’s pertinent details related to the canonical value.
CanocValText
Any text related to the canonical value.
An example response for a request for open-enumerated PerCode values might be:
<SvcDictInfoArray>
<SvcDictInfoRec>
Bill Pay Services API – User Guide
iPay Solutions™
42
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
<ElemName>PerCode</ElemName>
<ElemCanocType>Open</ElemCanocType>
<ElemCanocArray>
<ElemCanocRec> (1)
<ElemCanocVal>CanScheduleBillPayments
<ElemCanocValDesc>This subscriber's associated user can or cannot schedule
bill payments
<CanocValInfoArray>
<CanocValInfo>
<CanocValDetail>True
<CanonValTxt>True
<CanocValInfo>
<CanocValDetail>False
<CanonValTxt>False
</ElemCanocRec>
The SvcDictInfoRec also includes an x_SvcPrvdErrArray for the named element. However, the Bill
Pay Services API will not be returning errors at the element level.
The elements within the Bill Pay Services API that currently include an open enumerated list of canonical
values are:
• MobPrvdCode The list of mobile providers available within the Bill Pay Services API, located in the
BilPaySubInq and BilPaySubMod service operations.
• PerCode The list of permissions that may be applied to subscriber’s associated users, located in the
BilPaySubAdd, BilPaySubInq and BilPaySubMod service operations.
• CapCode The list of payment caps that may be applied to subscriber’s associated users, located in
the BilPaySubAdd, BilPaySubInq and BilPaySubMod service operations.
• Phone Type The list of phone types supported within the Bill Pay Services API, located in the
BilPayPayeeAdd, BilPayPayeeInq, BilPaySubSrch, BillPaySubAdd, BilPaySubInq, BilPaySubMod,
BilPaySchedPmtInq and BilPayPmtHistInq service operations.
• SvcFeeDesc The list of Payment-level Service Fee types supported within the Bill Pay Services API,
located in the BilPayPayeeInq, BilPaySchedPmtInq and BilPayPmtHistInq service operations.
• ElecMerAcctType The list of eBiller account types, returned as a matched pair value including both
code and corresponding description, supported within the Bill Pay Services API. Located in the
BilPayPayeeInq and BilPayPayeeMod service operations.
Bill Pay Services API – User Guide
iPay Solutions™
43
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Channel Inquiry
Container: TPG_BillPayMaster.xsd
Message: BilPayChanInq
Channel Inquiry <BilPayChanInq> is a Bill Pay Services API service designed to allow a consumer to retrieve
reference information about a specific FI, as well as information about available Bill Pay Service API
operations and supporting information specific to that Institution.
The elements at the root request message will be echoed back at the root response, regardless if those same
elements exist in the repeating complex.
Message Flow
The Channel Inquiry service uses a typical exchange of MType messages to retrieve reference information
about a specific FI and its Bill Pay Service API operations.
Request
The third-party consumer forwards the BilPayChanInqRq request message to the Service Provider.
These elements, contained within this request, are necessary for the Bill Pay Services API.
BilPayProd
This represents the type of iPay Solutions service operations being requested. Canonical values
are:
• BilPay
• Remit (reserved for future use)
The BilPayProd default value is BilPay.
BilPayProdType
This specifies the iPay Solutions Product Type associated with the product using the Bill Pay Service
API service operations. Canonical values are:
• Consm – Consumer
• Bus – Business
• iSB – Services Platform (reserved for future use)
If no BilPayProdType is specified, product information will be returned for all products that include the
specified BilPayProd (above).
Bill Pay Services API – User Guide
iPay Solutions™
44
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Response
The Service Provider (iPay Solutions) returns the BilPayChanInqRs response message to the Service
Consumer, which returns a package of product and other reference information for the specified FI.
The simple elements contained within the BilPayChanInfo complex element of the BilPayChanInqRs
response applicable for the Bill Pay Services API are:
FinInstName
This is the depository FI name.
PmtCutoffTime
This is the cutoff time (transmitted in UTC) when payments are no longer eligible for processing on the
same day. This payment cutoff time is based in the Eastern time zone, regardless of the location of the FI
(for example, a cutoff time of 3 p.m. ET would translate to a cutoff time of 2 p.m. CT for an FI located in
the Central time zone). All payments scheduled after this time for immediate processing are handled on
the next available processing day.
StorMos
This is the number of months that payment information is stored for the FI. For example, a value of 18
indicates that a maximum of 18 months of payment data is available for this FI’s subscribers.
ChkImgStorMos
This is the number of months that check image information is stored for the FI. For example, a value of 18
indicates that check images will be available for 18 months for this FI’s subscribers.
ChkFundModel
This represents the check processing model for the Institution. Canonical values are:
• SubDrft (Subscriber or Consumer draft)
• BilPayPrvdDrft (aka iPay check)
• InstDrft (Institution draft)
This value specifies where the check payment ‘originates’ and which account funds are drawn from to
satisfy the payment. It is also used to determine who has responsibility for stopping a check payment, if
required. For example, the Subscriber draft is drawn directly from the subscriber’s account, so the FI must
stop the check. The iPay Solutions check is drawn from the iPay Solutions account after subscriber funds
are placed in the iPay settlement account, so iPay Solutions must be contacted to stop these checks.
Bill Pay Provider/iPay check
This processing model utilizes a lag period that provides time to allow an FI to review all potential
debits to subscriber accounts before debiting the subscriber and crediting an iPay Solutions
settlement account, who then forwards the payment electronically to the Payee, or drops the
transaction to a check funded from an iPay Solutions settlement account.
Subscriber Draft Model
This draft model generates transactions funded directly from the subscriber’s account. All electronic
payments are debited from the subscriber’s financial account. For check payments, the subscriber’s
checking account and routing numbers are printed on the check and funds will not debit from the
account until presented by the Payee.
Institution Draft Model
The Institution Draft Model is a variation on the Subscriber Draft Model. The major variation is that
check payments are not drawn on the subscriber’s account, but rather on a central FI account. iPay
Solutions debits the subscriber’s account, moves funds to the institution’s clearing account, and the
checks are then drawn on the clearing account.
Bill Pay Services API – User Guide
iPay Solutions™
45
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
FundVerif
This indicates whether the FI requires that funds are verified before being submitted. If true, the
subscriber’s balance is checked and their account is debited before a transaction is processed. This
functionality allows the subscriber to avoid overdraft charges, and provides the ability to send payments
through consolidators who only accept good funds. Canonical values are:
• True
• False
The arrays within the BilPayChanInfo response message applicable for the Bill Pay Services API are:
NonProcDtInfoArray
This array contains a list of all non-processing dates (e.g., Federal Reserve holidays, weekends, etc.) for
the next 18 months, and includes the NonProcDtInfo complex element. The NonProcDtInfo complex
includes the following simple element which specifies each non-processing date:
NonProcDt
This is a non-processing date.
BilPayProdTypeInfoArray
This array includes the BilPayProdTypeInfo complex element, which contains a package of data for each
specified Bill Pay Product and includes following simple and complex elements and array(s):
Simple elements:
BilPayProdType
This represents the Product Type associated with the product utilizing the Bill Pay Service
operations. Canonical values are:
• Consm – Consumer
• Bus – Business
• iSB – Services Platform (reserved for future use)
PmtDtModel
This represents the Payment Date Model being utilized by the institution for the specified product.
Canonical values are:
• ProcDtModel – Process Date: Institution requires the subscriber to choose a Process Date.
The estimated arrival date of the payment is calculated based on the entered value.
• DueDtModel – Due Date (aka Estimated Arrival Date). Institution requires the subscriber to
choose a Due Date. The Process Date is calculated based on the entered value.
MaxPmtAmt
This is the maximum payment amount that can be requested for a single transaction by any
subscriber on this institution’s account.
MaxEmailPmtAmt
This is the maximum payment amount that can be requested for a single P2P payment.
MaxEmailDlyAmt
This is the maximum daily amount that can be requested for all P2P payments in a
single day for a given subscriber.
MaxIndvPmtAmt
This is the maximum payment amount that can be requested for a single electronic payment
to an Individual Payee. (A separate single payment cap exists for those individual Payees set up
through the ‘Email/P2P’ process—via email or text. See <MaxEmailPmtAmt> above.)
Bill Pay Services API – User Guide
iPay Solutions™
46
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
MaxIndvDlyAmt
This is the maximum daily amount that can be requested for all electronic payments to Individual
Payees in a single day for a given subscriber. (A separate daily payment cap exists for those
individual Payees set up through the ‘Email/P2P’ process—via email or text. See <MaxEmailDlyAmt>
above.)
.
AlwSecdPerson
This indicates whether a secondary account holder can be specified for all subscriber/customer
accounts associated with this product for this institution. Canonical values are:
• True
• False
AlwAddPayFromAcct
This indicates whether additional funding accounts (‘pay from accounts’), in addition to the default
funding accounts, are allowed for all subscriber/customer accounts associated with this product for
this institution. Canonical values are:
• True
• False
DlyElecRiskLmt
This is the daily dollar limit for electronic payments that can be requested by a given subscriber.
Electronic payments that exceed this limit will be converted to drafts/checks.
MthlyElecRiskLmt
This is the monthly dollar limit for electronic payments that can be requested by a given subscriber.
Electronic payments that exceed this limit will be converted to drafts/checks.
TaxIdReq
This indicates whether a Tax ID (e.g., SSN, EIN) is required to add/enroll the subscriber. Canonical
values are:
• True
• False
CanSetStartChkNum
This indicates if an FI allows the subscriber to specify the starting check number for a given funding
account. Canonical values are:
• True
• False
CanPayFromSavAcct
This indicates the subscriber can add a savings account as a funding account. Canonical values are:
• True
• False
DualSignOnReq
This indicates whether Dual Sign-On is required when accessing an iPay Solutions-hosted online Bill
Pay interface, if it is available for use by the institution’s subscribers. If Dual Sign-On is the required
login method, a temporary password is required, in addition to the LoginID, to add/enroll the new
subscriber. Canonical values are:
• True
• False
Bill Pay Services API – User Guide
iPay Solutions™
47
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
CanAddPayFromOwnInfo
This indicates if the FI allows specification of funding account (‘pay from account’) owner information.
Canonical values are:
• True
• False
ConsmOwnSubUsrPer
This indicates whether the Institution/Service Consumer will own,or manage all permissions for
subscriber’s associated users. It is applicable only if the sub user feature is available for the FI’s
product. A value of False indicates that the institution/service consumer will utilize the sub user
permission structure provided by the Service Provider (iPay Solutions). Canonical values are:
• True
• False
HidSubAssocUsrConsmCustId
This indicates if the institution allows an authorized user to view or modify the
SubAssocUsrConsmCustId, the consumer’s customer ID associated with the subscriber’s associated
user. Canonical values are:
• True
• False
NOTE: This element is not currently being used by iPay Solutions.
HidSubAssocUsrSubComId
This indicates if the FI allows an authorized user to view or modify the SubAssocUsrComId, the sub
user’s identifier that is common between the Provider and Consumer, typically the Login ID. If set to
True, the Service Consumer should hide the SubAssocUsrComId (i.e., Login ID), from all requesting
users, except when the requesting user is the sub user specified in the request. Canonical values are:
• True
• False
AlwSubType
This indicates the subscriber type(s) allowed for the listed Bill Pay product. Canonical values are:
• Comp – Company
• Indv – Individual
• All – All (both Company and Individual)
NOTE: This element is not currently being used by iPay Solutions.
ElecMerAutoPmtAlw
This indicates whether set up of Automatic Payment Schedule(s) for eBills is allowed for the listed Bill
Pay product. The Bill Pay product must include the eBills feature in order to be applicable. Canonical
values are:
• True
• False
NOTE: Prohibiting or enabling Automatic Payment Schedules is controlled at the individual eBiller level,
so a value of True does not guarantee this feature is available for the individual eBill account, only that it
has been made generally available for subscribers using the product. A Payee Inquiry can determine
whether an Automatic Payment Schedule can be established for a subscriber’s Payee.
Bill Pay Services API – User Guide
iPay Solutions™
48
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Complex element(s):
SubLogInIdRstr
This complex element contains the FI’s LoginID parameter information for the specified product,
which provides an explicit definition of restrictions that apply when constructing a subscriber LoginID.
It includes the following simple elements, as well as the SpecCharRstrArray array:
MinLenCharVal
This specifies the minimum number of characters the credential type should contain.
MaxLenCharVal
This specifies the maximum number of characters the credential type should contain.
MinAlphaCharVal
This specifies the minimum number of alphabetic characters (ASCII chars: a-z and A-Z) that the
credential type should contain. If the FI’s required maximum LoginID length is specified as 20,
and the minimum number of alphabetic characters is specified as 20, this would indicate a
LoginID that must be all alphabetic characters.
MinNumCharVal
This specifies the minimum number of numeric characters (ASCII chars: 0 - 9) that the credential
type should contain. If the FI’s required maximum LoginID length is specified as 20, and the
minimum number of numeric characters is specified as 20, this would indicate a LoginID that
must be all numeric characters.
MinSpecCharVal
This specifies the minimum number of special characters (ASCII chars: [space] ! @ # $ % ^
& * ( ) _ - + = { } [ ] | \ : ; “ ‘ < > ? / ) the credential type should contain.
MinLowCaseVal
This specifies the minimum number of lower-case characters (ASCII chars: a-z) the credential
type should contain.
MinUpCaseVal
This specifies the minimum number of upper-case characters (ASCII chars: A-Z) the credential
type should contain.
SpecCharRstrArray
This array includes the SpecCharRstrRec complex element, which contains data related to the
special characters that are not allowed for the credential type. It includes the following simple
element(s):
SpecCharRstrType
This specifies the special character that is restricted for the credential type.
Array(s)
The array(s) contained within the BilPayProdTypeInfo complex are listed below.
BilPayFeturInfoArray
This array contains a list of Bill Pay Service features (business service operations) available for the
specified product, and includes following simple elements and array(s):
Simple elements:
FeturType
This specifies the type of feature(s) available for the specified product. Canonical values are:
• AddSub - Add/Enroll new subscriber (includes ability to add funding
Bill Pay Services API – User Guide
iPay Solutions™
49
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
accounts)
• ViewSubInfo - View subscriber information
• MgmtSubInfo - Manage subscriber information
• ViewPayFromAcct - View funding accounts (‘pay from accounts’)
• MgmtPayFromAcct - Manage (Add, Edit, Delete) funding accounts
• Sub users - Manage (Add, Edit, Delete) sub users for Bill Pay account
• AddPayee - Add Payee
• ViewPayee - View Payees
• MgmtPayee - Manage Payee
• SchedSinglePmt - Schedule a Single Payment
• SchedRecurPmt - Schedule a Recurring Series
• MgmtRecurPmt - Manage Recurring Series
• EmailPmt - P2P Payments
• RushPmt - Rush Payments
• ViewPendPmt - View Pending/Scheduled Payments
• MgmtPendPmt - Manage Pending Payments
• ViewPmtHist - View Payment History
• ViewInstInfo - View Institution Information
• ElecBilPmt - Electronic Bill Payment Series
• XferToSubFinInst - Outbound Transfers
• PaybyCard - Pay by Card/Card-funded Payments
These features are mapped to specific Business Service Operations, allowing the Service
Provider (iPay Solutions) to ensure the requested business service operation is available for
the FI and, if applicable, the subscriber. Details can be found in Appendix A, below.
FeturAct
This indicates if the specified feature is activated for this product for this FI. Canonical values
are:
• True
• False
Only those features that are active for this product will be available as a Bill Pay Service
Operation for the specified Institution/Product. Attempts to request a non-active feature will
result in a permissions error.
SubTypeAccessFeturInfoArray
This array contains a list of subscriber types that can access the specified feature and
includes the SubTypeAccessFeturInfo complex element. The SubTypeAccessFeturInfo
complex specifies a package of data related to the subscriber types that can access the
specified feature for this product and includes the following simple element(s):
SubType
This specifies the subscriber type(s) that can access the specified feature. Canonical
values are:
• Comp – Company
• Indv – Individual
AlwSubAssocUsrMgmtOptInfoArray
This array contains the available options for managing a subscriber’s associated users (i.e., sub
users), and includes the following element(s):
Simple element(s):
Bill Pay Services API – User Guide
iPay Solutions™
50
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
AlwSubAssocUsrMgmtOpt
This specifies the options that are available for managing a subscriber’s associated users for
the specified Bill Pay product. If all sub-user management functions are not available, a value
for each available option will be included in the array (e.g., if no delete capability is available,
separate add, mod values will be provided.) Canonical values are:
• All - [default] Can do all associated user management functions
• None - Can do no associated user management functions
• Add - Can add associated users
• Mod - Can modify/change associated users’ information
• Delete - Can delete associated users
Bill Pay Services API – User Guide
iPay Solutions™
51
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Subscriber Services
Subscriber Lookup
Container: TPG_BillPayMaster.xsd
Message: BilPaySubConsmCustInq
The Bill Pay Subscriber Lookup <BilPaySubConsmCustInq> will return the unique subscriber identifier
<SubId> required by the Service Provider (iPay Solutions) for all subsequent user-specific service requests,
based on the previously-shared common user identifier provided by the Service Consumer.
The Service Consumer has the option of storing the subscriber identifier <SubId> required by iPay Solutions
for future use in requesting subscriber-specific Bill Pay services. However, if the consumer chooses not to
store the subscriber identifier, this look-up service operation allows the Service Consumer to retrieve the
required identifier as needed.
NOTE: Prior to using this lookup service, a common means of uniquely identifying each authorized user of a
subscriber’s account (e.g., subscriber or subscriber’s associated user) between the two systems must be
established.
Either the Service Consumer’s customer identifier for the subscriber or associated user, or a common
user identifier, known to both entities, must first be provided to the Service Provider (iPay Solutions) so it
can be associated with iPay Solutions’ key identifier for the specified subscriber <SubId> or associated
user <SubAssocUsrId>. At least one of these elements will be required when any new user is added
(enrolled) in Bill Pay services. These can be updated for both subscribers or associated users.
The elements at the root request message will be echoed back at the root response, regardless if those same
elements exist in the repeating complex.
Message Flow
The Subscriber Lookup service uses a typical exchange of MType messages to retrieve the Service
Provider’s key identifier for the specified subscriber or associated user, based on the common identifier
submitted by the Service Consumer.
Bill Pay Services API – User Guide
iPay Solutions™
52
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Request
The third-party consumer forwards the BilPaySubConsmCustInqRq request message to the Service
Provider. The following elements within the BilPaySubConsmCustInqRq message request are necessary for
the Bill Pay Services API.
BilPayProd
This represents the type of iPay Solutions service operations being requested. Canonical values are:
• BilPay
• Remit (reserved for future use)
The BilPayProd default value is BilPay.
SubConsmCustId
This optional element represents the consumer’s customer ID associated with the requesting user, either
the subscriber or subscriber’s associated user.
SubComId
This optional element represents the identification that is common between the provider and consumer
associated with the requesting user, either the subscriber or subscriber’s associated user. This is typically
the user’s LoginID used with a corresponding iPay Solutions-hosted online Bill Pay application.
NOTE: Either user identifier value can be used on the look-up request, regardless of whether Bill Pay
Services are Stand-Alone or non-Stand-Alone, if the submitted identifier has previously been supplied to
the Service Provider (iPay Solutions) and has been associated with the user.
Response
The service provider (iPay Solutions) returns the BilPaySubConsmCustIDRs response message to the
Service Consumer, which returns the unique [iPay] key user identifier associated with the provided customer
ID or common identifier.
The elements within the BilPaySubConsmCustInqRs response applicable for the Bill Pay Services API:
SubId
This is the Service Provider’s (iPay Solutions) identifier for the subscriber. This is required for all
subsequent subscriber-specific service requests.
SubAssocUsrId
This is the Service Provider’s (iPay Solutions) identifier for the subscriber’s associated user (or end user),
if the look-up request passed an associated user’s common identifier. This element can be used to
specify the requesting user on subsequent subscriber-specific service requests.
SubStat
This represents the subscriber’s status. Canonical values are:
• Act – Active
• Pend – Pending
• Cls – Deleted or rejected (Closed; not eligible for reactivation.)
• InAct – Inactive (Subscriber has been deactivated and is eligible for reactivation)
PersonName
This complex element contains the subscriber’s name information, and includes the following simple
elements, as well as an optional x_PersonName complex element (not currently used for the Bill Pay
Services API):
Bill Pay Services API – User Guide
iPay Solutions™
53
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
ComNam
This represents the [Company] subscriber’s Company name.
FirstName
This represents the [Individual] subscriber’s first name.
MiddleName
This represents the [Individual] subscriber’s middle name.
LastName
This represents the [Individual] subscriber’s last name.
Bill Pay Services API – User Guide
iPay Solutions™
54
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Subscriber Add
Container: TPG_BillPayMaster.xsd
Message: BilPaySubAdd
The Bill Pay Subscriber Add <BilPaySubAdd> will allow the service consumer to add (enroll) a new subscriber
for a specific FI and product. At least one common user identifier element is required on the Add request (for
individual subscribers: the <SubComId> or <SubConsmCustId>; for company subscribers: the primary
account holder <SubAssocUsrComId> or <SubAssocUsrConsmCustId>).
When adding a company (business) subscriber, all company-related information is passed within the root
BilPaySubInfo complex on the Add request, while information pertaining to the individuals who will utilize the
company subscriber account (such as the primary account holder or any other associated users) is passed
within the SubAssocUsrInfoArray, located within the BilPaySubInfo complex.
The elements at the root request message will be echoed back at the root response, regardless if those same
elements exist in the repeating complex.
Message Flow
The Subscriber Add service uses a typical exchange of MType messages to allow the service consumer to
add a new subscriber on behalf of a specific FI and product.
Request
The third-party consumer forwards the BilPaySubAddRq request message to the Service Provider.
The below elements contained within the BilPaySubAddRq message request are necessary for the Bill Pay
Services API.
BilPayProd
This represents the type of iPay Solutions service operations being requested. Canonical values are:
• BilPay
• Remit (reserved for future use)
The BilPayProd default value is BilPay.
Bill Pay Services API – User Guide
iPay Solutions™
55
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
SubId
This is the Service Provider’s (iPay Solutions) identifier for the subscriber. This element should be left
blank for the add request, as this information will not be available to the Service Consumer until the
Subscriber Add request has been completed.
BilPaySubInfo
This complex element contains a package of data related to the specified bill pay subscriber, and includes
the following simple and complex elements, as well as several arrays:
Simple elements:
SubType
This represents the subscriber type for the specified subscriber. Canonical values are:
• Comp – Company
• Indv – Individual
SubConsmCustId
This optional element represents the identification of the consumer’s customer associated with an
individual subscriber (e.g., the consumer’s or FI’s internal identifier for the customer/subscriber).
This element should be left blank for a Company subscriber add request, as identifier information
pertaining to users of a Company Bill Pay account must be passed separately, within the
SubAssocUsrInfoArray. A value entered here for a Company subscriber will be ignored.
SubComId
This optional element represents the identification that is common between the Service Provider (iPay
Solutions) and Service Consumer associated with an individual subscriber. This will typically be the
subscriber’s login ID used with a corresponding iPay Solutions-hosted online Bill Pay application.
This element should be left blank for a Company subscriber add request, as identifier information
pertaining to users of a Company Bill Pay account must be passed separately, within the
SubAssocUsrInfoArray. A value entered here for a Company subscriber will be ignored.
NOTE: The above subscriber identifier value(s) provided to the Service Provider (iPay Solutions)
can later be used in Subscriber Lookup requests to obtain the Service Provider’s (iPay Solutions)
SubId, which is necessary for all subsequent subscriber-level requests.
TaxId
This is the subscriber’s tax identifier (e.g., SSN or [Company] EIN).
For Company subscribers, the Tax ID is always required.
For individual subscribers, the Tax ID is needed only if the subscriber’s product requires it. A Channel
Inquiry can determine if this information is required in order to add a subscriber.
TempPswd
This is the password specified by the [Individual] subscriber, which will be used when accessing
iPay Solutions’ online Bill Pay interface, if it is available for use by the FI’s individual subscribers. The
value entered must be between 2-20 [alphanumeric] characters, and can contain special characters.
This element should be left blank for a Company subscriber add request, as password
information pertaining to users of a Company Bill Pay account must be passed separately, within the
SubAssocUsrInfoArray. A value entered here for a Company subscriber will be ignored.
NOTES:
Bill Pay Services API – User Guide
iPay Solutions™
56
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
1) A Temp Password is required only if the subscriber’s product requires it. A Channel Inquiry can
determine if this information is required when adding a subscriber.
2) The sub user will be required to change their Temp Password upon initial login to the online Bill
Pay application.
PmtApprvReq
This optional element indicates whether new payments scheduled for the specified [Company]
subscriber’s account will require approval from another associated user authorized to approve
payments in order to be processed. Canonical values are:
• True
• False
NOTE: This option is not applicable if the Service Consumer manages sub user permissions. A
Channel Inquiry can determine if the Servicer Consumer or the Service Provider manages sub user
permissions.
PswdChgFreq
This optional element indicates the frequency at which passwords must be changed for subscriber’s
associated users. Canonical values are:
• None – [default] no password change is required
• Weekly – password change is required weekly
• Mthly – password change is required monthly
• Qtr – password change is required quarterly
NOTE: Specification of this option is not applicable on the add request. This can, however, be
modified in a subsequent Subscriber Mod request. A value entered here will be ignored.
SubStat
This represents the subscriber’s status. Canonical values are:
• Act – Active
• Pend – Pending
• Cls – Deleted or rejected (‘Closed’)
• InAct – Inactive (Subscriber has been deactivated)
This element should be left blank for the add request, as this information will not be available to
the Service Consumer until the Subscriber Add request has been completed. A value entered
here will be ignored.
SubInActRsnType
This identifies the reason a subscriber was moved to Inactive. Canonical values are:
• AdminAcctCls – Subscriber’s account at FI has been closed.
• AdminPoorAcct – Subscriber’s account at FI is in poor standing.
• AdminFraudAct – Fraudulent activity in Subscriber’s account at FI.
• SubRq – Subscriber request to close account due to customer service or other issue.
This element should be left blank for the add request. A value entered here will be ignored.
BirthDt Reserved for future use; not supported by iPay Solutions at this time.
This is the subscriber’s date of birth.
Bill Pay Services API – User Guide
iPay Solutions™
57
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Complex elements:
PersonName
This complex element contains the subscriber’s name, and includes the following simple elements, as
well as an optional x_PersonName complex element (which is not currently used for the Bill Pay
Services API):
ComName
This represents the [Company] subscriber’s Company Name.
FirstName
This represents the [Individual] subscriber’s First Name.
MiddleName
This represents the [Individual] subscriber’s Middle Name.
LastName
This represents the [Individual] subscriber’s Last Name.
NOTE: For Company subscribers, only the ComName should be included in the add request. For
individual subscribers, only the First-, Middle- and LastName elements should be included in the
add request. Any inappropriate values entered will be ignored.
Addr
This complex element contains the following simple elements:
StreetAddr1
This is the subscriber’s street address.
StreetAddr2
This is the second line of the subscriber’s street address.
City
This is the name of the city in the subscriber’s address.
StateCode
This is the 2-character alpha code approved by the USPS which represents a state.
PostalCode
This is the postal or ZIP code. (ZIP+4 is supported.)
NOTE: For a Company subscriber, the address provided should be the Company address. For an
Individual subscriber, the address should be the subscriber’s home address.
Arrays
PhoneArray
This array contains phone information for the specified subscriber and includes following simple and
complex elements:
PhoneNum
This represents a phone number, including area code, for the subscriber. This can be the
subscriber’s home, work, cell or SMS/Text number. This is a numeric field that will not accept
hyphens.
Bill Pay Services API – User Guide
iPay Solutions™
58
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PhoneType
This specifies the type of phone number contained in the PhoneNum element (above).
Canonical values required for the Bill Pay Services API are:
• Home
• Work
• Cell
• SMS – text
• Fax
PhoneTime
This indicates the best usage time – Day or Evening.
This optional element will not be used for the Bill Pay Services API at this time, in favor of
the ConStartTime and ConEndTime elements below.
PhoneExt
This specifies a business phone extension, if one exists.
ConStartTime
This optional element represents the time (in UTC) when contact availability starts.
ConEndTime
This optional element represents the time (in UTC) when contact availability ends.
MobPhoneInfo
This complex element is an optional element which contains information for the subscriber’s
mobile phone, and includes the following simple elements:
MobPrvdCode
This is the provider code for the subscriber’s mobile device (e.g., Verizon, Sprint,
etc.) A Service Dictionary Search request is necessary to obtain the list of
available mobile providers and associated codes.
MobBB
This indicates whether the mobile device is a Blackberry. Canonical values are:
• True
• False (default value)
MobSendTestText
This optional element is valid on a subscriber Mod request only, and indicates if the
subscriber would like a test text sent to their mobile device to validate an update to
device information.
EmailArray
This array contains email information for the specified [Individual] subscriber, and includes the
following simple elements:
EmailAddr
This element specifies the email address of the individual subscriber.
EmailType
This element specifies to whom the email address applies. Canonical values required for the
Bill Pay Services API are:
• Prim – Primary owner (Individual subscriber)
• Secd – Secondary account holder (for Individual subscriber accounts only)
NOTE: This complex element should be left blank for a Company subscriber add request, as
Bill Pay Services API – User Guide
iPay Solutions™
59
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
email information pertaining to users of a Company bill pay account must be passed
separately (within the SubAssocUsrInfoArray). A value entered here for a Company
subscriber will be ignored.
PayFromAcctInfoArray
This array contains the PayFromAcctInfo complex element, which specifies a package of data related
to the subscriber’s funding account(s) (‘pay from account’) and includes the following simple and
complex elements:
PayFromId
This is the Service Provider’s identifier for the funding account within the subscriber’s
Bill Pay account. This identifier must be included for any request to schedule a payment,
unless the default funding account is desired for the payment.
This element should be left blank for the add request, as this information will not be
available to the Service Consumer until the Subscriber Add request has been completed.
PayFromAcctId
This is the account number of the subscriber’s funding account (‘pay from account’) at the
subscriber’s FI (e.g., checking or savings account number).
PayFromAcctType
The character(s) that categorize the type of funding account. Canonical values are:
• D – Checking (default value)
• S – Savings
PayFromAcctName
This is the account name (given by the subscriber) for the subscriber’s funding
account.
PayFromAcctDft
This indicates whether the funding account (‘pay from account’) is the default account, to be
used if a funding account is not specified when scheduling a payment. There can be only one
default funding account. Canonical values are:
• True
• False (default value)
NOTE: The subscriber’s default funding account is also the account used to bill the
subscriber.
StartChkNum
This is the check number, specified by the subscriber, that will be used to start check
payments from the specified funding account.
NOTE: The subscriber’s product must allow the inclusion of a Starting Check Number
on the subscriber’s funding account(s) to accept this value. A Channel Inquiry can
determine if this feature is available.
PayFromIntsRtId
This is the routing transit number or ABA number of the FI where the subscriber’s funding
account resides. Entry is not required unless the funding account resides with an external
institution.
Bill Pay Services API – User Guide
iPay Solutions™
60
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PayFromAcctStat
This is the status of the funding account as it relates to its potential use within the
subscriber’s Bill Pay account. Canonical values are:
• Pend – Pending
• Apprv – Approved
This element should be left blank for the add request, as this information will not be
available to the Service Consumer until the Subscriber Add request has been completed.
PayFromAcctOwnName
This optional complex element contains information for the funding account (‘pay from
account’) owner’s name (if the owner of the account is not the subscriber), and includes the
following simple elements, as well as an optional x_PersonName complex element (not
currently used by iPay Solutions):
ComName
This represents the funding account owner’s name, if the actual owner of the
account is a company.
FirstName
This represents the funding account owner’s first name, if the actual owner of the
account is a person.
MiddleName
This optional element represents the funding account owner’s middle name, if the
actual owner of the account is a person.
LastName
This optional element represents the funding account owner’s last name, if the actual
owner of the account is a person.
NOTE: Inclusion of funding account owner information on the Subscriber Add request is
allowed only if the subscriber’s product permits it on the subscriber’s funding account(s), and
only if the subscriber is authorized to include funding account owner information. A Channel
Inquiry can determine if the subscriber’s product allows funding account owner information.
PayFromAcctOwnAddr
This complex element is optional and contains information for the funding account (‘pay from
account’) owner’s address (if the owner of the account is not the subscriber), and includes the
following simple elements:
StreetAddr1
This is the subscriber’s street address.
StreetAddr2
This is the second line of the subscriber’s street address.
City
This is the name of the city in the subscriber’s address.
StateCode
This is the two-character alpha code approved by the USPS which represents a
state.
PostalCode
This is the postal or ZIP code (ZIP+4 is supported).
Bill Pay Services API – User Guide
iPay Solutions™
61
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
NOTE: Inclusion of funding account owner information on the Subscriber Add request is
allowed only if the subscriber’s product permits it, and only if the subscriber is authorized to
include this information. A Channel Inquiry can determine if the subscriber’s product allows
funding account owner information.
SecdPersonArray
This optional array contains an array of Secondary Account Holder information, if a secondary
account holder exists for the specified [Individual] subscriber, and includes the following information
necessary for the Bill Pay Services API:
AddlNameStat
This indicates the status of the Secondary Account Holder. Canonical values are:
• Act – Active
• NotAct – Not Active (Pending)
AddlName
This complex element contains the following simple elements, as well as an optional
x_PersonName complex element (which is not currently used for the Bill Pay Services API):
FirstName
This represents the customer’s First Name.
MiddleName
This represents the customer’s Middle Name.
LastName
This represents the customer’s Last Name.
NOTES:
1) The subscriber’s product must allow the inclusion of a Secondary Account Holder on the
[Individual] subscriber’s account in order to add one. A Channel Inquiry can determine if this
feature is available.
2) This array should be left blank for a Company subscriber add request, as Secondary Account
Holder information is not applicable for a Company bill pay account. A value entered here for a
Company subscriber will be ignored.
MktgOptInfoArray
This array contains the MktgOpInfo complex element, which specifies a package of available
marketing options that can be chosen by the subscriber, and includes the following simple elements:
MktgOptType
This indicates the type of marketing communication option(s) that are available to the
subscriber. Canonical values are:
• Email – Marketing materials delivered via email
MktgOptVal
This indicates whether the subscriber agrees to receive marketing materials via the
specified Marketing Option Type. Canonical values are:
• Accept
• Decline
NOTE: The MktgOptInfoArray should be left blank for a Company subscriber add request, as
marketing options (which pertain to users of a Company bill pay account) is passed separately
(within the SubAssocUsrInfoArray). A value entered here for a Company ubscriber will be ignored.
Bill Pay Services API – User Guide
iPay Solutions™
62
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
SubAssocUsrInfoArray
This optional array contains the SubAssocUsrInfo complex element, which specifies a package of
data for each subscriber’s associated user (i.e. sub user) that will use or have access to the
[Company] bill pay account. This complex element contains the following simple and complex
elements and arrays:
Simple elements:
SubAssocUsrId
This is the Service Provider’s (iPay Solutions’) identifier for the subscriber’s associated user
(or end user). This element should be left blank for the add request, as this information will
not be available to the Service Consumer until the Subscriber Add request has been
completed.
SubAssocUsrRole
This optional element indicates the role of the subscriber’s associated user. Canonical
values are:
• Prim – Primary Account Holder
NOTE: Only one user can be designated as the Primary Account Holder on a
Company subscriber account.
SubAssocUsrConsmCustId
This optional element represents the Service Consumer’s customer identifier associated with
a subscriber’s associated user (.e.g., the consumer’s or FI’s interna’ identifier for the
subscriber’s associated user).
SubAssocUsrComId
This optional element represents the identification that is common between the Service
Provider (iPay) and Service Consumer associated with a Company subscriber’s associated
user. This will typically be the subscriber associated user’s LoginID used to gain access to a
corresponding iPay Solutions-hosted online Bill Pay application.
SubAssocUsrTempPswd
This is the password specified by the subscriber’ associated user, which will be used when
accessing iPay Solutions’ online Bill Pay interface, if it is available for use by the FI’s
subscribers and associated users). The value entered is limited to a maximum of 20
[alphanumeric] characters.
NOTE: A Temp Password is needed only if the subscriber’s product requires it. A Channel
Inquiry can determine if one is required when adding a subscriber’s associated user.
SubAssocUsrCmnt
This optional element represents a comment pertaining to the subscriber’s associated user.
Complex elements:
SubAssocUsrName
This complex element contains the name of the subscriber associated user, and includes the
following simple elements, as well as an optional x_PersonName complex element (which is
not currently used for the Bill Pay Services API):
FirstName
This represents the subscriber associated user’s First Name.
MiddleName
This represents the subscriber associated user’s Middle Name.
Bill Pay Services API – User Guide
iPay Solutions™
63
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
LastName
This represents the subscriber associated user’s Last Name.
Arrays:
SubAssocUsrPhoneArray
This array contains an array of phone information for the specified subscriber’s
associated user and includes following simple and complex elements:
PhoneNum
This represents a phone number, including area code, for the associated user. This
can be the user’s home, work, cell or SMS/Text number. This is a numeric field that
will not accept hyphens.
PhoneType
This specifies the type of phone number contained in the PhoneNum element (above).
Canonical values required for the Bill Pay Services API are:
• Home
• Work
• Cell
• SMS - text
PhoneTime
This indicates the best usage time – Day or Evening.
This optional element will not be utilized for the Bill Pay Services API at this time,
in favor of the ConStartTime and ConEndTime elements (below).
PhoneExt
This specifies a business phone extension, if one exists.
ConStartTime
This optional element represents the time (in UTC) when contact availability
starts.
ConEndTime
This optional element represents the time (in UTC) when contact availability ends.
MobPhoneInfo
This complex element is an optional element which contains information for the
associated user’s mobile phone, and includes the following simple elements:
MobPrvdCode
This is the provider code for the associated user’s mobile device (e.g.,
Verizon, Sprint, etc.) A Service Dictionary Search request is necessary to
obtain the current available mobile providers and associated codes.
MobBB
This indicates if the mobile device is a Blackberry. Canonical
values are:
• True
• False (default value)
MobSendTestText
This optional element is valid on a Subscriber Mod request only, and
indicates whether the associated user would like a test text sent to their
mobile device in order to validate an update to device information.
Bill Pay Services API – User Guide
iPay Solutions™
64
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
SubAssocUsrEmailArray
This array contains an array of email information for the specified subscriber’s associated
user, and includes the following simple elements:
EmailAddr
This element specifies the email address of the subscriber’s associated user.
EmailType
This element specifies to whom the email address applies. Canonical values required
for the Bill Pay Services API are:
• Prim – [default] – subscriber’s associated user
MktgOptInfoArray
This array contains the MktgOpInfo complex element, which specifies a package of available
marketing options that can be chosen by the subscriber’s associated user , and includes the
following simple elements:
MktgOptType
This indicates the type of marketing communication option(s) that are available to the
subscriber’s associated user . Canonical values are:
• Email - Marketing materials delivered via email
MktgOptVal
This indicates whether the subscriber’s associated user agrees to receive marketing
materials via the specified Marketing Option Type. Canonical values are:
• Accept
• Decline
SubAssocUsrPerInfoArray
This optional array contains a list of permission options for the subscriber’s associated user.
It includes the SubAssocUsrPerInfo complex element, which specifies the name/value pair for
each available permission and includes the following simple elements:
PerCode
This specifies the desired permission code (e.g., CanScheduleBillPayments,
ScheduledBillPaymentExcludedPayeeId, etc.) A Service Dictionary Search request
is necessary to obtain the complete list of available permission codes and
corresponding values, if pre-defined values exist.
PerValue
This specifies the desired permission value (e.g., true, ‘<PayeeId’>, etc). A Service
Dictionary Search request is necessary to obtain the complete list of available
permission codes and corresponding values, if pre-defined values exist.
SubAssocUsrCapInfoArray
This optional array contains a list of payment cap options for the subscriber’s associated
user. It includes the SubAssocUsrCapInfo complex element, which specifies payment cap
information for each available payment cap and includes the following simple elements:
CapCode
This specifies the desired payment cap code (e.g., Default Payment Cap Amt,
PayeeSpecificPayment, etc.) A Service Dictionary Search request is necessary to
Bill Pay Services API – User Guide
iPay Solutions™
65
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
obtain the complete list of available payment cap codes and corresponding cap
details, if pre-defined values exist.
CapAssocPayeeId
This specifies the PayeeId of the Payee associated with the specified payment cap, if
a payee-specific payment cap is desired.
CapAmt
This specifies the desired payment cap amount. A Service Dictionary Search
request is necessary to get a list of available payment cap codes and corresponding
details, if pre-defined values exist.
Subscriber Add Behaviors
• At least one common subscriber/primary account holder identifier is required to add a subscriber
account:
o For Individual subscribers:
▪ using a StandAlone version of Bill Pay Services API, the SubConsmCustId is minimally
required.
▪ using a non-StandAlone version of Bill Pay Services API, the SubComId is minimally
required.
• Since this element will typically be used as the subscriber’s LoginID for the corresponding
online iPay Solutions Bill Pay application, the value entered must adhere to the FI’s
LoginID parameters, which can be obtained via a Channel Inquiry.
o For Company subscribers:
▪ using a StandAlone version of Bill Pay Services API, the primary account holder’s
SubAssocUsrConsmCustId is minimally required.
▪ using a non-StandAlone version of Bill Pay Services API, the primary account holder’s
SubAssocUsrComId is minimally required.
• Since this element will typically be used as the primary account holder’s LoginID for the
corresponding online iPay Solutions Bill Pay application, the value entered must adhere
to the institution’s LoginID parameters, which can be obtained via a Channel Inquiry.
o At least one subscriber or primary account holder identifier is required (as noted above), but both
identifiers can optionally be provided for any Subscriber add request, if desired.
• At least one subscriber phone number (Home, Work or Cell) must be included in the request.
• A primary email address for the [Individual] subscriber or [Company’s] primary account holder must be
included in the request.
• Accessibility to marketing materials is applicable only for non-StandAlone Bill Pay Services API.
o Any MktgOptInfoArray information received on a Subscriber Add request for a subscriber using
StandAlone Bill Pay Services API will be ignored.
Bill Pay Services API – User Guide
iPay Solutions™
66
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
• Funding Accounts (‘pay from accounts’):
o At least one funding account is required to complete a Subscriber Add request.
▪ Designation of a default funding account is required to complete the Subscriber Add request.
• If only one funding account is included in the Subscriber Add request, this account will be
automatically designated as the default funding account.
• If more than one funding account is included in the Subscriber Add request, selection of a
default funding account is required.
o The ability to add multiple funding accounts for a single subscriber is available only for those FIs
that have included this feature for the specified product. A Channel Inquiry can determine if this
feature is available.
o The subscriber’s product must allow the inclusion of savings accounts in order to add a one as a
funding account. A Channel Inquiry can determine if this feature is available.
o If funding account account owner information is entered and the subscriber’s product does not
allow it, the Subscriber Add request will be rejected.
• For Company Subscribers:
o The ability to add multiple users (i.e., subscriber’s associated users) to a subscriber account is
applicable only if explicitly indicated for the subscriber. Only Company subscribers are enabled for
multiple users.
o At least one set of subscriber’s associated user information must be included in a Subscriber Add
request – that of the primary account holder.
▪ Just one primary account holder role must be specified to complete the Subscriber Add
request. If no primary account holder is specified, or more than one is entered, the Subscriber
Add request will be rejected.
o Subscriber’s Associated User Permissions and Caps:
▪ Specification of permissions and payee payment caps for subscriber’s associated users is not
applicable if the Service Consumer manages sub user permissions, or if the associated user
is the primary account holder. (In this instance, Superuser permissions are always assigned.)
• A Channel Inquiry can determine whether the Servicer Consumer or the Service
Provider manages sub user permissions.
▪ Permissions must be granted explicitly; that is, each subscriber’s associated user, with the
exception of the primary account holder, is given NO user permissions, unless explicitly
indicated, as below.
• Permission codes that allow the user to perform a certain bill payment activity will typically
begin with the word “Can,” as in, CanScheduleBillPayments, whose paired Value will be
either True or False. The default value for any permission of this type is False.
o Specification of each individual permission is optional; however, any available
permissions not included in the add request will default to off or False.
• Permission codes that are used to limit otherwise-permissible activity by prohibiting that
activity for specific Payees or funding accounts, etc., will typically include the word
“Excluded,” as in, ScheduleBillPaymentExcludedPayeeId. The paired Value for this
element is the ID of the entity that is being excluded, such as the PayeeId or the
PayFromId. The initial Value for the specified exclusionary permission must be provided
by the Service Consumer on the add request.
Bill Pay Services API – User Guide
iPay Solutions™
67
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
o Exclusionary permissions are optional, and should be provided only if the
subscriber’s associated user is permitted to perform the corresponding function,
but is restricted from performing that function for the specified entity, such as
scheduling a bill payment for a specific Payee. Any exclusionary permissions
entered that don’t have a corresponding Can permission will be ignored.
o For example, if the CanScheduleBillPayments permission is set to false, but a
scheduleBillPaymentsExcludedPayeeID is specified on the add request, the
Excluded Payee ID value will be ignored.
o An exclusionary permission should be included for every Payee or funding
account where a restriction is desired.
▪ Payment caps must be defined explicitly; that is, each subscriber’s associated user will be
subject to the payment caps specified for the subscriber, unless user-specific payment caps
are explicitly set.
• A specified default payment cap will apply to all payments scheduled by the subscriber’s
associated user, while Payee-specific payment caps will apply only to payments
scheduled for the specified Payee.
o A Payee-specific payment cap should be included for every Payee where an
individual cap restriction is desired.
▪ For an illustration of an associated user-specific set of permissions/caps, please refer to the
example in Appendix B at the end of this document.
Response
The service provider (iPay Solutions) returns the BilPaySubAddRs response message to the service
consumer.
The simple elements and array(s) contained within the BilPaySubAddRs response applicable for the Bill Pay
Services API is/are:
Simple elements:
SubId
This is the Service Provider’s (iPay Solutions) identifier for the subscriber.
RsStat
This specifies the status of the add request. Canonical values are:
• Success
• Fail
Array(s):
SubAssocUsrIdInfoArray
This optional array contains the SubAssocUsrIdInfo complex element, which includes a list of all
subscriber’s associated user IDs (i.e. sub users) that were added with the add request. This complex
element contains the following simple element(s):
Bill Pay Services API – User Guide
iPay Solutions™
68
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
SubAssocUsrId
This is the Service Provider’s (iPay Solutions) identifier for the subscriber’s associated user or end
user.
The Service Provider will return the new subscriber ID <SubId> generated by the Bill Pay Services API for the
accepted new subscriber, as well as the IDs for all additional users (subscriber’s associated users) that were
added in the Subscriber Add request.
Bill Pay Services API – User Guide
iPay Solutions™
69
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Subscriber Search
Container: TPG_BillPayMaster.xsd
Message: BilPaySubSrch
The bill pay Subscriber Search <BilPaySubSrch> will return all users (subscribers and all active subscriber’s
associated users) for a particular bill pay product, based on client-specified filter criteria. The request provides
the following optional filters:
• Subscriber Name < PersonName >
• Phone number <PhoneNum>
• Address <SrchAddr>
• City <SrchCity>
• Subscriber Type <SubType>
• Subscriber Status <SubStat>
• Subscriber ID <SubId>
• Funding Account ID <PayFromAcctId>
• Subscriber SSN/Tax Id <TaxId>
• Subscriber or Secondary Acct Holder Email Address <EmailAddr>
• Subscriber Zip Code <PostalCode>
When more than one filter exists on the request, the resulting selection is based on the combined effect of the
filters. Each added filter will further restrict the results; however, inclusion of all available search filter criteria,
with the exception of Subscriber ID, does not guarantee the return of a single subscriber record. The Service
Consumer is responsible for determining the correct subscriber if multiple subscriber records are returned.
The search process supports multiple SrchType attributes, such as Exact Match, Starts With, Ends With.
However, the specific SrchType options applicable to a given filter criteria vary. Details for each filter criteria
can be found below.
The elements at the root request message will be echoed back at the root response, regardless if those same
elements exist in the repeating complex.
Message Flow
The Subscriber Search service uses a typical exchange of MType messages to retrieve subscriber
information for the specified Bill Pay product, based on optional filters.
Request
Bill Pay Services API – User Guide
iPay Solutions™
70
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
The third-party consumer forwards the BilPaySubSrchRq request message to the Service Provider. These
elements within the BilPaySubSrchRq message request are necessary for the Bill Pay Services API.
BilPayProd
This represents the type of iPay Solutions service operations being requested. Canonical values are:
• BilPay
• Remit (reserved for future use)
The BilPayProd default value is BilPay.
PhoneNum (optional)
This represents a phone number, including area code, for the subscriber. This can be the
subscriber’s Home, Work, Cell or SMS/Text number. This is a numeric field that will not accept
hyphens.
SrchAddr (optional)
This is the subscriber’s street address.
SrchCity (optional)
This is the subscriber’s city.
SubType (optional)
This specifies the subscriber type(s) that can access the specified feature. Canonical values are:
• Comp – Company
• Indv – Individual
SubStat (optional)
This represents the subscriber’s status. Canonical values are:
• Act – If selected, will return all actives subscribers.
• Pend – If selected, will return all pending subscribers (those awaiting approval).
• Cls – If selected, will return all rejected and/or deleted subscribers (not eligible for
reactivation).
• InAct – If selected, will return inactive (i.e., deactivated) subscribers who are eligible for
reactivation.
SubId (optional)
This is the Service Provider’s (iPay Solutions) identifier for the subscriber.
NOTE: Inclusion of the SubId will limit the result set to all users (subscriber, secondary
account holders and subscriber’s associated users) that satisfy all other entered filter
criteria within the specified subscriber record only.
For example, if both PersonName and a SubId are entered, the system will return only those
users (subscriber, secondary account holders and subscriber’s associated users) that match
the name entered within the subscriber account specified on the request.
PayFromAcctId (optional)
This is the account number of the subscriber’s funding account (‘pay from account’) at the
subscriber’s FI (e.g., checking or savings account number).
Entry of the entire Account Id is required, as search results will be returned based on an Exact match
only.
In addition, funding account information will be included in the matching subscribers result set only if
this entry is included as a filter in the search request.
Bill Pay Services API – User Guide
iPay Solutions™
71
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
TaxId (optional)
This is the subscriber’s tax identifier (e.g., SSN or [Company] EIN).
Valid entry formats:
• Complete SSN or EIN (9 digits); or
• Last four only (last four digits of SSN/EIN)
If the complete SSN/EIN is entered, search results will be returned based on an Exact match only. If
the last four digits only are entered, search results will be returned based on an Ends with
SrchType option. For example, if four digits entered: 1234, search results will include all subscriber
records where TaxId ends with 1234.
NOTE: If the entry includes a value greater than four digits, but less than nine, the search results will
be based on a “last four only” search.
PostalCode (optional)
This is the subscriber’s postal or ZIP Code.
Entry of 5-digit or 9-digit (ZIP+4) postal code is required.
If the complete’9-digit (ZIP+4) postal code is entered, search results will be returned based on an
Exact match only.
If a 5-digit postal code is entered, search results will be returned based on a Starts with
SrchType option. For example, if five digits entered: 12345, search results will include all subscriber
records where postal code starts with 12345.
NOTE: If the entry includes a value greater than five digits, but less than nine, the search results will
be based on a 5-digit, starts with search.
EmailAddr (optional)
This element specifies the email address of the customer (either the primary or secondary email
address).
If entered, the SrchType attribute entered for this element will be evaluated to determine the type of
Email Address search (i.e., wildcard search) to execute. Valid canonical values are:
• Exact – (default)
• StartsWith
PersonName (optional)
This optional complex element contains the following simple elements which allow the Service
Consumer to specify identifying information for the person(s) being searched for. The Name
information supplied will be used to search for the subscriber, secondary account holder, and also all
subscriber’s associated users, if applicable.
ComName
This represents the [Company] subscriber’s Company Name.
FirstName
This represents the person’s first name (subscriber, secondary account holder or
subscriber’s associated user).
MiddleName
This represents the person’s middle name (subscriber, secondary account holder or
subscriber’s associated user).
Bill Pay Services API – User Guide
iPay Solutions™
72
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
LastName
This represents the person’s last name (subscriber, secondary account holder or
subscriber’s associated user).
NOTE: Caution should be used when including filter criteria for subscriber-optional elements (i.e., those that
are not required to create a subscriber record, and therefore may be null or blank; for example SSN, address,
ZIP Code). If filter criteria for these elements is included in the search request, any subscriber records that do
not contain values for the corresponding field will not match and will not be included in the search results.
Response
The Service Provider (iPay Solutions) returns the BilPaySubSrchRs response message to the Service
Consumer, which returns a list of subscribers that meet the specified search criteria. The array(s) contained
within the BilPaySubSrchRs response applicable for the Bill Pay Services API are:
BilPaySubSrchArray
This array returns responses for the subscriber search and includes the BilPaySubSrchInfo complex element
for each subscriber or subscriber’s associated user. The BilPaySubSrchInfo complex contains a package of
data related to a Bill Pay subscriber or subscriber’s associated user, and includes the following simple and
complex elements and arrays:
Simple elements:
SubId
This is the Service Provider’s (iPay Solutions) identifier for the subscriber. (This element is required for
all subsequent subscriber-level service requests.)
SubAssocUsrId
This is the Service Provider’s (iPay Solutions) identifier for the subscriber’s associated user (or end user)
if the result record is for a subscriber’s associated user.
EnrollDt
This is the enrollment date for the subscriber.
SubType
This represents the subscriber type for the specified subscriber. Canonical values are:
• Comp – Company
• Indv – Individual
SubStat
This represents the subscriber’s status. Canonical values are:
• Act – Active
• Pend – Pending
• Cls – Deleted or rejected (Closed)
• InAct – Inactive (Subscriber has been deactivated; eligible for reactivation)
PayFromAcctId
This is the account number of the subscriber’s funding account (‘pay from account’) at the subscriber’s FI
(e.g., checking or savings account number).
Bill Pay Services API – User Guide
iPay Solutions™
73
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PayFromAcctType
The number(s) or character(s) that categorize the type of funding account. Canonical values are:
• D – Checking
• S – Savings
PayFromIntsRtId
This is the routing transit number or ABA number of the FI where the subscriber’s funding account
resides.
TaxId
This is the subscriber’s tax identifier (e.g., SSN or [Company] EIN). Value will be returned only if
available for the subscriber.
Valid formats:
• Complete SSN or EIN (nine digits)
• Last four only (last four digits of SSN/EIN)
BirthDt
This is the subscriber’s date of birth. Value will be returned only if available for the subscriber.
Complex elements:
PersonName
This complex element contains the subscriber’s name information, and includes the following simple
elements, as well as an optional x_PersonName complex element (which is not currently used for the Bill
Pay Services API):
ComName
This represents the [Company] subscriber’s Company Name.
FirstName
This represents the user’s (subscriber’s or subscriber’s associated user) first name.
MiddleName
This represents the user’s (subscriber’s or subscriber’s associated user ) middle name.
LastName
This represents the user’s (subscriber’s or subscriber’s associated user ) last name.
Addr
This complex element contains the following simple elements:
StreetAddr1
This is the subscriber’s street address.
StreetAddr2
This is the second line of the subscriber’s street address.
City
This is the name of the city in the subscriber’s address.
StateCode
This is the two-character alpha code approved by the USPS which represents a state.
Bill Pay Services API – User Guide
iPay Solutions™
74
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PostalCode
This is the postal or ZIP Code (ZIP+4 is supported).
NOTE: For Company subscribers, the above PersonName and Addr complex elements, are considered
Company profile information and can be viewed only if the requesting user has permission to view/update
Company information. If the requesting user does not have permission, the <Rstr> attribute for each of
these elements will be set to Hid, which indicates the Service Consumer should hide these elements from
the requesting user.
PayFromAcctOwnName
This optional complex element contains information for the funding account (‘pay from account’) owner’s
name (if the actual owner of the account is not the subscriber), and includes the following simple
elements, as well as an optional x_PersonName complex element (which is not currently used by iPay
Solutions):
ComName
This represents the funding account owner’s name, if the owner of the account is a company.
FirstName
This represents the funding account owner’s first name, if the owner of the account is a person.
MiddleName
This optional element represents the funding account owner’s middle name, if the owner of the
account is a person.
LastName
This optional element represents the funding account owner’s last name, if the owner of the account
is a person.
NOTE: Funding account (‘pay from account’) owner information is allowed only if the subscriber’s product
permits it, and if the specific subscriber is authorized to include funding account owner information.
PayFromAcctOwnAddr
This complex element is an optional element which contains information for the funding account (‘pay from
account’) owner’s address (if the actual owner of the account is not the subscriber), and includes the
following simple elements:
StreetAddr1
This is the subscriber’s street address.
StreetAddr2
This is the second line of the subscriber’s street address.
City
This is the name of the city in the subscriber’s address.
StateCode
This is the two-character alpha code approved by the USPS which represents a state.
PostalCode
This is the postal or ZIP Code (ZIP+4 is supported).
NOTE: Funding account (‘pay from account’) owner information is allowed only if the subscriber’s product
permit it, and if the specific subscriber is authorized to include funding account owner information
Bill Pay Services API – User Guide
iPay Solutions™
75
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Arrays:
SecdPersonArray
This optional array contains Secondary Account Holder information, if a secondary account holder
exists for the specified subscriber, and includes following complex elements applicable for the Bill Pay
Services API:
AddlName
This complex element includes the name of the secondary account holder, and includes the following
simple elements:
FirstName
This represents the secondary account holder’s first name.
MiddleName
This represents the secondary account holder’s middle name.
LastName
This represents the secondary account holder’s last name.
PhoneArray
This array contains phone information for the specified subscriber or subscriber’s associated user and
includes following simple and complex elements:
PhoneNum
This represents a phone number, including area code, for the subscriber or associated user. This can
be a Home, Work, Cell or SMS/Text number. This is a numeric field that will not accept hyphens.
PhoneType
This specifies the type of phone number contained in the PhoneNum element (above). Canonical
values required for the Bill Pay Services API are:
• Home
• Work
• Cell
• SMS – (text)
• Fax
PhoneTime
This indicates the best usage time – Day or Evening.
This optional element will not be utilized for the Bill Pay Services API at this time, in favor of the
ConStartTime and ConEndTime elements (below).
PhoneExt
This specifies a business phone extension, if one exists.
ConStartTime
This optional element represents the time (in UTC) when contact availability starts.
ConEndTime
This optional element represents the time (in UTC) when contact availability ends.
MobPhoneInfo
This complex element is an optional element which contains information for the subscriber’s or
associated user’s mobile phone, and includes the following simple elements:
Bill Pay Services API – User Guide
iPay Solutions™
76
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
MobPrvdCode
This is the provider code for the mobile device (e.g., Verizon, Sprint, etc.) A Service
Dictionary Search request is necessary to obtain the list of available mobile providers and
associated codes.
MobBB
This indicates whether the mobile device is a Blackberry. Canonical values are:
• True
• False (default value)
MobSendTestText
This optional element is valid on a Subscriber Mod request only, and indicates if the
subscriber or associated user would like a test text sent to their mobile device to validate an
update to device information.
NOTE: For Company subscribers, the above Phone Array information is considered Company profile
information and can be viewed only if the requesting user has permission to view/update Company
information. If the requesting user does not have permission, the <Rstr> attribute for each of these
elements will be set to Hid, which indicates the Service Consumer should hide these elements from the
requesting user.
EmailArray
This array contains email information for the [Individual] subscriber, and includes these simple elements:
EmailAddr
This element specifies the email address of the Individual subscriber.
EmailType
This element specifies to whom the email address applies. Canonical values required for the Bill
Pay Services API are:
• Prim – Primary owner (Individual subscriber)
• Secd – Secondary account holder (for Individual subscriber accounts only)
Bill Pay Services API – User Guide
iPay Solutions™
77
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Subscriber Inquiry
Container: TPG_BillPayMaster.xsd
Message: BilPaySubInq
The Bill Pay Subscriber Inquiry <BilPaySubInq> will return element details for a specific subscriber as related
to the Bill Pay Services API product. The subscriber identification element <SubId> is required on the request.
Optionally, a subscriber’s associated user ID <SubAssocUsrId> can be included on the request. If provided,
the response will return the specified subscriber’s information, as well as subscriber’s associated user
information for the specified [active] associated user only. (If not provided, the response will include user
information for all active users associated with the specified subscriber.)
The design of the inquiry was created in a manner that facilitates addition and modification requests.
The activity intention element <ActIntent> was added to support the concurrency model for future
modifications made to subscriber or subscriber’s associated user information.
The elements at the root request message will be echoed back at the root response, regardless if those same
elements exist in the repeating complex.
NOTE: Subscriber-specific payment cap data (e.g., Email Payment caps, Transfer Caps, Business Caps,
warn/notify limits) will not be transmitted to the Consumer via the Subscriber Inquiry operation at this time, as
these will be accounted for automatically via Fault processes within the Submit Payment feature.
Message Flow
The Subscriber Inquiry service uses a typical exchange of MType messages to retrieve subscriber profile
information for a specific subscriber and subscriber’s associated user(s), if applicable, based on the required
subscriber ID. If the subscriber ID is not known, the Service Consumer must first perform a Subscriber Search
or, if the requesting user’s common identifier information if known, a Subscriber Lookup to obtain the
subscriber ID for the desired subscriber.
Using Subscriber Search:
Bill Pay Services API – User Guide
iPay Solutions™
78
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Using Subscriber Lookup:
Request
The third-party consumer forwards the BilPaySubInqRq request message to the Service Provider.
The below elements contained within this message request are necessary for the Bill Pay Services API.
BilPayProd
This represents the type of iPay Solutions service operations being requested. Canonical values are:
• BilPay
• Remit (reserved for future use)
The BilPayProd default value is BilPay.
SubId
This is the Service Provider’s (iPay Solutions) identifier for the subscriber.
SubAssocUsrId
This is the Service Provider’s (iPay Solutions) identifier for the subscriber’s associated user or end user.
NOTE: This element is required if the inquiry request is intended to facilitate a subsequent Mod
request for a specific subscriber’s associated user.
ActIntent
This indicator conveys the Service Consumer’s intention for a subsequent operation for the data set
included in the response. Canonical values are:
• ReadOnly – indicates a view intent only for the data set included in the Inquiry response.
o This is the default value.
Bill Pay Services API – User Guide
iPay Solutions™
79
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
• Upd – indicates the intention to perform a subsequent update (Mod) to the data set included in the
Inquiry response.
• Dlt – indicates the intention to perform a subsequent delete of the data set included in the Inquiry
response. This action is not available for subscriber inquiries.
Response
The Service Provider (iPay Solutions) returns the BilPaySubInqRs response message to the Service
Consumer, which returns a package of subscriber profile information for the specified subscriber, as well as
an array of information for the subscriber’s associated users, if multiple users exist for the subscriber’s
account.
The simple and complex elements and arrays contained within the BilPaySubInqRs response applicable for
the Bill Pay Services API are:
EnrollDt
This is the enrollment date for the subscriber.
SubStat
This represents the subscriber’s status. Canonical values are:
• Act – Active
• Pend – Pending
• Cls – Deleted or rejected (Closed)
• InAct – Inactive (Subscriber has been deactivated)
DEPRECATED 01-01-2018: This element has been moved to the Bill Pay Subscriber Information
<BilPaySubInfo_CType> complex.
ActIntentKey
This is the key (provided by the Service Provider) delivered to the consumer to be submitted in the
subsequent modification (update or delete) operation for the data set returned in the inquiry response.
BilPaySubInfo
This complex element contains a package of data related to the specified Bill Pay subscriber, and
includes the following simple and complex elements, as well as several arrays:
Simple elements:
SubType
This represents the subscriber type for the specified subscriber. Canonical values are:
• Comp – Company
• Indv – Individual
SubConsmCustId
This optional element represents the consumer’s customer identifier associated with an Individual
subscriber (e.g., the consumer’s or FI’s internal identifier for the customer/subscriber).
SubComId
This optional element represents the identifier that is common between the Service Provider (iPay
Solutions) and Service Consumer associated with an Individual subscriber. This will typically be the
subscriber’s LoginID used with a corresponding iPay Solutions-hosted online Bill Pay application.
NOTE: These two elements are not applicable for a Company subscriber, as identifier information for
users of a Company Bill Pay account is passed separately, within the SubAssocUsrInfoArray.
Bill Pay Services API – User Guide
iPay Solutions™
80
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
TaxId
This is the subscriber’s tax identifier (e.g., SSN or [Company] EIN).
TempPswd
This is the password specified by the [Individual] subscriber, used to initially access an iPay
Solutions-hosted online Bill Pay Interface, if available for use by the institution’s subscribers. The
subscriber is required to change their password upon accessing iPay Solutions online Bill Pay
interface for the first time.
NOTE: This element will not be returned on the Subscriber Inquiry response.
PmtApprvReq
This optional element indicates if new payments scheduled for the specified subscriber’s account will
require approval from another subscriber’s associated user (authorized to approve payments) in order
to be processed.
NOTE: This option is not applicable if the Service Consumer manages sub user permissions.
PswdChgFreq
This optional element indicates the frequency at which passwords must be changed for subscriber’s
associated users. Canonical values are:
• None – [default] no password change is required
• Weekly – password change is required weekly
• Mthly – password change is required monthly
• Qtr – password change is required quarterly
BirthDt
This is the subscriber’s date of birth.
SubStat
This represents the subscriber’s status. Canonical values are:
• Act – Active
• Pend – Pending
• Cls – Deleted or rejected (Closed)
• InAct – Inactive (Subscriber has been deactivated; eligible for reactivation)
SubInActRsnType
This identifies the reason a subscriber’s status was moved to Inactive. Canonical values are:
• AdminAcctCls – Subscriber’s account at FI has been closed.
• AdminPoorAcct – Subscriber’s account at FI is in poor standing.
• AdminFraudAct – Fraudulent activity in Subscriber’s account at FI.
• SubRq – Subscriber request to close account due to customer service or other issue.
Complex elements:
PersonName
This complex element contains the subscriber’s name, and includes the following simple elements, as
well as an optional x_PersonName complex element, which is not currently used for the Bill Pay
Services API:
ComName
This represents the [Company] subscriber’s Company name.
FirstName
This represents the [Individual] subscriber’s first name.
Bill Pay Services API – User Guide
iPay Solutions™
81
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
MiddleName
This represents the [Individual] subscriber’s middle name.
LastName
This represents the [Individual] subscriber’s last name.
NOTE: Only the ComNam will be available for a Company subscriber. Likewise, only the
First/Middle/Last Name elements will be available for an Individual subscriber.
Addr
This complex element contains the following simple elements:
StreetAddr1
This is the subscriber’s street address.
StreetAddr2
This is the second line of the subscriber’s street address.
City
This is the name of the city in the subscriber’s address.
StateCode
This is the two-character alpha code approved by the USPS which represents a state.
PostalCode
This is the postal or ZIP Code (ZIP+4 is supported).
NOTE: For Company subscribers, the above TaxId, PmtApprvRedq and PswdChgFreq elements, as well as
PersonName and Addr complex elements, are considered company profile information and can be viewed
only if the requesting user has permission to update Company information. If the requesting user does not
have permission, the <Rstr> attribute for each of these elements will be to Hid, which indicates the Service
Consumer should hide these elements from the requesting user.
Arrays
PhoneArray
This array contains phone information for the subscriber and includes simple and complex elements:
PhoneNum
This represents a phone number, including area code, for the subscriber. This can be the
subscriber’s Home, Work, Cell or SMS/Text number. This is a numeric field that will not
accept hyphens.
PhoneType
This specifies the type of phone number contained in the PhoneNum element (above).
Canonical values required for the Bill Pay Services API are:
• Home
• Work
• Cell
• SMS – text
• Fax
PhoneTime
This indicates the best usage time – Day or Evening.
This optional element will not be used for the Bill Pay Services API at this time, in favor of
the ConStartTime and ConEndTime elements.
Bill Pay Services API – User Guide
iPay Solutions™
82
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PhoneExt
This specifies a business phone extension, if one exists.
ConStartTime
This optional element represents the time (in UTC) when contact availability starts.
ConEndTime
This optional element represents the time (in UTC) when contact availability ends.
MobPhoneInfo
This optional complex element contains information for the subscriber’s mobile phone, and
includes the following simple elements:
MobPrvdCode
This is the provider code for the subscriber’s mobile device (e.g., Verizon, Sprint,
etc.) A Service Dictionary Search request is necessary to obtain the list of
available mobile providers and associated codes.
MobBB
This indicates whether the mobile device is a Blackberry. Canonical values are:
• True
• False (default value)
MobSendTestText
This optional element is valid on a Subscriber Mod request only, and indicates if the
subscriber would like a test text sent to their mobile device to validate an update to
device information.
NOTE: For Company subscribers, the above Phone Array is considered Company profile information
and can be viewed only if the requesting user has permission to update Company information. If the
requesting user does not have permission, the <Rstr> attribute for each of these elements will be set
to Hid, which indicates the Service Consumer should hide these elements from the requesting user.
EmailArray
This array contains email information for the specified [Individual] subscriber, and includes the
following simple elements:
EmailAddr
This element specifies the email address of the customer.
EmailType
This element specifies to whom the email address applies. Canonical values required for the
Bill Pay Services API are:
• Prim – Primary account holder (subscriber)
• Secd – Secondary account holder
NOTE: This complex element is not applicable for a Company subscriber, as email Information
pertaining to users of a Company Bill Pay account is passed separately, within the
SubAssocUsrInfoArray.
PayFromAcctInfoArray
This array contains the PayFromAcctInfo complex element, which specifies a package of data related
to the subscriber’s funding account and includes the following simple and complex elements:
Bill Pay Services API – User Guide
iPay Solutions™
83
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PayFromId
This is the Service Provider’s identifier for the funding account within the subscriber’s Bill Pay
account. This identifier must be included for any request to schedule a payment, unless the
default funding account is desired for the payment.
PayFromAcctId
This is the account number of the subscriber’s funding account at the subscriber’s FI (e.g.,
checking or savings account number).
PayFromAcctType
The number(s) or character(s) that categorize the type of funding account. Canonical values
are:
• D – Checking
• S – Savings
PayFromAcctName
This is the account name (given by the subscriber) for the subscriber’s funding account.
PayFromAcctDft
This indicates if the funding account is the default account, to be used in the event a fundng
account is not specified when scheduling a payment. Canonical values are:
• True
• False (default value)
StartChkNum
This is the check number, specified by the subscriber, that will be used to start check
payments from the specified funding account. This will be available only if the subscriber’s
product allows specification of a starting check number.
PayFromIntsRtId
This is the routing transit number or ABA number of the FI where the subscriber’s funding
account resides.
PayFromAcctStat
This is the status of the funding account as it relates to its potential use within the
subscriber’s Bill Pay account. Canonical values are:
• Pend – Pending
• Apprv – Approved
PayFromAcctOwnName
This optional complex element contains information for the funding account (‘pay from
account’) owner’s name, if the actual owner of the account is not the subscriber, and includes
the following simple elements, as well as an optional x_PersonName complex element (which
is not currently used for the Bill Pay Services API):
ComName
This represents the funding account owner’s name, if the actual owner of the account
is a Company.
FirstName
This represents the funding account owner’s first name, if the actual owner of the
account is a person.
Bill Pay Services API – User Guide
iPay Solutions™
84
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
MiddleName
This optional element represents the funding account owner’s middle name, if the
actual owner of the account is a person.
LastName
This optional element represents the funding account owner’s last name, if the actual
owner of the account is a person.
NOTE: Funding account (‘pay from account’) owner information is allowed only if the
subscriber’s product permits it, and only if the specific subscriber is authorized to include
funding account owner information.
PayFromAcctOwnAddr
This complex element is an optional element which contains information for the funding
account (‘pay from account’) owner’s address, if the actual owner of the account is not the
subscriber, and includes the following simple elements:
StreetAddr1
This is the subscriber’s street address.
StreetAddr2
This is the second line of the subscriber’s street address.
City
This is the name of the city in the subscriber’s address.
StateCode
This is the two-character alpha code approved by the USPS which represents a
state.
PostalCode
This is the postal or ZIP Code (ZIP+4 is supported).
NOTE: Funding account (‘pay from account’) owner information is allowed only if the
subscriber’s product permits it, and only if the specific subscriber is authorized to include
funding account owner information.
PayFromAcctInfo Array NOTES:
1) For Company subscribers, the above PayFromAcctInfoArray is eligible for viewing only if the
requesting user has permission to Manage Pay From Account information. If the requesting user
does not have permission, the <Rstr> attribute for each of these elements will be set to Hid,
which indicates that the Service Consumer should hide these elements from the requesting user.
2) It is possible for an active subscriber to have NO active funding accounts. In that event, no
funding account information will be returned in the array. (A brief grace period is provided to a
subscriber whose funding accounts have been closed to allow them to resolve any issues and re-
open the account without having to re-enroll in Bill Pay.)
Bill Pay Services API – User Guide
iPay Solutions™
85
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
SecdPersonArray
This optional array contains Secondary Account Holder information, if a secondary account holder
exists for the specified subscriber, and includes the following information:
AddlNameStat
This indicates the status of the secondary account holder. Canonical values are:
• Act – Active
• NotAct – Not Active (Pending)
AddlName
This complex element contains the following simple elements, as well as an optional
x_PersonName complex element (which is not currently used for the Bill Pay Services API):
FirstName
This represents the customer’s first name.
MiddleName
This represents the customer’s middle name.
LastName
This represents the customer’s last name.
NOTES:
1) The [Individual] subscriber’s product must allow the inclusion of a secondary account holder on
thesubscriber’s account in order to add a secondary account holder.
2) This array is not available for a Company subscriber, as secondary account holder information is not
applicable for a Company Bill Pay account.
MktgOptInfoArray
This array contains the MktgOpInfo complex element, which specifies a package of available
marketing communication options that are available to the [Individual] subscriber, and includes the
following simple elements:
MktgOptType
This indicates the type of marketing communication options that are available to the
subscriber. Canonical values are:
• Email – Marketing materials delivered via email
MktgOptVal
This indicates whether the subscriber has agreed to receive marketing materials via the
specified Marketing Option Type. Canonical values are:
• Accept
• Decline
NOTE: The MktgOptInfoArray is not applicable for a Company subscriber add request, as marketing
options, which pertain to users of a Company Bill Pay account are passed separately, within the
SubAssocUsrInfoArray.
SubAssocUsrInfoArray
This optional array contains the SubAssocUsrInfo complex element, which specifies a package of
data for each active subscriber’s associated user (i.e. sub user) that will use or have access to the
Company Bill Pay account. If a SubAssocUsrId was included in the inquiry request, this array will
return subscriber’s associated user information for that associated user only. This complex element
contains the following simple and complex elements and arrays:
Bill Pay Services API – User Guide
iPay Solutions™
86
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Simple elements:
SubAssocUsrId
This is the Service Provider’s (iPay Solutions) identifier for the subscriber’s associated user
(or end user).
SubAssocUsrRole
This optional element indicates the role of the subscriber’s associated user. Canonical values
are:
• Prim – Primary Account Holder
NOTE: Only one user can be designated as the primary account holder on a Company
subscriber account.
SubAssocUsrConsmCustId
This optional element represents the Service Consumer’s customer identifier associated with
a subscriber’s associated user (e.g., the consumer’s or FI’s internal identifier for the
subscriber’s associated user).
SubAssocUsrComId
This optional element represents the identification that is common between the Service
Provider (iPay Solutions) and Service Consumer associated with a Company subscriber’s
associated user. This will typically be the associated user’s LoginID used with a
corresponding iPay Solutions-hosted online Bill Pay application.
NOTE: This element can be viewed by requesting users only if the subscriber’s product
allows it. A Channel Inquiry can determine if the Service Consumer should hide this element
from requesting users. Additionally, the <Rstr> attribute will be set to NoAccess, which
indicates the Service Consumer should not allow the requesting user to view this element.
SubAssocUsrTempPswd
This is the password specified by the subscriber’s associated user, which will be used when
accessing an iPay Solutions-hosted online Bill Pay interface, if it is available for use by the
Institution’s subscribers and associated users).
NOTE: This element will not be returned on the Subscriber Inquiry response.
SubAssocUsrCmnt
This optional element represents a comment pertaining to the subscriber’s associated user.
Complex elements:
SubAssocUsrName
This complex element contains the name of the subscriber associated user, and includes the
following simple elements, as well as an optional x_PersonName complex element (which is
not currently used for the Bill Pay Services API):
FirstName
This represents the subscriber associated user’s first name.
MiddleName
This represents the subscriber associated user’s middle name.
LastName
This represents the subscriber associated user’s last name.
Bill Pay Services API – User Guide
iPay Solutions™
87
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Arrays
SubAssocUsrPhoneArray
This array contains of phone information for the specified user and includes following simple
and complex elements:
PhoneNum
This represents a phone number, including area code, for the subscriber’s associated
sser. This can be a Home, Work, Cell or SMS/Text number. This is a numeric field
that will not accept hyphens.
PhoneType
This specifies the type of phone number contained in the PhoneNum element.
Canonical values required for the Bill Pay Services API are:
• Home
• Work
• Cell
• SMS – text
PhoneTime
This indicates the best usage time – Day or Evening.
This optional element will not be used for the Bill Pay Services API at this time, in
favor of the ConStartTime and ConEndTime elements (below).
PhoneExt
This specifies a business phone extension, if one exists.
ConStartTime
This optional element represents the time (in UTC) when contact availability starts.
ConEndTime
This optional element represents the time (in UTC) when contact availability ends.
MobPhoneInfo
This complex element is an optional element which contains information for the
associated user’s mobile phone, and includes the following simple elements:
MobPrvdCode
This is the provider code for the associated user’s mobile device (e.g.,
Verizon, Sprint, etc.) A Service Dictionary Search request is necessary to
obtain the list of available mobile providers and associated codes.
MobBB
This indicates if the mobile device is a Blackberry. Canonical values are:
• True
• False (default value)
MobSendTestText
This optional element is valid on a Subscriber Mod request only, and
indicates if the associated user would like a test text sent to their mobile
device to validate an update to device information.
NOTE: The above Phone Array is considered personal profile information for the associated user,
and can be viewed only by the actual subscriber’s associated user who owns the information.
Personal profile information will not be returned for any subscriber’s associated user except that
of the associated user making the inquiry request.
Bill Pay Services API – User Guide
iPay Solutions™
88
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
SubAssocUsrEmailArray
This array contains email information for the specified subscriber’s associated user, and
includes the following simple elements:
EmailAddr
This element specifies the email address of the subscriber’s associated user.
EmailType
This element specifies to whom the email address applies. Canonical values required
for the Bill Pay Services API are:
• Prim – [default] Subscriber’s associated user
SubAssocUsrMktgOptInfoArray
This optional array contains the MktgOpInfo complex element, which specifies a package of
available marketing options that were chosen by the subscriber’s associated user, and
includes the following simple elements:
MktgOptType
This indicates the type of marketing communication option(s) available to the
subscriber’s associated user. Canonical values are:
• Email – Marketing materials delivered via email
MktgOptVal
This indicates whether the subscriber’s associated user agrees to receive marketing
materials via the specified Marketing Option Type. Canonical values are:
• Accept
• Decline
SubAssocUsrPerInfoArray
This optional array contains a list of permission options for the subscriber’s associated user.
It includes the SubAssocUsrPerInfo complex element, which specifies the name/value pair for
each available permission and includes the following simple elements:
PerCode
This specifies the designated permission code (e.g., CanScheduleBillPayments,
ScheduledBillPaymentExcludedPayeeId, etc.)
PerValue
This specifies the permission value (e.g., True, <PayeeId>, etc.)
NOTE: There are two types of Payee permissions available for the subscriber’s associated
user: the ability to Manage Payees (where the user is allowed to add Payees and manage
Payee details on behalf of the subscriber); and permissions to schedule payments to [all or
specific] Payees. The Payees for which a subscriber’s associated user does not have
permissions to schedule payments will be returned in this array
<ScheduleBillPaymentExcludedPayeeId>.
To determine the Payees for which the subscriber’s associated user does have schedule
payments permissions, execution of a Payee Search is recommended to obtain a complete
list of Payees available for the subscriber. To ensure that all eligible Payees are returned, the
request should specify the primary subscriber as the requesting user, since the primary
subscriber has all available permissions.
A subsequent comparison of available Payees and the excluded Payees list for the
subscriber’s associated user will yield the list of permissible Payees.
Bill Pay Services API – User Guide
iPay Solutions™
89
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
SubAssocUsrCapInfoArray
This optional array contains a list of payment cap options for the subscriber’s associated
user. It includes the SubAssocUsrCapInfo complex element, which specifies payment cap
information for each available payment cap and includes the following simple elements:
CapCode
This specifies the designated payment cap code (e.g., Default Payment Cap Amt,
PayeeSpecificPayment, etc.)
CapAssocPayeeId
This specifies the PayeeId of the Payee associated with the specified payment cap, if
a payee-specific payment cap exists.
CapAmt
This specifies the payment cap amount for the designated payment cap.
NOTE: For Company subscribers, the SubAssocUsrInfoArray is eligible for viewing only if the
requesting user has permission to manage sub users. If the requesting user does not have
permission, the <Rstr> attribute for each of these elements will be set to Hid, which indicates
the Service Consumer should hide these elements from the requesting user.
Bill Pay Services API – User Guide
iPay Solutions™
90
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Subscriber Modify
Container: TPG_BillPayMaster.xsd
Message: BilPaySubMod
The Bill Pay Subscriber Modification <BilPaySubMod> will allow the service consumer to update (modify)
certain elements for a specific Subscriber or Subscriber’s Associated User. The subscriber identification
element <SubId> and Activity Intent Key <ActIntenKey> is required on the Mod request.
The ability to delete a subscriber is not available within the Bill Pay Services API service operations. However,
a subscriber can be deactivated in order to prevent access to the Bill Pay application. Some deactivated
subscribers may be eligible for subsequent reactivation. Deactivated subscribers who are eligible for
reactivation can be identified via the Subscriber Search request (<SubStat> filter set to InAct) or via the
Subscriber Lookup service.
A delete of a subscriber’s associated user can be completed via a Subscriber Mod request, provided the
subscriber’s product includes this feature.
The elements at the root request message will be echoed back at the root response, regardless if those same
elements exist in the repeating complex.
Message Flow
The Subscriber Modification service uses a typical exchange of MType messages to allow updates to
subscriber or associated user information for a specific subscriber or subscriber’s associated user, based on
the required <SubId> (and <SubAssocUsrId>, if the update is for a subscriber’s associated user). A
Subscriber Inquiry must always be performed prior to the modification request in order to retrieve the Activity
Intent Key necessary for modification operations.
Bill Pay Services API – User Guide
iPay Solutions™
91
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Request
The third-party consumer forwards the BilPaySubModRq request message to the Service Provider.
The below simple and complex elements within the BilPaySubModRq message request are necessary for the
Bill Pay Services API.
BilPayProd
This represents the type of iPay Solutions service operations being requested. Canonical values are:
• BilPay
• Remit (reserved for future use)
The BilPayProd default value is BilPay.
SubId
This is the Service Provider’s (iPay Solutions) identifier for the subscriber.
ActIntentKey
This is the Service Provider key delivered to the Service Consumer via a preceding inquiry request,
to be submitted in the modification request operation.
Dlt
This indicates a desire for deletion of the specified entity. Canonical values are:
• True
• False (default)
This element is not currently eligible for use with a Subscriber Mod request.
BilPaySubInfo
This complex element contains a package of data related to the specified Bill Pay subscriber, and may
include all the simple and complex elements and arrays returned in the preceding Subscriber Inquiry
response. However, the following are the only elements within this complex that are eligible for
modification (add, update or delete) for a Subscriber Modification request:
Simple elements:
SubConsmCustId
This optional element represents the consumer’s customer identifier associated with an Individual
subscriber (e.g., the consumer’s or FI’s internal identifier for the customer/subscriber).
This element is a required for subscribers utilizing StandAlon Bill Pay Services, and cannot be
deleted (i.e., cannot be set to JHANull).
This element should be left blank for a Company subscriber mod request, as identifier information
pertaining to users of a Company Bill Pay account must be passed separately (within the
SubAssocUsrInfoArray). A value entered here for a Company subscriber will be ignored.
SubComId
This optional element represents the identification that is common between the provider and
consumer associated with an Individual subscriber.This will typically be the subscriber’s LoginID, and
is used to gain access to a corresponding iPay Solutions-hosted online Bill Pay application.
This element is required for subscribers using Bill Pay Services that are not considered Stand-Alone,
and cannot be deleted (i.e., cannot be set to JHANull). This element should be left blank for a
Company subscriber mod request, as identifier information pertaining to users of a Company Bill Pay
account must be passed separately, within the SubAssocUsrInfoArray. A value entered here for a
Company subscriber will be ignored.
Bill Pay Services API – User Guide
iPay Solutions™
92
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
TaxId
This is the subscriber’s tax identifier (e.g., SSN or [Company] EIN).
This element is required for certain subscribers, and cannot be deleted (i.e., cannot be set to
JHANull) for those subscribers. A Channel Inquiry can determine if this is required for the subscriber’s
product.
PmtApprvReq
This optional element indicates whether new payments scheduled for the specified [Company]
subscriber’s account will require approval from another subscriber’s associated user in order to be
processed. Canonical values are:
• True
• False
NOTE: This option is not applicable if the Service Consumer manages sub user permissions. A
Channel Inquiry can determine if the Servicer Consumer or the Service Provider manages sub user
permissions.
PswdChgFreq
This optional element indicates the frequency at which passwords must be changed for subscriber’s
associated users. Canonical values are:
• None – [default] no password change is required
• Weekly – password change is required weekly
• Mthly – password change is required monthly
• Qtr – password change is required quarterly
SubStat
This represents the subscriber’s status. Canonical values available for modification are:
• Act – Active
• InAct – Inactive (Subscriber deactivated)
This element must be set to InAct to deactivate a currently Active Subscriber, and must be set to Act
to reactivate an [eligible] subscriber who is currently Inactive. Any inappropriate values entered will be
ignored.
SubInActRsnType
This identifies why a subscriber was moved to Inactive (deactivated). Canonical values are:
• AdminAcctCls – Subscriber’s account at FI has been closed.
• AdminPoorAcct – Subscriber’s account at FI is in poor standing.
• AdminFraudAct – Fraudulent activity in Subscriber’s account at FI.
• SubRq – Subscriber request to close account due to customer service or other issue.
Entry is required when deactivating a subscriber.
BirthDt Reserved for future use; not supported by iPay Solutions at this time.
This is the subscriber’s date of birth.
Complex elements:
PersonName
This complex element represents the subscriber’s name. Only the following simple elements within
this complex are eligible for modification:
Bill Pay Services API – User Guide
iPay Solutions™
93
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
ComName
This represents the [Company] subscriber’s company name.
FirstName (required element)
This represents the [Individual] subscriber’s first name.
MiddleName (optional)
This represents the [Individual] subscriber’s middle name.
LastName (required element)
This represents the [Individual] subscriber’s last name.
NOTES:
1) For Company subscribers, only the ComName is editable in the mod request.
2) For Individual subscribers, only the First-, Middle- and LastName elements are editable in the
mod request. Any inappropriate values entered will be ignored. This element is required for
subscribers, and therefore cannot be deleted (i.e., cannot be set to JHANull).
Addr
This complex element represents the subscriber’s address. Only the following simple elements within
this complex are eligible for modification:
StreetAddr1 (required element)
This is the customer’s street address.
StreetAddr2 (optional)
This is the second line of the customer’s street address.
City (required element)
This is the name of the city in the customer’s address.
StateCode (required element)
This is the two-character alpha code approved by the USPS which represents a state.
PostalCode (required element)
This is the postal or ZIP Code (ZIP+4 is supported).
This complex element is required for subscribers, and cannot be deleted (i.e., cannot be set to
JHANull).
NOTE: For Company subscribers, the above TaxId, PmtApprvRedq and PswdChgFreq elements, as
well as PersonName and Addr complex elements, are considered Company profile information and
are eligible for update only if the requesting user has permission to update Company information.
Arrays
The below arrays contained within the BilPaySubModRq message request complex are necessary for
the Bill Pay Services API. Only those arrays that contain elements that are eligible for modification
are listed, and only those modification-eligible elements within the array will be addressed.
PhoneArray
This array contains phone information for the specified subscriber. At least one phone number is
required for every subscriber.
Only the following elements within this array are eligible for modification:
Bill Pay Services API – User Guide
iPay Solutions™
94
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PhoneNum
This represents a phone number, including area code, for the subscriber. This can be the
subscriber’s Home, Work, Cell or SMS/Text number. This is a numeric field that will not
accept hyphens.
PhoneType
This specifies the type of phone number contained in the PhoneNum element (above).
Canonical values required for the Bill Pay Services API are:
• Home (required)
• Work (optional)
• Cell (optional)
• SMS (optional)
• Fax (optional)
Use of the SMS Phone Type requires additional entry for Mobile Phone information (below).
ConStartTime (optional)
This optional element represents the time (in UTC) when phone contact availability starts.
ConEndTime (optional)
This optional element represents the time (in UTC) when phone contact availability ends.
MobPhoneInfo (conditional)
This complex element is optional and contains information for the subscriber’s mobile phone.
However, this information is required for the SMS Phone Type (above), as this supporting
information is necessary to send text messages to the subscriber.
NOTE: Updates are allowed only for mobile device providers in an approved status.
Only the following simple elements within this complex are eligible for modification
(add/update/delete):
MobPrvdCode (optional, unless PhoneType = SMS)
This is the provider code for the subscriber’s mobile device (e.g., AT&T, Verizon, Sprint, etc.)
This entry can be selected from a list of available providers. A Service Dictionary Search
request is necessary to obtain the current available mobile providers and associated codes.
MobBB (optional)
This indicates if the mobile device is a Blackberry. Canonical values are:
• True
• False (default value)
MobSendTestText (optional)
This optional element is valid on a Subscriber Mod request only, and indicates if the
subscriber would like a test text sent to their mobile device to validate an update to
device information. Canonical values are:
• True
• False (default value)
NOTES:
1) A request to send a test text message is not persisted by the Service Provider (iPay Solutions).
Therefore, there is no record that the message was sent. However, a new request can be sent at
any time.
Bill Pay Services API – User Guide
iPay Solutions™
95
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
2) For Company subscribers, the above Phone array is considered Company Profile information
and is eligible for update only if the requesting user has permission to update Company
information.
EmailArray
This array contains the EmailInfo complex element, which includes a package of email data for the
[Individual] Subscriber. Only the following elements within the EmailInfo complex are eligible for
modification:
EmailAddr (Primary Email is required)
This element specifies the email address of the Individual Subscriber.
A Primary email address is required for the Subscriber. A Secondary email address is
optional, and can be specified only if the Subscriber’s account allows a Secondary Account
Holder.
EmailType (required element)
This element specifies to whom the email address applies. Canonical values required for the
Bill Pay Services API are:
• Prim – Primary account holder (Subscriber)
• Secd – Secondary account holder
NOTE: This complex element should be left blank for a Company subscriber mod request, as email
Information pertaining to users of a Company Bill Pay account must be passed separately, within
the SubAssocUsrInfoArray. A value entered here for a Company subscriber will be ignored.
PayFromAcctInfoArray
This array contains the PayFromAcctInfo complex element, which specifies a package of data related
to the Subscriber’s funding accounts (‘pay from accounts’) and includes following simple and complex
elements:
PayFromId
This is the service provider’s identifier for the funding account within the subscriber’s Bill Pay
account. This identifier must be included for any request to update or delete a funding
account.
This element should be left blank for a request to add a funding account, as this information
will not be available to the Service Consumer until the add request has been completed.
PayFromAcctId
This is the account number of the subscriber’s funding account at the Subscriber’s FI (e.g.,
checking or savings account number).
PayFromAcctType
The number(s) or character(s) that categorize the type of funding account. Canonical values
are:
• D – Checking
• S – Savings
Bill Pay Services API – User Guide
iPay Solutions™
96
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PayFromAcctName
This is the account name for the subscriber’s funding account.
PayFromAcctDft
This indicates whether the funding account is the default account, to be used in the event a
funding account is not specified when scheduling a payment. Canonical values are:
• True
• False (default value)
NOTE: The subscriber’s default funding account is the account that is used to bill the
subscriber.
StartChkNum
This is the check number that will be used to start check payments from the specified funding
account . This will be available only if the subscriber’s product allows specification of a
starting check number.
PayFromIntsRtId
This is the routing transit number or ABA number of the FI where the subscriber’s funding
account resides.
PayFromAcctOwnName
This optional complex element contains information for the funding account (‘pay from
account’) owner’s name (if the owner of the account is not the subscriber), and includes the
following simple elements, as well as an optional x_PersonName complex element (which is
not currently used by iPay Solutions):
ComName
This represents the funding account owner’s name, if the owner of the account is a
Company.
FirstName
This represents the funding account owner’s first name, if the owner of the account is
a person.
MiddleName
This optional element represents the funding account owner’s middle name, if the
owner of the account is a person.
LastName
This optional element represents the funding account owner’s last name, if the owner
of the account is a person.
NOTE: Inclusion of new or update of existing fundng account owner information on the
Subscriber Mod request is allowed only if the subscriber’s product permits it, and only if the
specific subscriber is authorized to include funding account owner information. A Channel
Inquiry can determine if the subscriber’s product allows funding account owner information.
PayFromAcctOwnAddr
This complex element is an optional element which contains information for the funding
account (‘pay from account’) owner’s address (if the actual owner of the account is not the
subscriber), and includes the following simple elements:
StreetAddr1
This is the subscriber’s street address.
Bill Pay Services API – User Guide
iPay Solutions™
97
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
StreetAddr2
This is the second line of the subscriber’s street address.
City
This is the name of the city in the subscriber’s address.
StateCode
This is the two-character alpha code approved by the USPS which represents a
state.
PostalCode
This is the postal or ZIP Code (ZIP+4 is supported).
NOTES:
Inclusion of new or update of existing funding account owner information on the Subscriber Mod
request is allowed only if the subscriber’s product permits it, and if the specific subscriber is
authorized to include funding account owner information. A Channel Inquiry can determine if the
subscriber’s product allows funding account owner information.
For Company subscribers, the above PayFromAcctInfoArray is eligible for update only if the
requesting user has been granted permission to Manage Pay From Account information for the
specified funding account.
SecdPersonArray
This optional array includes a package of Secondary Account Holder information, if a secondary
account holder is allowed for the specified [Individual] subscriber’s account.
Only the following complex elements within this array are eligible for modification:
AddlName
Only the following simple elements within this complex are eligible for modification
(add/update/delete):
FirstName (optional)
This represents the secondary account holder’s first name.
MiddleName (optional)
This represents the secondary account holder’s middle name.
LastName (optional)
This represents the secondary account holder’s last name.
NOTES:
1) The [Individual] subscriber’s product must allow the addition of a secondary account holder in
order to include one on the subscriber’s account.
2) Adding or updating a secondary account holder requires approval by the subscriber’s FI. This
has the effect of setting the secondary account holder’s status to Not Active, or pending. Upon
approval by the FI, the secondary account holder’s status will be set to Active. Only Active
secondary account holders are eligible for modification (update or delete).
3) This array should be left blank for a Company subscriber mod request, as secondary account
holder information is not applicable for a Company Bill Pay account. A value entered here for a
Company subscriber will be ignored.
Bill Pay Services API – User Guide
iPay Solutions™
98
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
MktgOptInfoArray
This array contains the MktgOpInfo complex element, which specifies a package of available
marketing communication options available to the [Individual] subscriber, and includes the following
simple elements:
MktgOptType
This indicates the type of marketing communication options available to the subscriber.
Canonical values are:
• Email – Marketing materials delivered via email
MktgOptVal
This indicates if the subscriber has agreed to receive marketing materials via the specified
Marketing Option Type. Canonical values are:
• Accept
• Decline
NOTE: This array should be left blank for a Company subscriber mod request, as marketing options
(which pertain to users of a Company Bill Pay account) must be passed (within the
SubAssocUsrInfoArray. A value entered here for a Company subscriber will be ignored.
SubAssocUsrInfoArray
This optional array contains the SubAssocUsrInfo complex element, which specifies a package of
data for each subscriber’s associated user (i.e. sub user) that will use or have access to the
[Company] Bill Pay account. This complex element contains the following simple and complex
elements and arrays:
Simple elements:
SubAssocUsrId
This is the Service Provider’s (iPay Solutions) identifier for the Subscriber’s Associated User (or end
user). It is required on the mod request for identification purposes only, and cannot be modified.
This element should be left blank if adding a new associated user via the mod request, as this
information will not be available to the Service Consumer until the user has been added to the
subscriber’s account.
SubAssocUsrRole
This optional element indicates the role of the subscriber’s associated user. Canonical values
are:
• Prim – Primary Account Holder
NOTE: This element is not currently eligible for update with a Subscriber Mod request.
SubAssocUsrConsmCustId
This optional element represents the Service Consumer’s customer identifier associated with a
Subscriber’s Associated User (e.g., the consumer’s or FI’s internal identifier for the Subscriber’s
Associated User).
This element is a required for an associated user utilizing Bill Pay Services that are not considered
Stand-Alone, and therefore cannot be deleted (i.e., cannot be set to JHANull) on a mod request.
Bill Pay Services API – User Guide
iPay Solutions™
99
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
SubAssocUsrComId
This optional element represents the identification that is common between the Service Provider (iPay
Solutions) and Service Consumer associated with a Company Subscriber’s Associated User. This will
typically be the Subscriber Associated User’s LoginID used to gain access to a corresponding iPay
Solutions-hosted online Bill Pay application.
This element is a required element for associated user utilizing Bill Pay Services that are not
considered Stand-Alone, and therefore cannot be deleted (i.e., cannot be set to JHANull) on a mod
request
NOTE: The ability to update this element is allowed only if the Subscriber’s Product explicitly allows it.
A Channel Inquiry can determine if the Service Consumer should hide this element from requesting
users.
SubAssocUsrTempPswd
This is the password specified by the Subscriber’s Associated User, which will be used when
accessing iPay Solutions’ online Bill Pay interface, if it is available for use by the Institution’s
Subscribers and Associated Users). The value entered is limited to a maximum of 20 [alphanumeric]
characters.
NOTE: A Temp Password is required only when adding a new associated user, and only if the
subscriber’s product requires it. A Channel Inquiry can determine if this information is required when
adding Subscriber’s Associated User.
SubAssocUsrCmnt
This optional element represents a comment pertaining to the Subscriber’s Associated User.
Complex elements:
SubAssocUsrName
This complex element contains the name of the Subscriber’s Associated User, and includes
the following simple elements, as well as an optional x_PersonName complex element (which
is not currently used for the Bill Pay Services API):
FirstName
This represents the associated user’s first name.
MiddleName
This represents the associated user’s middle name.
LastName
This represents the associated user’s last name.
NOTE: This complex element is required for associated users, and therefore cannot be deleted (i.e.,
cannot be set to JHANull).
Arrays
SubAssocUsrPhoneArray
This array contains phone information for the specified subscriber’s associated user (at least
one is required) and includes following simple and complex elements:
Bill Pay Services API – User Guide
iPay Solutions™
100
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PhoneNum
This represents a phone number, including area code, for the associated user. This
can be a Home, Work, Cell or SMS/Text number. This is a numeric field that will not
accept hyphens.
PhoneType
This specifies the type of phone number contained in the PhoneNum element
(above). Canonical values required for the Bill Pay Services API are:
• Home
• Work
• Cell
• SMS – text
PhoneTime
This indicates the best usage time – Day or Evening.
This optional element will not be used for the Bill Pay Services API at this time, in
favor of the ConStartTime and ConEndTime elements (below).
PhoneExt
This specifies a business phone extension, if one exists.
ConStartTime
This optional element represents the time (in UTC) when contact availability starts.
ConEndTime
This optional element represents the time (in UTC) when contact availability ends.
MobPhoneInfo
This complex element is an optional element which contains information for the
associated user’s mobile phone, and includes the following simple elements:
MobPrvdCode
This is the provider code for the associated user’s mobile device (e.g.,
Verizon, Sprint, etc.) A Service Dictionary Search request is necessary to
obtain the list of available mobile providers and associated codes.
MobBB
This indicates whether the mobile device is a Blackberry. Canonical values
are:
• True
• False (default value)
MobSendTestText
This optional element is valid on a Subscriber Mod request only, and
indicates if the associated user would like a test text sent to their mobile
device to validate an update to device information.
NOTE: The above SubAssocUsr Phone Array is considered personal profile information for
the associated user, and is editable only by the subscriber’s associated user who owns the
information.
SubAssocUsrEmailArray
This array contains email information for the specified subscriber’s associated user, and
includes the following simple elements:
Bill Pay Services API – User Guide
iPay Solutions™
101
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
EmailAddr
This element specifies the email address of the subscriber’s associated user .
EmailType
This element specifies to whom the email address applies. Canonical values required
for the Bill Pay Services API are:
• Prim – [default] – subscriber’s associated user
This complex element is required for associated users, and therefore cannot be deleted
(i.e., cannot be set to JHANull).
MktgOptInfoArray
This array contains the MktgOpInfo complex element, which specifies a package of available
marketing options that can be chosen by the subscriber’s associated user , and includes the
following simple elements:
MktgOptType
This indicates the type of marketing communication option(s) that are available to the
subscriber’s associated user. Canonical values are:
• Email – Marketing materials delivered via email
MktgOptVal
This indicates whether the subscriber’s associated user agrees to receive marketing
materials via the specified Marketing Option Type. Canonical values are:
• Accept
• Decline
SubAssocUsrPerInfoArray
This optional array contains a list of permission options for the subscriber’s associated user .
It includes the SubAssocUsrPerInfo complex element, which specifies the name/value pair for
each available permission and includes the following simple elements:
PerCode
This specifies the desired permission code (e.g., CanScheduleBillPayments,
ScheduledBillPaymentExcludedPayeeId, etc.) A Service Dictionary Search request
is necessary to obtain the list of available permission codes and corresponding
values, if pre-defined values exist.
PerValue
This specifies the desired permission value (e.g., true, <PayeeId>, etc). A Service
Dictionary Search request is necessary to obtain the list of available permission
codes and corresponding values, if pre-defined values exist.
SubAssocUsrCapInfoArray
This optional array contains a list of payment cap options for the subscriber’s associated
user. It includes the SubAssocUsrCapInfo complex element, which specifies payment cap
information for each available payment cap and includes the following simple elements:
CapCode
This specifies the desired payment cap code (e.g., ‘Default Payment Cap Amt’,
‘PayeeSpecificPayment, etc.) A Service Dictionary Search request is necessary to
obtain the list of available payment cap codes and corresponding cap details, if pre-
defined values exist.
Bill Pay Services API – User Guide
iPay Solutions™
102
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
CapAssocPayeeId
This specifies the PayeeId of the Payee associated with the specified payment cap, if
a payee-specific payment cap is desired.
CapAmt
This specifies the desired payment cap amount. A Service Dictionary Search request
is necessary to obtain the complete list of available payment cap codes and
corresponding cap details (if pre-defined values exist).
NOTE: For Company Subscribers, the above SubAssocUsrInfo Array is eligible for update only if the
requesting user has been granted permission to manage sub users.
Subscriber Mod Behaviors
• The Service Provider (iPay Solutions) will generate a change notification email to the subscriber, as well
as a SMS/Text message, for the following updates:
o when the SMS/Text message address is updated;
o the subscriber’s [Primary] email address is modified;
• The service provider (iPay Solutions) also posts an alert on the FI’s Bill Pay administration portal
(MASTER) when any of the following subscriber profile information is updated:
o Subscriber address
o Subscriber phone numbers (Home, Work or Cell)
o Email addresses (Primary and Secondary)
• Funding Accounts (‘pay from accounts’) :
o Adding or deleting an additional funding accounts:
▪ At least one funding account must be available for a subscriber’s account at all times.
▪ The ability to add additional funding accounts for a subscriber is available via the SubMod
request, but only for those FIs that have included this feature for the specified product. A
Channel Inquiry can determine if this feature is available.
• Required entries for adding an additional funding account are specified in the
Subscriber Add request above.
▪ Deletes of funding accounts are allowed via the SubMod request, as long as at least one
funding account remains available for a subscriber’s account.
• Deletion of the subscriber’s default funding account is prohibited.
• If there are pending payments associated with the funding account being deleted, a fault
override is required to complete the delete request.
• Deleting a funding account also causes any automatic eBill payment schedule(s) that
use the specified funding account to be permanently stopped.
o Modifying an existing funding account:
▪ Only the following elements can be edited when modifying an existing funding account:
• Account Name
• Starting Check Number
Bill Pay Services API – User Guide
iPay Solutions™
103
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
• Funding account default
• Funding account owner information (if applicable)
▪ If funding account owner information is entered when adding a new or modifying an existing
funding ccount, and either the subscriber’s product does not allow it or the specified
subscriber is not allowed to add owner information, the Subscriber Mod request will be
rejected.
o For Company subscribers, funding account information can be added or modified only if the
requesting user has been granted permission to ‘Manage Pay From Account’ information.
• Accessibility to marketing materials is applicable only for non-StandAlone Bill Pay Services API.
o Any MktgOptInfoArray information received on a SubMod request for a subscriber using
StandAlone Bill Pay Services API will be ignored.
o Company profile information: The TaxId, PmtApprvRedq and PswdChgFreq elements, as well as
PersonName and Addr complex elements, are considered Company profile information and can
be updated via the SubMod request if the requesting user has permission to update Company
information.
o Funding Account information: The entire funding account complex element can be updated via the
SubMod request if the requesting user has permission to ‘Manage Pay From Account’ information.
o The ability to add multiple users (i.e., subscriber’s associated users) to a subscriber account is
applicable only if explicitly indicated for the subscriber. Only Company subscribers are enabled for
multiple users.
o Subscriber’s Associated User:
▪ Associated user information can be added or modified via a SubMod request if the requesting
user has permission to manage sub user information.
▪ Only one Primary Account Holder (role) is allowed for a Company subscriber. The primary
account holder cannot be changed.
▪ Additional associated users can be added via the SubMod request if the subscriber’s product
includes the ability to add multiple users.
• Required entries for adding an additional associated user are specified in the
Subscriber Add request above.
• Multiple associated users can be added via a single SubMod request.
▪ Associated users can be deleted via the SubMod request if that function is available for the
subscriber’s product). A Channel Inquiry can determine if the ability to delete associated
users is available for this subscriber.
• Deleting the subscriber’s Primary Account Holder is prohibited.
▪ When modifying associated user information via a Subscriber Mod request, the
SubAssocUsrInfo array should contain only the subscriber’s associated user entry for the
associated user being modified.
• If more than one associated user is included in the mod request, it will be rejected.
• Permissions for subscribers/primary sub user cannot be modified (Superuser role is
permanent).
Bill Pay Services API – User Guide
iPay Solutions™
104
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
• Associated users’ Phone and Email Arrays are considered personal profile information,
and can be edited by the actual subscriber’s associated user who owns the information.
Update of user personal profile information will not be allowed for any subscriber’s
associated user except that of the associated user making the mod request.
▪ Permissions and Caps:
• Specification of permissions and payee payment caps for subscriber’s associated users is
not applicable if the Service Consumer manages sub user permissions, or if the
associated user is the primary account holder. (In this instance, Superuser permissions
are always assigned.)
o A Channel Inquiry can determine if the Servicer Consumer or the Service Provider
manages sub user permissions.
• Permissions must be granted explicitly; that is, each subscriber’s associated user (with
the exception of the primary account holder) is given no user permissions, unless
explicitly indicated, as below.
o Permission codes that allow the user to perform certain bill payment activities will
typically begin with the word Can (as in, CanScheduleBillPayments), whose paired
Value will be either true or false.The default value for any permission of this type is
false.
▪ Specification of each individual permission is optional; however, any
available permissions not included in the add request will default to off or
false.
o Permission codes used to prohibit an activity for specific Payees or funding accounts,
etc., typically include the word Excluded, as inScheduleBillPaymentExcludedPayeeId.
o The paired Value for this element is the ID of the entity that is being excluded (such
as the PayeeId or the PayFromId). The initial value for the specified exclusionary
permission must be provided by the Service Consumer on the add request.
▪ Exclusionary permissions are optional, and should be provided only if the
subscriber’s associated user is permitted to perform the corresponding
function, but is restricted from performing that function for the specified entity
(such as scheduling a bill payment for a specific Payee). Any exclusionary
permissions entered that don’t have a corresponding Can permission will be
ignored.
For example, if the CanScheduleBillPayments permission is set to false,
but a ScheduleBillPaymentsExcludedPayeeId is specified on the add
request, the Excluded Payee ID value will be ignored.
▪ An exclusionary permission should be included for every Payee or funding
account where a restriction is desired.
• Payment caps must defined explicitly; that is, each subscriber’s associated user will be
subject to the payment caps specified for the subscriber, unless user-specific payment
caps are explicitly set.
o A specified default payment cap will apply to all payments scheduled by the
subscriber’s associated user, while Payee-specific payment caps will apply only to
payments scheduled for the specified Payee.
▪ A Payee-specific payment cap should be included for every Payee where an
individual cap restriction is desired.
• For an illustration of an associated user-specific set of permissions/caps, please refer to
the example in Appendix B at the end of this document.
Bill Pay Services API – User Guide
iPay Solutions™
105
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Response
The service provider (iPay Solutions) returns the BilPaySubModRs response message to the Service
Consumer. The element(s) contained within the BilPaySubModRs response applicable for the Bill Pay
Services API is/are:
RsStat
This specifies the status of the mod request. Canonical values are:
• Success
• Fail
Bill Pay Services API – User Guide
iPay Solutions™
106
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Payee Services
Payee Add
Container: TPG_BillPayMaster.xsd
Message: BilPayPayeeAdd
The Bill Pay Payee Add <BilPayPayeeAdd> will allow the Service Consumer to add a new Payee or Transfer
account for a specific subscriber.The subscriber identification element <SubId> is required on the Add
request.
The elements at the root request message will be echoed back at the root response, regardless if those same
elements exist in the repeating complex.
Message Flow
The Payee Add service uses a typical exchange of MType messages to allow the subscriber to add a new
Payee or Transfer account to their Bill Pay account.
Bill Pay Services API – User Guide
iPay Solutions™
107
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Request
The third-party consumer forwards the BilPayPayeeAddRq request message to the Service Provider.
The below elements and arrays contained within the BilPayPayeeAddRq message request are necessary for
the Bill Pay Services API.
Simple elements:
BilPayProd
This represents the type of iPay Solutions service operations being requested. Canonical values are:
• BilPay
• Remit (reserved for future use)
The BilPayProd default value is BilPay.
SubId
This is the Service Provider’s (iPay Solutions) identifier for the subscriber.
Complex elements:
BilPayPayeeInfo
This complex element contains a package of data related to a Bill Pay Payee or Transfer account, and
includes the below simple and complex elements and arrays necessary to add a Payee or Transfer
account via the Bill Pay Services API. This complex is required for the request; however, many of the child
nodes encapsulated are optional or not applicable to the Payee Add process (those that are not applicable
are not itemized below).
PayeeName
This is the name of the Payee. Entry of this value is not allowed for Transfer accounts.
PayeeNickname
This represents the subscriber’s nickname for the Payee or Transfer account. If not specified (for
Company or Individual Payees), this will default to the PayeeName . A value is required for Transfer
accounts.
PayeeClsf
This specifies the classification of a Payee. Canonical values are:
• Comp (Company)
• Indv (Individual/Person)
• FinInst (FI) – to be used for Transfer accounts
[Payee] PmtIntentType
This represents the payment intention of the Payee. Canonical values are:
• PayBill – Payment for a bill (default)
• XferToSubFinInst –Transfer to subscriber account at external FI (Outbound)
• XferFromSubFinInst – not supported by iPay Solutions at this time
• XferTo – not supported by iPay Solutions at this time
• XferFrom – not supported by iPay Solutions at this time
The Payee’s PmtIntentType must be appropriate for the specified Payee Classification (e.g., for FI
Payees – Transfer Accounts), only Xfer-type values are appropriate).
Bill Pay Services API – User Guide
iPay Solutions™
108
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
SubMerAcctId
This is the subscriber’s account number with the Merchant/Payee. A value is required for a Company
payee. If no value is passed for this element for an Individual payee, it will be defaulted based on the
Payee’s Payment Method. For a check or electronic payee, this will default to the subscriber’s name.
For an email payee, the value will default to N/A. Entry of this value is not allowed for Transfer
accounts.
SubMerPayerName
This is the subscriber’s name understood by the merchant and is used to override the subscriber’s
name on record. If no value is passed for this element for an Individual payee, it will be defaulted with
the subscriber’s name. Entry of this value is not allowed for Transfer accounts.
PayeeCatName (reserved for future use)
The name of the category assigned to the Payee or Transfer account.
PayeeEmailSharedSecret
A shared secret word or code provided by the subscriber to a desired person-to-person (P2P) Payee,
used to confirm the P2P Payee’s identity when providing their financial deposit information. This is a
required element when adding a P2P Payee.
PayeeP2PType
This optional element specifies the type of communication method to be used for person-to-person
Payee contact. Applicable only for an Individual Payee (PayeeClsf = Indv). Canonical values are:
• SMS – Text
• Email
NOTE: A Mobile (SMS) phone number is required for the P2P Payee to set up the P2P Payee using
the SMS PayeeP2PType. Likewise, an email address is required for the P2P Payee to set up the P2P
Payee using the Email PayeeP2PType.
PayeeFIAcctInfo
This optional complex element contains a package of financial deposit account information for the
Individual Payee or Transfer account.
FIRtId
The Bank Routing Number (ABA number) of the Individual Payee’s bank (deposit)
account or, for Transfer accounts, the subscriber’s external FI.
FIAcctId
Individual Payee’s bank account number or, for Transfer accounts, subscriber’s (checking or
savings) account number at their FI.
FIAcctType
This represents the type of deposit account for the Payee or Transfer account. Canonical
values are:
• D – Checking
• S – Savings
If the above information is included in the Add Payee request for an Individual Payee, the Individual
Payee will be considered an Electronic Payee. The information is required to set up an Individual
Electronic Payee or Transfer account. This information is not allowed for a Company Payee.
Bill Pay Services API – User Guide
iPay Solutions™
109
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PayFromAcctInfo
This optional complex element contains information on the default Bill Pay funding account (‘pay from
account’) to be used to make payments to the specified Payee or Transfer account.
PayFromId
The identifier for the funding account. This is the only element necessary to identify the
desired default Bill Pay funding account for the specified Payee.
If the Payee’s funding account is not specified, the funding account designated as the default fundng
account will be used.
NOTE: For Company subscribers, funding account information, other than the subscriber’s default
account, can be specified only if the requesting user has been granted permission to ‘Designate Pay
From Accounts’.
Arrays
PayeeAddrInfoArray
This array provides payee addresses. However, only the Payee’s primary address is required for
a Payee Add request. The payee’s address is an optional entry for P2P Payees, and for
Individual Electronic Payees (where PayeeClsf = Indv and PayeeFIAcctInfo is provided). Entry of
payee’s address is not allowed for Transfer accounts. This array includes the following simple
and complex elements:
PayeeAddrType
This specifies the type of payee address. The Payee’s primary (i.e., payment
remittance) address is required when adding a new Payee. Canonical values are:
• Prim – Primary (default)
• Rush – Rush
NOTE: The specification of a Rush Address is required only for a Payment Add (see details
below in Payment Add section). A Rush address provided for a Payee Add request will be
ignored.
PayeeAddr
This complex element contains elements representing the Payee’s [Primary] address, and is
required when adding a Payee.
StreetAddr1
This is the Payee’s street address.
StreetAddr2 (optional)
This is the second line of the Payee’s street address.
City
This is the name of the city in the Payee’s address.
StateCode
This is the two-character alpha code approved by the USPS which represents a
state.
PostalCode
This is the postal or ZIP Code (ZIP+4 is supported).
Bill Pay Services API – User Guide
iPay Solutions™
110
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
NOTE: It should be noted that to leverage check processing efficiencies gained from iPay
Solutions’ Merchant Management process for Company Payees, the Payee Address
provided may not always be the address used for a check.
PayeePhoneArray
This array contains phone information for the specified Payee. A phone number is required for every
Payee. Entry of this value is not allowed for Transfer accounts.
PhoneNum
This represents a phone number, including area code, for the Payee. This is a numeric field
that will not accept hyphens.
PhoneType
This specifies the type of phone number contained in the PhoneNum element (above).
Current canonical values available for Payees for the Bill Pay Services API are:
• Work (required for Company Payees)
• SMS – Text
NOTES:
1) SMS PhoneType is required for an Individual Payee when PayeeP2PType = SMS.
2) Work Phone Type is required for Company Payees.
3) It should be noted that to leverage payment processing efficiencies gained from iPay
Solutions’ Merchant Management process for Company Payees, the Payee PhoneNum
provided may not always be the phone number returned on subsequent Payee inquiries.
PayeeEmailArray
This optional array contains the EmailInfo complex element, which includes a package of email data
for the Payee. Entry of this value is not allowed for Transfer accounts. If submitted, only a primary
email address is applicable for the Payee:
EmailAddr
This element specifies the email address of the Payee. This is a required if the Payee’s
PayeePmtMthd = Email.
EmailType
This element specifies to whom the email address applies. Applicable canonical values
required for adding a Payee for the Bill Pay Services API are:
• Prim – Primary (default)
NOTES:
1) If the above email information is included in the Add Payee request for an Individual
Payee, the Individual Payee will be considered a P2P Email Payee. All information in the
PayeeEmailArray is required in order to set up a P2P Email Payee.
2) The above Email Address information is optional for a Company Payee. If entered, it
should be noted that to leverage payment processing efficiencies gained from iPay
Solutions’ Merchant Management process for Company Payees, the Payee EmailAddr
provided may not always be the email address returned on subsequent Payee inquiries.
Bill Pay Services API – User Guide
iPay Solutions™
111
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Payee Add Behaviors
• For Company Subscribers:
o Payees can be added only if the requesting user (subscriber’s associated user) has permission to
Manage Payees.
o Transfer accounts can be added only if the requesting user (subscriber’s associated user) has
permission to Manage Transfer Accounts.
o Funding account (‘pay from account’) information (other than the subscriber’s default account) can
be specified only if the requesting user has permission to ‘Designate Pay From Accounts’.
• For Individual Payees (PayeeClsf = Individual)
o If Payee deposit information is included in the request, the Payee will be set up to receive
payments electronically.
o If Payee email or SMS phone number information is included in the request, the Payee will be
considered a P2P payee (Payee deposit information will be obtained directly from the Payee).
PayeePmtMthd will be set to Email for all P2P Payees. (See P2P Payees section below for further
details.)
o If no Payee deposit information or Payee P2P information is included in the request, the Payee will
be considered a check payee. Payments will be sent via check to the Primary Payee address
specified.
o iPay Solutions will fault an Add Payee request if both Payee deposit account information and
Payee P2P information (e.g., email shared secret, PayeeP2PType, email address) is passed at
the same time, as the intended payment method is unclear.
o Design tip:
The service consumer may want to guide the subscriber through the Payee set-up experience
by using explicit indicators for setting up individual Payees, such as:
▪ Set up a Payee using bank account information
• the subscriber wants to add an Individual payee where payments can be sent
electronically using the provided account information
▪ Set up a P2P Payee
• the subscriber wants to add an Individual as a P2P payee, and wants iPay Solutions to
initiate the email or SMS/text procedures for obtaining the Payee’s financial account
information
▪ Set up a Payee using Payee’s address’
• the subscriber wants to add an Individual payee where payments are sent by check
using the provided Payee address.
▪ ‘Set up a Transfer account
• the subscriber wants to add a Transfer account where funds are transferred electronically
using the provided account information
o P2P Payees (individual Payees set up via email or SMS/text):
▪ The ability to add a P2P Payee is available for those FIs with the Email Payments feature
within the Bill Pay Services API. A Channel Inquiry can determine if this feature is available.
▪ Entry of PayeeP2PType is not required to complete a P2P Payee setup; however, entry is
recommended to ensure the desired P2P Payee communication method is clearly
documented:
• If communications to the P2P Payee are desired via SMS (text), PayeeP2PType should
be set to SMS.
Bill Pay Services API – User Guide
iPay Solutions™
112
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
o Phone Number entry (with PhoneType = SMS) is required for an individual Payee
when PayeeP2PType = SMS.
• If communications to the P2P Payee are desired via email, PayeeP2PType should be set
to Email.
o Payee’s EmailAddr is required when PayeeP2PType = Email.
▪ If PayeeP2PType is not specified for an individual Payee, but information is provided that
would imply P2P Payee setup is desired, the service provider (iPay Solutions) will derive the
desired P2P Payee setup as follows:
• If Payee’s Mobile Number (PhoneType = SMS) is provided, and no email address is
provided, communication with the P2P Payee will be via SMS (text).
• If Payee’s Email Address is provided (with or without a SMS Phone Number),
communication with the P2P Payee will be via email.
▪ PayeeEmailSharedSecret is required to complete Payee set up for all P2P Payees.
• The PayeeEmailSharedSecret element works only in conjunction with a request to add a
P2P Payee. iPay Solutions will ignore this element when delivered by the Service
Consumer without supporting P2P Payee information (e.g., PayeeP2PType,
PayeeEmailArray, [SMS] PhoneNum).
Notes:
1) The Payee’s EmailAddr or [SMS] PhoneNum is required for P2P Payees in order to send
communications in the desired method (email or text) to the Payee directing them to an
iPay Solutions-hosted Bill Pay website to provide their financial deposit information. To
confirm the identity of the P2P Payee on this site, the P2P Payee must enter the
PayeeEmailSharedSecret, which has been communicated to them by the subscriber,
before account information will be accepted.
2) Financial deposit account information provided by a P2P Payee is never shared with
the subscriber.
Response
The service provider (iPay Solutions) returns the BilPayPayeeAddRs response message to the service
consumer. The simple elements contained within the BilPayPayeeAddRs response applicable for the Bill Pay
Services API is/are:
PayeeId
This is the Payee identifier associated with the Payee or Transfer account for the Bill Pay Services
API.
RsStat
This specifies the status of the add request. Canonical values are:
• Success
• Fail
The Service Provider will return the new Payee ID <PayeeId> generated by the Bill Pay Services API service
application for the accepted new payee or Transfer account.
Bill Pay Services API – User Guide
iPay Solutions™
113
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Payee Search
Container: TPG_BillPayMaster.xsd
Message: BilPayPayeeSrch
The Bill Pay Payee Search <BilPayPayeeSrch> will return all Payees and Transfer accounts for a particular
product and subscriber.
The request provides the following optional filters:
• Payee Category Name < PayeeCatName> (Reserved for future use)
• Exclude non-activated <ExclNonAct> - Default = false
• Include deleted <InclDlt> - Default = false
• ‘eBill’ Payees Only <ElecMerPayeeOnly> - Default = false
• Last Modified Start Date <LastMainStartDt>
• Last Modified End Date <LastMainEndDt>
• CardPay <CardPayFilter>>
When there is more than one filter on the request, the resulting selection is based on the combined effect of
the filters (i.e., ‘and’ operator). Each added filter option will further restrict the result set.
The elements at the root request message will be echoed back at the root response, regardless if those same
elements exist in the repeating complex.
Message Flow
The Payee Search service uses a typical exchange of MType messages to retrieve Payee and Transfer
account information for a specified product and Subscriber, based on optional filters.
Request
The third-party consumer forwards the BilPayPayeeSrchRq request message to the Service Provider. The
elements within the BilPayPayeeSrchRq message request are necessary for the Bill Pay Services API.
BilPayProd
This represents the type of iPay Solutions service operation being requested. Canonical values are:
• BilPay (default value)
• Remit (reserved for future use)
Bill Pay Services API – User Guide
iPay Solutions™
114
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
SubId
This is the Service Provider’s (iPay Solutions) identifier for the subscriber.
PayeeCatName
This is the name of the category assigned to the payee or transfer account. This element is reserved
for future use by the Bill Pay Services API and is not currently a valid search filter option. A value
submitted for this element will be ignored by the Bill Pay Services API.
ExclNonAct
This is used to exclude non-activated (i.e., awaiting activation) payees or transfer accounts from the
search results. Canonical values are:
• True
• False
NOTE: Payments can no longer be scheduled for non-activated payees.
InclDlt
This is used to include deleted payees and transfer accounts in search results. Canonical values are:
• True
• False
Note: Deleted payees are required only when the Payee Search request is being used as
a precursor to requesting payment or transfer history for specific payees. This is necessary
to ensure the complete history for a specific payee or transfer account is received. (Payee
management processes require a payee or transfer account be deleted and re-added as a new
payee to modify certain payee information.) For example, if a payee (e.g., AT&T) is deleted and re-
added three times for a given subscriber, the Payee Search request with InclDlt set to True will return
three AT&T payee records (each with a different PayeeId; one would have a Payee Status of Active
and two would be Deleted). However, all three are necessary to provide a complete picture of
payment history for this particular payee.
Deleted payees are not required for a Payee Search requested as a precursor to making a payment.
ElecMerPayeeOnly
This is used to include only eBill payees (i.e., both eBill-eligible payees, as well as payees with
registered eBill accounts) in search results. If set to true, only eBill payees will be included in search
results. Canonical values are:
• True
• False
LastMainStartDt
The date that designates the starting point for payees’ Last Modified date selections. If no Start Date
is specified, the Bill Pay Services API will return all available payees with a LastMainDt equal to or
less than the specified End Date.
LastMainEndDt
The date that designates the ending point for payees’ Last Modified date selections. If no End Date is
specified, the Bill Pay Services API will return all available payees that have a LastMainDt that is
equal to or greater than the specified Start Date.
NOTE: If no LastMainDt date range is specified, the Bill Pay Services API will return all
available payees that satisfy all other filter requirements.
Bill Pay Services API – User Guide
iPay Solutions™
115
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
CardPayFilter
This is used to filter payees that are available for pay by card in the search results. Canonical values
are:
• Incl – Include payees eligible for Pay by Card (default)
• OnlyCardPay – Only return payees that are eligible for Pay by Card
• Excl – Exclude payees eligible for Pay by Card
Response
The service provider (iPay Solutions) returns the BilPayPayeeSrchRs response message to the service
consumer, which returns a list of Company and Individual payees, as well as transfer accounts, if available,
for the specified product and subscriber that meet the given search criteria.
Notes:
1) Other types of payees, such as Gift Payees, etc., will not be included in the result set.
2) For Company Subscribers: Payee information can be viewed only if the requesting user (subscriber’s
associated user) has permission to Manage Payees or, for transfer accounts, the requesting user has
permission to manage Transfer Accounts.
a. When the purpose of the Payee Search is to obtain a complete list of the subscriber’s eligible
payees to allow a subscriber’s associated user to schedule a payment, or for comparison with
the excluded payees list for a subscriber’s associated user (in order to determine the list of
payees for which the subscriber’s associated user has payment scheduling permissions), it is
recommended that the Search request specify the primary subscriber as the requesting user
to ensure that all eligible payees are returned.
3) Payee Search results will be returned in alphabetical order (A-Z) by Payee Name.
The array(s) contained within the BilPayPayeeSrchRs response applicable for the Bill Pay Services API are:
BilPayPayeeSrchArray
This array returns an array of responses for the Payee search and includes the BilPayPayeeSrchInfo
complex element for each payee and transfer account returned. The BilPayPayeeSrchInfo complex
contains a package of data related to a subscriber’s payee and includes the following simple and complex
elements and arrays:
These elements within the BilPayPayeeSrchInfo complex are included for the Bill Pay Services API:
Simple elements:
PayeeId
This is the ID of the payee or transfer account.
PayeeName
This is the name of the payee. For Transfer accounts, this will be the subscriber’s name or, for
Company subscribers, the Company name.
NOTE: Bill Pay subscribers have an option to hide certain payees in iPay Solutions’ online Bill Pay
application to prevent that payee from being displayed on their Payments page. To ensure that the list
of payees available for payment is aligned between iPay Solutions’ online application and Bill Pay
Services API, an indicator is provided on the PayeeSrch response (only) to alert the Service
Consumer of a hidden payee. If the specified payee is identified as hidden, the <Rstr> attribute for the
Bill Pay Services API – User Guide
iPay Solutions™
116
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PayeeName element will be set to Hid, which indicates to the Service Consumer that this payee
should be hidden from the requesting user.
PayeeNickname
This represents the subscriber’s nickname for the payee or transfer account.
PayeeCatName (reserved for future use)
The name of the category assigned to the payee or transfer account.
PayeeClsf
This specifies the classification of a payee. Canonical values are:
• Comp (Company)
• Indv (Individual/Person)
• FinInst (FI) – indicates a Transfer account
[Payee] PmtIntentType
This represents the payment intention of the payee. Valid canonical values are:
• PayBill – Payment for a bill (default)
• XferToSubFinInst – Transfer to subscriber account at external FI (Outbound)
• XferFromSubFinInst – not supported by iPay Solutions at this time
• XferTo – not supported by iPay Solutions at this time
• XferFrom – not supported by iPay Solutions at this time
PayeePmtMthd
This is the payment method for the payee. Transfer accounts will always be Electronic. Canonical
values are:
• Chk – Check
• Email – P2P (electronic, but initial set up is via an email or SMS process)
• Elec – Electronic
SubMerAcctId
This is the subscriber’s account number with the merchant/payee. For transfer accounts, this value
will be the Account Holder’s account number (of the transfer account).
PayeeLastPdAmt
This is the amount of the last payment or transfer paid to the payee by the subscriber.
PayeeLastPdDt
This is the date of the last payment or transfer paid to the payee by the subscriber.
CanRush
This indicator is used to show if payee offers expedited (Rush) payment options. Not applicable for
Transfer accounts. Canonical values are:
• True
• False
Bill Pay Services API – User Guide
iPay Solutions™
117
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PayeeStat
This indicates the status of the payee or transfer account. Canonical values are:
• Act – Activated (payments can be scheduled and processed for this payee)
• NotAct – Not activated (Pending; payments cannot be scheduled)
• Dlt – Deleted (Payee is not available scheduling payments)
ElecBilPayeeType
This indicates whether the payee is eligible for eBills and, if so, if enrolled. Not applicable for Transfer
accounts. Canonical values are:
• NotAlw – (default) Payee is not eligible for eBills.
• Alw – Payee eligible for eBills, but the subscriber has not yet registered for an eBill account.
• Enroll – Payee is actively registered for eBills (i.e., has an established eBill account).
• EnrollPend – Payee eBill account registration has been requested, but is not yet complete.
• EnrollAlw – Payee is actively registered for eBill summary information, but is also eligible to
re-enroll to receive eBill details.
NOTE: If payee’s eBill account registration is pending for additional information needed from
the subscriber, the ElecBilAcctErrExist element for this payee will be set to True.
ElecBilPayeeCatType
This indicates the level of ebill detail available for the eBill payee. Canonical values are:
• Sum – Summary level eBill information is available.
• Det – Detailed eBill information is available.
The following payee eBill Account eligibility options are available, based on the specified
combinations of <ElecBilPayeeType> and <ElecBilPayeeCatType>:
Table 3 – eBill Account Eligibility Options – Payee Search
ElecBil
PayeeType
ElecBil
PayeeCatType
eBill Account Status Option
NotAlw
blank
Payee is not eligible for eBills
Alw
Sum
Payee is eligible for eBills, summary level of eBill information
only
Alw
Det
Payee is eligible for eBills, detailed information available
(including full electronic billing statements)
NOTE: It is possible for a payee that is already registered
to receive eBills at a summary level (eligibility
status of Enroll/Sum) to become eligible for an
upgrade to receive detailed eBill information. A
new registration/set-up process is required to
receive the upgrade, which will be reflected with a
new eligibility status of Alw/Det.
Summary-level eBill information will continue to
be available if the subscriber does not
immediately choose to upgrade.
Design tip: The service consumer may want to guide the
subscriber through the eBill set up/upgrade
Bill Pay Services API – User Guide
iPay Solutions™
118
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
experience by providing explicit indicators for
initial set up vs. an upgrade, such as:
▪ Set up eBill
• For initial set up of an eBill account for the
given Payee (where Payee eBill account
eligibility = Alw/Sum or Alw/Det and Payee
is not already enrolled for eBills).
▪ Request eBill PDF or Upgrade to full billing
statements
• Where Payee is already registered for
summary eBill information (eBill account
eligibility previously = Enroll/Sum; and
Payee Inquiry now returns Alw/Det,
indicating this Payee is eligible for an
upgrade to begin receiving full electronic
billing statements.
Enroll
Sum
Payee is registered for eBills, summary level of eBill
information only available
Enroll
Det
Payee is registered for eBills, detailed information available
(including full electronic billing statements)
EnrollAlw
Det
Payee is registered for eBills (summary level of eBill
information), but is eligible for detailed information (including
full electronic billing statements) if a new registration is
completed
EnrollPend
Det
Payee’s eBill registration is pending, detailed information will
be available once registration complete
ElecBilAcctErrExist
This indicator is used to show if an eBill-enrolled payee has any outstanding eBill account errors that
require subscriber action to resolve. If an account error exists for an eBill account, no new eBill
activity can occur until the error is resolved. A PayeeInquiry request is necessary to get eBill account
error details. Canonical values are:
• True
• False
FirstAvlProcDt
This is the first available process or transfer date for a payment to the payee. This date is affected by
the Institution’s Payment Cutoff Time and required Lag Days, as well as applicable Non-Processing
days.
FirstAvlEstArvDt
This is the first available estimated arrival date for a payment or Transfer to the payee. This date is
affected by the payee’s Payment Method, as well as transit days.
EstArvDay
This is the number of transit days required for a check payment to be delivered to this payee. This is
affected by the payee’s payment method and ZIP Code, as well as applicable Non-Processing Days.
This value is added to the First Available Process Date to determine an Estimated Arrival Date.
Bill Pay Services API – User Guide
iPay Solutions™
119
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
This element has a default value that uses the Standard payment delivery method (non-Rush
payment). Selecting a Rush payment option when scheduling a payment, which has the potential to
change the payment method, will change the time required for transit.
LastMainDt
This is the date of the most recent (i.e., last) modification to the given payee’s information.
PayFromAcctInfo
This optional complex element contains information on the funding account (‘pay from account’)
designated for the specified payee or transfer account.
NOTE: For Company subscribers: PayFromAcctInfo can be viewed only if the requesting user has
permission to ‘Designate Pay From Account’ information. If the requesting user does not have
permission, the <Rstr> attribute for these elements will be set to Hid, which indicates the Service
Consumer should hide these elements from the requesting user.
PayFromId
This is the Bill Pay Services API identifier for the payee’s designated funding account.
PayFromAcctId
The bank account number of the funding account designated for this payee.
PayFromAcctType
The number(s) or character(s) that categorize the type of funding account. Canonical values
are:
• D – Checking
• S – Savings
PayFromAcctName
This is the account name for the subscriber’s funding account.
PayFromAcctDft
This indicates whether the funding account is the default account, to be used in the event a
funding account is not specified when scheduling a payment or transfer. Canonical values
are:
• True
• False (default value)
StartChkNum
This is the check number that will be used to start check payments from the specified funding
account. This will be available only if the subscriber’s product allows specification of a
starting check number. A Channel Inquiry can determine if this feature is available.
PayFromIntsRtId
This is the routing transit number or ABA number of the FI where the subscriber’s funding
account resides.
PayFromAcctStat
This is the status of the funding account as it relates to its potential use within the
subscriber’s Bill Pay account. Canonical values are:
• Pend – Pending
• Apprv – Approved
Bill Pay Services API – User Guide
iPay Solutions™
120
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PayFromAcctOwnName
This optional complex element contains information for the funding account (‘pay from
account’) owner’s name (if the owner of the account is not the subscriber), and includes the
following simple elements, as well as an optional x_PersonName complex element (which is
not currently used for the Bill Pay Services API):
ComName
This represents the funding accoiunt owner’s name, if the owner of the account is a
Company.
FirstName
This represents the funding account owner’s first name, if the owner of the account is
a person.
MiddleName
This optional element represents the funding account owner’s middle name, if the
owner of the account is a person.
LastName
This optional element represents the funding account owner’s last name, if the owner
of the account is a person.
NOTE: Funding account (‘pay from account’) owner information is allowed only if the
subscriber’s product permits it, and if the specific subscriber is authorized to include fundig
account owner information.
PayFromAcctOwnAddr
This complex element is optional and contains information for the funding account (‘pay from
account’) owner’s address, if the owner of the account is not the subscriber, and includes the
following simple elements:
StreetAddr1
This is the subscriber’s street address.
StreetAddr2
This is the second line of the subscriber’s street address.
City
This is the name of the city in the subscriber’s address.
StateCode
This is the two-character alpha code approved by the USPS which represents a
state.
PostalCode
This is the postal or ZIP Code (ZIP+4 is supported).
The PayFromAcctInfo complex element may be empty if no default funding account has been
specified for the payee or transfer account.
Array(s)
RushOptArray
This array contains possible Rush options that are available for the specified payee and includes the
following simple elements within the RushOptInfo complex, and will be returned only if the value of
the CanRush element (above) = True:
Bill Pay Services API – User Guide
iPay Solutions™
121
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
RushOpt
This represents the desired option for expediting (Rushing) a payment to the specified payee.
Canonical values are:
• Std – Standard (default; this specifies a non-expedited payment)
• Ovrngt – Overnight
• 2ndDay – Second Business Day
• 2ndDayEc – Second-Day Economy
Not all options may be available for the specified payee. Only those options that are
appropriate for the specified payee will be returned in the Rush Option Array.
RushOptFeeAmt
This specifies the fee associated with the Rush option.
RushOptSurChg
This specifies the surcharge applicable for Rush payments sent to Puerto Rico. This
surcharge will be automatically applied to any Rush payment request to Puerto Rico.
NOTE: Rush options not applicable for Transfer accounts.
Bill Pay Services API – User Guide
iPay Solutions™
122
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Payee Inquiry
Container: TPG_BillPayMaster.xsd
Message: BilPayPayeeInq
The Bill Pay Payee Inquiry <BilPayPayeeInq> will return element details for a specific Payee or Transfer
account for a given subscriber. The subscriber identification element <SubId> is required on the request.
The design of the inquiry was created in a manner that facilitates addition and modification requests.
The activity intention element <ActIntent> was added to support the concurrency model for future
modifications made to payee information.
The elements at the root request message will be echoed back at the root response, regardless if those same
elements exist in the repeating complex.
Message Flow
The Payee Inquiry service uses a typical exchange of MType messages to retrieve Payee information for a
specific Payee or Transfer account for a subscriber, based on the required Subscriber ID. If the Payee ID is
not known, the third-party consumer must first perform a Payee Search to obtain the Payee ID for the desired
Payee.
Request
The third-party consumer forwards the BilPayPayeeInqRq request message to the Service Provider. The
elements within the BilPayPayeeInqRq message request are necessary for the Bill Pay Services API.
Bill Pay Services API – User Guide
iPay Solutions™
123
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
BilPayProd
This represents the type of iPay Solutions service operations being requested. Canonical values are:
• BilPay
• Remit (reserved for future use)
The BilPayProd default value is BilPay.
SubId
This is the Service Provider’s (iPay Solutions) identifier for the subscriber.
PayeeId
This is the Bill Pay Services API identifier for the subscriber’s Payee or Transfer account.
ActIntent
This indicator conveys the Service Consumer’s intention for a subsequent operation for the data set
included in the response. Canonical values are:
• ReadOnly – indicates a view intent for the data set in the Inquiry response. This is the default.
Upd – indicates the intention to perform an update (Mod) to the data set in the Inquiry response.
• Dlt – indicates the intention to perform a delete of the data set in the Inquiry response.
IncXtendElemArray
This optional array conveys the list of ‘x_’ elements by name which are to be included in the response.
The inclusion of this array is necessary only if eBill and/or Card-funded information associated with the
Payee is desired in the response. The complex element contained in this array, IncXtendElemInfo,
includes the following simple element(s):
XtendElem
This is the extended element (by name) which the service consumer is requesting be included in the
response. The Extended Elements currently available for the BilPayPayeeInqRq are:
• x_ElecMerPayeeInfo – returns the Payee’s eBill account information (not applicable for Transfer
accounts)
• x_CardFundedPayeeArray – returns the <CardFundedPayeeInfo> complex, which includes the
subscriber’s custom ‘Payee URL’ to make a card-funded payment.
Response
The service provider (iPay Solutions) returns the BilPayPayeeInqRs response message to the service
consumer, which returns a package of Payee information for the Subscriber’s specified Payee or Transfer
account.
NOTE: For Company Subscribers: Payee information can be viewed if the requesting user has permission to
manage Payees, or for Transfer accounts, the requesting user has permission to manage Transfer Accounts.
The simple and complex elements within the BilPayPayeeInqRs response applicable for the Bill Pay Services
API are:
PayeePmtMthd
This is the payment method for the Payee or Transfer account. Transfer accounts will always be
electronic. Canonical values are:
• Chk – Check
• Email – P2P (electronic, but initial set up is via an email or SMS process)
• Elec – Electronic
Bill Pay Services API – User Guide
iPay Solutions™
124
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PayeeLastPdAmt
This is the amount of the last payment or Transfer paid to the Payee by the subscriber.
PayeeLastPdDt
This is the date of the last payment or Transfer paid to the Payee by the subscriber.
FirstAvlProcDt
This is the first available process date for a payment or Transfer to the Payee. This date is affected by the
FI’s Payment Cutoff Time and required Lag Days, as well as applicable Non-Processing days.
FirstAvlEstArvDt
This is the first available estimated arrival date for a payment or Transfer to the Payee. This date is
affected by the Payee’s payment method, as well as transit days.
EstArvDay
This is the number of transit days required for a check payment to be delivered to this Payee.This is
affected by the payment method and ZIP Code, as well as applicable Non-Processing Days. This value is
added to the First Available Process Date to determine an Estimated Arrival Date.
This element has a default value that uses the Standard payment delivery method (non-Rush payment).
Selecting a Rush payment option when scheduling a payment, which has the potential to change the
Payment Method, will change the time required for transit.
PayeeStat
This indicates the status of the Payee or Transfer account. Canonical values are:
• Act – Activated (payments can be scheduled and processed for this payee)
• NotAct – Not activated (pending; payments cannot be scheduled)
• Dlt – Deleted (payee is not available for scheduling payments)
ActIntentKey
This is the key provided by the Service Provider, delivered to the consumer to be submitted in the
subsequent modification (update or delete) operation for the data set returned in the inquiry response.
SubModMerAcctId
This is the iPay Solutions, or internal, version of the subscriber’s account number with the
Merchant/Payee. In this version, all special characters have been eliminated from the account number in
order to fit the format required for successful payment disbursement to the Merchant.
This element is included in the Payee Inquiry response for informational purposes only, in the event it
may be required for comparison to the user-submitted version of the subscriber’s account number with
the Merchant/Payee. The user-submitted version [SubMerAcctId] should be used for display on all
subscriber transactions.
AlwCardFundedType
This indicates whether the Payee is available to receive card funded payments. Canonical values are:
• True
• False (default value)
NOTE: Card funded payments for a given Payee are allowed only for those FI products with the
<PaybyCard> feature. A Channel Inquiry can determine if this feature is available.
Additionally, the Payee must be eligible for card funded payments, which is based on a
partnership agreement between the Payee and the ‘Pay by Card’ vendor, and not that of the
subscriber.
Bill Pay Services API – User Guide
iPay Solutions™
125
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
BilPayPayeeInfo
This complex element contains a package of data related to a bill pay Payee or Transfer account, and
includes the below simple and complex elements and arrays for the Bill Pay Services API.
Simple elements:
PayeeName
This is the name of the Payee. For Transfer accounts, this will be the subscriber’s name or, for
Company subscribers, the Company Name.
NOTE: For certain Payees, the Payee Name may be eligible for modification. If the Payee
Name is not able to be edited, the <Rstr> attribute for this element will be set to Read-
Only, which indicates the Service Consumer should not make this element available
for update from the requesting user.
PayeeNickname
This represents the subscriber’s nickname for the Payee or Transfer account.
PayeeEmailSharedSecret
This represents the shared secret word or code provided by the subscriber for the specified person-
to-person (P2P) Payee, used to confirm the P2P Payee’s identity when providing their financial
deposit information.
PayeeClsf
This specifies the classification of a Payee. Canonical values are:
• Comp – (Company)
• Indv – (Individual/Person)
• FinInst (FI) – indicates a Transfer account
[Payee] PmtIntentType
This represents the payment intention of the Payee. Canonical values are:
• PayBill – Payment for a bill (default)
• XferToSubFinInst – Transfer to subscriber account at external FI (Outbound)
• XferFromSubFinInst – not supported by iPay Solutions at this time
• XferTo – not supported by iPay Solutions at this time
• XferFrom – not supported by iPay Solutions at this time
SubMerAcctId
This is the subscriber’s account number with the Merchant/Payee. For Transfer accounts, this value
will be the Account Holder’s account number (of the Transfer account). If the subscriber’s name (Last
Name, First Name) is being used for this element, the value will be truncated at 50 characters.
SubMerPayerName
This is the subscriber’s name understood by the merchant and is used to override the subscriber’s
name on record.
PayeeCatName (reserved for future use)
The name of the category assigned to the Payee or Transfer account.
ElecBilPayeeType
This indicates whether the Payee is eligible for eBills and, if so, if enrolled. Not applicable for Transfer
accounts. Canonical values are:
• NotAlw – (default) Payee is not eligible for eBills.
Bill Pay Services API – User Guide
iPay Solutions™
126
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
• Alw – Payee is eligible for eBills, but the subscriber has not yet registered for an eBill
account.
• Enroll – Payee is actively registered for eBills (i.e., has an established eBill account.
• EnrollPend – Payee eBill account registration has been requested, but is not yet complete.
• EnrollAlw – Payee is actively registered for eBill summary information, but is also eligible to
re-enroll to receive eBill details.
NOTE: If Payee’s eBill account registration is pending for additional information from the subscriber,
the ElecBilAcctErrExist element for this Payee will be set to True. Details for the needed information
can be found in the <ElecMerAcctErrInfoArray> and <AuthenQuesArray>.
ElecBilPayeeCatType
This indicates the level of ebill detail that is available for the eBill Payee. Canonical values are:
• Sum – Summary level eBill information only is available for Payee.
• Det – Detailed eBill information is available for Payee.
The following Payee eBill Account eligibility options are available, based on the specified
combinations of <ElecBilPayeeType> and <ElecBilPayeeCatType>:
Table 4 – eBill Account Eligibility Options – Payee Inquiry
ElecBil
PayeeType
ElecBil
PayeeCatType
eBill Account Status Option
NotAlw
blank
Payee is not eligible for eBills
Alw
Sum
Payee is eligible for eBills, summary level of eBill information
only
Alw
Det
Payee is eligible for eBills, detailed information available
(including full electronic billing statements)
NOTE: It is possible for a Payee that is already registered
to receive eBills at a summary level (eligibility
status of ‘Enroll/Sum’) to become eligible for an
upgrade to receive detailed eBill information. A
new registration/set-up process is required to
receive the upgrade, which will be reflected with a
new eligibility status of ‘Alw/Det’.
Summary-level eBill information will continue to
be available if the subscriber does not
immediately choose to upgrade.
Design tip: The service consumer may want to guide the
subscriber through the eBill setup/upgrade
experience by providing explicit indicators for
initial setup vs. an ‘upgrade’, such as:
▪ ‘Set up eBill’
• For initial setup of an eBill account for the
given Payee (where Payee eBill account
eligibility = ‘Alw/Sum’ or ‘Alw/Det’ and
Payee is not already enrolled for eBills).
▪ ‘Request eBill PDF’ or ‘Upgrade to full billing
statements’
Bill Pay Services API – User Guide
iPay Solutions™
127
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
• Where Payee is already registered for
summary eBill information (eBill account
eligibility previously = ‘Enroll/Sum’; and
Payee Inquiry now returns ‘Alw/Det’,
indicating this Payee is eligible for an
upgrade to begin receiving full electronic
billing statements.
Enroll
Sum
Payee is registered for eBills, summary level of eBill
information only available
Enroll
Det
Payee is registered for eBills, detailed information available
(including full electronic billing statements)
EnrollAlw
Det
Payee is registered for eBills (summary level of eBill
information), but is eligible for detailed information (including
full electronic billing statements) if a new registration is
completed
EnrollPend
Det
Payee’s eBill registration is pending, detailed information will
be available once registration complete
ElecBilAcctErrExist
This indicator is used to show whether an eBill-enrolled Payee has any outstanding eBill account
errors that require subscriber action to resolve. If an account error exists for an eBill account, no new
eBill activity can occur until the error is resolved. Canonical values are:
• True
• False
PayeeP2PType
This optional element specifies the type of communication method to be used for person-to-person
Payee contact. Applicable only for an Individual Payee (PayeeClsf = ‘Indv’). Canonical values are:
• SMS – Text
• Email
LastMainDt
This is the date of the most recent (i.e., last) modification to the given Payee’s information.
Complex elements:
PayeeFIAcctInfo
This complex element contains a package of financial deposit account information. (Available for the
Individual Payee with an Electronic Payment Method, and for Transfer accounts.)
FIRtId
The Bank Routing Number (ABA number) of the Payee’s Bank (deposit) or Transfer account.
FIAcctId
Payee’s Bank Account Number. For Transfer accounts, this value will be the subscriber’s
account number at the designated FI.
FIAcctType
This represents the type of deposit account for the Payee or Transfer account. Canonical
values are:
• D – Checking
• S – Savings
Bill Pay Services API – User Guide
iPay Solutions™
128
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PayFromAcctInfo
This optional complex element contains information on the default funding account (‘pay from
account’ designated for the specified Payee or Transfer account.
NOTE: For Company subscribers: PayFromAcctInfo can be viewed if the requesting user has
permission to designate funding account information. If the requesting user does not have
permission, the <Rstr> attribute for each of these elements will be set to Hid, which indicates the
Service Consumer should hide these elements from the requesting user.
PayFromId
This is the Bill Pay Services API identifier for the Payee’s or Transfer account’s designated
funding account.
PayFromAcctId
The bank account number of the funding account designated for this Payee or Transfer
account.
PayFromAcctType
The number(s) or character(s) that categorize the type of funding account. Canonical values
are:
• D – Checking
• S – Savings
PayFromAcctName
This is the account name for the subscriber’s Bill Pay funding account.
PayFromAcctDft
This indicates if the funding account is the default account to be used in the event a funding
account is not specified when scheduling a payment or Transfer. Canonical values are:
• True
• False
This complex element may be empty if no default funding account has been specified for the
Payee or Transfer account. If no funding account has been specified for the Payee, the
funding account designated as the subscriber’s default funding account will be used to make
payments to this Payee or Transfer account.
StartChkNum
This is the check number that will be used to start check payments from the specified funding
account. This will be available only if the subscriber’s product allows specification of a
starting check number.
PayFromIntsRtId
This is the routing transit number or ABA number of the FI where the subscriber’s funding
account resides.
PayFromAcctStat
This is the status of the funding account as it relates to its potential use within the
subscriber’s Bill Pay account. Canonical values are:
• Pend – Pending
• Apprv – Approved
Bill Pay Services API – User Guide
iPay Solutions™
129
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PayFromAcctOwnName
This optional complex element contains information for the funding account (‘pay from
account’) owner’s name (if the owner of the account is not the subscriber), and includes the
following simple elements, as well as an optional x_PersonName complex element (which is
not currently used for the Bill Pay Services API):
ComName
This represents the funding account owner’s name, if the owner of the account is a
Company.
FirstName
This represents the funding account owner’s first name, if the owner of the account is
a person.
MiddleName
This optional element represents the funding account owner’s middle name, if the
owner of the account is a person.
LastName
This optional element represents the funding account owner’s last name, if the owner
of the account is a person.
NOTE: Funding account (‘pay from account’) owner information is allowed only if the
subscriber’s Product allows this information on the subscriber’s funding account(s), and
then only if the specific subscriber is authorized to include funding account owner
information.
PayFromAcctOwnAddr
This complex element is an optional element which contains information for the funding
account owner’s address, if the actual owner of the account is not the subscriber, and
includes the following simple elements:
StreetAddr1
This is the subscriber’s street address.
StreetAddr2
This is the second line of the subscriber’s street address.
City
This is the name of the city in the subscriber’s address.
StateCode
This is the two-character alpha code approved by the USPS which represents a
state.
PostalCode
This is the postal or ZIP Code (ZIP+4 is supported).
NOTE: Funding account (‘pay from account’) owner information is allowed only if the
subscriber’s Product allows this information on the subscriber’s funding account(s), and then
only if the specific subscriber is authorized to include funding account Owner information.
Arrays:
PayeeAddrInfoArray
Bill Pay Services API – User Guide
iPay Solutions™
130
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
This array provides a list of available Payee addresses. Not applicable for Transfer accounts. All
available Payee addresses (including both Primary and Rush address, if one is on file for this Payee),
will be included in this array. This array includes the following simple and complex elements:
PayeeAddrId
This is the Bill Pay Services API identifier for the specified address for the Payee.
PayeeAddrType
This specifies the type of payee address. Canonical values are:
• Prim – Primary (default)
• Rush - Rush
PayeeAddr
This complex element contains elements representing the Payee’s address for the specified
Address Type.
StreetAddr1
This is the Payee’s street address.
StreetAddr2 (optional)
This is the second line of the Payee’s street address.
City
This is the name of the city in the Payee’s address.
StateCode
This is the 2-character alpha code approved by the USPS which represents a state.
PostalCode
This is the postal or zip code (Zip+4 is supported).
PayeePhoneArray
This array contains an array of phone information for the specified Payee. Not applicable for Transfer
accounts.
PhoneNum
This represents a phone number, including area code, for the Payee. This must be the
Payee’s Work (Business) number. This is a numeric field that will not accept hyphens.
NOTE: For certain Payees, the Payee Phone Number may now be eligible for
modification.
If the Payee Phone Number is NOT editable, the <Rstr> attribute for this
element will be set to ‘Read-Only’, which indicates that the Service Consumer
should NOT make this element available for update from the requesting user.
PhoneType
This specifies the type of phone number contained in the PhoneNum element (above).
Current canonical values available for Payees for the Bill Pay Services API are:
• Work
• SMS
Bill Pay Services API – User Guide
iPay Solutions™
131
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PayeeEmailArray
This optional array contains the EmailInfo complex element, which includes a package of email data
for the Payee. An email address is available only for Individual Payees with a Payment Method =
‘Email’. If available, only a ‘primary’ email address is applicable for the Payee:
EmailAddr
This element specifies the email address of the Payee.
EmailType
This element specifies to whom the email address applies. Applicable canonical values
required adding a Payee for the Bill Pay Services API are:
• Prim – Primary (default)
BilPaySvcFeeArray
This optional array contains the BilPaySvcFeeInfoRec complex element, which includes a package of
Payment-level Service Fees, or ‘payment surcharges’, applicable for certain types of payments (such
as P2P payments) made to the Payee. The Service Fee will be automatically applied to any payment
that requires a surcharge (as determined by the SvcFeeDesc).
SvcFeeDesc
This element specifies the type of payment or Transfer to which the service fee is applied. A
‘Service Dictionary Search’ request is necessary to obtain the current list of available Service
Fee Descriptions.
SvcFeeAmt
This element specifies the amount of the Service Fee that will be applied to a Payment or
Transfer matching the SvcFeeDesc for the specified Payee.
x_ElecMerPayeeInfo
(As with all ‘x_’ elements, this Payee eBill x_ element will be included in the response only if explicitly
requested in the IncXtendElemArray within the BilPayPayeeInqRq message.)
Not applicable for Transfer accounts.
This optional complex contained within the root BilPayPayeeInqRs contains an array of eBill information
for the specified Payee (the ElecMerPayeeInfoArray). This array contains the ElecMerPayeeInfoRec, a
complex element containing a package of data for each ‘eBiller’ associated with the Payee.
For a Payee who is Eligible (but not yet enrolled) for eBills, this array will contain a package of data for
each eligible eBiller (or product/line of business’that allows eBills) associated with the Payee. In most
cases, there will be only one eBiller associated with a given Payee. However, for some Payees several
types of product lines may exist, and each will have its own package of eBill information.
For example, a large financial services company may have multiple types of financial products available
(e.g., personal and business credit cards, a bank, an insurance company, etc.) In those instances, all
available products must be made available to the subscriber so the correct product can be selected when
setting up the eBill account for a given Payee.
For a Payee who is Enrolled (i.e., has a registered eBill account) or where enrollment is pending
(ElecBilPayeeType = EnrollPend), this array will contain a [single] package of data for the registered or
pending eBill account associated with the Payee.
See Appendix D for additional detail on eBill Account Set up and eBill Account Error Resolution flows.
Bill Pay Services API – User Guide
iPay Solutions™
132
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
The ElecMerPayeeInfoRec complex includes the following simple elements and arrays for the Bill Pay
Services API:
Simple elements:
ElecMerPayeeId
This is the identifier for the ‘eBiller’ (i.e., ‘eBill product’). Each eBiller has its own ‘eBiller ID’.
This element is applicable, and will be returned, only when the Payee’s ElecBilPayeeType (‘eBill
status’) is set to ‘Alw’, meaning the Payee is eligible for eBills, but the subscriber has not yet
registered for an eBill account. An ElectMerPayeeId will be provided for each eBiller (’eBill product’)
available for the specified Payee. Once an eBill account has been set up for the Payee, only the
[below] ElecBilPayeeAcctId (‘eBill Account ID’) is necessary to identify the eBill account.
ElecBilPayeeAcctId
This is the identifier associated with the subscriber’s registered eBill account with the
Merchant/Payee.
This element is applicable when the Payee’s ElecBilPayeeType (‘eBill status’) is set to ‘Enroll’,
meaning the Payee is actively registered for eBills (i.e., has an ‘established’ eBill account). Once an
eBill account has been set up for the Payee, only the eBill Account ID for the registered eBill account
will be returned in the Payee Inquiry response.
ElecMerPayeeURL
This is the URL that contains the eBiller’s electronic address (for the biller’s, or ‘Payee’s’, website).
This may be specific to the given ‘product’.
ElecBilPayeeName
This is the name for the ‘eBiller’ (i.e., the name of the ‘product’ for the Payee) that is often used for
GUI representation understandable to the end-user.
ElecMerPayeeToSStat
This is the status of the eBill Terms of Service acceptance for the given eBill account. Canonical
values are:
• NotActp – not accepted (default value)
• Actp – accepted
• ReqNewActp – requires new acceptance
Acceptance of the eBill Terms of Service is required in order to set up (‘register’) an eBill account.
For a Payee currently registered for eBills where a new Terms of Service acceptance is required by
the eBiller, ongoing eBill activity will continue to be allowed. However, it is assumed that the new
Terms of Service will be presented by the Servicer Consumer to the subscriber/end-user for review
and acceptance (and new acceptance will then be conveyed to the Service Provider via a PayeeMod
request.)
ElecMerPayeeToS
This specifies the entire Terms of Service applicable for the given ‘eBiller’.
The subscriber must agree to the eBiller’s Terms of Service in order to set up (‘register’) an eBill
account for the specified Payee.
NOTE: This element may be delivered as a CDATA section, as it could include (but is not
limited to) HTML and ‘illegal’ XML characters.
Bill Pay Services API – User Guide
iPay Solutions™
133
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
ElecMerAcctStat
This is the current status of the eBill account for the Payee. Canonical values are:
• Act (default) – Active
• Susp – Temporarily Suspended
• PendTer – Pending Termination
This element is applicable (and will be available) only when the Payee’s ElecBilPayeeType (i.e., ‘eBill
status’) is set to ‘Enroll’, meaning the Payee is actively registered for eBills (i.e., has an ‘established’
eBill account).
Notes:
1) An eBill account in ‘temporary suspension’ is temporarily unavailable for eBill updates or
account error resolution. If known, the date the temporary suspension expires will be provided
(ElecMerSuspExpDt). Typically, the eBill account will be returned to ‘active’ status after the
temporary suspension expires.
2) An eBill account that is ‘pending termination’ will become permanently unavailable on the
Pending Termination Date (ElecMerPendTerDt). The eBill account will be ‘unregistered’ on this
date.
ElecMerSuspExpDt
This is the date that a ‘temporary suspension’ of an eBill account will expire. This value may not be
available if the date the temporary suspension expires has not been provided by the eBiller.
ElecMerPendTerDt
This is the date that an eBill account will become permanently unavailable for the Payee. The eBill
account will be automatically ‘unregistered’ on this date.
ElecMerAutoPmtAlw
This indicator specifies whether setup of an automatic payment schedule for eBills is allowed for the
given eBiller. Canonical values are:
• True
• False
[Automatic eBill Payment Schedule Options]:
ElecBilPmtAmtType
This specifies the payment amount option selected for the automatic eBill payment schedule set up
for the Payee. This value is used in combination with the <ElecBilPmtRuleAlgSymb> to determine
the actual intent of the selected payment option. Canonical values are:
• StmtBal – Payment based on statement balance
• MinDue – Pay the minimum due
• AmtDue – Payment based on amount due
• FixedAmt – Pay a fixed amount
NOTE: If the ‘StmtBal/EQ’ option is selected, this will be the amount paid, even if a Current
Balance exists that is different from the Statement Balance.
Bill Pay Services API – User Guide
iPay Solutions™
134
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
ElecBilPmtRuleAlgSymb
This is the algebraic symbol for the eBill payment amount option selection, which determines how the
selected eBill payment amount option will be applied. Canonical values used by the Bill Pay Services
API are:
• EQ – Equal to
• LE – Less than or equal to
ElecBilPmtAmt
This is amount of the payment (specified by the subscriber) that will be paid for the automatically
scheduled eBill.
This value will be available only if the selected Payment Amount Option requires a specified value
(and a value exists).
The following Payment Amount Options are available, based on the specified combinations of
<ElecBilPmtAmtType>, <ElecBilPmtRulAlgSymb> and <ElecBilPmtAmt>:
Table 5 - eBill Auto Payment Options - Payee Inquiry
ElecBil
PmtAmtType
ElecBil
PmtRuleAlgSymb
ElecBil
PmtAmt
Payment Amount Option
StmtBal
EQ
N/A
Always pay [full] Statement Balance
StmtBal
LE
<Amt value>
Only pay Statement Balance if LE
$<PmtAmt>
MinDue
EQ
N/A
Always pay Minimum Due
FixedAmt
EQ
<Amt value>
Always pay $<PmtAmt>
AmtDue
EQ
N/A
Always pay [full] Amount Due
AmtDue
LE
<Amt value>
Only pay Amount Due if LE $<PmtAmt>
ElecBilPmtInstrType
This specifies the payment instruction for the automatically scheduled eBill payment. Canonical
values are:
• ElecMerStmt – Pay immediately when eBill arrives (is received) from eBiller
• ElecBilDueDt – Deliver payment by the [Statement] Due Date
NOTES:
1) The [four] elements above can contain values ONLY if the ElecMerAutoPmtAlw indicator is set
to ‘true’.
2) Automatic Payment Schedule details will be available for registered eBill accounts ONLY if
previously specified by the subscriber.
Arrays:
ElecMerAcctTypeInfoArray
This array contains a list of account types that exist for the eBiller.
In most cases, there will be only one account type associated with a given eBiller. However, for some
eBillers, several different account types may exist. For example, as one of many product lines
available through a large financial services company, a bank (i.e., eBiller) could offer several different
types of accounts: Credit card, mortgage, home equity, auto loan, etc.
Bill Pay Services API – User Guide
iPay Solutions™
135
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
For a Payee who is Eligible, but not yet enrolled for eBills, this array will contain a package of data for
each applicable account type for the given eBiller.
For a Payee who is Enrolled (i.e., has a registered eBill account), this array will contain a [single]
package of data for the account type previously designated by the subscriber during the eBill account
registration process.
This matched pair value array includes the following simple elements:
ElecMerAcctType
This represents the code for the eBiller account type.
ElecMerAcctTypeDesc
This is the description of the eBiller Account Type code, as denoted above.
A Service Dictionary Search request is necessary to obtain the current list of available eBiller
account type codes and descriptions.
ElecMerPayeeCredInfoArray
This array contains a list of the eBiller’s ‘end-user’ credentialing requirements, or connection
parameters, used to identify and authenticate the subscriber. In order to retrieve eBill account
information on behalf of the subscriber, the subscriber’s credentialing information must be provided to
the eBiller.
This array contains the ElecMerPayeeCredInfoRec, a complex element containing a package of data
for each ‘credentialing parameter’ required by the eBiller, and includes the following simple elements:
ElecMerCredType
This specifies the credential type. Canonical values currently utilized by the Bill Pay Services
API are:
• UsrName – User Name
• Pswd – Password
ElecMerCredTypeDesc
This specifies the eBiller’s preferred ‘name’ (or ‘label’) for the credentialing parameter. For
example, if a given eBiller requires a ‘UserName’ credential, this may be displayed on the
eBiller’s website as ‘Login ID’, or ‘UserName’ or ‘Email Address’, or ‘Phone Number’, etc.
ElecMerCredRegEx
This optionally specifies a variable ‘RegEx’ (Regular Expression) validation for the specified
credential. It represents a sequence of characters that convey the pattern requirements,
including (but not necessarily limited to) maximum length and case sensitivity requirements.
Examples are:
• For case sensitivity (Lower Case): ^[a-z0-9]{minlength,maxLength}$
• For case sensitivity (Upper Case): ^[A-Z0-9] {minlength,maxLength}$
• For case sensitivity (Case Insensitive): ^[a-zA-Z0-9] {minlength,maxLength}$
NOTE: The required number of login credential attributes varies by eBiller (for example,
while most biller websites require two (2): the user’s username and password, some may
require more than two, such as when a security PIN is required in addition to the
username and password). Therefore, the Service Consumer must be able to support the
display of (and user entry for) a variable number of credential attributes.
Bill Pay Services API – User Guide
iPay Solutions™
136
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
ElecMerAcctErrInfoArray
This optional array provides a list of eBill account errors that require remediation by the subscriber,
and contains the ElecMerAcctErrInfoRec complex element, which includes a package of data for
each applicable eBill account error. It includes the following simple elements:
ElecMerAcctErrCode
This specifies the eBill account error code for the eBill account error currently associated with
the Payee’s registered eBill account.
ElecMerAcctErrDesc
This provides the description of the eBill account error.
NOTES:
1) If an account error exists for an eBill account, a request is first made to the eBiller prior to
returning this array in order to obtain the ‘latest’ account error information available. No new
eBill activity can occur until the error is resolved.
Resolution of eBill account errors regarding incorrect Login credentials, MFA (Multi-Factor
Authentication) or OTA (One-Time Authentication) issues will require additional information
from the subscriber (needed information for MFA/OTA authentication issues will be itemized
in the AuthenQuesArray—see below) and may require a ‘time-restricted’ response. This
information must be provided via a Payee Mod request. (See Payee Mod section for
additional details.) Other eBill account errors may require subscriber remediation directly via
the Payee’s website.
2) See Appendix E for a complete list of possible eBill account errors that require remediation by
the subscriber.
AuthenQuesArray
This optional array provides a list of additional eBill account authentication requirements required by
the eBiller to complete authentication of the subscriber, and corresponds to eBill account errors
regarding ‘MFA Failure’ (as noted in ElecMerAcctErrInfoArray, above). This array contains the
AuthenQuesRec complex element, which includes a package of data for each MFA authentication
requirement for the Subscriber. It includes the following simple element(s):
AuthenQuesDesc
This specifies the subscriber-specific MFA authentication requirement from the eBiller. This
is often in the form of a ‘randomized’ security challenge question, but can include any type of
additional authentication requirement, as defined by the eBiller.
NOTE: This element may be delivered as a CDATA section, as it could include (but is not
limited to) HTML and ‘illegal’ XML characters.
NOTE: eBiller MFA and OTA authentication processes are often ‘time-restricted’; that is, the
randomized ‘security challenge question’ or OTA requirement(s) presented for user response
are valid only for a specified time period, often as little as 2-10 minutes. After expiration, a
new security challenge question or one-time authentication is required from the eBiller.
Therefore, it is possible that an authentication process will ‘time out’ (i.e., become ‘invalid’) if
too much time passes between the PayeeInquiry response from the Service Provider (iPay
Solutions) that provided the initial MFA or OTA authentication requirement (the
AuthenQuesDesc) and subsequent submission of the subscriber’s ‘answer’ (the
AuthenAnswDesc) via the PayeeModRq.
Bill Pay Services API – User Guide
iPay Solutions™
137
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
In that event, the PayeeModRs response will indicate that a ‘time out’ error has occurred, and
a new PayeeInquiry request is required in order to ‘trigger’ receipt of a new MFA/OTA
authentication requirement from the eBiller and restart the ‘time-clock’.
Also note that some eBiller user authentication methods involve a multi-step response
process, requiring an initial PayeeModRq with the subscriber’s first response
(AuthenAnswDesc), wherein the PayeeModRs response to that request returns another MFA
failure error and an additional AuthenQuesDesc. The response to the additional
authentication question(s) must be returned in a subsequent PayeeModRq, and must be
received within the initially allocated time period in order to avoid a ‘time out’. If a time out
occurs at any step of this multi-step process, the process must be restarted in its entirety,
starting with the request that returned the first MFA failure and AuthenQuesArray (e.g.,
PayeeInquiryRq if obtaining eBill account error resolution information, or PayeeModRq for
initial eBill account setup).
See Appendix D for additional detail on eBill Account Setup and eBill Account Error Resolution
flows.
Arrays
The arrays contained within BilPayPayeeInqRs response message applicable for the Bill Pay Services API
are:
RushOptArray
This array contains an array of possible rush options that are available for the specified Payee and
includes the following simple elements:
RushOpt
This represents the desired option for expediting (rushing) a payment to the specified Payee.
Canonical values are:
• Std – Standard (default) – this specifies a ‘non-expedited’ payment
• Ovrngt – Overnight
• 2ndDay – Second Day
• 2ndDayEc – Second Day Economy
Not all options may be available for the specified Payee. Only those options that are
appropriate for the specified Payee will be returned in the Rush Option Array.
RushOptFeeAmt
This specifies the fee associated with the Rush Option.
RushOptSurChg
This specifies the surcharge that is applicable for Rush payments sent to Puerto Rico. This
surcharge will be automatically applied to any Rush payment request to Puerto Rico.
NOTE: Not applicable for Transfer accounts.
x_CardFundedPayeeArray
(As with all ‘x_’ objects, this CardFunded Payee x_ array will be included in the response only if
explicitly requested in the IncXtendElemArray within the BilPayPayeeInqRq message.)
This optional array contained within the root BilPayPayeeInqRs contains an array of card funded
Payee information.
Bill Pay Services API – User Guide
iPay Solutions™
138
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Complex elements:
CardFundedPayeeInfo
This complex element contains a package of information related to card funded payments.
WebPgURL
This specifies the subscriber’s ‘custom’ URL to be used to access the Payee’s website to
complete a card funded payment.
NOTES:
• This element includes several pieces of information returned as an embedded part of
the URL string:
a) the URL for the Payee’s website
b) A JSON web token (‘JWT’) that includes subscriber-specific information to
enable the card funded payment
c) Company ID, which represents the Service Provider’s (‘iPay’s’) Payee card-
funded identifier
Bill Pay Services API – User Guide
iPay Solutions™
139
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Payee Modify
Container: TPG_BillPayMaster.xsd
Message: BilPayPayeeMod
The bill pay Payee Modification <BilPayPayeeMod> will allow the service consumer to update (modify) certain
elements for a subscriber’s specified Payee or Transfer account, or delete the Payee or Transfer account
entirely. The <SubId>, <PayeeId> and Activity Intent Key <ActIntenKey> are required on the Mod request.
A request that provides the SubId, PayeeId and ActIntentKey along with the delete element (<Dlt>) that is set
to ‘True’ will convey to the service provider to remove (delete) the Payee or Transfer account for the specified
subscriber.
For Payee eBill account management activities (e.g., setting up/registering a new eBill account, managing
eBill account details or error resolution, deleting/unregistering an eBill account, etc.), inclusion of the
ElecMerPayeeInfoRec is required.
The elements at the root request message will be echoed back at the root response, regardless if those same
elements exist in the repeating complex.
Message Flow
The Payee Modification service uses a typical exchange of MType messages to allow updates to Payee or
Transfer account information for a specific subscriber, based on the required subscriber ID and Payee ID. A
Payee Inquiry must always be performed prior to the modification request in order to retrieve the Activity
Intent Key necessary for modification operations.
Request
The third-party consumer forwards the BilPayPayeeModRq request message to the Service Provider.
Bill Pay Services API – User Guide
iPay Solutions™
140
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
The below simple and complex elements contained within the BilPayPayeeModRq message request are
necessary for the Bill Pay Services API.
BilPayProd
This represents the type of iPay Solutions service operations being requested. Canonical values are:
• BilPay
• Remit (reserved for future use)
The BilPayProd default value is ‘BilPay’.
SubId
This is the Service Provider’s (iPay Solutions) identifier for the subscriber.
PayeeId
This is the Bill Pay Services API identifier for the subscriber’s Payee or Transfer account.
ActIntentKey
This is the service provider key delivered to the service consumer via a preceding inquiry request, to
be submitted in the modification request operation.
Dlt
This indicates a desire for deletion of the specified [Payee] entity. Canonical values are:
• True
• False
ElecMerAcctErrCode
This specifies the eBill account error code for the eBill error currently associated with the Payee. This
value must be included in a subsequent Payee Mod request by the Service Consumer when submitting
additional information needed to resolve an eBill setup or eBill account error, as specified in the preceding
Payee Inquiry or Payee Mod response.
A Payee Inquiry response will return eBill account error(s) in the ElecMerAcctErrInfoArray, while a Payee
Mod response will return eBill setup or eBill account error(s) in the MsgRsHdr.
NOTES:
1) If an eBill account setup error (that specifies additional subscriber information is required) is
returned from a preceding Payee Mod request to register an eBill account, the error code
returned in that original response must be included here, along with the additional information
needed to complete setup.
2) If an account error exists for an existing eBill account, no new eBill activity can occur until the
error is resolved. Resolution of eBill account errors regarding incorrect Login credentials or MFA
(Multi-Factor Authentication) issues require additional information from the subscriber, and can be
provided via the Payee Mod request, which must include the eBill account error code returned in
the previous response.
(Other eBill account errors may require subscriber remediation directly via the Payee’s website.)
3) See Appendix D for additional detail on eBill Account Setup and eBill Account Error Resolution
flows.
4) See Appendix E for a complete list of possible eBill account errors that require remediation by
the subscriber.
Bill Pay Services API – User Guide
iPay Solutions™
141
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
BilPayPayeeInfo
This complex element contains a package of data related to the Subscriber’s specified Payee or Transfer
account, and may include all of the simple and complex elements and arrays returned in the preceding
Payee Inquiry response. However, the following are the only elements within this complex that are
eligible for modification (add, update or delete) for a Payee Modification request:
PayeeName
This is the name of the Payee or Transfer account. Modification of this value is not allowed for
Transfer accounts. This is a required element, and therefore cannot be deleted (i.e., cannot be set to
‘Null’).
NOTE: For certain Payees, the Payee Name may now be eligible for modification. If the Payee
Name is NOT editable, the <Rstr> attribute for this element will be set to ‘ReadOnly’ in
the Payee Inquiry response, which indicates that the Service Consumer should NOT
make this element available for update from the requesting user.
PayeeNickname
This represents the Subscriber’s ‘nickname’ for the Payee or Transfer account.
SubMerAcctId
This is the Subscriber’s account number with the Merchant/Payee.
The entered value must pass the Payee’s ‘Account Mask Validation’, if one exists in iPay Solutions’
Payee record for this Payee. If this validation fails, the subscriber must either correct the account
number to match the Payee’s specified account mask, or delete this Payee and re-add as a new
Payee.
This element is not available for modification for P2P Payees or Transfer accounts.
SubMerPayerName
This is the Subscriber’s name understood by the merchant and is used to override the Subscriber’s
name on record.
This element is not available for modification for P2P Payees or Transfer accounts.
PayeeCatName (reserved for future use)
The name of the category assigned to the Payee or Transfer account
[Payee] PmtIntentType
This represents the payment intention of the Payee. Canonical values are:
• PayBill - Payment for a bill (default)
• XferToSubFinInst - Transfer to subscriber account at external FI (Outbound)
• XferFromSubFinInst - not supported by iPay Solutions at this time
• XferTo - not supported by iPay Solutions at this time
• XferFrom - not supported by iPay Solutions at this time
The Payee’s PmtIntentType must be appropriate for the specified Payee Classification (e.g., for FI
Payees – Transfer Accounts), only Xfer-type values are appropriate).
Bill Pay Services API – User Guide
iPay Solutions™
142
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PayeeP2PType
This element specifies the type of communication method to be used for person-to-person Payee
contact.
Applicable only for P2P Payees (where PayeePmtMthd = ‘Email’). This element is a required element
for P2P Payees and therefore cannot be deleted (i.e., cannot be set to ‘JHANull’). iPay Solutions will
ignore entries for any other Payee type. Canonical values are:
• SMS (‘Text’)
• Email
NOTE: A Mobile (‘SMS’) Phone Number is required for the P2P Payee to set up the P2P Payee
using the ‘SMS’ PayeeP2PType. Likewise, an Email address is required for the P2P Payee
to set up the P2P Payee using the ‘Email’ PayeeP2PType.
PayFromAcctInfo
This optional complex element contains information on the ‘default’ funding account (‘pay from
account’) designated for the specified Payee or Transfer account.
PayFromId
This is the Bill Pay Services API identifier for the Payee’s designated funding account.
This is the only element necessary to specify the desired ‘default’ funding account for the
Payee or Transfer account.
If the Payee’s funding account is not specified, the funding account designated as the Subscriber’s
default funding account will be used.
NOTE: Funding account (‘pay from account’) information (other than the subscriber’s default
funding account) can be specified only if the requesting user has been granted permission
to ‘Designate Pay From Accounts’.
PayeeFIAcctInfo
This optional complex element contains a package of financial deposit account information (allowed
only for the Individual Payee with an ‘Electronic’ Payment Method and for Transfer accounts).
FIRtId
The Bank Routing Number (ABA number) of the Payee’s Bank (deposit) account.
FIAcctId
Payee’s Bank Account Number or, for Transfer accounts, subscriber’s account number at FI.
FIAcctType
This represents the type of deposit account for the Payee or Transfer account. Canonical
values are:
• D – Checking
• S – Savings
This complex element is not available for modification for Transfer accounts.
Bill Pay Services API – User Guide
iPay Solutions™
143
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PayeeAddrInfoArray
This array provides the ability to update an array of payee addresses. A primary address is required
for Company Payees (i.e. can be updated, but not be deleted). The payee’s address is an optional
entry for ‘P2P’ Payees, and for ‘Individual Electronic’ Payees (where PayeeClsf = ‘Indv’ and
PayeeFIAcctInfo is provided). Entry or update of payee’s address is not allowed for Transfer
accounts. This array includes the following (optionally editable) simple and complex elements:
PayeeAddrType
This specifies the type of payee address. Canonical values are:
• Prim – Primary (default)
• Rush - Rush
PayeeAddr
This complex element contains elements representing the Payee’s address for the specified
Address Type.
StreetAddr1
This is the Payee’s street address.
StreetAddr2 (optional)
This is the second line of the Payee’s street address.
City
This is the name of the city in the Payee’s address.
StateCode
This is the 2-character alpha code approved by the USPS which represents a state.
PostalCode
This is the postal or zip code (Zip+4 is supported).
NOTE: It should be noted that, in order to leverage check processing efficiencies gained from
iPay Solutions’ Merchant Management process, the [primary] Payee Address provided may not
always be the address used for a check.
PayeePhoneArray
This array contains an array of phone information for the specified Payee. Not applicable for Transfer
accounts. This is a required element, and therefore cannot be deleted (i.e., cannot be set to
‘JHANull’).
PhoneNum
This represents a phone number, including area code, for the Payee. This is the Payee’s
Work (Business) number.
NOTE: For certain Payees, the PhoneNum may now be eligible for modification. If the
Payee Phone Number is NOT editable, the <Rstr> attribute for this element will be set
to ‘ReadOnly’ in the Payee Inquiry response, which indicates that the Service Consumer
should NOT make this element available for update from the requesting user.
PhoneType
This specifies the type of phone number contained in the PhoneNum element (above).
Current canonical values available for Payees for the Bill Pay Services API are:
• Work (required for Company Payees)
• SMS
NOTES:
1) ‘SMS’ PhoneType is required for an Individual Payee when PayeeP2PType = ‘SMS’.
2) ‘Work’ Phone Type is required for Company Payees.
Bill Pay Services API – User Guide
iPay Solutions™
144
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
3) It should be noted that, in order to leverage payment processing efficiencies gained
from iPay Solutions’ Merchant Management process for Company Payees, the
Payee PhoneNum provided may not always be the phone number returned on
subsequent Payee inquiries.
PayeeEmailArray
This optional array contains the EmailInfo complex element, which includes a package of email data
for the Payee. An email address is available only for Individual Payees with a Payment Method =
‘Email’. If available, only a ‘primary’ email address is applicable for the Payee:
EmailAddr
This element specifies the email address of the Payee.
EmailType
This element specifies to whom the email address applies. Applicable canonical values
required adding a Payee for the Bill Pay Services API are:
• Prim – Primary (default)
ElecMerPayeeInfoRec
Not applicable for Transfer accounts.
This optional complex element contains a package of data related to the Subscriber’s selected eBiller for
the Payee (in the case of a request to set up, or ‘register’, an eBill account for the Payee), or eBill
Account information (if the Payee is already enrolled, or ‘registered’, for eBills), and may include all of the
simple and complex elements and arrays returned in the preceding Payee Inquiry response. However,
the following are the only elements within this complex that are eligible for modification (add, update or
delete) for a Payee Modification request:
Simple elements:
ElecMerPayeeId
This is the identifier for the ‘eBiller’ selected by the Subscriber when electing to set up an eBill
account for the Payee, and is required in order to complete eBill account setup.
Once an eBill account has been set up for the Payee, only the [below] ElecBilPayeeAcctId (‘eBill
Account ID’) is necessary to identify the eBill account.
ElecBilPayeeAcctId
This is the identifier associated with the Subscriber’s registered eBill account with the
Merchant/Payee.
This element is applicable when the Payee’s ElecBilPayeeType (i.e., ‘eBill status’) is set to ‘Enroll’,
meaning the Payee is actively registered for eBills (i.e., has an ‘established’ eBill account). Once an
eBill account has been set up for the Payee, only the eBill Account ID is necessary to identify the eBill
account associated with the Payee.
Bill Pay Services API – User Guide
iPay Solutions™
145
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
ElecMerPayeeToSStat
This is the status of the eBill Terms of Service acceptance for the given eBill account. Canonical
values are:
• NotActp – not accepted (default value)
• Actp – accepted
• ReqNewActp – requires new acceptance
Acceptance (‘Actp’) of the eBill Terms of Service is required in order to set up (‘register’) an eBill
account.
For a Payee currently registered for eBills where a new Terms of Service acceptance is required by
the eBiller, ongoing eBill activity will continue to be allowed. However, it is expected that the Service
Consumer will require new acceptance of the ToS by the Subscriber/end-user, which would then be
conveyed to the Service Provider via a PayeeMod request.
NOTE: It is assumed that submission of a ToS ‘Acceptance’ implies that all required Terms of
Service have been presented by the Service Consumer to the end-user, and that the Service
Consumer has received explicit acceptance from the end-user.
[Automatic eBill Payment Schedule Options]:
ElecMerAutoSuspType
This indicates the Subscriber’s desire to stop an automatic eBill payment schedule, and allows the
Subscriber to choose to stop the automated schedule immediately, or after any currently scheduled
automatic eBill payment(s) for the associated Payee are processed. Canonical values are:
• Perm – This stops the automatic eBill payment schedule immediately, and stops any currently-
scheduled eBill payments for the associated Payee.
• NxtBil – This stops the automatic eBill payment schedule immediately, but processes all
currently-scheduled eBill payment(s) for the associated Payee.
ElecBilPmtAmtType
This specifies the payment amount option selected for the automatic eBill payment schedule set up
for the Payee. This value is used in combination with the <ElecBilPmtRuleAlgSymb> to determine
the actual intent of the selected payment option. Canonical values are:
• StmtBal – Payment based on statement balance
• MinDue – Pay the minimum due
• AmtDue – Payment based on amount due
• FixedAmt – Pay a fixed amount
NOTES:
1) The ‘AmtDue’ option is not a valid selection for ‘CCA’ (Credit Card) account types.
2) The ‘StmtBal’ and ‘MinDue’ options are valid selections ONLY for ‘CCA’ (Credit Card)
account types.
3) If the ‘StmtBal/EQ’ option is selected, this will be the amount paid, even if a Current Balance
exists that is different from the Statement Balance.
Bill Pay Services API – User Guide
iPay Solutions™
146
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
ElecBilPmtRuleAlgSymb
This is the algebraic symbol for the automatic eBill payment option selection, which determines how
the selected eBill payment option will be applied. Canonical values used by the Bill Pay Services API
are:
• EQ – Equal to
• LE – Less than or equal to
ElecBilPmtAmt
This is amount of the payment (specified by the Subscriber) that will be paid for the automatically
scheduled eBill.
Entry of this value is allowed only if the selected Payment Amount Option and ‘algebraic symbol’
combination requires a specified value.
The following Payment Amount Options are available, based on the specified combinations of
<ElecBilPmtAmtType>, <ElecBilPmtRulAlgSymb> and <ElecBilPmtAmt>:
Table 6 - eBill Auto Payment Options - Payee Mod
ElecBil
PmtAmtType
ElecBil
PmtRuleAlgSymb
ElecBil
PmtAmt
Payment Amount Option
Valid for
Acct
Type(s)
StmtBal
EQ
N/A
Always pay Statement
Balance
CCA
StmtBal
LE
<Amt value>
Only pay Statement Balance
if LE $<PmtAmt>
CCA
MinDue
EQ
N/A
Always pay Minimum Due
CCA
FixedAmt
EQ
<Amt value>
Always pay $<PmtAmt>
All
AmtDue
EQ
N/A
Always pay [full] Amount Due
‘non-CCA’
AmtDue
LE
<Amt value>
Only pay Amount Due if LE
$<PmtAmt>
‘non-CCA’
ElecBilPmtInstrType
This specifies the desired payment instruction for the automatically scheduled eBill payment.
Canonical values are:
• ElecMerStmt – Pay immediately when eBill arrives (is received) from eBiller
• ElecBilDueDt – Deliver payment by the [Statement] Due Date
NOTE: Entry of any/all of the above ‘automatic eBill payment schedule’ elements is allowed
ONLY if the ElecMerAutoPmtAlw indicator is set to ‘true’ for the specified eBiller (see
preceding Payee Inquiry response).
Arrays:
Bill Pay Services API – User Guide
iPay Solutions™
147
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
ElecMerAcctTypeInfoArray
This array contains a single ElecMerAcctTypeInfoRec denoting the ‘account type’ specified for the
selected eBiller. In the case where multiple account types are applicable for a given eBiller, the
Subscriber must select the account type that is desired when setting up the Payee’s eBill account.
For a Payee who is ‘Enrolled’ (i.e., has a registered eBill account), this array will contain a [single]
package of data for the account type previously selected by the Subscriber during the eBill account
registration process.
This array includes the following simple elements:
ElecMerAcctType
This represents the account type specified by the Subscriber for the eBill account.
NOTE: The list of available ‘account types’ applicable for a given eBiller (or eBill account) will
be returned in the preceding Payee Inquiry response.
ElecMerPayeeCredInfoArray
This optional array contains a list of the Subscriber’s credentialing requirements, or ‘connection
parameters’, for the specified eBiller or eBill account (if already registered). In order to retrieve eBill
account information on behalf of the Subscriber, the Subscriber’s credentialing information must be
provided to the eBiller to gain access to the specified eBill account.
This information is required upon initial setup of the eBill account, and updated credentials must be
provided periodically if the Subscriber’s credentials for the specified eBiller are changed or updated.
(For example, if an eBill account is currently unavailable due to a ‘Login Failure’, the Subscriber’s
updated credentials must be submitted in order to regain access to eBill account information.)
This array contains the ElecMerPayeeCredInfoRec, a complex element containing a package of data
for each ‘credentialing parameter’ provided by the Subscriber, and includes the following simple
elements:
ElecMerCredType
This specifies the credential type for the entered value. Canonical values currently utilized by
the Bill Pay Services API are:
• UsrName – User Name
• Pswd – Password
ElecMerCredValue
This specifies the Subscriber’s actual value for the specified credential type, and is subject to
the limits provided in the ElecMerCredRegEx expression returned in the preceding Payee
Inquiry response.
AuthenQuesArray
This optional array contains a list of the Subscriber’s response(s) to multi-factor (‘MFA’) or one-time
(‘OTA’) authentication requirements required by the eBiller in order to complete authentication of the
Subscriber, and corresponds to eBill errors regarding ‘MFA Failure’ that were provided in the
preceding Payee Inquiry or Payee Mod response. This array contains the AuthenQuesRec complex
element, which includes the Subscriber’s response for each authentication requirement by the eBiller.
It includes the following simple element(s):
AuthenAnswDesc
This specifies the Subscriber-provided answer to the MFA/OTA requirement from the eBiller.
Bill Pay Services API – User Guide
iPay Solutions™
148
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
NOTE: eBiller MFA and OTA authentication processes are often ‘time-restricted’; that is, the
randomized ‘security challenge question’ or OTA requirement(s) presented for user response are
valid only for a specified time period, often as little as 2-10 minutes. After expiration, a new security
challenge question or one-time authentication code is required from the eBiller.
Therefore, it is possible that an authentication process will ‘time out’ (i.e., become ‘invalid’) if too
much time passes between the PayeeInquiry or PayeeMod response from the Service Provider (iPay
Solutions) that provided the initial MFA or OTA authentication requirement (the AuthenQuesDesc)
and subsequent submission of the Subscriber’s ‘answer’ (the AuthenAnswDesc) via the
PayeeModRq.
In that event, the PayeeModRs response will indicate that a ‘time out’ error has occurred, and the
original request that prompted the MFA/OTA authentication (e.g., PayeeInquiryRq for obtaining eBill
account error resolution information, or PayeeModRq for initial eBill account setup) must be retried in
order to ‘trigger’ receipt of a new MFA/OTA authentication requirement from the eBiller and a restart
of the ‘time-clock’.
Also note that some eBiller user authentication methods involve a multi-step response process,
requiring an initial PayeeModRq with the Subscriber’s first response (AuthenAnswDesc), wherein the
PayeeModRs response to that request returns another MFA failure error and an additional
AuthenQuesDesc. The response to the additional authentication question(s) must be returned in a
subsequent PayeeModRq, and must be received within the initially allocated time period in order to
avoid a ‘time out’. If a time out occurs at any step of this multi-step process, the process must be
restarted in its entirety, starting with the request that returned the first MFA failure and
AuthenQuesArray (e.g., PayeeInquiryRq if obtaining eBill account error resolution information, or
PayeeModRq for initial eBill account setup).
See Appendix D for additional detail on eBill Account Setup and eBill Account Error Resolution
flows.
Payee Mod Behaviors
• For Company Subscribers:
o Payees can be added or modified only if the requesting user (subscriber’s associated user) has
been granted permission to Manage Payees. Further, Payee information can be modified only if
the requesting user has been granted permission to ‘manage’ the specified Payee.
o Transfer accounts can be modified only if the requesting user (subscriber’s associated user)
has been granted permission to Manage Transfer Accounts.
o Funding account (‘pay from account’) information can be modified for the Payee only if the
requesting user has been granted permission to ‘Designate Pay From Accounts’.
• To select a new default funding account for a Payee, the third-party consumer must first perform a
Subscriber Inquiry to get a list of funding accounts from which to choose.
• iPay Solutions will ignore all element values other than those specified above, if passed on a Payee
Mod request.
• In order to change any Payee elements other than those specified above, a delete of the existing
Payee record and a re-add of the Payee with the new values is required. For P2P Payees, a new P2P
Setup process will be required.
Bill Pay Services API – User Guide
iPay Solutions™
149
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
• For a Payee Delete request, a Pending Payments Exist fault will be returned if pending payments
exist for the specified Payee. This error states: “Pending payments are associated with this Payee.
Deleting Payee will stop all associated pending payments.”
o The third-party consumer can override this fault by providing an error override. If provided, iPay
Solutions will stop all pending payments associated with the Payee to be deleted and move
them to Payment History. The Payee will then be deleted as requested.
• NOTE: While the Payee Address can be updated at any time, the updated address will be only be
utilized in the following scenarios:
o For future scheduled payments that must be sent by check to Merchants whose ‘preferred’
payment method is ‘electronic’.
▪ Any newly scheduled or recurring ‘electronic-to-check’ payment added after a successful Payee
Mod to add or update the address will use the new address; all previously scheduled ‘electronic-
to-check’ payments will continue to use the Payee Address that was available at the time the
payment was added.
o For check payments to Payees that are exclusive to the subscriber (i.e., exist only for the given
subscriber, such as payments to individuals, etc.)
It is advisable for the Service Consumer to display a message to the end-user when the Address update
will NOT impact the address where the check payment will ultimately be sent.
• eBill Accounts:
o Setting up (‘registering’) an eBill account:
▪ Initial Request - The following elements are required when initially requesting to set up an
eBill account:
• ElecMerPayeeId (‘eBiller ID’)
• ElecMerPayeeToSStat
o Must be set to ‘Actp’ in order to complete eBIll account registration
o It is assumed that submission of a ToS ‘Acceptance’ implies that all required
Terms of Service have been presented by the Service Consumer to the end-user,
and that the Service Consumer has received explicit acceptance from the end-
user.
• ElecMerAcctType (within ElecMerAcctTypeInfoArray)
• ElecMerPayeeCredInfoArray
• Automatic eBill payment schedule details (optional)
▪ Additional Information Needed to Complete Setup - The following elements are required
when a subsequent modification request (PayeeModRq) is required, supplying additional
information needed to complete the setup of an eBill account (based on the preceding Payee
Mod response):
• ElecMerPayeeId (‘eBiller ID’)
• ElecMerAcctErrCode (returned in preceding Payee Mod response)
• Additional information:
o ElecBilPayeeAcctId (matched eBill account ID) – (required for ‘account match’
error code E6521)
▪ Must be returned in the ElecBilPayeeAcctId field on subsequent
PayeeModRq
Bill Pay Services API – User Guide
iPay Solutions™
150
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
▪ Entries here will be ignored for any other error condition
o ElecMerPayeeCredInfoArray (required for ‘Login Failure’ error E6513)
▪ All applicable ElecMerCredVal elements must be returned in the response.
o AuthenQuesArray (required for ‘MFA Failure’ error E6518 or E6519)
▪ Entries here will be ignored for any other error condition
▪ The ability to add an eBill account for a Payee is available via the PayeeMod request, but
only for those FIs that have included this feature for the specified product.
o Resolving registered eBill account error conditions:
▪ The following elements are required when a Payee modification request is submitted,
supplying additional information needed to resolve an eBill account error condition (based on
preceding Payee Inquiry or Payee Mod response):
• ElecBilPayeeAcctId
• ElecMerAcctErrCode (returned in preceding Payee Inq or Payee Mod response)
• Additional information:
o ElecMerPayeeCredInfoArray (required for ‘Login Failure’ error E6551)
▪ All applicable ElecMerCredVal elements must be returned in the response.
o AuthenQuesArray (required for ‘MFA Failure’ errors E6550 or E6519)
▪ Entries here will be ignored for any other error condition
▪ Requests to resolve eBill account error conditions should be executed within a short period of
time after a PayeeInquiryRs or PayeeModRs specifies an eBill Account Error that requires
Subscriber remediation. Delays may result in a ‘session time out’ error, which requires that
the process be restarted.
o See Appendix D for additional detail on eBill Account Setup and eBill Account Error Resolution
flows.
o See Appendix E for a complete list of possible eBill account errors that require remediation by the
Subscriber.
o Modifying existing eBill account details:
▪ Only the following elements are editable when modifying an existing eBill account:
• ElecMerPayeeToSStat
• ElecMerPayeeCredInfoArray
o If updated, all applicable ElecMerCredVal elements must be returned in the
response.
• ElecMerAutoSuspType
• Automated eBill payment schedule details:
o ElecBilPmtAmtType
o ElecBilPmtRuleAlgSymb
o ElecBilPmtAmt
o ElecBilPmtInstrType
Bill Pay Services API – User Guide
iPay Solutions™
151
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
o Deleting (‘unregistering’) an existing eBill account:
▪ Deletes of eBill account(s) are allowed via the PayeeMod request.
• Existing eBill history for the deleted eBill account will continue to be made available to
the Subscriber.
• Any associated automatic eBill payment schedule for the Payee will be stopped
immediately upon delete of the eBill account.
Response
The service provider (iPay Solutions) returns the BilPayPayeeModRs response message to the service
consumer.
The simple element(s) contained within the BilPayPayeeModRs response applicable for the Bill Pay
Services API is/are:
RsStat
This specifies the status of the mod request. Canonical values are:
• Success
• Fail
NOTE: Any modification request errors associated with eBill account setup or account remediation
activities will be returned in the MsgRsHdr with an Error Category <ErrCat> canonical value as
~Fault~ in order to be able to provide the consumer with information related to the error. This
could optionally include the Authentication Question Array (AuthenQuesArray) or the Electronic
Merchant Account Identification Array (ElecMerAcctIdArray) (see below).
The array(s) contained within the BilPayPayeeModRs response for the Bill Pay Services API (that are
applicable for eBill account activity) are:
AuthenQuesArray
This optional array provides a list of additional authentication requirements required by the eBiller to
complete authentication of the Subscriber, and corresponds to eBill setup or eBill account errors
regarding ‘MFA Failure’. This array contains the AuthenQuesRec complex element, which includes a
package of data for each MFA authentication requirement for the Subscriber. It includes the following
simple element(s):
AuthenQuesDesc
This specifies the Subscriber-specific MFA or OTA authentication requirement from the eBiller. This
is often in the form of a ‘randomized’ security challenge question, but can include any type of
additional authentication requirement, as defined by the eBiller.
NOTE: This element may be delivered as a CDATA section, as it could include (but is not limited
to) HTML and ‘illegal’ XML characters.
NOTE: eBiller MFA and OTA authentication processes are often ‘time-restricted’; that is, the
randomized ‘security challenge question’ or OTA requirement(s) presented for user response are v
alid only for a specified time period, often as little as 2-10 minutes. After expiration, a new security
Bill Pay Services API – User Guide
iPay Solutions™
152
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
challenge question or one-time authentication code is required from the eBiller.
Therefore, it is possible that an authentication process will ‘time out’ (i.e., become ‘invalid’) if too
much time passes between the PayeeInquiry or PayeeMod response from the Service Provider (iPay
Solutions) that provided the initial MFA or OTA authentication requirement (the AuthenQuesDesc)
and subsequent submission of the Subscriber’s ‘answer’ (the AuthenAnswDesc) via the
PayeeModRq.
In that event, the PayeeModRs response will indicate that a ‘time out’ error has occurred, and the
original request that prompted the MFA/OTA authentication (e.g., PayeeInquiryRq for obtaining eBill
account error resolution information, or PayeeModRq for initial eBill account setup) must be retried in
order to ‘trigger’ receipt of a new MFA/OTA authentication requirement from the eBiller and a restart
of the ‘time-clock’.
Also note that some eBiller user authentication methods involve a multi-step response process,
requiring an initial PayeeModRq with the Subscriber’s first response (AuthenAnswDesc), wherein the
PayeeModRs response to that request returns another MFA failure error and an additional
AuthenQuesDesc. The response to the additional authentication question(s) must be returned in a
subsequent PayeeModRq, and must be received within the initially allocated time period in order to
avoid a ‘time out’. If a time out occurs at any step of this multi-step process, the process must be
restarted in its entirety, starting with the request that returned the first MFA failure and
AuthenQuesArray (e.g., PayeeInquiryRq if obtaining eBill account error resolution information, or
PayeeModRq for initial eBill account setup).
ElecMerAcctIdArray
This optional array provides a list of the Subscriber’s accounts with the eBiller, and is returned when an
exact match cannot be determined for an account identification being registered for the Subscriber.
Return of this information permits the Service Consumer to present the accounts so the Subscriber may
register the correct account identification.
This array corresponds to eBill setup error number E6521, and contains the ElecMerAcctIdInfoRec
complex element, which includes a package of data for each Subscriber account found with the specified
eBIller. It includes the following simple element(s):
ElecMerAcctId
This specifies the identifier for the eBill account generated by the Service Provider to be returned in a
subsequent Payee Mod, enabling the Service Consumer to submit the correct account identification
to be registered once the Subscriber has selected the appropriate account to complete eBill account
setup.
NOTE: The selected value must be returned in a subsequent Payee Mod request in the
ElecBilPayeeAcctId field, along with the ElecMerAcctErrCode returned in the preceding
Payee Mod response.
SubMerAcctId
This is the Subscriber’s account number with the Merchant/Payee, returned from the eBiller (and is
often presented as a ‘masked’ account number).
ElecMerAcctAliasName
This is the name for the ‘eBiller’s account’ that is often used for GUI representation understandable to
the end-consumer.
See Appendix E for a complete list of possible eBill account errors that require remediation by the Subscriber.
Bill Pay Services API – User Guide
iPay Solutions™
153
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Payment Services
Payment Add
Container: TPG_BillPayMaster.xsd
Message: BilPaySchedPmtAdd
The bill pay Payment Add <BilPaySchedPmtAdd> will allow the service consumer to schedule (add) a single
or recurring Payment or Transfer for a specific Subscriber. The subscriber identification element <SubId> is
required on the Payment Add request.
The elements at the root request message will be echoed back at the root response, regardless if those same
elements exist in the repeating complex.
Message Flow
The Scheduled Payment Add service uses a typical exchange of MType messages to allow the subscriber to
schedule a single or recurring Payment or Transfer from their bill pay account.
Bill Pay Services API – User Guide
iPay Solutions™
154
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Request
The third-party consumer forwards the BilPaySchedPmtAddRq request message to the Service Provider.
The below simple and complex elements contained within the BilPaySchedPmtAddRq message request are
necessary for the Bill Pay Services API.
BilPayProd
This represents the type of iPay Solutions service operations being requested. Canonical values are:
• BilPay
• Remit (reserved for future use)
The BilPayProd default value is ‘BilPay’.
SubId
This is the Service Provider’s (iPay Solutions) identifier for the subscriber.
BilPaySchedPmtInfo
This complex element contains a package of data related to a scheduled single or recurring Payment or
Transfer, and includes the below simple and complex elements and arrays necessary to add a scheduled
single or recurring payment or Transfer using the Bill Pay Services API. This complex is required for the
request; however, many of the child nodes encapsulated are optional.
Simple elements:
PmtProcDt
This is the Process Date for a single payment or Transfer. This date cannot be less than the First
Available Process Date for the specified Payee or Transfer account. (For recurring payment series
dates, see the RecurPmtInfo complex below.)
This date is required for all single payments or Transfers for FIs that utilize the ‘Process Date’
payment date model, and should NOT be completed when adding a recurring payment or transfer
series. iPay Solutions will ignore a value submitted for this element for FIs that utilize the ‘Due Date’
payment date model.
PmtEstArvDt
This is the Estimated Arrival Date (i.e. ‘Due Date’) for a single payment or Transfer to the Payee or
Transfer account. This date cannot be less than the First Available Estimated Arrival Date for the
specified Payee or Transfer account. (For recurring payment series dates, see the RecurPmtInfo
complex below.)
This date is required for all single payments or Transfers for FIs that utilize the ‘Due Date’ payment
date model, and should NOT be completed when adding a recurring payment or transfer series. iPay
Solutions will ignore a value submitted for this element for FIs that utilize the Process Date payment
date model.
PmtAmt
This is the amount of the single scheduled payment or Transfer or, for a recurring series, the
amount of each payment or Transfer in the series.
PmtCmnt
This is the comment that will be stored with the payment(s) or Transfer(s). This is for the Subscriber’s
internal use only and is not included with the Payment. Entry is limited to a 1000-character string.
Bill Pay Services API – User Guide
iPay Solutions™
155
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PmtChkMemo
This is the memo to be added to a check associated with a check payment. Entry is limited to 25
characters.
iPay Solutions will ignore a value submitted for this element for any non-check payments (including
SubCmntToPayee
This is the personalized message that will be added to the email sent to a P2P payment recipient
notifying them that a payment has been made. Entry is limited to 500 characters for email notification
(25 characters for text messages).
[Payment] PmtIntentType
This represents the payment intention for the Payment(s) or Transfer(s). Canonical values are:
• PayBill - Payment for a bill (default)
• XferToSubFinInst - Transfer to Subscriber account at external FI (Outbound)
• XferFromSubFinInst - not supported by iPay Solutions at this time
• XferTo - not supported by iPay Solutions at this time
• XferFrom - not supported by iPay Solutions at this time
NOTE: Until such time as additional Transfer options are available, the PmtIntentType of the
Payment or Transfer will be automatically set to match the PmtIntentType of the Payee or Transfer
account. iPay Solutions will ignore a value submitted for this element.
Complex elements:
PmtPayeeInfo
This required complex element contains a package of data related to the intended Payee or Transfer
account who will receive the payment(s) or Transfer(s).
PayeeId
This is the Bill Pay Services API identifier for the Subscriber’s Payee or Transfer account.
This is the only element necessary to identify the desired Payee for the Scheduled or
recurring payment(s) or Transfer(s).
PayeeAddrInfo
This complex is required for Rush payments (only), and provides the ability to specify the
Payee’s Rush Address to be used for the payment. An address is required only for Overnight
and 2
nd
Day rush payment options, as these payments are always sent via check. This
complex includes the following simple and complex elements:
PayeeAddrId
This is the Bill Pay Services API identifier for the specified Rush address for the
Payee.
This is the only element required if the Rush Address provided via the preceding
Payee Inquiry is the desired address to be used for the Rush payment.
PayeeAddrType
This specifies the type of payee address being submitted. For Rush payments, the
only applicable Payee Address Type is ‘Rush’. Canonical values are:
• Prim – Primary (default)
• Rush - Rush
Bill Pay Services API – User Guide
iPay Solutions™
156
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PayeeAddr
This complex element contains elements representing the Payee’s Rush address,
and is required for the Rush payment if no Rush Address exists for the Payee (i.e., no
Rush Address information was returned in the preceding Payee Inquiry), or the
Subscriber chooses not to use the Rush Address provided via the Payee Inquiry.
StreetAddr1
This is the Payee’s street address for Rush payments.
StreetAddr2 (optional)
This is the second line of the Payee’s street address for Rush payments.
City
This is the name of the city in the Payee’s Rush payment address.
StateCode
This is the 2-character alpha code approved by the USPS which represents a
state.
PostalCode
This is the postal or zip code (Zip+4 is supported).
PmtRushOptInfo
This optional complex element contains information on the Rush payment options desired for the
specified payment. Not applicable for Transfers.
RushOpt
This represents the desired option for expediting (rushing) the payment to the Payee.
Canonical values are:
• Std – Standard (default) – this specifies a ‘non-expedited’ payment.
• Ovrngt – Overnight
• 2ndDay – Second Day
• 2ndDayEc – Second Day Economy
Not all options may be available for the specified Payee. Only those options that are
appropriate for the specified Payee may be utilized for a Rush payment to this Payee.
Eligible Rush options the Payee can be obtained from the preceding Payee Inquiry request.
This is the only element necessary to identify the desired Rush payment option for the
Scheduled payment.
PmtPayFromAcctInfo
This optional complex element contains information on the funding account (‘pay from account’) to be
used for the specified Payment(s) or Transfer(s).
PayFromId
This is the Bill Pay Services API identifier for the funding account.
This is the only element necessary to specify the desired funding account for the Payment or
Transfer.
Bill Pay Services API – User Guide
iPay Solutions™
157
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
If the funding account for the payment or Transfer is not specified, the funding account designated as
the Payee’s default funding account will be used.
NOTE: Funding account (‘pay from account’) information (other than the default funding account
previously designated for the Payee) can be specified only if the requesting user has been
granted permission to ‘Designate Pay From Accounts’.
RecurPmtInfo
This optional complex element contains a package of scheduling data related to a recurring payment
or recurring Transfer series, and includes the below simple elements and arrays necessary to add a
recurring payment or recurring Transfer series using the Bill Pay Services API.
StartPmtProcDt
This is the starting date for processing a new recurring payment or Transfer series. This date
cannot be less than the First Available Process Date for the specified Payee that would be
available based on Frequency and Payment Day selections.
This date is required for all recurring payments for FIs that utilize the ‘Process Date’ payment
date model. iPay Solutions will ignore a value submitted for this element for FIs that utilize
the Due Date payment date model.
StartPmtEstArvDt
This is the starting estimated arrival date (i.e., due date) for a new recurring payment or
recurring Transfer series. This date cannot be less than the First Available Estimated Arrival
Date for the specified Payee that would be available based on Frequency and Payment Day
selections.
This date is required for all recurring payments for FIs that utilize the ‘Due Date’ payment
date model. iPay Solutions will ignore a value submitted for this element for FIs that utilize
the Process Date payment date model.
PmtFreqUnits
This is the payment frequency for a recurring payment or recurring Transfer series. A
specified frequency of ‘Once’ indicates a ‘single’ (i.e. not a recurring) payment. Canonical
values are:
• Once (default)
• Weekly
• EveryOtherWeek
• Every4Weeks
• Monthly
• TwiceMonthly
• EveryOtherMonth
• Every3Months
• Every6Months
• Annual
Bill Pay Services API – User Guide
iPay Solutions™
158
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PmtDayOfWeek
This is the desired day of the week when recurring payments or Transfers will be made if the
specified payment frequency is: ‘Weekly’, ‘EveryOtherWeek’ or ‘Every4Weeks’. Canonical
values are:
• Mon - Monday
• Tues - Tuesday
• Wed - Wednesday
• Thur - Thursday
• Fri - Friday
PmtDayInfoArray
This optional array contains the PmtDayInfo complex element, which includes a package of
data related to the day(s) of the month a recurring payment or Transfer should be made if the
payment frequency has been specified as ‘Monthly’, ‘TwiceMonthly’, ‘EveryOtherMonth’,
‘Every3Months’, ‘Every6Months’ or ‘Annual’. It includes the following simple elements:
PmtDayofMonth
This is the day of the month when the recurring payment or Transfer will be made
(e.g., 1 - 31). This value is not required if the desired payment day is to be the last
business day of each month.
PmtUseLastBusDay
This indicates that the payment or Transfer should be made on the last business day
of the month. Canonical values are:
• True
• False (default)
PayDtInstr
This is the payment date instruction when a recurring payment or Transfer date falls on a
non-processing date (such as a weekend or holiday). Canonical values are:
• Before – Pay before (default)
• After – Pay after
PmtOccur
This is the number of desired payment occurrences for the recurring payment or recurring
Transfer series. Valid values are between 1 and 9999.
PmtSerExpDt
This is the expiration date for the recurring payment or recurring Transfer series. The final
payment in the series will be made on this date. This date can be any date in the future, but
cannot be less than the Starting Payment Date.
PmtSerFinite
This indicates whether the payment or Transfer series is finite or ‘has no end’. If the series is
not finite, recurring payments or Transfers will continue to be made until the series is
terminated by the Subscriber. This value will automatically be set to ‘True’ if either the
PmtOccur or PmtSerExpDt is included in the recurring payment request. Canonical values
are:
• True
• False (default)
Bill Pay Services API – User Guide
iPay Solutions™
159
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PmtFinalAmt
This is the amount of the final payment on a loan, which may often differ from the other
payment installments on the loan. The use of this element within the Bill Pay Services API is
not available at this time.
RetroToOrigPmtDt
This optional element is available for a recurring payment or recurring Transfer series that
may be pended for additional payment approval, and specifies the desired action to be taken
in the event a scheduled recurring payment or Transfer is missed while awaiting payment
approval. A Subscriber Inquiry can be performed to determine if payment/Transfer approvals
are required for this Subscriber. Canonical values are:
• True
• False (default)
NOTE: Setting this value to ‘false’ will ignore a missed payment or Transfer and
schedule the next [second] payment or Transfer in the series, once payment approval
is received. A response of ‘true’ will reschedule the original [first] payment or Transfer (with
the originally specified amount) in order to catch up the series, as well as schedule the next
[second] payment or Transfer in the series.
Array(s):
InvoiceInfoArray
This array is applicable for Company Subscribers only at this time and can include a list of invoices,
if applicable for the scheduled payment, and includes the InvoiceInfo complex element for each line
item needed for the Invoice, and contains the following simple elements:
InvoiceID
This is the Service Provider’s (iPay Solutions) identifier for the Invoice.
This element should be left blank for the add request, as this information will not be
available to the Service Consumer until the Payment Add request has been completed.
InvoiceNum
This is the invoice number assigned to the invoice by the Payee. A maximum of 20
alphanumeric characters is allowed.
InvoiceCat
This indicates the invoice category for the entered line item. Canonical values are:
• Invoice - Invoice
• Adj – Adjustment
• Disc - Discount
• Oth - Other
InvoiceDesc
This optional element specifies a free-form text description of the invoice line item. A
maximum of 100 alphanumeric characters is allowed.
InvoiceAmtPos
This optional element indicates a positive amount value for the invoice line item.
Bill Pay Services API – User Guide
iPay Solutions™
160
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
InvoiceAmtNeg
This optional element indicates a negative amount value for the invoice line item (such as for
an adjustment or discount).
NOTE: Invoice information is not applicable for Transfers.
Payment Add Behaviors
• Prior to the utilization of any payment-related function, the third-party consumer must first perform:
o a Subscriber Inquiry - in order to obtain the available list of funding accounts from which to
choose
o a Payee Inquiry - in order to obtain the most accurate, up-to-date Payee information required
to schedule the payment.
NOTE: PayeeId values are subject to change without notice, so inquiry for current Payee IDs
should always be completed before actual use
• For Company Subscribers:
o ‘Standard’ Bill payments can be added only if the requesting user (subscriber’s associated
user) has been granted permission to ‘schedule bill payments’, and for the specified Payee.
o P2P Payments can be added only if the requesting user has been granted permission to
‘schedule email payments’, and for the specified P2P Payee.
o Transfer payments can be added only if the requesting user (subscriber’s associated user) has
been granted permission to ‘Schedule Transfers’ (i.e., ‘CanTransfer’), and for the specified
Transfer account.
o Funding account information (other than the Payee’s designated default account) can be
specified only if the requesting user has been granted permission to ‘Designate Pay From
Accounts’.
o Scheduled Payments or Transfers requiring additional payment approval from another
associated user authorized to approve payments/Transfers will be pended (Payment Status =
PmtApprvReq). The Service Provider (iPay Solutions) will notify the subscriber whenever
payment approval is required.
▪ A separate Scheduled Payment Approval request must be submitted to execute the
payment or Transfer approval.
o Invoice information can be added to the scheduled payment.
▪ There is no limit to the number of invoice line items that can be added to a single
payment.
▪ Multiple Invoice Numbers can be included in a single payment.
▪ Only one amount (either Pos or Neg) can be entered per invoice line item.
▪ Invoice information is NOT allowed for recurring payments or Transfers.
• The Process Date will be adjusted automatically by the service provider (iPay’ Solutions) to the First
Available Process Date if the entered value is equal to today’s date, but the payment or Transfer
request is received after the FI’s Payment Cutoff Time.
Bill Pay Services API – User Guide
iPay Solutions™
161
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
• Payments cannot be scheduled for Pending Payees or Transfers (those awaiting Activation), and
payment add requests for non-Activated Payees or Transfer accounts will be rejected.
• A fault will be returned for a check payment request if the subscriber’s home address is not on file.
• A fault will also be returned for any payment or Transfer request if no subscriber phone number is on
file.
o A Subscriber Mod request must be performed to add the subscriber’s phone number (Home,
Work or Cell) or address prior to attempting another ‘Payment Add’ request.
• A fault will also be returned for a payment request that is subject to Electronic Risk Limits if no
primary payee address is on file.
o A Payee Mod request must be performed to add the Payee’s primary address prior to
attempting another ‘Payment Add’ request.
• A Duplicate Payment Alert warning will be returned for any payment or Transfer scheduled where a
possible duplicate payment or Transfer exists. The existence of a payment or Transfer to the same
Payee processed within the preceding 14 days (that has not been stopped or cancelled), or any
scheduled payment or Transfer to the same Payee will trigger this warning.
• For Rush Payments:
o The Rush payment option is available only for those FIs that possess the Rush Payments
feature within the Bill Pay Services API. A Channel Inquiry can be performed to determine if this
feature is available in order to request a Rush Payment.
o iPay Solutions will fault an Add Payment request if both the Payee’s Rush Address ID and
Payee’s Rush Address are passed at the same time, as the intended Rush payment address is
unclear.
o iPay Solutions will also fault an Add Payment request if a Rush Option other than standard has
been specified, but no Payee Rush Address information is included.
o The Process Date and/or Estimated Arrival Date will be adjusted by the service provider to
accommodate the specified Rush Option.
o For Overnight and Second Business Day rush options:
▪ The payment method for the payment is set to Check regardless of the Payee’s designated
payment method.
▪ The selected funding account must be a checking account (to facilitate the check payment
method).
▪ Upon acceptance of the payment request, the payment is placed immediately in Paid
status, and cannot be updated or stopped.
o It is assumed that any fees associated with Rush payments have been presented by the
Consumer to the Subscriber/end-user, and that submission of a Rush payment implies fee
acceptance.
▪ A Payee Inquiry can be performed to determine available Rush Options and associated
Rush Payment Fee amounts.
• For P2P Payments:
Bill Pay Services API – User Guide
iPay Solutions™
162
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
o The P2P payment option is available only for those FIs that possess the Email Payments
feature within the Bill Pay Services API. A Channel Inquiry can be performed to determine if this
feature is available in order to request a P2P Payment.
o If a P2P payment requires a Service Fee (or surcharge), it is assumed that the service fee
applicable to the P2P payment has been presented by the Service Consumer to the
Subscriber/end-user, and that submission of the P2P payment implies fee acceptance.
▪ A Payee Inquiry can be performed to determine if a P2P (Email) Service Fee is
applicable and the Fee amount.
• For Recurring Payments:
o The ‘Standard’ RushOpt is the only valid Payment Rush Option for Recurring payments or
Transfers.
o For all payment frequencies except ‘TwiceMonthly’, only one PmtDayInfo entry is required.
▪ A second PmtDayInfo entry will be ignored for all payment frequency units except
‘TwiceMonthly’.
▪ For a specified payment frequency of ‘TwiceMonthly’, a second PmtDayInfo entry is
required.
• Values can be entered in any order, but there must be at least 6 days’ difference
between the two values.
o The Starting Payment Date (StartPmtProcDt or StartPmtEstArvDt) must be valid for the
specified Frequency and Payment Day of Week or Payment Day specified. For example, if a
new recurring payment or recurring Transfer series is requested on the 23
rd
of the current
month, and a Frequency of ‘Monthly’ is specified along with a Payment Day of the 18
th
, the
Starting Payment Date cannot be less than the 18
th
of the following month.
o The Processing Date and Estimated Arrival Date (i.e., ‘Due Date’) will be set automatically by
the Service Provider (iPay Solutions) for the first scheduled payment or Transfer in a recurring
series, based on the entered Starting Payment Date for the series.
▪ A Pay Before PayDtInstr is required for FIs using the Due Date Payment Model. The
Service Provider (iPay Solutions) will automatically reset this value if any value other
than Pay Before is received for a Due Date Payment Model.
• For eBill Payments:
o When a scheduled payment associated with an eBill is processed, the corresponding eBill will
be marked Paid.
Response
The service provider (iPay Solutions) returns the BilPaySchedPmtAddRs response message to the service
consumer.
The elements contained within the BilPaySchedPmtAddRs response applicable for the Bill Pay Services API
is/are:
PmtID
This is the Payment identifier associated with the Payment or Transfer for the Bill Pay Services API.
Bill Pay Services API – User Guide
iPay Solutions™
163
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
RsStat
This specifies the status of the add request. Canonical values are:
• Success
• Fail
The Service Provider (iPay Solutions) will return the Payment ID <PmtID> generated by the Bill Pay Services
API for the accepted new scheduled payment or Transfer.
Bill Pay Services API – User Guide
iPay Solutions™
164
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Scheduled Payment Search
Container: TPG_BillPayMaster.xsd
Message: BilPaySchedPmtSrch
The Bill Pay Scheduled Payment Search <BilPaySchedPmtSrch> will return all scheduled payments or
Transfers for a particular bill pay product and Subscriber.
The request provides the following optional filters:
• Payment Start Date <PmtStartDt>
• Payment End Date <PmtEndDt>
• Payment Low Amount <PmtLowAmt>
• Payment High Amount <PmtHightAmt>
• Payment Status <PmtStat> - default = All
• Payment Intention Type <PmtIntentType> - default = All
• Payee ID <PayeeId>
• Payee Payment Method <PayeePmtMthd>
• P2P Payees <P2PFilter>
• Recurring Payments <RecurFilter>
• Transfers <XferFilter>
When there exists more than one filter on the request, the resulting selection is based on the combined effect
of the filters (i.e., ‘and’ operator). Each added filter option will further restrict the result set.
The elements at the root request message will be echoed back at the root response, regardless if those same
elements exist in the repeating complex.
Message Flow
The Scheduled Payment Search service uses a typical exchange of MType messages to retrieve Scheduled
Payment and/or Transfer information for a specified product and Subscriber, based on optional filters.
Request
The third-party consumer forwards the BilPaySchedPmtSrchRq request message to the Service Provider.
Bill Pay Services API – User Guide
iPay Solutions™
165
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
The below elements contained within the BilPaySchedPmtSrchRq message request are necessary for the Bill
Pay Services API.
BilPayProd
This represents the type of iPay Solutions service operations being requested. Canonical values are:
• BilPay
• Remit (reserved for future use)
The BilPayProd default value is BilPay.
SubId
This is the Service Provider’s (iPay Solutions) identifier for the subscriber.
PmtStartDt
The date that designates the starting point for Scheduled Payment or Transfer [Process] date
selections. If no Start Date is specified, the Bill Pay Services API will return all available pending
payments and/or pending Transfers that have a Process Date that is less than the specified End
Date.
PmtEndDt
The date that designates the ending point for Scheduled Payment or Transfer [Process] date
selections. If no End Date is specified, the Bill Pay Services API will return all available pending
payments and/or pending Transfers that have a Process Date that is greater than the specified Start
Date.
NOTE: If no date range is specified, the Bill Pay Services API will return all available pending
payments and/or Transfers that satisfy all other filter requirements.
PmtLowAmt
This is the value that designates a starting point for payment/Transfer amount selections.
This value is the lowest amount to begin searching when a range of amounts is used to refine the
scheduled payment search. If no value is specified, the Bill Pay Services API will utilize a default
value of $0 for this filter parameter.
PmtHighAmt
This is the value that designates an ending point for payment/Transfer amount selections.
This value is the highest amount to begin searching when a range of amounts is used to refine the
scheduled payment search. If no value is specified, the Bill Pay Services API will utilize a default
value of ‘null’ (i.e., no upper payment amount limit) for this filter parameter.
PmtStat
The status of the payment or Transfer. Valid canonical values for all pending payments/Transfers
are:
• All – All (default)
• Sched – Scheduled
• Pend – Pending
• PendSkip - Pending Skip
• PmtApprvReq - Payment Approval Required
NOTE: See Appendix C for Payment Status definitions.
Bill Pay Services API – User Guide
iPay Solutions™
166
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
[Payment] PmtIntentType
This represents the payment intention for the Payment(s) or Transfer(s). Canonical values are:
• PayBill - Payment for a bill (default)
• XferToSubFinInst - Transfer to Subscriber account at external FI (Outbound)
• XferFromSubFinInst - not supported by iPay Solutions at this time
• XferTo - not supported by iPay Solutions at this time
• XferFrom - not supported by iPay Solutions at this time
If no Payment Intent Type is specified, the Bill Pay Services API will return all available pending
payments and/or Transfers that satisfy all other filter requirements
PayeeId
This is the Bill Pay Services API identifier for the Payee or Transfer account to whom the payment or
Transfer has been scheduled.
If no Payee is specified, the Bill Pay Services API will return pending payments and/or Transfers for
all Payees and/or Transfer accounts that satisfy all other specified filters.
PayeePmtMthd
This is the payment method for the Payee or Transfer account associated with the scheduled
payment or Transfer. Canonical values are:
• Chk – Check
• Email – P2P (electronic, but initial set up is via an email or SMS process)
• Elec - Electronic
P2PFilter
This is used to filter payments associated with P2P Payees into (or from) the search results.
Canonical values are:
• Incl – Include P2P payments (default)
• OnlyP2P – Only return P2P payments
• Excl – Exclude P2P payments
RecurFilter
This is used to filter recurring payments and/or Transfers into (or from) the search results. Canonical
values are:
• Incl – Include recurring payments (default)
• OnlyRecur – Only return recurring payments
• Excl – Exclude recurring payments
XferFilter
This is used to filter Transfer payments into (or from) the search results. Canonical values are:
• Incl – Include Transfers (default)
• OnlyXfer – Only return Transfer payments
• Excl – Exclude Transfer payments
NOTE: If any value entered directly conflicts with another entered filter parameter (i.e., the parameters
are mutually exclusive), no results will be returned.
Response
Bill Pay Services API – User Guide
iPay Solutions™
167
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
The service provider (iPay Solutions) returns the BilPaySchedPmtSrchRs response message to the service
consumer, which returns a list of all Scheduled (single and/or recurring) Payments and/or Transfers for the
specified product and Subscriber that meet the given search criteria.
Notes:
1) Other types of Payments, such as Gift Payments, etc., will not be included in the result set at this
time.
2) For Company Subscribers:
a. Scheduled [Bill] Payment information can be viewed only if the requesting user (subscriber’s
associated user) has been granted permission to ‘Scheduled Bill Payments.
b. P2P Payments can be viewed only if the requesting user has been granted permission to
Schedule Email Payments.
c. Scheduled Transfer information can be viewed only if the requesting user (subscriber’s
associated user) has been granted permission to ‘Schedule Transfers’.
To summarize, only those payment types for which the requesting user has permissions will be
eligible to be returned in the search results.
3) Scheduled Payment search results will be returned in descending Process Date order (newest to
oldest).
The array(s) within the BilPaySchedPmtSrchRs response applicable for the Bill Pay Services API are:
BilPaySchedPmtSrchArray
This array returns an array of responses for the Scheduled Payment search and includes the
BilPaySchedPmtSrchInfo complex element for each Scheduled (single or recurring) Payment or Transfer
returned, and includes the following simple and complex elements:
PmtId
This is the Bill Pay Services API identifier for the Payment or Transfer.
PayeeId
This is the ID of the Payee or Transfer account.
PayeeName
This is the name of the Payee or Transfer account.
PayeeNickname
This represents the subscriber’s nickname for the Payee or Transfer account.
PmtProcDt
This is the date the payment or Transfer is scheduled to be processed.
PmtEstArvDt
This is the date the scheduled payment or Transfer is estimated to be delivered to the Payee.
PmtAmt
The amount of the scheduled payment or Transfer.
PmtStat
The status of the payment or Transfer. Valid canonical values for all pending payments/Transfers
are:
• Sched – Scheduled
• Pend – Pending
• PendSkip – Pending Skip
• PmtApprvReq – Payment Approval Required
NOTE: See Appendix C for Payment Status definitions.
Bill Pay Services API – User Guide
iPay Solutions™
168
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PmtMthd
This is the payment method used for the Payment or Transfer. Canonical values are:
• Chk – Check
• Email – P2P (electronic, but initial set up is via an email or SMS process)
• Elec – Electronic
PmtFreqUnits
This is the payment frequency for a recurring payment or recurring Transfer series. A specified
frequency of Once indicates a single payment or Transfer. Canonical values are:
• Once (default)
• Weekly
• EveryOtherWeek
• Every4Weeks
• Monthly
• TwiceMonthly
• EveryOtherMonth
• Every3Months
• Every6Months
• Annual
P2PType
This indicates whether the payment is P2P payment (for a P2P Payee type). Canonical values are:
• True
• False (default)
ElecMerBilPmt
This indicates whether the payment is an eBill payment (i.e., has an associated eBill). Canonical
values are:
• True
• False
[Payment] PmtIntentType
This represents the payment intention for the Payment(s) or Transfer(s). Canonical values are:
• PayBill - Payment for a bill (default)
• XferToSubFinInst - Transfer to Subscriber account at external FI (Outbound)
• XferFromSubFinInst - not supported by iPay Solutions at this time
• XferTo - not supported by iPay Solutions at this time
• XferFrom - not supported by iPay Solutions at this time
PayFromAcctInfo
This optional complex element contains information on the funding account (‘pay from account’)
designated for the specified Payment or Transfer.
NOTE: For Company Subscribers: Funding account information can be viewed if the requesting user
has permission to ‘Designate Pay From Account’ information. If the requesting user does not have
permission, the <Rstr> attribute for these elements will be set to Hid, which indicates that the Service
Consumer should hide these elements from the requesting user.
PayFromId
This is the Bill Pay Services API identifier for the funding account specified for the Payment
or Transfer.
Bill Pay Services API – User Guide
iPay Solutions™
169
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PayFromAcctId
The bank account number of the funding account designated for this Payment or Transfer.
PayFromAcctType
The number(s) or character(s) that categorize the type of funding account. Canonical values
are:
• D – Checking
• S – Savings
PayFromAcctName
This is the account name for the subscriber’s funding account.
PayFromAcctDft
This indicates if the funding account is the default funding account, to be used in the event a
funding account is not specified when scheduling a payment or Transfer. Canonical values
are:
• True
• False (default value)
StartChkNum
This is the check number that will be used to start check payments from the specified funding
account. This will be available only if the subscriber’s product allows specification of a
starting check number.
PayFromIntsRtId
This is the routing transit number or ABA number of the FI where the subscriber’s funding
account resides.
PayFromAcctStat
This is the status of the funding account as it relates to its potential use within the
subscriber’s Bill Pay account. Canonical values are:
• Pend - Pending
• Apprv - Approved
PayFromAcctOwnName
This optional complex element contains information for the funding account (‘pay from
account’) owner’s name (if the actual owner of the account is not the subscriber), and
includes the following simple elements, as well as an optional x_PersonName complex
element (which is not currently used for the Bill Pay Services API):
ComName
This represents the funding account owner’s Name, if the owner of the account is a
Company.
FirstName
This represents the funding account owner’s first name, if the owner of the account is
a person.
MiddleName
This optional element represents the funding account owner’s middle name, if the
owner of the account is a person.
Bill Pay Services API – User Guide
iPay Solutions™
170
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
LastName
This optional element represents the funding account owner’s last name, if the owner
of the account is a person.
NOTE: Funding account (‘pay from account’) owner information is allowed if the subscriber’s
product permits it, and if the subscriber is authorized to include funding account owner
information.
PayFromAcctOwnAddr
This complex element is an optional element which contains information for the funding
account (‘pay from account’) owner’s address, if the owner of the account is not the
subscriber, and includes the following simple elements:
StreetAddr1
This is the subscriber’s street address.
StreetAddr2
This is the second line of the subscriber’s street address.
City
This is the name of the city in the subscriber’s address.
StateCode
This is the two-character alpha code approved by the USPS which represents a
state.
PostalCode
This is the postal or ZIP Code (ZIP+4 is supported).
Bill Pay Services API – User Guide
iPay Solutions™
171
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Scheduled Payment Inquiry
Container: TPG_BillPayMaster.xsd
Message: BilPaySchedPmtInq
The Bill Pay Scheduled Payment Inquiry <BilPaySchedPmtInq> will return element details for a specific
scheduled (Pending) single or recurring payment or Transfer for a given Subscriber. The subscriber
identification element <SubId> and Payment ID <PmtId> are required on the request.
The design of the inquiry was created in a manner that facilitates addition and modification requests.
The activity intention element <ActIntent> was added to support the concurrency model for future
modifications made to scheduled single or recurring payments or Transfers.
The elements at the root request message will be echoed back at the root response, regardless if those same
elements exist in the repeating complex.
Message Flow
The Scheduled Payment Inquiry service uses a typical exchange of MType messages to retrieve scheduled
payment or scheduled Transfer information for a given Subscriber, based on the required Subscriber ID and
Payment ID. If the Payment ID is not known, the third-party consumer must first perform a Scheduled
Payment Search to obtain the Payment ID for the desired scheduled payment or Transfer.
Bill Pay Services API – User Guide
iPay Solutions™
172
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Request
The third-party consumer forwards the BilPaySchedPmtInqRq request message to the Service Provider.
The below elements and array(s) contained within the BilPaySchedPmtInqRq message request are
necessary for the Bill Pay Services API.
BilPayProd
This represents the type of iPay Solutions service operations being requested. Canonical values are:
• BilPay
• Remit (reserved for future use)
The BilPayProd default value is BilPay.
SubId
This is the Service Provider’s (iPay Solutions) identifier for the subscriber.
PmtId
This is the Bill Pay Services API identifier for the scheduled payment or Transfer.
ActIntent
This indicator conveys the Service Consumer’s intention for a subsequent operation for the data set
included in the response. Canonical values are:
• ReadOnly – indicates a view intent for the data set in the Inquiry response. This is the default.
• Upd – indicates the intention to perform an update (Mod) to the data set in the Inquiry response.
• Dlt – indicates the intention to perform a delete of the data set in the Inquiry response.
IncXtendElemArray
This array conveys the list of ‘x_’ elements by name which are to be included in the response. The
inclusion of this array is necessary only if future payments or Transfers associated with a recurring
payment or recurring Transfer series are desired in the response. The complex element contained in this
array, IncXtendElemInfo, includes the following simple element(s):
XtendElem
This is the extended element (by name) which the service consumer is requesting be included in the
response. At this time, the only Extended Element that is available for the BilPaySchedPmtInqRq is:
• x_FutPmtInfoArray
Response
The service provider (iPay Solutions) returns the BilPaySchedPmtInqRs response message to the service
consumer, which returns a package of payment or Transfer information for the specified scheduled single or
recurring payment or Transfer.
NOTE: For Company Subscribers:
o Scheduled Payment information can be viewed only if the requesting user (subscriber’s
associated user) has permission to schedule bill payments.
o P2P Payments can be viewed only if the requesting user has permission to schedule email
payments.
o Scheduled Transfer information can be viewed only if the requesting user has permission to
schedule transfers.
The simple and complex elements and array(s) contained within the BilPaySchedPmtInqRs response
applicable for the Bill Pay Services API are:
Bill Pay Services API – User Guide
iPay Solutions™
173
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PmtCrtDt
The date a payment or Transfer was created by the subscriber.
PmtStat
The status of the scheduled payment or Transfer. Valid canonical values for all pending
payments/Transfers are:
• Sched – Scheduled
• Pend – Pending
• PendSkip - Pending Skip
• PmtApprvReq - Payment Approval Required
NOTE: See Appendix C for Payment Status definitions.
PmtMthd
This is the payment method used for the scheduled payment or Transfer. anonical values are:
• Chk – Check
• Email – P2P electronic, but initial set up is via an email or SMS process)
• Elec – Electronic
ActIntentKey
This is the key (provided by the service provider) delivered to the consumer to be submitted in the
subsequent modification (update or delete) operation for the data set returned in the inquiry
response.
BilPaySchedPmtInfo
This complex element contains a package of data related to a scheduled single or recurring payment or
Transfer and includes the below simple and complex elements and arrays for the Bill Pay Services API.
PmtProcDt
This is the date the pending payment or Transfer is scheduled to be processed. For a recurring
payment or recurring transfer series, this will be the date associated with the currently scheduled
payment or Transfer in the series.
PmtEstArvDt
This is the date the pending payment or Transfer is estimated to be delivered to the Payee. For a
recurring payment or recurring transfer series, this will be the date associated with the currently
scheduled payment or Transfer in the series.
PmtAmt
The amount of the scheduled payment or Transfer.
PmtCmnt
This is the comment that will be stored with the payment or Transfer. This is for the subscriber’s
internal use only and is not included with the Payment.
PmtChkMemo
This is the memo to be added to a check associated with a check payment. (Not applicable for
Transfers.)
SubCmntToPayee
This is the personalized message that will be added to the email sent to a P2P payment recipient
notifying them that a payment has been made. Message is limited to 500 characters for email
notification (25 characters for text messages).
Bill Pay Services API – User Guide
iPay Solutions™
174
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
[Payment] PmtIntentType
This represents the payment intention for the Payment(s) or Transfer(s). Canonical values are:
• PayBill - Payment for a bill (default)
• XferToSubFinInst - Transfer to Subscriber account at external FI (Outbound)
• XferFromSubFinInst - not supported by iPay Solutions at this time
• XferTo - not supported by iPay Solutions at this time
• XferFrom - not supported by iPay Solutions at this time
NOTE: Until such time as additional Transfer options are available, the PmtIntentType of the
Payment or Transfer will match the PmtIntentType of the Payee.
PmtPayeeInfo
This required complex contains the package of data related to the Payee or intended Transfer
account of the scheduled single or recurring payment or Transfer and includes the following simple
and complex elements and arrays:
PayeeId
This is the ID of the Payee or Transfer account.
PayeeName
This is the name of the Payee or Transfer account.
PayeeNickname
This represents the subscriber’s nickname for the Payee or Transfer account.
PayeeClsf
This specifies the classification of a Payee Canonical values are:
• Comp (Company)
• Indv (Individual/Person)
• FinInst (FI) – indicates a Transfer account
[Payee] PmtIntentType
This represents the payment intention of the Payee or Transfer account. Canonical values
are:
• PayBill - Payment for a bill (default)
• XferToSubFinInst - Transfer to Subscriber account at external FI (Outbound)
• XferFromSubFinInst - not supported by iPay Solutions at this time
• XferTo - not supported by iPay Solutions at this time
• XferFrom - not supported by iPay Solutions at this time
PayeePmtMthd
This is the default payment method for the Payee or Transfer account. This may not be the
actual Payment method utilized for the scheduled payment or Transfer. Canonical values are:
• Chk – Check
• Email – P2P (electronic, but initial set up via an email or SMS process)
• Elec – Electronic
Bill Pay Services API – User Guide
iPay Solutions™
175
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
SubMerAcctId
This is the subscriber’s account number with the Merchant/Payee. For Transfer accounts, this
value will be the Account Holder’s account number (of the Transfer account).
If the subscriber’s name (Last Name, First Name) is being used for this element, the value
will be truncated at 50 characters.
SubMerPayerName
This is the subscriber’s name understood by the merchant and is used to override the
subscriber’s name on record.
PayeeCatName (reserved for future use)
The name of the category assigned to the Payee or Transfer account.
PayeeAddrInfo
This complex contains a package of data related to the Payee’s address specified for the
scheduled single or recurring payment. Not applicable for Transfer accounts. In the case of an
electronic payment, this will simply be the Payee’s primary or standard address. This complex
includes the following simple and complex elements:
PayeeAddrId
This is the Bill Pay Services API identifier for the specified address for the Payee.
PayeeAddrType
This specifies the type of payee address being utilized for the scheduled payment.
Canonical values are:
• Prim – Primary (default)
• Rush – Rush
PayeeAddr
This complex element contains elements representing the Payee’s address used for
the scheduled payment.
StreetAddr1
This is the Payee’s street address for Rush payments.
StreetAddr2 (optional)
This is the second line of the Payee’s street address for Rush payments.
City
This is the name of the city in the Payee’s Rush payment address.
StateCode
This is the two-character alpha code approved by the USPS which
represents a state.
PostalCode
This is the postal or ZIP Code (ZIP+4 is supported).
NOTE: It should be noted that, in order to leverage check processing efficiencies gained from iPay Solutions
Merchant Management process, the [primary] Payee Address listed may not always be the address used for
a check payment.
BilPaySvcFeeInfoRec
This complex contains a package of Service Fee (or payment surcharge information
applicable to the Payment or Transfer.
Bill Pay Services API – User Guide
iPay Solutions™
176
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
SvcFeeDesc
This element specifies the type of payment or Transfer to which the service fee is
applicable. A Service Dictionary Search request is necessary to obtain the current
list of available Service Fee Descriptions.
SvcFeeAmt
This element specifies the amount of the Service Fee that was applied to the
Payment or Transfer.
PayeePhoneArray
This array contains phone information for the specified Payee. Not applicable for Transfer
accounts.
PhoneNum
This represents a phone number, including area code, for the Payee. This is the
Payee’s Work (Business) number.
PhoneType
This specifies the type of phone number contained in the PhoneNum element
(above). Current canonical values for Payees for the Bill Pay Services API are:
• Work
• SMS
PayeeEmailArray
This optional array contains the EmailInfo complex element, which includes a package of
email data for the Payee. Not applicable for Transfer accounts.
EmailAddr
This element specifies the email address of the Payee. This is a valid element only if
the Payee’s PayeePmtMthd = Email.
EmailType
This element specifies to whom the email address applies. Applicable canonical
values for a Payee for the Bill Pay Services API are:
• Prim – Primary (default)
PmtRushOptInfo
This optional complex contains the rush payment details that were specified for the given scheduled
[single] payment and includes the following simple elements:
RushOpt
This represents the desired option for expediting (Rushing) the payment to the specified
Payee. Canonical values are:
• Std – Standard (default; specifies a non-expedited payment)
• Ovrngt – Overnight
• 2ndDay – Second Business Day
• 2ndDayEc – Seccond Day Economy
RushOptFeeAmt
This specifies the fee associated with the selected Rush Option.
RushOptSurChg
This specifies the surcharge that is applicable for Rush payments sent to Puerto Rico. This
surcharge is automatically applied to any Rush payment request to Puerto Rico.
NOTE: Not applicable for Transfers.
Bill Pay Services API – User Guide
iPay Solutions™
177
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PmtPayFromAcctInfo
This required complex element contains information on the funding account (‘pay from account’) used
to make the payment or Transfer to specified the Payee for this scheduled payment or Transfer.
NOTE: For Company subscribers: Funding account information can be viewed only if the requesting
user has been granted permission to ‘Designate Pay From Account’ information. If the requesting
user does not have permission, the <Rstr> attribute for each of these elements will be set to Hid,
which indicates that the Service Consumer should hide these elements from the requesting user.
PayFromId
This is the Bill Pay Services API identifier for the funding account specified for the scheduled
payment or Transfer.
PayFromAcctId
The bank account number of the funding account designated for this Payment or Transfer.
PayFromAcctType
The number(s) or character(s) that categorize the type of funding account. Canonical values
are:
• D – Checking
• S – Savings
PayFromAcctName
This is the account name for the specified funding account.
PayFromAcctDft
This indicates whether the funding account is the subscriber’s designated default funding
account, which is the funding account used in the event a funding account is not specified
when scheduling a payment or Transfer. Canonical values are:
• True
• False (default value)
StartChkNum
This is the check number that will be used to start check payments from the specified funding
account. This will be available only if the subscriber’s product allows specification of a
starting check number.
PayFromIntsRtId
This is the routing transit number or ABA number of the FI where the subscriber’s funding
account resides.
PayFromAcctStat
This is the status of the funding account as it relates to its potential use within the
subscriber’s Bill Pay account. Canonical values are:
• Pend – Pending
• Apprv – Approved
PayFromAcctOwnName
This optional complex element contains information for the funding account (‘pay from
account’) owner’s name (if the owner of the account is not the subscriber), and includes the
following simple elements, as well as an optional x_PersonName complex element (which is
not currently used for the Bill Pay Services API):
ComName
This represents the funding account owner’s name, if the owner of the account is a
Company.
Bill Pay Services API – User Guide
iPay Solutions™
178
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
FirstName
This represents the funding account owner’s first name, if the owner of the account is
a person.
MiddleName
This optional element represents the funding account owner’s middle name, if the
owner of the account is a person.
LastName
This optional element represents the funding account owner’s last name, if the owner
of the account is a person.
.
PayFromAcctOwnAddr
This complex element is an optional element which contains information for the funding
account (‘pay from account’) Owner’s Address (if the actual owner of the account is not the
Subscriber), and includes the following simple elements:
StreetAddr1
This is the subscriber’s street address.
StreetAddr2
This is the second line of the subscriber’s street address.
City
This is the name of the city in the subscriber’s address.
StateCode
This is the two-character alpha code approved by the USPS which represents a
state.
PostalCode
This is the postal or ZIP Code (ZIP+4 is supported).
NOTE: Funding account (‘pay from account’) owner information is allowed only if the
subscriber’s product permits it, and if the subscriber is authorized to include funding account
owner information.
RecurPmtInfo
This optional complex element contains a package of scheduling data related to the recurring
payment or recurring Transfer series (if the scheduled payment inquiry is for a recurring payment or
Transfer) and includes the below simple elements and arrays necessary to support a recurring
payment or Transfer series using the Bill Pay Services API.
StartPmtProcDt
This is the [original] process date for the first payment that started the recurring payment or
recurring Transfer series.
StartPmtEstArvDt
This is the [original] estimated arrival date (i.e., due date) for first payment that the recurring
payment or recurring Transfer series.
PmtFreqUnits
This is the payment frequency for a recurring payment or recurring Transfer series. A
specified frequency of Once indicates a single payment or Transfer. Canonical values are:
• Once (default)
• Weekly
Bill Pay Services API – User Guide
iPay Solutions™
179
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
• EveryOtherWeek
• Every4Weeks
• Monthly
• TwiceMonthly
• EveryOtherMonth
• Every3Months
• Every6Months
• Annual
PmtDayOfWeek
This is the desired day of the week when recurring payments or Transfers will be made if the
specified payment frequency is: Weekly, EveryOtherWeek or Every4Weeks. Canonical
values are:
• Mon – Monday
• Tues – Tuesday
• Wed – Wednesday
• Thur – Thursday
• Fri – Friday
PmtDayInfoArray
This optional array contains the PmtDayInfo complex element, which includes a package of
data related to the day(s) of the month a recurring payment or recurring Transfer should be
made if the payment frequency has been specified as Monthly, TwiceMonthly,
EveryOtherMonth, Every3Months, Every6Months or Annual. It includes the following simple
elements:
PmtDayofMonth
This is the day of the month when the recurring payment or Transfer will be made
(e.g., 1 - 31). This value will not be present if the desired payment day is the last
business day of each month.
PmtUseLastBusDay
This indicates that payment or Transfer should be made on the last business day of
the month. Canonical values are:
• True
• False (default)
PayDtInstr
This is the payment date instruction when a recurring payment or recurring Transfer date falls
on a non-processing date (such as a weekend or holiday). Canonical values are:
• Before – Pay before (default)
• After – Pay after
PmtOccur
This is the number of remaining payment or Transfer occurrences for the recurring payment
or recurring Transfer series.
PmtSerExpDt
This is the expiration date for the recurring payment or recurring Transfer series.
Bill Pay Services API – User Guide
iPay Solutions™
180
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PmtSerFinite
This indicates whether the payment or Transfer series is finite or has no end. If the series is
not finite, recurring payments or Transfers will continue to be made until the series is
terminated by the Subscriber. Canonical values are:
• True
• False
PmtFinalAmt
This is the amount of the final payment on a loan. The use of this element within the Bill Pay
Services API is not available at this time.
NOTE: For subscribers using non-StandAlone Bill Pay Services, an email from the
service provider (iPay Solutions) is generated to the subscriber when a recurring
payment series is about to expire (when one payment remains in the series). This
email provides notification of the expiration of the series in the event the subscriber
would like to extend the series if additional payments are needed.
No email notification is provided by the service provider (iPay Solutions) to
subscribers using StandAlone Bill Pay Services. However, a BilPaySchedPmtInq
request will provide all necessary information about the impending end of the series,
in the event the service consumer opts to provide similar notification to the subscriber.
RetroToOrigPmtDt
This optional element is available for recurring payments or recurring Transfers that may be
pended for additional payment approval, and specifies the desired action to be taken in the
event a scheduled recurring payment or recurring Transfer is missed while awaiting payment
approval. Canonical values are:
• True
• False (default)
NOTE: A value of False will ignore a missed payment or Transfer and schedule the next [second]
payment or Transfer in the series once payment approval is received. A value of true will reschedule
the original [first] payment or Transfer (with the originally specified amount) in order to catch up the
series, as well as schedule the next [second] payment or Transfer in the series.
BilPayeeElecPmtInfo
This complex element contains a package of data related to the eBill that corresponds to the
scheduled payment and includes the below simple elements and arrays for the Bill Pay Services API.
StmtDt
This is the statement date for the associated eBill.
PmtDueDt
This is the date the payment is due for the associated eBill.
StmtBal
This is the statement balance for the associated eBill. A statement balance amount is
available only for credit card account (CCA) types.
Bill Pay Services API – User Guide
iPay Solutions™
181
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
CurBal
This is the total [outstanding] current balance of the subscriber’s account with the Payee.
This amount may be different than the Statement Balance for the corresponding eBill. A
current balance amount is available only for credit card account (CCA) types.
PmtAmtDue
This is the payment amount due for the associated eBill. This value is available only for non-
credit card accounts (account type not = CCA).
MinPmtAmt
This is the minimum amount due for the associated eBill. A minimum amount due is available
only for credit card account (CCA) types.
ElecBilPmtAuto
This indicates whether the [eBill] payment was scheduled based on an automatic eBill
payment schedule for the Payee. Canonical values are:
• True
• False
NOTE: Not applicable for Transfer accounts.
Array(s)
InvoiceInfoArray
This array can include a list of invoices, if applicable for the scheduled payment, and includes the
InvoiceInfo complex element for each line item entered for the Invoice, and contains the following
simple elements:
InvoiceID
This is the Service Provider’s (iPay Solutions) identifier for the Invoice.
InvoiceNum
This is the invoice number assigned to the invoice by the Payee.
InvoiceCat
This indicates the invoice category for the entered line item. Canonical values are:
• Invoice – Invoice
• Adj – Adjustment
• Disc – Discount
• Oth – Other
InvoiceDesc
This optional element specifies a free-form text description of the invoice line item.
InvoiceAmtPos
This optional element indicates a positive amount value for the invoice line item.
InvoiceAmtNeg
This optional element indicates a negative amount value for the invoice line item (such as for
an adjustment or discount).
NOTE: Not applicable for Transfers
Bill Pay Services API – User Guide
iPay Solutions™
182
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
x_FutPmtInfoArray
This optional array contains a [limited] list of future payments or Transfers in the recurring payment or
recurring Transfer series and includes the FutPmtInfo complex, which contains a package of data related
to each future scheduled payment or Transfer in the recurring series. To optimize system performance,
the number of future payments or Transfers returned in the array will be limited and may not include all
possible future payments or Transfers in the series.
As with all ‘x_’ elements, this x_ array must be explicitly requested in the IncXtendElemArray included in
the BilPaySchedPmtInqRq message (above), if future payment or future Transfer detail is desired in the
response.
The complex includes the following simple and complex elements for the Bill Pay Services API:
FutPmtId
This is the Bill Pay Services API identifier for the specified future payment or Transfer in the recurring
payment or recurring Transfer series.
FutPmtStat
The status of the specified future payment or Transfer in the recurring payment or recurring Transfer
series. Valid canonical values for all future payments/Transfers are:
• Sched – Scheduled
• Pend – Pending
• Skip – Skipped
NOTE: See Appendix C for Payment Status definitions.
FutPmtOrigProcDt
This is the original or calculated process date for the specified future payment or Transfer based
solely on the specified frequency and payment day(s) specified for the recurring payment or recurring
Transfer series.
FutPmtActualProcDt
This is the actual date the future payment or Transfer is scheduled to be processed, adjusted for non-
processing dates.
FutPmtAmt
This is the amount of the specified future payment or Transfer.
FutPmtCmnt
This is the comment that will be stored with the specified future payment or Transfer. This is for the
subscriber’s internal use only and is not included with the Payment.
FutPmtChkMemo
This is the memo to be added to a check associated with the specified future [check] payment.
FutPmtModUsrID
This is the user ID of the individual who modified the specified future payment.
FutPmtLastMainDt
This is the last date maintenance was performed on the specified future payment or Transfer. A date
will be present only if the specified future payment or Transfer was previously modified.
SubCmntToPayee
This is the personalized message that will be added to the email sent to a P2P payment recipient
notifying them that a payment has been made. Not applicable for Transfers. Message is limited to 500
characters for email notification (25 characters for text messages).
Bill Pay Services API – User Guide
iPay Solutions™
183
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
FutPmtPayFromAcctInfo
This required complex element contains information on the funding account (‘pay from account’) to be
used to make the specified future payment or Transfer in the recurring payment or recurring Transfer
series.
PayFromId
This is the Bill Pay Services API identifier for the funding account specified for the specified
future payment or Transfer.
PayFromAcctId
The bank account number of the funding account designated for the specified future Payment
or Transfer.
PayFromAcctType
The number(s) or character(s) that categorize the type of funding account. Canonical values
are:
• D – Checking
• S – Savings
PayFromAcctName
This is the account name for the specified funding account.
PayFromAcctDft
This indicates if the funding account is the Subscriber’s designated default funding account,
which is the funding account used in the event a funding account is not specified when
scheduling a payment or Transfer. Canonical values are:
• True
• False (default value)
StartChkNum
This is the check number that will be used to start check payments from the specified funding
account. This will be available only if the subscriber’s product allows specification of a
starting check number.
PayFromIntsRtId
This is the routing transit number or ABA number of the FI where the subscriber’s funding
account resides.
PayFromAcctStat
This is the status of the funding account as it relates to its potential use within the
subscriber’s Bill Pay account. Canonical values are:
• Pend - Pending
• Apprv - Approved
Bill Pay Services API – User Guide
iPay Solutions™
184
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Scheduled Payment Mod
Container: TPG_BillPayMaster.xsd
Message: BilPaySchedPmtMod
The Bill Pay Scheduled Payment Modification <BilPaySchedPmtMod> will allow the service consumer to
update (modify) certain elements for a Subscriber’s scheduled/pending single or recurring payment or
Transfer, or delete (stop) the payment or Transfer entirely. For a recurring payment or recurring Transfer
series, an option to delete (i.e., ‘skip’) a specific payment or Transfer, or delete the entire series, is available.
The <SubId>, <PmtId> and Activity Intent Key <ActIntenKey> are required on the Mod request.
A request that provides the SubId, PmtId and ActIntentKey along with the delete element (<Dlt>) that is set to
‘True’ will convey to the service provider to remove (stop) the Scheduled Payment or Transfer for the
specified Subscriber.
The elements at the root request message will be echoed back at the root response, regardless if those same
elements exist in the repeating complex.
Message Flow
The Scheduled Payment Modification service uses a typical exchange of MType messages to allow updates
to scheduled single or recurring payment or Transfer information for a specific Subscriber, based on the
required Subscriber ID and Payment ID. A Scheduled Payment Inquiry must always be performed prior to the
modification request in order to retrieve the Activity Intent Key necessary for modification operations, as well
as to ensure that the most up-to-date Payee information is reflected on the Scheduled Payment or Transfer.
Bill Pay Services API – User Guide
iPay Solutions™
185
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Request
The third-party consumer forwards the BilPaySchedPmtModRq request message to the Service Provider.
The below simple and complex elements contained within the BilPaySchedPmtModRq message request are
necessary for the Bill Pay Services API.
BilPayProd
This represents the type of iPay Solutions service operations being requested. Canonical values are:
• BilPay
• Remit (reserved for future use)
The BilPayProd default value is BilPay.
SubId
This is the Service Provider’s (iPay Solutions) identifier for the subscriber.
PmtId
This is the Bill Pay Services API identifier for the scheduled payment or Transfer.
ActIntentKey
This is the service provider key delivered to the service consumer via a preceding inquiry request, to
be submitted in the modification request operation.
Dlt
This indicates a desire for deletion of the specified entity. For recurring payments/Transfers, a value of
‘true’ indicates a desire to delete (i.e. ‘stop’) the entire recurring payment or Transfer series immediately.
Canonical values are:
• True
• False (default)
DltRecur
This element is applicable for recurring payments or recurring Transfer series’ only and indicates a desire
for deletion (i.e., ‘stop’) of the specified recurring payment or recurring Transfer series, but only after the
currently scheduled payment or Transfer has been processed. Canonical values are:
• True
• False (default)
FutPmtId
This is the Bill Pay Services API identifier for a single specified current or future payment or Transfer in a
recurring series. If entered, all eligible recurring payment or recurring Transfer updates will be applied to
that specified current or future payment or Transfer only. If the mod request is for an update to the entire
recurring payment or Transfer series, a value should not be entered here.
SkipPmtOccur
This indicates whether the specified future payment or Transfer (above) in the recurring payment or
recurring Transfer series should be skipped. Canonical values are:
• True
• False (default)
BilPaySchedPmtInfo
This complex element contains a package of data related to the Subscriber’s specified pending payment
or Transfer, and may include all of the simple and complex elements and arrays returned in the preceding
Scheduled Payment Inquiry response. However, the following are the only elements within this complex
that are eligible for modification (add, update or delete) for a Scheduled Payment Modification request:
Bill Pay Services API – User Guide
iPay Solutions™
186
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PmtProcDt
This is the date the currently scheduled payment or Transfer is scheduled to be processed. (For
changes to the overall schedule for a recurring series, see the RecurPmtInfo complex below.)
PmtEstArvDt
This is the date the currently scheduled payment or Transfer is estimated to be delivered to the
Payee. (For changes to the overall schedule for a recurring series, see the RecurPmtInfo complex
below.)
PmtAmt
This is the amount of the scheduled single or recurring payment(s) or Transfer(s). If a FutPmtId is
specified for this ‘mod’ request, only the amount of the specified future payment or Transfer in the
recurring payment or recurring Transfer series will be updated. The recurring series information will
remain unchanged.
PmtCmnt
This is the comment that will be stored with the single or recurring payment(s) or Transfer(s). This is
for the Subscriber’s internal use only and is not included with the Payment. If a FutPmtId is specified
for this ‘mod’ request, only the comment associated with the specified future payment or Transfer in
the recurring payment or recurring Transfer series will be updated. The recurring series information
will remain unchanged.
PmtChkMemo
This is the memo to be added to a check associated with a single or recurring check payment. If a
FutPmtId is specified for this ‘mod’ request, only the ChkMemo value associated with the specified
future payment in the recurring payment series will be updated. The recurring series information will
remain unchanged.
[Payment] PmtIntentType
This represents the payment intention for the Payment(s) or Transfer(s). Canonical values are:
• PayBill - Payment for a bill (default)
• XferToSubFinInst - Transfer to Subscriber account at external FI (Outbound)
• XferFromSubFinInst - not supported by iPay Solutions at this time
• XferTo - not supported by iPay Solutions at this time
• XferFrom - not supported by iPay Solutions at this time
NOTE: Until such time as additional Transfer options are available, the PmtIntentType of the
Payment or Transfer will be automatically set to match the PmtIntentType of the Payee or Transfer
account. iPay Solutions will ignore a value submitted for this element.
SubCmntToPayee
This is the personalized message that will be added to the email sent to a P2P payment recipient
notifying them that a payment has been made. Entry is limited to 500 characters for email notification
(25 characters for text messages).
PmtPayeeInfo
This optional complex contains the package of data related to the Payee of the scheduled payment or
Transfer and includes the following simple and complex elements and arrays:
PayeeId
This is the Bill Pay Services API identifier for the Payee to whom the single or recurring
payment or Transfer is scheduled. This element is not modifiable for a scheduled
payment or Transfer, but is necessary for the Mod request if newly specified Rush
payment options are included (below).
Bill Pay Services API – User Guide
iPay Solutions™
187
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PayeeAddrInfo
This complex is required for Rush payments (only), and provides the ability to specify the
Payee’s Rush Address to be used for the scheduled payment. An address is required only
for Overnight and 2
nd
Day rush payment options, as these payments are always sent via
check. This complex includes the following simple and complex elements:
PayeeAddrId
This is the Bill Pay Services API identifier for the specified Rush address for the
Payee.
This is the only element required if the Rush Address provided via the preceding
Payee Inquiry is the desired address to be used for the Rush payment.
PayeeAddrType
This specifies the type of payee address being submitted. For Rush payments, the
only applicable Payee Address Type is ‘Rush’. Canonical values are:
o Prim – Primary (default)
o Rush - Rush
PayeeAddr
This complex element contains elements representing the Payee’s Rush address,
and is required for the Rush payment if no Rush Address exists for the Payee (no
Rush Address information was returned in the preceding Payee Inquiry), or the
Subscriber chooses not to use the Rush Address provided via the Payee Inquiry.
StreetAddr1
This is the Payee’s street address for Rush payments.
StreetAddr2 (optional)
This is the second line of the Payee’s street address for Rush payments.
City
This is the name of the city in the Payee’s Rush payment address.
StateCode
This is the 2-character alpha code approved by the USPS which represents a
state.
PostalCode
This is the postal or zip code (Zip+4 is supported).
PmtPayFromAcctInfo
This required complex element contains information on the funding account (‘pay from account’) to be
used to make the payment or Transfer to specified the Payee for this scheduled single or recurring
payment or Transfer.
PayFromId
This is the Bill Pay Services API identifier for the funding account specified for the scheduled
single or recurring payment or Transfer.
If a FutPmtId is specified for this ‘mod’ request, only the funding account associated with the
specified future payment or Transfer in the recurring payment or recurring Transfer series will
be updated. The funding account specified for all other payments in the recurring series will
remain unchanged.
Bill Pay Services API – User Guide
iPay Solutions™
188
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
NOTE: Funding account information (other than the Subscriber’s default account designated for the
Payee) can be specified only if the requesting user has been granted permission to ‘Designate Pay
From Accounts’.
PmtRushOptInfo
This optional complex contains the rush payment details that were specified for the given scheduled
[single] payment and includes the following simple elements:
RushOpt
This represents the desired option for expediting (rushing) the payment to the specified
Payee. Canonical values are:
• Std – Standard (default) – this specifies a ‘non-expedited’ payment
• Ovrngt – Overnight
• 2ndDay – Second Day
• 2ndDayEc – Second Day Economy
NOTE: Not applicable for Transfers.
RecurPmtInfo
This optional complex element contains a package of data related to the recurring payment or
recurring Transfer series (if the scheduled payment mod is for a recurring payment or recurring
Transfer) and includes the below simple elements and arrays necessary to support a recurring
payment or Transfer series using the Bill Pay Services API.
StartPmtProcDt
If updated, this will be the new starting date for processing the existing recurring payment or
recurring Transfer series.This date cannot be less than the First Available Process Date for
the Payee that would be available based on Frequency and Payment Day selections.
StartPmtEstArvDt
If updated, this will be the new starting estimated arrival date (i.e., due date) for the existing
recurring payment or recurring Transfer series.This date cannot be less than the First
Available Estimated Arrival Date for the specified Payee that would now be available based
on Frequency and Payment Day selections.
PmtFreqUnits
This is the payment frequency for a recurring payment or recurring Transfer series. A
specified frequency of ‘Once’ indicates a single payment. Canonical values are:
• Once (default)
• Weekly
• EveryOtherWeek
• Every4Weeks
• Monthly
• TwiceMonthly
• EveryOtherMonth
• Every3Months
• Every6Months
• Annual
Bill Pay Services API – User Guide
iPay Solutions™
189
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PmtDayOfWeek
This is the desired day of the week when recurring payments or recurring Transfers will be
made if the specified payment frequency is: ‘Weekly’, ‘EveryOtherWeek’ or ‘Every4Weeks’.
Canonical values are:
• Mon - Monday
• Tues - Tuesday
• Wed - Wednesday
• Thur - Thursday
• Fri - Friday
PmtDayInfoArray
This optional array contains the PmtDayInfo complex element, which includes a package of
data related to the day(s) of the month a recurring payment or recurring Transfer should be
made if the payment frequency has been specified as ‘Monthly’, ‘TwiceMonthly’,
‘EveryOtherMonth’, ‘Every3Months’, ‘Every6Months’ or ‘Annual’. It includes the following
simple elements:
PmtDayofMonth
This is the day of the month when the recurring payment or Transfer will be made
(e.g., 1 - 31). This value should not be entered if the desired payment/Transfer day is
the last business day of each month.
PmtUseLastBusDay
This indicates that payment or Transfer should be made on the last business day of
the month. Canonical values are:
• True
• False (default)
PayDtInstr
This is the payment date instruction when a recurring payment or recurring Transfer date falls
on a non-processing date (such as a weekend or holiday). For Institutions using the ‘Due
Date’ Payment Date model, this value must be set to ‘Pay Before’. Any other entered value
will be ignored. Canonical values are:
• Before – Pay before (default)
• After – Pay after
PmtOccur
This is the number of payment or Transfer occurrences desired for the recurring payment or
recurring Transfer series.
PmtSerExpDt
This is the expiration date for the recurring payment or recurring Transfer series.
PmtSerFinite
This indicates whether the payment or Transfer series is finite or ‘has no end’. If the series is
not finite, recurring payments/Transfers will continue to be made until the series is terminated
by the Subscriber. Canonical values are:
• True
• False (default)
Bill Pay Services API – User Guide
iPay Solutions™
190
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
RetroToOrigPmtDt
This optional element is available for recurring payments or recurring Transfers that may be
pended for additional payment approval, and specifies the desired action to be taken in the
event a scheduled recurring payment or Transfer is missed while awaiting payment approval.
A Subscriber Inquiry can be performed to determine if payment approvals are required for the
Subscriber. Canonical values are:
• True
• False (default)
NOTE: Setting this value to ‘false’ will ignore a missed payment/Transfer and schedule
the next [second] payment or Transfer in the series once payment approval is received.
A response of ‘true’ will reschedule the original [first] payment or Transfer (with the originally
specified amount) in order to catch up the series, as well as schedule the next [second]
payment or Transfer in the series.
Array(s)
InvoiceInfoArray
This array is applicable for Company Subscribers only at this time and can include a list of
invoices, if applicable for the scheduled payment, and includes the InvoiceInfo complex element for
each line item needed for the Invoice, and contains the following simple elements:
InvoiceId
This is the Service Provider’s (iPay Solutions) identifier for the Invoice.
This element should be left blank when adding a new invoice line item to an existing
scheduled payment, as this value will not be available to the Service Consumer until the
Payment Mod request to add the new invoice item has been completed.
InvoiceNum
This is the invoice number assigned to the invoice by the Payee. A maximum of 20
alphanumeric characters is allowed.
InvoiceCat
This indicates the invoice category for the entered line item. Canonical values are:
• Invoice - Invoice
• Adj – Adjustment
• Disc - Discount
• Oth - Other
InvoiceDesc
This optional element specifies a free-form text description of the invoice line item. A
maximum of 100 alphanumeric characters is allowed.
InvoiceAmtPos
This optional element indicates a positive amount value for the invoice line item.
InvoiceAmtNeg
This optional element indicates a negative amount value for the invoice line item (such as for
an adjustment or discount).
NOTE: Not applicable for Transfers.
Bill Pay Services API – User Guide
iPay Solutions™
191
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Scheduled Payment Mod Behaviors
• iPay will ignore all element values other than those specified above, if passed on a Scheduled
Payment SolutionsMod request.
• In order to change any Scheduled Payment or Transfer elements other than those specified above, a
delete (stop) of the existing scheduled payment or Transfer record is required and the payment or
Transfer must be rescheduled with the new values.
• A request to modify a Scheduled Payment or Transfer that is processing today cannot be
accommodated after the FI’s designated Payment Cutoff Time.
• If a ‘delete’ (stop) of the Scheduled Payment or Transfer is requested, any other information that may
have been modified within the Mod request will be ignored and no update(s) will occur.
o The payment or Transfer will be placed in ‘Stopped’ Payment Status.
• If the scheduled payment or Transfer’s Estimated Arrival Date (i.e., ‘Due Date’) is changed, the
Process Date will be adjusted automatically by the service provider.
o Similarly, if the scheduled payment or Transfer’s Process Date is changed, the Estimated
Arrival Date will be adjusted automatically by the service provider.
• For Company Subscribers:
o Scheduled [Bill] Payments can be modified only if the requesting user (subscriber’s associated
user) has been granted permission to ‘Schedule Bill Payments’, and for the specified Payee.
o P2P Payments can be modified only if the requesting user has been granted permission to
‘Schedule Email Payments’, and for the specified P2P Payee.
o Transfer payments can be modified only if the requesting user (subscriber’s associated user)
has been granted permission to ‘Schedule Transfers’ (i.e., ‘CanTransfer’), and for the specified
Transfer account.
o Funding account (‘pay from account’) information (other than the Subscriber’s default funding
account designated for the Payee) can be modified only if the requesting user has been
granted permission to ‘Designate Pay From Accounts’.
o Modification of the amount or funding account on a Scheduled Payment or Transfer that was
previously approved for payment (where additional payment approval is required) will require
additional payment approval and will be ‘re-pended’ until new payment approval is obtained.
o Invoice information for a scheduled payment can be added or modified.
▪ There is no limit to the number of invoice line items that can be added to a single
payment.
▪ Multiple Invoice Numbers can be included in a single payment.
▪ Only one amount (either Pos or Neg) can be entered per invoice line item.
▪ Invoice information is NOT allowed for recurring payments or Transfers.
• Rush Payment modification options:
o A ‘standard’ (non-expedited) payment can be modified to a Rush payment using any Rush
Option currently available for the specified Payee, provided the Process Date has not passed.
▪ For Overnight or 2
nd
Day rush payments (which are delivered via check), the Payee’s desired
Rush Address must be specified as either of the following:
Bill Pay Services API – User Guide
iPay Solutions™
192
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
• the Payee’s PayeeAddrId, if the Rush Address provided for the Payee in the
preceding Payee Inquiry is the desired address; or
• a new Rush Address for the Payee (PayeeAddr), if no Rush Address exists for the
Payee (no Rush Address information was returned in the preceding Payee Inquiry),
or the Subscriber chooses not to use the Rush Address provided via the Payee
Inquiry.
▪ iPay Solutions will fault a request to change the scheduled payment to a Rush payment
if the payment’s specified Process Date has already passed.
o iPay Solutions will fault a Scheduled Payment mod request if both the Payee’s Rush Address
ID and Payee’s Rush Address are passed at the same time, as the intended Rush payment
Address is unclear.
o iPay Solutionswill also fault a Scheduled Payment Mod request if a Rush Option other than
‘standard’ has been specified, but no Payee Rush Address information is included.
o The Process Date and/or Estimated Arrival Date will be adjusted by the service provider to
accommodate the newly specified Rush Option.
o All Rush payments are subject to the same Expedited Payment rules as when initially
scheduling a Rush payment (See Payment Add details).
• A scheduled payment can also be modified to a standard (non-expedited) payment from a Second
Day Economy Rush payment (only).
NOTE: All corresponding Rush details (e.g., Fees, Rush Address, etc.) will be removed from the
scheduled payment record.
• Recurring Payment modification options:
o Specification of a Future Payment ID in the ‘Mod’ request indicates that the user is intending to
update a single current or future payment or Transfer instance in the recurring series.
o Any updates to recurring series information included in the RecurPmtInfo complex will be applied
to the entire recurring series.
o Modification of any of the elements that affect the Payment Date(s) of the recurring payment or
recurring Transfer series (e.g., Starting Payment Date, Frequency, Payment Day(s), etc.) will
prompt a recalculation of the payment dates for all currently scheduled and future payments or
Transfers associated with the series.
▪ Any modifications to specified future payments or Transfers in the original series will be lost.
o To stop the series, or skip a single payment or Transfer within the series:
▪ An entry in the ‘Dlt’ element indicates a desire for immediate deletion (i.e., ‘stop’) of the entire
recurring payment or recurring Transfer series. The currently scheduled payment or Transfer
and all future payments or Transfers within the series will NOT be processed.
▪ An entry in the ‘DltRecur’ element indicates a desire for deletion (i.e., ‘stop’) of the specified
recurring payment or recurring Transfer series, but only after the currently scheduled
payment or Transfer has been processed. (In other words, a delete of the ‘recurring’ aspect
of the series is desired, but not of the currently scheduled payment or Transfer.)
▪ An entry in the ‘SkipPmtOccur’ element, along with a specification of a FutPmtId, indicates
that only the specified future payment or future Transfer should be skipped; all other
payments or Transfers within the recurring payment or recurring Transfer series will continue
to be processed.
Bill Pay Services API – User Guide
iPay Solutions™
193
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
• Once a future payment or Transfer has been ‘skipped’, no further modifications are
allowed for this future payment/Transfer, including the ability to ‘unskip’ or ‘resume’ the
payment/Transfer.
Response
The service provider (iPay Solutions) returns the BilPaySchedPmtModRs response message to the service
consumer.
The element(s) contained within the BilPaySchedPmtModRs response applicable for the Bill Pay Services
API is/are:
RsStat
This specifies the status of the mod request. Canonical values are:
• Success
• Fail
Bill Pay Services API – User Guide
iPay Solutions™
194
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Scheduled Payment Approval
Container: TPG_BillPayMaster.xsd
Message: BilPaySchedPmtApprv
The bill pay Scheduled Payment Approval <BilPaySchedPmtApprv> will allow the Service Consumer to
provide a payment approval from an authorized approver for a scheduled payment or Transfer that requires
additional approval. The subscriber identifier element <SubId> and Payment ID <PmtId> are required on the
Payment Approval request.
The elements at the root request message will be echoed back at the root response, regardless if those same
elements exist in the repeating complex.
Message Flow
The Scheduled Payment Approval service uses a typical exchange of MType messages to allow the
authorized requesting user to approve a scheduled payment or Transfer that has been pended for additional
payment approval. A Scheduled Payment Search is suggested prior to the approval request in order to
retrieve the Payment ID <PmtID> necessary for payment approval operations.
Request
The third-party consumer forwards the BilPaySchedPmtApprvRq request message to the Service Provider.
Bill Pay Services API – User Guide
iPay Solutions™
195
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
The below simple and complex elements contained within the BilPaySchedPmtApprvRq message request are
necessary for the Bill Pay Services API.
BilPayProd
This represents the type of iPay Solutions service operations being requested. Canonical values are:
• BilPay
• Remit (reserved for future use)
The BilPayProd default value is BilPay.
SubId
This is the Service Provider’s (iPay Solutions) identifier for the subscriber.
PmtId
This is the Bill Pay Services API identifier for the scheduled payment or Transfer that requires
payment approval.
NOTES:
1) The Subscriber Associated User ID <SubAssocUsrId> (i.e., sub user ID) of the requestor providing
payment approval should be entered in the AuthenUsrCred element in the request Message Header.
If NO <SubAssocUsrId> is included in this header field, the Service Provider will assume the payment
approval request is from the Primary Account Holder.
2) In order to execute a payment approval request, the requesting user must have the Approve
Transactions permission.
3) If approval is received for a pending recurring payment or recurring Transfer series, the
‘RetroToOrigPmtDate’ element for the Scheduled Payment or Transfer will be evaluated to determine
if a missed payment should be rescheduled (should a payment or Transfer have been missed); or
ignore any missed payment(s) and simply schedule the next available payment or Transfer in the
recurring series.
Response
The service provider (iPay Solutions) returns the BilPaySchedPmtApprvRs response message to the service
consumer.
The element(s) contained within the BilPaySchedPmtApprvRs response applicable for the Bill Pay Services
API is/are:
RsStat
This specifies the status of the mod request. Canonical values are:
• Success
• Fail
Bill Pay Services API – User Guide
iPay Solutions™
196
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Payment History Search
Container: TPG_BillPayMaster.xsd
Message: BilPayPmtHistSrch
The bill pay Payment History Search <BilPayPmtHistSrch> is designed to allow the consumer to perform
searches on payment history and will return all processed single and/or recurring payments and/or Transfers
for a particular bill pay product and Subscriber.
The request provides the following optional filters:
• Payment Start Date <PmtStartDt>
• Payment End Date <PmtEndDt>
• Payment Low Amount <PmtLowAmt>
• Payment High Amount <PmtHightAmt>
• Payment Status <PmtStat> - default = All
• Payment Intention Type <PmtIntentType> - default = All
• Payee ID <PayeeId>
• Payee Payment Method <PayeePmtMthd>
• P2P Payees <P2PFilter>
• Recurring Payments <RecurFilter>
• Transfers <XferFilter>
• [NEW!] CardPay <CardPayFilter>
When there exists more than one filter on the request, the resulting selection is based on the combined effect
of the filters (i.e., ‘and’ operator). Each added filter option will further restrict the result set.
The elements at the root request message will be echoed back at the root response, regardless if those same
elements exist in the repeating complex.
Message Flow
The Payment History Search service uses a typical exchange of MType messages to retrieve processed
Payment and/or Transfer information for a specified product and Subscriber, based on optional filters.
Request
Bill Pay Services API – User Guide
iPay Solutions™
197
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
The third-party consumer forwards the BilPayPmtHistSrchRq request message to the Service Provider.
The below elements contained within the BilPayPmtHistSrchRq message request are necessary for the Bill
Pay Services API.
BilPayProd
This represents the type of iPay Solutions service operations being requested. Canonical values are:
• BilPay
• Remit (reserved for future use)
The BilPayProd default value is BilPay.
SubId
This is the Service Provider’s (iPay Solutions) identifier for the subscriber.
PmtStartDt
The date that designates the starting point for Payment and/or Transfer [Process] date selections. If
no Start Date is specified, the Bill Pay Services API will return all available processed payments
and/or Transfers that have a Process Date that is less than the specified End Date.
PmtEndDt
The date that designates the ending point for Payment and/or Transfer [Process] date selections. If
no End Date is specified, the Bill Pay Services API will return all available processed payments
and/or Transfers that have a Process Date that is greater than the specified Start Date.
NOTE: If no Date range is specified, the Bill Pay Services API will return all available payments
and/or transfers that satisfy all other filter requirements.
PmtLowAmt
This is the value that designates a starting point for payment and/or Transfer amount selections.
This value is the lowest amount to begin searching when a range of amounts is used to refine the
payment search. If no value is specified, the Bill Pay Services API will utilize a default value of $0 for
this filter parameter.
PmtHighAmt
This is the value that designates an ending point for payment and/or Transfer amount selections.
This value is the highest amount to search for when a range of amounts is used to refine the
payment search. If no value is specified, the Bill Pay Services API will utilize a default value of ‘null’
(i.e., no upper payment amount limit) for this filter parameter.
PmtStat
The status of the payment or Transfer. Valid canonical values for all processed (i.e., ‘non-pending’)
payments are:
• All – All (default)
• Proc – Processed
• Pd – Paid
• Stop – Stopped
• Canc – Canceled
• ReSbm - Resubmitted
• Rfd - Refunded
• Skip – Skipped
• PmtApprv - Payment Approved (for processed payment that received payment approval)
NOTE: See Appendix C for Payment Status definitions.
Bill Pay Services API – User Guide
iPay Solutions™
198
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
[Payment] PmtIntentType
This represents the payment intention for the Payment(s) or Transfer(s). Canonical values are:
• PayBill - Payment for a bill (default)
• XferToSubFinInst - Transfer to Subscriber account at external FI (Outbound)
• XferFromSubFinInst - not supported by iPay Solutions at this time
• XferTo - not supported by iPay Solutions at this time
• XferFrom - not supported by iPay Solutions at this time
If no Payment Intent Type is specified, the Bill Pay Services API will return all available processed
Payments and/or Transfers that satisfy all other filter requirements
PayeeId
This is the Bill Pay Services API identifier for the Payee to whom the payment(s) and/or Transfer(s)
have been made.
If no Payee is specified, the Bill Pay Services API will return processed payments and/or Transfers for
all Payees that satisfy all other specified filters.
PayeePmtMthd
This is the payment method for the Payee associated with the processed payment or Transfer.
Canonical values are:
• Chk – Check
• Email – P2P (electronic, but initial set up is via an email or SMS process)
• Elec - Electronic
P2PFilter
Used to filter payments associated with P2P (i.e., ‘Email’) Payees into (or from) the search results.
Canonical values are:
• Incl – Include P2P payments (default)
• OnlyP2P – Only return P2P payments
• Excl - Exclude P2P payments
RecurFilter
Used to filter recurring payments/Transfers into (or from) the search results. Canonical values are:
• Incl – Include recurring payments (default)
• OnlyRecur – Only return recurring payments
• Excl - Exclude recurring payments
XferFilter
Used to filter Transfer payments into (or from) the search results. Canonical values are:
• Incl – Include Transfers (default)
• OnlyXfer – Only return Transfer payments
• Excl - Exclude Transfer payments
[NEW!] CardPayFilter
Used to filter CardPay payments into (or from) the search results. Canonical values are:
• Incl – Include CardPay payments (default)
• OnlyCardPay – Only return CardPay payments
• Excl - Exclude CardPay payments
Bill Pay Services API – User Guide
iPay Solutions™
199
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
NOTE: If any value entered directly conflicts with another entered filter parameter (i.e., the parameters
Are ‘mutually exclusive’), NO results will be returned.
Response
The service provider (iPay Solutions) returns the BilPayPmtHistSrchRs response message to the service
consumer, which returns a list of all processed single and/or recurring Payments for the specified product and
Subscriber that meet the given search criteria.
Notes:
1) Other types of Payments, such as Gift Payments, etc., will not be included in the result set at this
time.
2) The amount of history that is available to be viewed is determined by the FI’s Extended Storage
specification. For instance, if Extended Storage is set at 18 months, the maximum amount of
Payment (or Transfer) History available for any Subscriber associated with that FI will be 18 months.
3) Payment Historysearch results will be returned in descending Process Date order (newest to oldest).
The array(s) contained within the BilPayPmtHistSrchRs response applicable for the Bill Pay Services API are:
BilPayPmtHistSrchArray
This array returns an array of responses for the Payment History search and includes the
BilPayPmtHistSrchInfo complex element for each single or recurring Payment and/or Transfers returned,
and includes the following simple and complex elements:
PmtID
This is the Bill Pay Services API identifier for the Payment or Transfer.
PayeeId
This is the ID of the Payee or Transfer account.
PayeeName
This is the name of the Payee or Transfer account.
PayeeNickname
This represents the Subscriber’s ‘nickname’ for the Payee or Transfer account.
PmtProcDt
This is the date the payment or Transfer was processed.
PmtEstArvDt
This is the date the payment or Transfer was estimated to be delivered to the Payee.
PmtAmt
This is the amount of the payment or Transfer.
PmtStat
This is the status of the payment or Transfer. Valid canonical values for all processed
payments/Transfers are:
• Proc – Processed
• Pd – Paid
• Stop – Stopped
• Canc – Canceled
Bill Pay Services API – User Guide
iPay Solutions™
200
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
• ReSbm - Resubmitted
• Rfd - Refunded
• Skip – Skipped
• PmtApprv - Payment Approved (for processed payment that received payment approval)
NOTE: See Appendix C for Payment Status definitions.
PmtMthd
This is the payment method used for the Payment or Transfer (this may be different than the original
Payment Method specified for the Payee). Canonical values are:
• Chk – Check
• Elec – Electronic
PmtFreqUnits
This is the payment frequency for the recurring payment or recurring Transfer series at the time the
payment/Transfer was processed. A specified frequency of ‘Once’ indicates a single payment or
Transfer. Canonical values are:
• Once (default)
• Weekly
• EveryOtherWeek
• Every4Weeks
• Monthly
• TwiceMonthly
• EveryOtherMonth
• Every3Months
• Every6Months
• Annual
P2PType
This indicates whether the payment is ‘P2P payment’ (for a ‘P2P Payee type’). Canonical values are:
• True
• False (default)
ElecMerBilPmt
This indicates whether the payment is an ‘eBill payment’ (i.e., has an associated eBill). Canonical
values are:
• True
• False
[Payment] PmtIntentType
This represents the payment intention for the Payment(s) or Transfer(s). Canonical values are:
• PayBill - Payment for a bill (default)
• XferToSubFinInst - Transfer to Subscriber account at external FI (Outbound)
• XferFromSubFinInst - not supported by iPay Solutions at this time
• XferTo - not supported by iPay Solutions at this time
• XferFrom - not supported by iPay Solutions at this time
PayFromAcctInfo
This complex element contains information on the funding account (‘pay from account’) designated
for the specified Payment or Transfer.
Bill Pay Services API – User Guide
iPay Solutions™
201
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
NOTE: For Company Subscribers, Pay From Account Info (‘funding account’) is eligible for viewing
ONLY if the requesting user has been granted permission to ‘Designate Pay From Account’
information. If the requesting user does not have permission, the <Rstr> attribute for each of these
elements will be set to ‘Hid’, which indicates that the Service Consumer should hide these elements
from the requesting user.
PayFromId
This is the Bill Pay Services API identifier for the funding account specified for the Payment
or Transfer.
PayFromAcctId
The bank account number of the funding account designated for this Payment or Transfer.
PayFromAcctType
The number(s) or character(s) that categorize the type of funding account. Canonical values
are:
• D – Checking
• S – Savings
PayFromAcctName
This is the account name for the subscriber’s funding account.
PayFromAcctDft
This indicates whether the funding account is the ‘default’ account, to be used in the event a
pay from account is not specified when scheduling a payment or Transfer. Canonical values
are:
• True
• False (default value)
StartChkNum
This is the check number that will be used to start check payments from the specified funding
account. This will be available only if the Subscriber’s Product allows specification of a
starting check number.
PayFromIntsRtId
This is the routing transit number or ABA number of the FI where the subscriber’s funding
account resides.
PayFromAcctStat
This is the status of the pay from account as it relates to its potential use within the
Subscriber’s Bill Pay account. Canonical values are:
• Pend - Pending
• Apprv - Approved
PayFromAcctOwnName
This optional complex element contains information for the funding account (‘pay from
account’) Owner’s Name (if the actual owner of the account is not the Subscriber), and
includes the following simple elements, as well as an optional x_PersonName complex
element (which is not currently used for the Bill Pay Services API):
ComName
This represents the funding account Owner’s Name, if the ‘actual’ owner of the
account is a Company.
FirstName
Bill Pay Services API – User Guide
iPay Solutions™
202
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
This represents the funding account owner’s First Name, if the owner of the account
is a person.
MiddleName
This optional element represents the funding account owner’s Middle Name, if the
owner of the account is a person.
LastName
This optional element represents the funding account owner’s Last Name, if the
owner of the account is a person.
NOTE: Funding account (‘pay from account’) owner information is allowed only if the subscriber’s
product permits it, and if the specific subscriber is authorized to include funding account owner
information.
PayFromAcctOwnAddr
This complex element is an optional element which contains information for the funding
account (‘pay from account’) Owner’s Address (if the actual owner of the account is not the
Subscriber), and includes the following simple elements:
StreetAddr1
This is the Subscriber’s street address.
StreetAddr2
This is the second line of the Subscriber’s street address.
City
This is the name of the city in the Subscriber’s address.
StateCode
This is the two-character alpha code approved by the USPS which represents a
state.
PostalCode
This is the postal or ZIP Code (ZIP+4 is supported).
Bill Pay Services API – User Guide
iPay Solutions™
203
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Payment History Inquiry
Container: TPG_BillPayMaster.xsd
Message: BilPayPmtHistInq
The bill pay Payment History Inquiry <BilPayPmtHistInq> will return element details for a specific single or
recurring payment or Transfer made for a given Subscriber. The subscriber identification element <SubId>
and Payment ID <PmtId> are required on the request.
The service provider will include the additional payment or Transfer status history, payment check status
history, and payment check tracking information elements when the x_PmtStatHistArray,
x_PmtChkStatHistArray, and x_PmtChkTrakInfo are included in the extended element array complex request.
To receive eBill information pertaining to the payment, the request must include the x_ElecBilPmtInfo complex
in the extended element array complex.
The elements at the root request message will be echoed back at the root response, regardless if those same
elements exist in the repeating complex.
Message Flow
The Payment History Inquiry service uses a typical exchange of MType messages to retrieve payment or
Transfer information for a given Subscriber, based on the required Subscriber ID and Payment ID. If the
Payment ID is not known, the third-party consumer must first perform a Payment History Search to obtain the
Payment ID for the desired payment or Transfer.
Payment History Inquiry Request
BilPayPmtHistInqRq_MType
The Third Party sends the
BilPayPmtHistInqRq
message containing the required
SubID
and optional
BilPayProd
element
,
as well as the required
PmtID
element for the
desired payment
.
Payment History Inquiry Response
BilPayPmtHistInqRs_MType
The Service Provider sends the BilPayPmtHistInqRs message containing an echo of the
request, plus BilPayPmtHistInfo for the specified payment.
Payment History Search Request
BilPayPmtHistSrchRq_MType
Payment History Search Response
BilPayPmtHistSrchRs_MType
The Service Provider sends the
BilPayPmtHistSrchRs
message containing an echo of the
request
,
plus
BilPayPmtHistSrchArray
,
as well as the required Payment ID
<
PmtID
>
for the
desired payment
.
The Third Party sends the
BilPayPmtHistSrchRq
message containing the
SubID
and optional
BilPayProd
element
,
as well as optional search filter
elements
:
PmtStartDt
,
PmtEndDt
,
PmtLowAmt
,
PmtHightAmt
,
PmtStat
.
PayeeID
,
PayeePmtMtdh
,
P
2
PFilter
and
RecurFilter
Request
Bill Pay Services API – User Guide
iPay Solutions™
204
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
The third-party consumer forwards the BilPayPmtHistInqRq request message to the Service Provider.
The below elements contained within the BilPayPmtHistInqRq message request are necessary for the Bill Pay
Services API.
BilPayProd
This represents the type of iPay Solutions service operations being requested. Canonical values are:
• BilPay
• Remit (reserved for future use)
The BilPayProd default value is BilPay.
SubId
This is the Service Provider’s (iPay Solutions) identifier for the Subscriber.
PmtId
This is the Bill Pay Services API identifier for the processed payment or Transfer.
IncChkImg
This is used to request check image information. (Not applicable for Transfers.) Canonical values are:
• True
• False
If the specified payment was not made by check, any entry for this element will be ignored.
IncXtendElemArray
This array contains a list of extended ‘x_’ elements that are to be included in the response. Valid
canonical values for the Bill Pay Services API are:
• x_PmtStatHistArray
• x_PmtChkStatHistArray (not applicable for Transfers)
• x_PmtChkTrakInfo (not applicable for Transfers)
• x_ElecBilPmtInfo (not applicable for Transfers)
Response
The service provider (iPay Solutions) returns the BilPayPmtHistInqRs response message to the service
consumer, which returns a package of payment information for the specified single or recurring payment or
Transfer.
The simple and complex elements contained within the BilPayPmtHistInqRs response applicable for the Bill
Pay Services API are:
PmtCrtDt
The date the payment or Transfer was created by the Subscriber.
PmtStat
The status of the payment or Transfer. Valid canonical values for all processed payments are:
• Proc – Processed
• Pd – Paid
• Stop – Stopped
• Canc – Canceled
• ReSbm - Resubmitted
• Rfd – Refunded
• Skip – Skipped
• PmtApprv - Payment Approved (for processed payment that required payment approval)
NOTE: See Appendix C for Payment Status definitions.
Bill Pay Services API – User Guide
iPay Solutions™
205
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PmtMthd
This is the payment method that was used for the payment or Transfer. Applicable canonical values for
the actual payment or Transfer are:
• Chk – Check
• Elec – Electronic
BilPayPmtInfo
This complex element contains a package of data related to a payment or Transfer and includes the
below simple and complex elements and arrays for the Bill Pay Services API.
PmtProcDt
This is the date the payment or Transfer was processed.
PmtEstArvDt
This is the date the payment or Transfer was estimated to be delivered to the Payee.
PmtAmt
This is the amount of the payment or Transfer.
PmtCmnt
This is the comment that was stored with the payment or Transfer. This is for the Subscriber’s
internal use only and was not included with the Payment.
PmtChkMemo
This is the memo that was added to a check payment, if the payment was made by check.
SubCmntToPayee
This is the personalized message that was added to the email sent to a P2P payment recipient
notifying them that a payment was made.
[Payment] PmtIntentType
This represents the payment intention for the Payment(s) or Transfer(s). Canonical values are:
• PayBill - Payment for a bill (default)
• XferToSubFinInst - Transfer to Subscriber account at external FI (Outbound)
• XferFromSubFinInst - not supported by iPay Solutions at this time
• XferTo - not supported by iPay Solitions at this time
• XferFrom - not supported by iPay Solutions at this time
NOTE: Until such time as additional Transfer options are available, the PmtIntentType of the
Payment or Transfer will match the PmtIntentType of the Payee.
PmtPayeeInfo
This complex contains the package of data related to the Payee of the payment or Transfer and
includes the following simple and complex elements and arrays:
PayeeId
This is the ID of the Payee to whom the payment or Transfer was made.
PayeeName
This is the name of the Payee to whom the payment or Transfer was made.
PayeeNickname
This represents the Subscriber’s ‘nickname’ for the Payee or Transfer account.
Bill Pay Services API – User Guide
iPay Solutions™
206
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PayeeClsf
This specifies the classification of the Payee or Transfer account. Canonical values are:
• Comp (Company)
• Indv (Individual/Person)
• FinInst (FI) – to be used for Transfer accounts
PayeePmtMthd
This is the ‘default’ payment method specified for the Payee or Transfer account. This may
not be the actual Payment method utilized for the payment or Transfer. Canonical values
are:
• Chk – Check
• Email – P2P (electronic, but initial set up via an email or SMS process)
• Elec – Electronic
[Payee] PmtIntentType
This represents the payment intention of the Payee or Transfer account. Canonical
values are:
• PayBill - Payment for a bill (default)
• XferToSubFinInst - Transfer to Subscriber account at external FI (Outbound)
• XferFromSubFinInst - not supported by iPay Solutions at this time
• XferTo - not supported by iPay Solutions at this time
• XferFrom - not supported by iPay Solutions at this time
SubMerAcctId
This is the Subscriber’s account number with the Merchant/Payee. For Transfer accounts,
this value will be the Account Holder’s account number (of the Transfer account).
If the subscriber’s name (Last Name, First Name) is being used for this element, the value
will be truncated at 50 characters.
If no value exists for this element, the default value returned will be ‘N/A’.
SubMerPayerName
This is the Subscriber’s name understood by the merchant and is used to override the
Subscriber’s name on record.
PayeeAddrInfo
This complex contains a package of data related to the Payee’s address specified for the
payment. In the case of an electronic payment, this will simply be the Payee’s ‘primary’ or
‘standard’ address. No address will be available for Transfer accounts. This complex includes
the following simple and complex elements:
PayeeAddrId
This is the Bill Pay Services API identifier for the specified address for the Payee.
Bill Pay Services API – User Guide
iPay Solutions™
207
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PayeeAddrType
This specifies the type of payee address that was utilized for the payment. Canonical
values are:
• Prim – Primary (default)
• Rush - Rush
PayeeAddr
This complex element contains elements representing the Payee’s address utilized
for the payment. For Rush payments made by check, this will be the Payee’s
specified ‘Rush’ address.
StreetAddr1
This is the Payee’s street address.
StreetAddr2 (optional)
This is the second line of the Payee’s street address.
City
This is the name of the city in the Payee’s address.
StateCode
This is the 2-character alpha code approved by the USPS which represents a
state.
PostalCode
This is the postal or ZIP Code (ZIP+4 is supported).
PayeePhoneArray
This array contains an array of phone information for the specified Payee, if available (not
applicable for all Payees).
PhoneNum
This represents a phone number, including area code, for the Payee. This is the
Payee’s Work (Business) number.
PhoneType
This specifies the type of phone number contained in the PhoneNum element
(above). Current canonical values for Payees for the Bill Pay Services API are:
• Work
• SMS
PayeeEmailArray
This optional array contains the EmailInfo complex element, which includes a package of
email data for the Payee, if available (not applicable for all Payees).
EmailAddr
This element specifies the email address of the Payee. This is a valid element only if
the Payee’s PayeePmtMthd = ‘Email’.
EmailType
This element specifies to whom the email address applies. Applicable canonical
values for a Payee for the Bill Pay Services API are:
• Prim – Primary (default)
Bill Pay Services API – User Guide
iPay Solutions™
208
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PmtRushOptInfo
This optional complex contains the rush payment details that were specified for the given payment, if
the payment was a rush payment, and includes the following simple elements:
RushOpt
This represents the specified option for expediting (rushing) the payment to the specified
Payee. Canonical values are:
• Std – Standard (default) – this specifies a ‘non-expedited’ payment
• Ovrngt – Overnight
• 2ndDay – Second Day
• 2ndDayEc – Second Day Economy
RushOptFeeAmt
This specifies the fee associated with the selected Rush Option.
RushOptSurChg
This specifies the surcharge that was applied for the Rush payment, if the Rush payment was
sent to Puerto Rico.
PmtPayFromAcctInfo
This required complex element contains information on the furnding account (‘pay from account’) that
was used to make the payment or Transfer to the specified Payee or Transfer account.
NOTE: For Company Subscribers: Funding account information can be viewed if the requesting user
has permission to designate funding account information. If the requesting user does not have
permission, the <Rstr> attribute for each of these elements will be set to Hid, which indicates the
Service Consumer should hide these elements from the requesting user.
PayFromId
This is the Bill Pay Services API identifier for the funding account specified for the payment or
Transfer.
PayFromAcctId
The bank account number of the funding account designated for this Payment or Transfer.
PayFromAcctType
The number(s) or character(s) that categorize the type of funding account. Canonical values
are:
• D – Checking
• S – Savings
PayFromAcctName
This is the account name for the specified funding account.
PayFromAcctDft
This indicates whether the funding account is the subscriber’s designated ‘default’ funding
account, which is the funding account used if a funding account was not specified when the
payment or Transfer was scheduled. Canonical values are:
• True
• False (default value)
StartChkNum
This is the check number that will be used to start check payments from the specified funding
account. This will be available only if the Subscriber’s Product allows specification of a
starting check number.
Bill Pay Services API – User Guide
iPay Solutions™
209
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PayFromIntsRtId
This is the routing transit number or ABA number of the FI where the subscriber’s funding
account resides.
PayFromAcctStat
This is the status of the funding account as it relates to its potential use within the
Subscriber’s Bill Pay account. Canonical values are:
• Pend - Pending
• Apprv - Approved
PayFromAcctOwnName
This optional complex element contains information for the funding account (‘pay from
account’) Account Owner’s Name (if the actual owner of the account is not the Subscriber),
and includes the following simple elements, as well as an optional x_PersonName complex
element (which is not currently used for the Bill Pay Services API):
ComName
This represents the funding account Owner’s Name, if the ‘actual’ owner of the
account is a Company.
FirstName
This represents the funding account Owner’s First Name, if the ‘actual’ owner of the
account is a person.
MiddleName
This optional element represents the funding account Owner’s Middle Name, if the
‘actual’ owner of the account is a person.
LastName
This optional element represents the funding account Owner’s Last Name, if the
‘actual’ owner of the account is a person.
NOTE: Funding account (‘pay from account’) Owner information is allowed only if the
Subscriber’s Product allows this information on the Subscriber’s funding account(s), and
then only if the specific Subscriber is authorized to include funding account Owner
information.
PayFromAcctOwnAddr
This complex element is an optional element which contains information for the funding
account (‘pay from account’) Owner’s Address (if the actual owner of the funding account is
not the Subscriber), and includes the following simple elements:
StreetAddr1
This is the Subscriber’s street address.
StreetAddr2
This is the second line of the Subscriber’s street address.
City
This is the name of the city in the Subscriber’s address.
StateCode
This is the 2-character alpha code approved by the USPS which represents a state.
PostalCode
This is the postal or zip code (Zip+4 is supported).
Bill Pay Services API – User Guide
iPay Solutions™
210
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
NOTE: Funding account (‘pay from account’) Owner information is allowed only if the
Subscriber’s Product allows this information on the Subscriber’s funding account(s), and
then only if the specific Subscriber is authorized to include funding account Owner
information.
RecurPmtInfo
This optional complex element contains a package of data related to the recurring payment or
recurring Transfer series (if the payment history inquiry is for a recurring payment or recurring
Transfer) and includes the below simple elements and arrays associated with the recurring payment
or Transfer series at the time the specified payment or Transfer was processed (any modifications to
the recurring payment or recurring Transfer series made after the specified payment or Transfer was
processed will not be represented here).
StartPmtProcDt
This is the [original] starting date for processing the recurring payment or Transfer series.
StartPmtEstArvDt
This is the [original] starting estimated arrival date (i.e., ‘due date’) for the recurring payment
or Transfer series.
PmtFreqUnits
This is the payment frequency for the recurring payment or Transfer series. A specified
frequency of ‘Once’ indicates a ‘single’ (i.e. not a recurring) payment or Transfer. Canonical
values are:
• Once (default)
• Weekly
• EveryOtherWeek
• Every4Weeks
• Monthly
• TwiceMonthly
• EveryOtherMonth
• Every3Months
• Every6Months
• Annual
PmtDayOfWeek
This is the specified day of the week when recurring payments or Transfers will be made if
the specified payment frequency is: ‘Weekly’, ‘EveryOtherWeek’ or ‘Every4Weeks’. Canonical
values are:
• Mon - Monday
• Tues - Tuesday
• Wed - Wednesday
• Thur - Thursday
• Fri - Friday
Bill Pay Services API – User Guide
iPay Solutions™
211
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PmtDayInfoArray
This optional array contains the PmtDayInfo complex element, which includes a package of
data related to the day(s) of the month a recurring payment or recurring Transfer should be
made if the payment frequency has been specified as ‘Monthly’, ‘TwiceMonthly’,
‘EveryOtherMonth’, ‘Every3Months’, ‘Every6Months’ or ‘Annual’. It includes the following
simple elements:
PmtDayofMonth
This is the day of the month when the recurring payment or Transfer will be made
(e.g., 1 - 31). This value will not be present if the desired payment day is the last
business day of each month.
PmtUseLastBusDay
This indicates that the payment or Transfer should be made on the last business day
of the month. Canonical values are:
• True
• False (default)
PayDtInstr
This is the payment date instruction when a recurring payment or Transfer date falls on a
non-processing date (such as a weekend or holiday). Canonical values are:
• Before – Pay before (default)
• After – Pay after
PmtOccur
This is the number of remaining payment or Transfer occurrences for the recurring payment
or recurring Transfer series at the time the specified payment or Transfer was processed.
PmtSerExpDt
This is the expiration date for the recurring payment or Transfer series that was indicated at
the time the payment or Transfer was processed.
PmtSerFinite
This indicates whether the payment or Transfer series is finite or ‘has no end’. If the series is
not finite, recurring payments/Transfers will continue to be made until the series is terminated
by the Subscriber. Canonical values are:
• True
• False (default)
RetroToOrigPmtDt
This element is for recurring payments or Transfers that may have been pended for additional
payment approval, and specifies the desired action taken in the event a scheduled recurring
payment or Transfer was missed while awaiting payment approval. Canonical values are:
• True
• False (default)
NOTE: A value of ‘false’ ignores a missed payment or Transfer and schedules the next
[second] Payment/Transfer in the series once payment approval is received. A value of
‘true’ reschedules the original [first] payment or Transfer (with the originally specified
amount) in order to catch up the series, as well as schedules the next [second] payment or
Transfer in the series.
Bill Pay Services API – User Guide
iPay Solutions™
212
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
BilPaySvcFeeInfoRec
This complex contains a package of Service Fee (or ‘payment surcharge’) information applied to the
Payment or Transfer.
SvcFeeDesc
This element specifies the type of payment or Transfer to which the service fee is applicable.
A ‘Service Dictionary Search’ request is necessary to obtain the current list of available
Service Fee Descriptions.
SvcFeeAmt
This element specifies the amount of the Service Fee that was applied to the Payment or
Transfer.
Array(s):
InvoiceInfoArray
This array can include a list of invoices, if applicable for the processed payment, and includes the
InvoiceInfo complex element for each line item entered for the Invoice, and contains the following
simple elements:
InvoiceID
This is the Service Provider’s (iPay Solutions) identifier for the Invoice.
InvoiceNum
This is the invoice number assigned to the invoice by the Payee.
InvoiceCat
This indicates the invoice category for the entered line item. Canonical values are:
• Invoice - Invoice
• Adj – Adjustment
• Disc - Discount
• Oth - Other
InvoiceDesc
This optional element specifies a free-form text description of the invoice line item.
InvoiceAmtPos
This optional element indicates a positive amount value for the invoice line item.
InvoiceAmtNeg
This optional element indicates a negative amount value for the invoice line item (such as for
an adjustment or discount).
NOTE: Not applicable for Transfers
PmtChkNum
This is the check number of the check created for the payment, if the payment was made by
check.
Bill Pay Services API – User Guide
iPay Solutions™
213
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PmtChkStat
The status of the check associated with the payment, if the payment was made by check. Canonical
values are:
• Pend – Pending
• Prt – Printed
• Stop – Stopped
• Ri – Reissued
• PrtRi – Printed Reissue
• PendRi – Pending Reissue
• Rfd – Refunded
• Prst – Presented
• Clr – Cleared
• StopRq – Stop Requested
• SusNotPd – Suspect Not Paid
PmtChkImgInfo
An optional complex element containing a package of data related to a payment check image, if the
payment was made by check.
ChkImgFormat
This is the value that defines the file format that is used to deliver the check image. Canonical values
are:
• JPG
• TIFF
• GIF
• PNG
• IOCA
FrontChkImgLength
This specifies the length of the front of the check image.
FrontChkImg
The front of the check image.
BakChkImgLength
This specifies the length of the back of the check image.
BakChkImg
The back of the check image.
NOTE: The availability of check image information is based on the following factors:
1) whether the check has cleared (only cleared checks are available for imaging);
2) whether the Subscriber’s FI has the ‘Check Image’ service (this information is provided in the
Channel Inquiry);
3) the payment’s processing date falls within the Check Image availability time frame specified
for the FI; and
4) the Check Funding Model utilized by the FI (e.g., check images are available for the iPay
Solutions Draft/Good Funds model, but not for Institutions utilizing the Subscriber Draft/Risk
model).
Bill Pay Services API – User Guide
iPay Solutions™
214
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
x_ElecBilPmtInfo
This optional complex element contains a package of data related to the eBill that corresponds to the
processed payment and includes the below simple elements and arrays for the Bill Pay Services API.
StmtDt
This is the statement date for the eBill associated with the payment.
PmtDueDt
This is the date the payment was due for the eBill associated with the payment.
StmtBal
This is the statement balance for the eBill associated with the payment. A ‘statement balance’
amount is available only for credit card (‘CCA’) account types.
CurBal
This is the total [outstanding] current balance of the Subscriber’s account with the Payee that was
provided on the eBill associated with the payment. This amount may be different than the Statement
Balance for the corresponding eBill. A ‘current balance’ amount is available only for credit card
(‘CCA’) account types.
PmtAmtDue
This is the payment amount that was due for the eBill associated with the payment. This value is
available only for ‘non-credit card’ accounts (account type not = ‘CCA’).
MinPmtAmt
This is the minimum amount that was due for the eBill associated with the payment. A minimum
amount due is available only for credit card (‘CCA’) account types.
ElecBilPmtAuto
This indicates whether the [eBill] payment was originally scheduled based on an automatic eBill
payment schedule for the Payee. Canonical values are:
• True
• False
NOTE: Not applicable for Transfers.
x_PmtStatHistArray
An optional array of responses for the payment status changes associated with this payment or Transfer.
This will be always be included in the the Bill Pay Services API response, regardless of any entry in the
Xtended Element Array in the BilPayPmtHistInqRq message.
PmtStat
The status of the payment or Transfer as of the payment’s Status Change Date. Valid canonical
values for all processed payments are:
• Proc – Processed
• Pd – Paid
• Stop – Stopped
• Canc – Canceled
• ReSbm - Resubmitted
• Rfd – Refunded
Bill Pay Services API – User Guide
iPay Solutions™
215
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
• Skip – Skipped
• PmtApprv - Payment Approved (for processed payment that required payment approval)
NOTE: See Appendix C for Payment Status definitions.
PmtStatChngDt
The date the status of the payment or Transfer was changed.
PmtExcDesc
The exception description associated with a payment or Transfer status change.
PmtChngBy
The entity that made the status change.
x_PmtChkStatHistArray
An optional array of responses for the check status changes associated with this payment, if the payment was
made by check. This x_ array must be explicitly requested in the Xtended Element Array in the
BilPayPmtHistInqRq message, if check status history is desired in the response.
PmtChkStat
The status of the check associated with the payment as of the check’s Status Change Date.
Canonical values are:
• Pend – Pending
• Prt – Printed
• Stop – Stopped
• Ri – Reissued
• PrtRi – Printed Reissue
• PendRi – Pending Reissue
• Rfd – Refunded
• Prst – Presented
• Clr – Cleared
• StopRq – Stop Requested
• SusNotPd – Suspect Not Paid
PmtChkStatChngDt
The date the status of the payment check was changed.
NOTE: The availability of check status history information is based on the Check Funding Model used by the
FI (e.g., check status timelines are available for both the iPay Solutions Draft/Good Funds and Subscriber
Draft/Risk models, but not for FIs using the Institution Draft model).
x_PmtChkTrakInfo
An optional complex which includes a package of data related to a payment’s check tracking information,
if the payment was made by check. This will be always be included in the Bill Pay Services API response
(if available), regardless of any entry in the Xtended Element Array in the BilPayPmtHistInqRq message.
PmtChkTrakCarr
The tracking carrier of the check created for the payment.
PmtChkTrakId
The tracking identifier of the check created for the payment.
Bill Pay Services API – User Guide
iPay Solutions™
216
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PmtChkTrakArray
This is an array of the individual responses for payment check tracking records, and includes the
following complex element for each available tracking record:
PmtChkTrakRecInfo
PmtChkTrakDt
This is the tracking date of the check.
PmtChkTrakLoc
This is the tracking location of the check created for the payment as of the specified
tracking date.
PmtChkTrakStat
The tracking status description provided by the tracking carrier of the check created
for the payment.
PmtChkTrakCmnt
The tracking comment provided by the tracking carrier of the check created for the
payment.
Bill Pay Services API – User Guide
iPay Solutions™
217
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
eBill Services
eBill Search
Container: TPG_BillPayMaster.xsd
Message: BilPayElecBillSchedSrch
The bill pay eBill Search <BilPayElecBillSchedSrch> is designed to allow the consumer to perform searches
on eBills (both current and historical) and will return all eBills for a particular bill pay product and Subscriber.
The request provides the following optional filters:
• eBill Start Date <StartDt>
• eBill End Date <EndDt>
• Payee Name <PayeeName>
• eBill Status <ElecBilStat>
When there exists more than one filter on the request, the resulting selection is based on the combined effect
of the filters (i.e., ‘and’ operator). Each added filter option will further restrict the result set.
The elements at the root request message will be echoed back at the root response, regardless if those same
elements exist in the repeating complex.
Message Flow
The eBill Search service uses a typical exchange of MType messages to retrieve eBill information for a
specified product and Subscriber, based on optional filters.
Request
The third-party consumer forwards the BilPayElecBilSchedSrchRq request message to the Service Provider.
The below elements contained within the BilPayElecBilSchedSrchRq message request are necessary for the
Bill Pay Services API.
Bill Pay Services API – User Guide
iPay Solutions™
218
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
BilPayProd
This represents the type of iPay Solutions service operations being requested. Canonical values are:
• BilPay
• Remit (reserved for future use)
The BilPayProd default value is ‘BilPay’.
SubId
This is the Service Provider’s (iPay Solutions) identifier for the Subscriber.
StartDt
This is the date that designates the starting point for eBill [Due] date selections. If no Start Date is
specified, the Bill Pay Services API will return all available eBills that have a Due Date that
is less than the specified End Date.
EndDt
This is the date that designates the ending point for eBill [Due] date selections. If no End Date is
specified, the Bill Pay Services API will return all available eBills that have a Due Date that
is greater than the specified Start Date.
NOTE: If no Date range is specified, the Bill Pay Services API will return all available eBills that
satisfy all other filter requirements.
PayeeName
This is the name of the Payee.
If no Payee Name is specified, the Bill Pay Services API will return eBills for all ‘eBill-enrolled’ Payees
(i.e., Payees with registered eBill accounts) that satisfy all other specified filters.
If entered, the ‘SrchType’ attribute entered for this element will be evaluated to determine the type of
‘Name’ search (i.e., ‘wildcard’ search) to execute. Valid canonical values are:
• Exact – (default)
• StartsWith
• Contains
ElecBilStat
This is the status of the eBill. Valid canonical values are:
• ComingDue – eBill with a Due Date that has not yet passed (may be associated with a
currently scheduled payment)
• UnPd – Unpaid (eBill’s Due Date is in the past, but eBill is not associated with a processed
payment on the Subscriber’s bill pay account and has not been ‘filed’)
• Pd – Paid (eBill is associated with a processed payment on the Subscriber’s bill pay
account)
• SubProc – eBill has been ‘filed’ by the Subscriber
If no eBill Status is specified, the Bill Pay Services API service will return all eBills that satisfy all other
specified filters, regardless of status.
ElecBilPayeeAcctId
This is the identifier associated with the Subscriber’s registered eBill account with the
Merchant/Payee.
If entered, the Bill Pay Services API will return only those eBills received for the specified Payee eBill
Account that also satisfy all other specified filters.
Bill Pay Services API – User Guide
iPay Solutions™
219
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Response
The service provider (iPay Solutions) returns the BilPayElecBilSchedSrchRs response message to the
service consumer, which returns a list of all eBills for the specified product and Subscriber that meet the given
search criteria.
NOTE: The amount of history that is available to be viewed is determined by the FI’s Extended Storage
specification. For instance, if Extended Storage is set at 18 months, the maximum amount of eBill history
available for any Subscriber associated with that FI will be 18 months.
The array(s) contained within the BilPayElecBilSchedSrchRs response applicable for the Bill Pay Services
API are:
BilPayElecBilSchedSrchArray
This array returns an array of responses for the eBill search and includes the BilPayElecBilSchedSrchInfo
complex element for each eBill returned, which includes the following simple elements:
ElecBilId
This is the Bill Pay Services API identifier for the eBill.
ElecBilPayeeName
This is the name of the Payee for the specified eBill.
ElecBilPayeeAcctId
This is the identifier associated with the Subscriber’s registered eBill account with the
Merchant/Payee.
ElecBilStat
This is the status of the eBill. Valid canonical values are:
• ComingDue – eBill with a Due Date that has not yet passed (may be associated with a
currently scheduled payment)
• UnPd – Unpaid (eBill’s Due Date is in the past, but eBill is not associated with a processed
payment on the Subscriber’s bill pay account and has not been ‘filed’)
• Pd – Paid (eBill is associated with a processed payment on the Subscriber’s bill pay
account)
• SubProc – eBill has been ‘filed’ by the Subscriber
PmtDueDt
This is the date the payment is/was due for the specified eBill.
StmtDt
This is the statement date for the specified eBill.
StmtBal
This is the statement balance for the specified eBill. A ‘statement balance’ amount is available only
for credit card (‘CCA’) account types.
PmtAmtDue
This is the payment amount that is/was due for the specified eBill. This value is available only for
‘non-credit card’ accounts (account type not = ‘CCA’).
Bill Pay Services API – User Guide
iPay Solutions™
220
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
CurrBal
This is the total [outstanding] current balance of the Subscriber’s account with the Payee. This
amount may be different than the Statement Balance for the corresponding eBill. A ‘current balance’
amount is available only for credit card (‘CCA’) account types.
MinPmtAmt
This is the minimum amount due for the specified eBill. A minimum amount due is available only for
credit card (‘CCA’) account types.
Bill Pay Services API – User Guide
iPay Solutions™
221
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
eBill Inquiry
Container: TPG_BillPayMaster.xsd
Message: BilPayElecBilSchedInq
The bill pay eBill Inquiry <BilPayElecBilSchedInq> will return element details for a specific eBill for a given
Subscriber. The subscriber identification element <SubId> and eBill ID <ElecBilId> are required on the
request.
The design of the inquiry was created in a manner that facilitates modification requests. The activity intention
element <ActIntent> was added to support the concurrency model for future modifications made to eBills.
The elements at the root request message will be echoed back at the root response, regardless if those same
elements exist in the repeating complex.
Message Flow
The eBill Inquiry service uses a typical exchange of MType messages to retrieve eBill information for a given
subscriber, based on the required Subscriber ID and eBill ID. If the eBill ID is not known, the third-party
consumer must first perform an eBill Search to obtain the eBill ID for the desired eBill.
Request
The third-party consumer forwards the BilPayElecBilSchedInqRq request message to the Service Provider.
Bill Pay Services API – User Guide
iPay Solutions™
222
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
The below elements contained within the BilPayElecBilSchedInqRq message request are necessary for the
Bill Pay Services API.
BilPayProd
This represents the type of iPay Solutions service operations being requested. Canonical values are:
• BilPay
• Remit (reserved for future use)
The BilPayProd default value is BilPay.
SubId
This is the Service Provider’s (iPay Solutions) identifier for the subscriber.
ElecBilId
This is the Bill Pay Services API identifier for the eBill.
ActIntent
This indicator conveys the service consumer’s intention for a subsequent operation for the data set
included in the response. Canonical values are:
• ReadOnly – indicates a view intent only for the data set included in the Inquiry response.
This is the default value.
• Upd – indicates the intention to perform a subsequent update (‘Mod’) to the data set
included in the Inquiry response
• Dlt – indicates the intention to perform a subsequent delete of the data set included in the
Inquiry response. This action is not available for eBill inquiries.
The following three (3) elements are required entries ONLY if detailed eBill information (i.e., full
electronic billing statements) is available for the specified eBiller (where Payee’s
<ElecBilPayeeType> = ‘Enroll’ and <ElecBilPayeeCatType> = ‘Det’) and then ONLY if the full eBill
statement will be viewed on a mobile device.
MobDevType
This indicates whether the [end-user’s] device being used to view eBill detail information is a mobile
device. This is necessary so correct sizing of eBill detail media can be delivered to the mobile
device. Canonical values are:
• True
• False (default value)
MobDevResoType
This specifies the size of the resolution for the mobile device, and is needed to deliver correct sizing
of eBill detail media to the device. Entry is required if the request indicates a mobile device is being
used. If no value is specified, the default value will be used. Valid canonical values are:
• 1 - small resolution (under 1280 pixels)
• 2 - medium resolution (1280x768 to 1440x900 pixels) (default value)
• 3 - large resolution (1600x900 to 2732x2048 pixels)
• 4 - extra large resolution (3000x2000 to 5120x2880 pixels)
NOTE: The largest current resolutions per device are:
• 2560x1440 – largest current phone resolution
• 2732x2048 – largest current tablet resolution
• 5120x2880 – largest current desktop resolution
Bill Pay Services API – User Guide
iPay Solutions™
223
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Orientation
This specifies the desired orientation of the eBill detail media when displayed on the mobile
device. Entry is required if the request indicates a mobile device is being used. If no value is
specified, the default value will be used. Valid canonical values are:
• Landscape
• Portrait (default value)
• RvrLandscape (not supported by iPay Solutions at this time)
• RvrPortrait (not supported by iPay Solutions at this time)
Response
The service provider (iPay Solutions) returns the BilPayElecBilSchedInqRs response message to the service
consumer, which returns a package of eBill statement information for the specified eBill.
The simple and complex elements contained within the BilPayElecBilSchedInqRs response applicable for the
Bill Pay Services API are:
ElecBilId
This is the Bill Pay Services API identifier for the eBill.
ActIntentKey
This is the key (provided by the service provider) delivered to the consumer to be submitted in the
subsequent modification (update) operation for the data set returned in the Inquiry response.
BilPayElecBilSchedInqInfo
This complex element contains a package of data related to a specific eBill and includes the below simple
elements for the Bill Pay Services API.
ElecBilPayeeName
This is the name of the Payee for the specified eBill.
ElecBilPayeeAcctId
This is the identifier associated with the Subscriber’s registered eBill account with the
Merchant/Payee.
ElecBilStat
This is the status of the eBill. Valid canonical values are:
• ComingDue – eBill with a Due Date that has not yet passed (may be associated with a
currently scheduled payment)
• UnPd – Unpaid (eBill’s Due Date is in the past, but eBill is not associated with a processed
payment on the Subscriber’s bill pay account and has not been ‘filed’)
• Pd – Paid (eBill is associated with a processed payment on the Subscriber’s bill pay
account)
• SubProc – eBill has been ‘filed’ by the Subscriber
NOTE: Only the current (i.e., ‘Coming Due’) eBill can be paid by scheduling a payment for the
specified Payee. All historical ‘Unpaid’ eBills can only be ‘filed’, or remain in ‘Unpaid’ status.
Bill Pay Services API – User Guide
iPay Solutions™
224
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
ElecBilPmtMthd
This is the filing method specified for the eBill, if the eBill was filed by the Subscriber. Canonical
values are:
• SubPdDir – eBill was paid ‘directly’ by the Subscriber (by cash or check), outside of the
Subscriber’s bill pay account.
• SubPdElecDir – eBill was paid ‘directly’ by the Subscriber (‘electronically’: e.g., on biller’s
website, or via bank transfer, etc.), outside of the Subscriber’s bill pay
account.
• NotPd – eBill was not paid
ElecBilPmtAuto
This indicates whether the [eBill] payment was included in an automatic eBill payment schedule for
the Payee. Canonical values are:
• True
• False
PmtCmnt
This optional element represents a comment entered by the Subscriber that will be stored with a filed
eBill.
StmtDt
This is the statement date for the specified eBill.
PmtDueDt
This is the date the payment is/was due for the specified eBill.
StmtBal
This is the statement balance for the specified eBill. A ‘statement balance’ amount is available only
for credit card (‘CCA’) account types.
CurrBal
This is the total [outstanding] current balance of the Subscriber’s account with the Payee. This
amount may be different than the Statement Balance for the corresponding eBill. A ‘current balance’
amount is available only for credit card (‘CCA’) account types.
PmtAmtDue
This is the payment amount that is/was due for the specified eBill. This value is available only for
‘non-credit card’ accounts (account type not = ‘CCA’).
MinPmtAmt
This is the minimum amount due for the specified eBill. A minimum amount due is available only for
credit card (‘CCA’) account types.
WebPgURL (Ver 2)
This specifies the URL to be used to access/view the full electronic billing statement for the
selected eBill. This information is available ONLY for those eBillers that are enabled for full eBill
detail (where Payee’s <ElecBilPayeeType> = ‘Enroll’ and <ElecBilPayeeCatType> = ‘Det’).
NOTES:
1) For this version of the WebPgURL element, a JSON web token (‘JWT’) is returned as an
embedded part of the URL string in order to provide added security around the transmission of
the URL. The JWT is valid only for a specified period of time (currently 10 minutes), and will ‘time
out’ after this time span expires. The JWT timer begins at the instant the JWT is created
(essentially, when the BilPayElecBilSchedInq response is generated by the Service Provider).
Bill Pay Services API – User Guide
iPay Solutions™
225
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Therefore, it is possible that a request to view eBill detail via this URL will time out if too much
time passes between the initial BilPayElecBilSchedInq response from the Service Provider
(iPay Solutions) and the end-user’s use of the URL to view the full eBill statement.
It is suggested that, in order to maximize the available time period for the JWT, the initial
BilPayElecBilSchedInq request to obtain eBill detail information be sent only after the end-
user has explicitly requested to view the full eBill statement.
The receipt of the BilPayElecBilSchedInq response can then be used to determine
approximately when the JWT will expire, after which a new BilPayElecBilSchedInq request
would be required in order to trigger the creation of a new JWT and restart the ‘time-clock’.
2) Limitations on some web browsers may result in an inability to read the entire URL string (thereby
truncating the JWT/token value). To ensure the entire JWT is transmitted correctly in the URL
request, iPay recommends that the Service Consumer parse the token (JWT) within the query
string from the URL and place it in the URL’s HTTP request header in a name/value pair with the
header field name of ‘Token’.
WebPgURLNoToken (Ver 3)
This version of the WebPgURL element specifies the URL to be used to access/view the full
electronic billing statement for the selected eBill, and does NOT include an embedded JSON web
token. This version can be used as an alternate option to the <WebPgURL> element above, and
does not require the Service Consumer to parse the token (JWT) from the URL string (token is sent
separately, in the <WebPgToken> element, below).
WebPgToken (Ver 3)
This specifies the JSON web token (‘JWT’), which is used to provide added security around the
transmission of the WebPgURL. This token is valid only for a specified period of time, and will ‘time
out’ after this time span expires.
TokenExpTimeDt (Ver 3)
This specifies the expiration time (and date) for the WebPgToken.
NOTES:
1) The above (Ver 3) information is available ONLY for those eBillers that are enabled for full eBill
detail (where Payee’s <ElecBilPayeeType> = ‘Enroll’ and <ElecBilPayeeCatType> = ‘Det’).
2) The JWT timer begins at the instant the JWT is created (essentially, when the
BilPayElecBilSchedInq response is generated by the Service Provider).
Therefore, it is suggested that, in order to maximize the available time period for the JWT, the
initial BilPayElecBilSchedInq request to obtain eBill detail information be sent only after the end-
user has explicitly requested to view the full eBill statement.
If the JWT expires, a new BilPayElecBilSchedInq request is required in order to trigger the
creation of a new JWT and reset the TokenExpTimeDt.
Bill Pay Services API – User Guide
iPay Solutions™
226
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
eBill Mod
Container: TPG_BillPayMaster.xsd
Message: BilPayElecBilSchedMod
The bill pay eBill Modification <BilPayElecBilSchedMod> will allow the service consumer to update (modify)
certain elements for a Subscriber’s eBill. The <SubId>, <eBilId> and Activity Intent Key <ActIntenKey> are
required on the Mod request.
The ability to ‘file’ an eBill is currently the only update (modify) process available for an eBill within the Bill Pay
Services API.
The ability to delete an eBill is not available within the Bill Pay Service API operations.
The elements at the root request message will be echoed back at the root response, regardless if those same
elements exist in the repeating complex.
Message Flow
The eBill Modification service uses a typical exchange of MType messages to allow updates to eBill
information for a specific Subscriber, based on the required Subscriber ID and eBill ID. An eBill Inquiry must
always be performed prior to the modification request in order to retrieve the Activity Intent Key necessary for
modification operations, as well as to ensure that the most up-to-date eBill information is reflected on the eBill
Inquiry.
Bill Pay Services API – User Guide
iPay Solutions™
227
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Request
The third-party consumer forwards the BilPayElecBilSchedPmtModRq request message to the Service
Provider.
The below simple and complex elements contained within the BilPayElecBilSchedPmtModRq message
request are necessary for the Bill Pay Services API.
BilPayProd
This represents the type of iPay Solutions service operations being requested. Canonical values are:
• BilPay
• Remit (reserved for future use)
The BilPayProd default value is ‘BilPay’.
SubId
This is the Service Provider’s (iPay Solutions) identifier for the Subscriber.
ElecBilId
This is the Bill Pay Services API identifier for the eBill.
ActIntentKey
This is the service provider key delivered to the service consumer via a preceding inquiry request, to be
submitted in the modification request operation.
Dlt
This indicates a desire for deletion of the specified entity. For recurring payments, a value of ‘true’
indicates a desire to delete (i.e. ‘stop’) the entire recurring payment series immediately. Canonical values
are:
• True
• False (default)
This element is not currently eligible for use with an eBill Mod request.
BilPayElecBilSchedModInfo
This complex element contains a package of data related to the Subscriber’s specified eBill, and may
include all of the simple and complex elements returned in the preceding eBill Inquiry response.
However, the following are the only elements within this complex that are eligible for modification (add or
update) for an eBill Modification request:
ElecBilStat
This is the status of the eBill. Valid canonical values for eBill Mod are:
• SubProc – eBill has been ‘filed’ by the Subscriber
ElecBilPmtMthd
This is the filing method for the eBill, as selected by the Subscriber when filing the eBill. The filing
method is required when filing an eBill. Canonical values are:
• SubPdDir – eBill was paid ‘directly’ by the Subscriber (by cash or check), outside of the
Subscriber’s bill pay account.
• SubPdElecDir – eBill was paid ‘directly’ by the Subscriber (electronically: e.g., on biller’s
website, or via bank transfer, etc.), outside of the subscriber’s bill pay
account.
• NotPd – eBill was not paid
Bill Pay Services API – User Guide
iPay Solutions™
228
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
ElecBilSchedPmtCmnt
This optional element represents a comment entered by the Subscriber that will be stored with a filed
eBill.
eBill Mod Behaviors
• iPaySolutions will ignore all element values other than those specified above, if passed on an eBill
Mod request.
• Only an eBill that is currently in a ‘Due’ or ‘Unpaid’ status can be filed.
• For Company Subscribers:
o eBills can be modified (‘filed’) only if the requesting user (subscriber’s associated user) has
been granted permission to ‘Schedule Bill Payments’.
Response
The service provider (iPay) returns the BilPayElecBilSchedPmtModRs response message to the service
consumer.
The element(s) contained within the BilPayElecBilSchedPmtModRs response applicable for the Bill Pay
Services API is/are:
RsStat
This specifies the status of the mod request. Canonical values are:
• Success
• Fail
Bill Pay Services API – User Guide
iPay Solutions™
229
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Appendix A: Business Service Operation-to-Feature Mapping – Bill
Pay Services
Service Operation
(by Message Set)
Functionality Name
Feature Required
Additional Feature
Required
Payees
Add Payee
Add Payee
AddPayee
Add Email Payee
AddPayee
EmailPmt
Add Outbound Transfer
Payee
Outbound Transfers
Edit Payee
Edit Payee
MgmtPayee
Edit Email Payee
MgmtPayee
EmailPmt
Edit Outbound Transfer
Payee
Outbound Transfers
Edit Payee with Add eBill
Acct
MgmtPayee
eBills/Bill Presentment
Edit Payee with Edit eBill
Acct
MgmtPayee
eBills/Bill Presentment
Payee Search
Payee Search
ViewPayee
Payee Srch/Incl Outbound
Transfers
View Payees
Outbound Transfers
Payee Srch/Only Outbound
Transfers
Outbound Transfers
Payee Search with eBill
Info
ViewPayee
eBills/Bill Presentment
Payee Inquiry
Payee Inquiry
ViewPayee
Outbound Transfer Payee
Inquiry
Outbound Transfers
Payee Inquiry with eBill Info
ViewPayee
eBills/Bill Presentment
Pay by Card
PaybyCard
Payments
Scheduled Payment Add
Add Payment
SchedSinglePmt
Add Email Payment
SchedSinglePmt
EmailPmt
Add Rush Payment
SchedSinglePmt
RushPmt
Add Recurring Pmt Series
SchedSinglePmt
SchedRecurPmt
Add Outbound Transfer
Outbound Transfers
Add Recurring Outbound
Transfer Series
Outbound Transfers
Add Recurring Payment
Series
Schedule Payment Mod
Edit Payment
MgmtPendPmt
Edit Email Payment
MgmtPendPmt
EmailPmt
Edit Rush Payment
MgmtPendPmt
RushPmt
Edit Recurring Pmt Series
MgmtPendPmt
MgmtRecurPmt
Edit Outbound Transfer
Payment
Outbound Transfers
Bill Pay Services API – User Guide
iPay Solutions™
230
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Edit Recurring Outbound
Transfer Series
Outbound Transfers
Add Recurring Payment
Series
Scheduled Payment Inquiry
Scheduled Payment Inquiry
ViewPendPmt
(includes Recurring Pmts)
Scheduled Outbound
Transfer Inquiry`
Outbound Transfers
Scheduled Payment Search
Scheduled Payment
Search
ViewPendPmt
(includes Recurring Pmts)
Scheduled Payment
Srch/INCL Outbound
Transfers
ViewPendPmt
(includes Recurring Pmts)
Outbound Transfers
Scheduled Payment
Srch/ONLY Outbound
Transfers
Outbound Transfers
Scheduled Payment Approval
Scheduled Payment
Approval
Manage Pending Payments
Scheduled Recurring
Payment Approval
Manage Pending Payments
Manage Recurring Payment
Series
Scheduled Outbound
Transfer Approval
Outbound Transfers
Scheduled Recurring
Outbound Transfer
Approval
Outbound Transfers
Manage Recurring Payment
Series
Payment History Inquiry
Payment History Inquiry
ViewPmtHist
(includes Recurring Pmts)
Outbound Transfer History
Inquiry
Outbound Transfers
Payment History Search
Payment History Search
ViewPmtHist
(includes Recurring Pmts)
Pmt History Srch/INCL
Outbound Transfers
View Payment History
(includes Recurring Pmts)
Outbound Transfers
Pmt History Srch/ONLY
Outbound Transfers
Outbound Transfers
eBills
eBill Search
View eBills [eBill History]
eBills/Bill Presentment
eBill Inquiry
eBill Inquiry
eBills/Bill Presentment
eBIll Mod
File eBill
eBills/Bill Presentment
Subscribers
Subscriber Add
Add (Enroll) Subscriber
AddSub
Add (Enroll) Subscriber
with Add of Sub users
AddSub
Sub users
Subscriber Search
Subscriber Search
ViewSubInfo
Subscriber Inquiry
Subscriber Inquiry
ViewSubInfo
Subscriber Inquiry with
PayFromAccount Info
ViewSubInfo
ViewPayFromAcct
Subscriber Mod
Subscriber Mod
MgmtSubInfo
Bill Pay Services API – User Guide
iPay Solutions™
231
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Subscriber Mod with Edit
(existing) Pay From
Account
MgmtSubInfo
MgmtPayFromAcct
Subscriber Mod with Add
(additional) Pay From
Account(s)
MgmtSubInfo
MgmtPayFromAcct
Subscriber Mod with edit
Sub user
(profile/contact info)
MgmtSubInfo
Sub users
(requesting user must be
actual Sub user)
Subscriber Mod with
Add/Edit/Delete Sub user
MgmtSubInfo
Sub users
(requesting user must have
Manage Users permission)
Institutions
Channel Inquiry
Channel Inquiry
ViewInstInfo
Service Dictionary Search
Service Dictionary Search
Available for all Institutions /
No special permission
required
Bill Pay Services API – User Guide
iPay Solutions™
232
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Appendix B: Subscriber’s Associated User – Permission/Caps
specifications example
Subscriber’s Associated User Information Array
<SubAssocUsrName>
:
<PermissionsArray>
<Permission>
<PermissionCode>CanManagePayees
<PermissionValue>true
<Permission>
<PermissionCode>CanManageTransferAccounts
<PermissionValue>true
<Permission>
<PermissionCode>CanManagePayFromAccounts
<PermissionValue>true
<Permission>
<PermissionCode>CanScheduleBillPayments
<PermissionValue>true
<Permission>
<PermissionCode>ScheduleBillPaymentExcludedPayeeId
<PermissionValue>123
<Permission>
<PermissionCode>ScheduleBillPaymentExcludedPayeeId
<PermissionValue>456
<Permission>
<PermissionCode>CanScheduleP2PPayment
<PermissionValue>true
<Permission>
<PermissionCode>ScheduleP2PPaymentExcludedPayeeId
<PermissionValue>123
<Permission>
<PermissionCode>ScheduleP2PPaymentExcludedPayeeId
<PermissionValue>456
<Permission>
<PermissionCode>ScheduleP2PPaymentExcludedPayeeId
<PermissionValue>789
<Permission>
<PermissionCode>CanDesignatePayFromAccounts
<PermissionValue>true
<Permission>
<PermissionCode>ExcludedPayFromAccountIdThatTheSubUserCannotDesignate
<PermissionValue>111
<Permission>
<PermissionCode>ExcludedPayFromAccountIdThatTheSubUserCannotDesignate
<PermissionValue>222
<Permission>
<PermissionCode>CanEstablishPaymentCaps
<PremissionValue>true
<Permission>
<PermissionCode>CanViewPaymentHistory
<PermissionValue> false
Bill Pay Services API – User Guide
iPay Solutions™
233
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
<Permission>
<PermissionCode>CanTransfer
<PermissionValue>true
<Permission>
<PermissionCode>TransferExcludedPayeeId
<PermissionValue>562
<Permission>
<PermissionCode>CanViewTransferHistory
<PermissionValue> false
<Permission>
<PermissionCode>EstablishTransferCaps
<PermissionValue> true
<Permission>
<PermissionCode>CanUpdateCompanyInformation
<PermissionValue> false
<Permission>
<PermissionCode>CanManageSubUsers
<PermissionValue>true
<Permission>
<PermissionCode>CanApproveTransactions
<PermissionValue>false
<Permission>
<PermissionCode>CanAccessReports (Not applicable for ‘StandAlone’ Bill Pay Svcs)
<PermissionValue>true
<Permission>
<PermissionCode>CanScheduleReminders (Not applicable for ‘StandAlone’ Bill Pay
Svcs)
<PermissionValue>true
<Permission>
<PermissionCode>CanAccessMessageCenter (Not applicable for ‘StandAlone’ Bill Pay Svcs)
<PermissionValue>true
</PermissionsArray>
<CapsArray>
<Cap>
<CapFor>DefaultPaymentCap
<PayeeId><Null>
<CapAmount>$5,000
<Cap>
<CapFor>PayeeSpecificPaymentCap
<PayeeId>321
<CapAmount>$1,000
<Cap>
<CapFor>PayeeSpecificPaymentCap
<PayeeId>654
<CapAmount>$2,000
<Cap>
<CapFor>PayeeSpecificPaymentCap
<PayeeId>987
<CapAmount>$3,000
<Cap>
<CapFor>DefaultTransferCap
<PayeeId><Null>
<CapAmount>$4,000
Bill Pay Services API – User Guide
iPay Solutions™
234
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
<Cap>
<CapFor>PayeeSpecificTransferCap
<PayeeId>3375
<CapAmount>$1,500
</CapsArray>
Bill Pay Services API – User Guide
iPay Solutions™
235
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Appendix C: Payment Statuses and Definitions
The following table includes the bill payment status (‘PmtStat’) values used in iPay Solutions’ Bill Pay
Services, as well as the canonical value and a definition for each status.
Payment Status
Canonical Value
Definition
Scheduled
Sched
A payment or Transfer that has been submitted by the
subscriber, but has not yet been processed.
Pending
Pend
A payment or Transfer that has been submitted by the
subscriber, but will not process until requirements are met to
move the transaction into scheduled status.
Example: a P2P transaction that has been submitted by the
subscriber, but the P2P payee has not provided their bank
account information.
Pending Skip
PendSkip
An instance of a recurring payment or Transfer that is
selected by the subscriber and scheduled by the system to
be skipped when its processing date occurs.
This payment/Transfer will be reflected in Pending Payments
until it is skipped.
Processed
Proc
A payment or Transfer for which the funds have been
debited from the subscriber’s account.
Paid
Pd
A payment or Transfer that has been processed and sent to
the payee.
Stopped
Stop
1. A payment or Transfer that has been stopped by the
subscriber before the payment cutoff time on the scheduled
processing date.
2. A pending payment or Transfer that has been stopped by
the system when requirements to move the
payment/Transfer into scheduled status have not been met.
Cancelled
Canc
A payment or Transfer that has been processed by iPay
Solutions but was cancelled by the FI before the subscriber’s
funding account was debited.
Example: the FI cancels a payment because the subscriber
does not have sufficient funds for the payment.
Refunded
Rfd
A returned payment that has been refunded to the
subscriber.
Resubmitted
ReSbm
A returned payment that has been resubmitted to the payee.
Skipped
Skip
An instance of a recurring payment or Transfer that was
selected by the subscriber and skipped by the system on its
processing date.
This status will be reflected as Skipped in Transaction
History after the processing date for the instance has
passed.
Payment Approval
Required
PmtApprvReq
A payment or Transfer that has been scheduled but requires
a user’s approval before being submitted for processing.
This status only applies to payments/transfers made by
Business subscribers or sub users.
Payment Approved
PmtApprv
A payment or transfer that has received the required user
approval to be processed.
This status only applies to payments/transfers made by
Business subscribers or sub users.
Bill Pay Services API – User Guide
iPay Solutions™
236
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Appendix D: eBill Account Setup and Error Resolution Flows
eBill Account Setup Flow
Bill Pay Services API – User Guide
iPay Solutions™
237
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
eBill Account Info/Error Resolution Flow
Bill Pay Services API – User Guide
iPay Solutions™
238
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Appendix E: eBill Account Errors – Subscriber remediation required
The following table includes possible eBill account error codes and descriptions that require remediation by
the Subscriber in order to complete eBill setup or continue receiving eBills.
Error Code
Error Description – for eBill Setup/Registration or Account Error Resolution
E6513
Login Failure. Request must be resubmitted with valid login credentials for payee website.
E6515
Payee requires Subscriber action directly via Payee website. Request may be retried after
corrective action taken.
E6516
User account no longer found on payee website. eBill account has been deleted. eBill Account
setup process must be repeated to reactivate account.
E6517
User account locked on payee website. Corrective action required on payee website. Request
may be retried after account unlocked.
E6518
MFA Failure – Additional eBill account authentication information required. Request must be
resubmitted with valid security authentication response.
E6519
MFA Failure – Invalid response to requested eBill account authentication information. Request
must be resubmitted with valid security authentication response.
E6521
Ambiguous results encountered on attempt to match Subscriber’s account number on Payee
website. Request must be resubmitted with confirmed account match.
E6551
Login Failure. Valid login credentials for payee website must be submitted via Payee Mod
request.
E6550
MFA Failure – Additional eBill account authentication information required. Payee Mod request
must be submitted with valid security authentication response.
E6570
OTA Failure – Additional eBill account authentication information required. Request must be
resubmitted with valid security authentication response.
E6571
eBill Account is currently in 'Pending' status and updates can not be applied. Refer to Payee
Inquiry response for additional information.
E6572
eBill Account is currently in 'Issue' status. eBill Account Error(s) must be resolved before updates
can be applied. Refer to Payee Inquiry response for additional information about 'Issue' detail(s).
Bill Pay Services API – User Guide
iPay Solutions™
239
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Glossary
Term
Definition
ABA Number
An identification number consisting of a two-part code assigned to banks and savings
associations. The first part shows the location and the second identifies the bank.
Account ID
Unique identifier for Payee attached to subscriber. Equivalent to Payee ID in web
interface.
Account [Payee]
The account created for the Subscriber which represents the Merchant they’re trying to
pay. A Merchant can have one or more subscriber [Payee] Accounts attached to it, each
of which has its own Merchant Account Number.
See also ‘Payee’
Activation [Payee]
The process where a Subscriber enters an activation code (provided by iPay Solutions)
in order to complete Payee setup. This process is required for Payees added via Online
Bill Pay as an added security measure to ensure Payee setup is completed by
authorized account users.
Authentication
The process of identifying an individual, usually based on a user name and password. In
security systems, authentication is distinct from authorization, which is the process of
giving individuals access to system objects based on their identity. Authentication
ensures that the individual is who he or she claims to be, but says nothing about the
access rights of the individual.
Authorization
The process of granting or denying access to a network resource. Most computer
security systems are based on a two-step process. The first stage is authentication,
which ensures that a user is who he or she claims to be. The second stage is
authorization, which allows the user access to various resources based on the user's
identity.
Bill Pay Services
API
iPay Solutions’ web service-based bill payment solution (product).
Bus
A subsystem that transfers data between components (i.e., a data highway).
Business Service
Provider
A Business Services Provider (BSP) is an application service provider that focuses on
providing and hosting applications related exclusively to business functions.
Consumer
A network application that uses Internet protocols to access information and functionality
provided by a Service Provider.
Aka ‘Requestor’ or ‘Client’. The channel partner, institution, Remittance partner or
application making the request for bill payment services from the Bill Pay Services API.
[Service] Contract
A ‘communication agreement’ to which service(s) must adhere.
Due Date
The date the payment is expected to be delivered, or the date the Subscriber would like
the Payee to receive the payment. (Estimated Arrival Date)
eBill
Digital (i.e., ‘electronic’) version of a bill being sent by an ‘eBiller’ to a Subscriber.
eBiller
The Subscriber-facing [Payee] product or line of business that Subscribers connect with
to receive digital billing information (e.g. AT&T or American Express). Also referred to as
“Biller” or “Payee”.
Electronic Risk
Limits
Daily and monthly dollar limits (by Subscriber) on ‘electronic’ payments. Used by
Institutions using the ‘Subscriber Draft’ (i.e., ‘Risk’) funding model who want to mitigate
Bill Pay Services API – User Guide
iPay Solutions™
240
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Term
Definition
their financial exposure on electronic payments that settle on the same day as
processed.
Enterprise Service
Bus
A modular and component-based software architecture model used for designing and
implementing the interaction and communication between mutually-interacting software
applications in Service Oriented Architecture (SOA). Promotes ‘message-oriented’
design.
Feature
A defined ‘function’ that is available for a specific ‘Service’ (i.e., ‘sub-product’ of a
Product). Examples are: Enroll Subscriber, Add Pay Anyone Payee, Submit Email
Payment, Submit Transfer, etc.
Funding Account
The Subscriber’s checking or savings account(s) used to fund payments.
FI
Financial Institution
IB
Internet Banking
Identification
The process of determining the ‘unique identity’ of a particular person or entity (e.g.,
Institution, etc.) From an iPay Solutions perspective, this involves identifying the unique
Institution or subscriber record in the Bill Pay system that is associated with the specified
entity.
iSB
[iPay Service Bus]
A framework that exposes a comprehensive ‘suite’ of iPay Solutions’ core Bill Pay (and
other) services) through web services to JHA’s jXchange and other external or internal
systems.
Institution Routing
ID
The identification of the entity of the submitted message. A financial institution entity will
utilize the routing transit or ABA nine (9) digit number assigned to FIs for the purpose of
routing as assigned by the American Bankers Association. Any leading zeros must be
provided for a complete routing and transit number. A non-financial institution entity will
use a mutually agreed upon identification that must contain at least one non-integer
character. When a record is directed to a specific FI within a holding company, the
institution routing identification is the specific FI routing identification and not the holding
company identification.
Module
See Feature.
Non-Activated
Payee
A Payee who has not yet been ‘activated’ (see Payee Activation above).
Payee
The entity (business, person, or account) to which the subscriber is trying to pay for
goods or services provided.
P2P Payee
A person-to-person (‘P2P’) Payee. At iPay Solutions, this is an ‘Individual’ payee who,
as part of their initial setup process, receives an email or text with a link that allows them
to securely and confidentially provide their financial deposit information for payment.
Pay From Account
See Funding Account.
Payment Cutoff
A configuration set at the Institution level which depicts the latest available time for which
a subscriber can schedule a payment for processing that same day.
Primary Account
Holder
The ‘primary individual’ associated with the Company Subscriber account. This is
typically the ‘owner’ or ‘primary user’ for the company.
Bill Pay Services API – User Guide
iPay Solutions™
241
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Term
Definition
Process Date
The day the funds will be removed and sent to the payee for electronic payments and
checks are printed for draft checks (funds are removed when payee cashes the check).
Product
Any of iPay Solutions’ online or service-based bill payment solutions, such as Bill Pay
Services, Consumer (includes Classic, Plus, etc.), Business, PayCenter, etc.
[iPay] Service
Any of a defined set of features that is available for a specific FI or for an iPay Solutions
Product (such as the ‘Bill Pay Services API’, Mobile API,etc.)
Services can be configured at the FI-level (e.g., Extendend Storage, Bill Pay Services
API), or at the Product level (e.g., Bill Pay Services API, Transfer services, Mobile API,
Email Payments, etc.)
[Web] Service
A mechanism to enable access to one or more well-defined business functionalities,
where the access is provided using a prescribed interface and is exercised consistent
with constraints and policies as specified by the service description.
Loosely coupled, re-usable software components that are expected to be independently
deployed, running heterogeneously and disparately within a network.
Service Consumer
The channel partner, institution, remittance partner or application making the request for
bill payment services from the Bill Pay Services API.
Service Provider
The ‘creator/publisher’ of the Bill Pay Services API web services. (e.g., iPay Solutions).
Service Oriented
Architecture (SOA)
An architectural style for building systems based on interacting coarse grained
autonomous components called services. Each service expose processes and behavior
through contracts, which are composed of messages at discoverable address called
endpoints. Services’ behavior is governed by policies which are set externally to the
service itself.
Email ‘Shared
Secret’ Keyword
Utilized when setting up a person-to-person (‘P2P’) Payee. A keyword is simply a single
word, specified by Subscriber, known only to the subscriber and the designated P2P
payee, and is required in order to authenticate the P2P recipient prior to requesting
deposit account information.
Prior to setting up a new P2P payee, subscriber must share the Keyword with the P2P
Payee (i.e., recipient). This exchange of information occurs outside of the Bill Pay
application.
‘StandAlone’ Bill
Pay Services
Bill Pay Services API services that are not utilized in conjunction with a corresponding
iPay Solutions-hosted online Bill Pay website. Bill Pay Services API services are
considered ‘StandAlone’ if the FI is utilizing iPay Solutions’ Bill Pay processes only via
the API services, and has not also purchased Bill Pay access via any of iPay Solutions’
Online Bill Pay applications.
Subscriber
The owner of the bill pay account. In the case of a Company Subscriber, the notion of
‘Subscriber’ is intended to represent the ‘Company’ bill pay account.
Subscriber
Deactivation
The process of inactivating an [approved], active Subscriber Bill Pay account so that it is
unavailable for bill payment activities. The account remains in an ‘approved’ status, but
has been inactivated so that future bill payment activities cannot be completed.
A deactivated account may be eligible for reactivation. However, a subscriber account
that has been deactivated and is not eligible for reactivation has the effect of permanent
prohibition from bill payment activities (i.e., as if the account has been closed or deleted).
Bill Pay Services API – User Guide
iPay Solutions™
242
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Term
Definition
Subscriber
Identifier
Any of the accepted identifiers that will be used to uniquely identify the Individual
subscriber for each Service request. (e.g., login ID, token/GUID, Partner ID, etc.)
[Company]
Subscriber’s
Associated User
AKA sub user. Any authorized user of a bill pay account that allows multiple users,
including the Primary Account Holder. The sub user can be authorized by the Primary
Account Holder or by another sub user authorized to add sub users to the bill pay
account.
Subscriber’s
Associated User
Identifier
Any of the accepted identifiers that will be used to uniquely identify the subscriber’s
associated user for each Service request. (e.g., login ID, token/GUID, Partner ID, etc.)
Subscriber
Reactivation
The process of reactivating an [approved], inactive Subscriber Bill Pay account so that it
once again becomes available for bill payment activities. The reactivation process allows
a Subscriber to ‘restart’ their account without having to re-enroll. Therefore, a re-
activated account contains all original identifier values, such as original LoginID,
SubscriberID, etc.
Not all deactivated accounts are eligible for reactivation.
Transfer
A direct deposit payment from (or to) a subscriber’s bill payment account to (or from) a
checking or savings account owned by the subscriber at another FI.
Transfer, Inbound
Monies originating from an external account (not a bill pay account) that is being
transferred into the Subscriber’s bill pay account (i.e., transfer is from remote account to
[bill pay] FI account).
Transfer, IntraBank
Monies originating from an account at the same institution as the bill pay account that is
being transferred to a different account within the institution. A transfer is considered an
intra-bank transfer only when the routing numbers are the same.
Transfer, Outbound
Monies originating from the subscriber’s Bill Pay account that is being transferred to an
external account that is not the bill pay account (i.e., transfer is to a remote account from
a [bill pay] FI account). This is the most common type of Transfer.
User
Individual subscriber or sub user on behalf of which bill payment services are being
requested.
Bibliography
There are no sources in the current document.
Bill Pay Services API – User Guide
iPay Solutions™
243
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Index
ActIntent, 77, 78, 122, 123, 171, 172, 221, 222
ActIntentKey, 22, 79, 91, 124, 139, 140, 173, 184, 185, 223, 227
AddlName, 5, 29, 61, 75, 85, 97
AddlNameStat, 61, 85
Addr, 57, 73, 74, 81, 93, 103
AlwAddPayFromAcct, 46
AlwCardFundedType, 124
AlwSecdPerson, 46
AlwSubAssocUsrMgmtOpt, 50
AlwSubAssocUsrMgmtOptInfoArray, 49
AlwSubType, 29, 47
AuthenAnswDesc, 136, 147, 148, 152
AuthenQuesArray, 136, 147, 150, 151
AuthenQuesDesc, 136, 148, 151, 152
Authentication, 16
AuthenUsrCred, 17
Authorization, 16
Automatic eBill Payment Schedule Options, 133, 145
BakChkImg, 213
BakChkImgLength, 213
BilPayeeElecPmtInfo, 180
BilPayElecBilSchedInqInfo, 223
BilPayElecBilSchedModInfo, 227
BilPayElecBilSchedSrchArray, 219
BilPayFeturInfoArray, 48
BilPayPayeeInfo, 29, 31, 107, 125, 141
BilPayPayeeSrchArray, 115
BilPayPmtHistSrchArray, 199
BilPayPmtInfo, 28, 205
BilPayProd, 43, 52, 54, 70, 78, 91, 107, 113, 123, 140, 154, 165, 172, 185, 195, 197, 204, 218,
222, 227
BilPayProdType, 43, 45
BilPayProdTypeInfoArray, 5, 6, 7, 45
BilPaySchedPmtInfo, 154, 173, 185
BilPaySchedPmtSrchArray, 167
BilPaySubInfo, 4, 5, 26, 54, 55, 79, 91
BilPaySubSrchArray, 72
BilPaySvcFeeArray, 131
BilPaySvcFeeInfoRec, 131, 175, 212
BirthDt, 9, 32, 56, 73, 80, 92
Business Service Operations, 24
Business Service Operations – General Behaviors, 37
Business Service Operations – Updates, 26
CanAddPayFromOwnInfo, 47
CanocValDetail, 41
CanocValInfo, 41
CanocValInfoArray, 41
Bill Pay Services API – User Guide
iPay Solutions™
244
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
CanocValText, 41
Canonicals, 18
CanPayFromSavAcct, 46
CanRush, 116
CanSetStartChkNum, 46
CapAmt, 65, 89, 102
CapAssocPayeeId, 65, 89, 102
CapCode, 40, 42, 64, 89, 101
CardFundedPayeeInfo, 138
CardPayFilter, 113, 115, 198
Channel Inquiry, 24, 43
ChkFundModel, 44
ChkImgFormat, 213
ChkImgStorMos, 44
City, 57, 60, 69, 73, 74, 81, 84, 93, 97, 109, 120, 129, 130, 143, 156, 170, 175, 178, 187, 202, 207,
209
ClosedEnums, 18
ComNam, 53, 81
ComName, 57, 60, 71, 73, 74, 80, 83, 93, 96, 120, 129, 169, 177, 201, 209
ConEndTime, 58, 63, 75, 81, 82, 87, 94, 100
ConsmOwnSubUsrPer, 47
ConStartTime, 58, 63, 75, 81, 82, 87, 94, 100
ConsumerName, 17
ConsumerProd, 17
CurBal, 181, 214
CurrBal, 220, 224
Cursor, 10, 21
Deprecation Policy, 23
Dlt, 79, 91, 117, 123, 124, 139, 140, 172, 184, 185, 192, 222, 227
DltRecur, 185, 192
DlyElecRiskLmt, 46
DualSignOnReq, 46
eBill Inquiry, 25, 221
eBill Mod, 226
eBill Mod Behaviors, 228
eBill Modification, 25
eBill Search, 25, 217
ElecBilAcctErrExist, 118, 127
ElecBilId, 219, 221, 222, 223, 227
ElecBilPayeeAcctId, 132, 144, 149, 150, 152, 218, 219, 223
ElecBilPayeeCatType, 117, 126
ElecBilPayeeName, 132, 219, 223
ElecBilPayeeType, 117, 125, 132, 133, 144
ElecBilPmtAmt, 117, 126, 134, 146, 150
ElecBilPmtAmtType, 117, 126, 133, 134, 145, 146, 150
ElecBilPmtAuto, 181, 214, 224
ElecBilPmtInstrType, 134, 146, 150
ElecBilPmtMthd, 224, 227
ElecBilPmtRuleAlgSymb, 133, 134, 145, 146, 150
ElecBilStat, 217, 218, 219, 223, 227
Bill Pay Services API – User Guide
iPay Solutions™
245
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
ElecMerAcctAliasName, 152
ElecMerAcctErrCode, 136, 140, 149, 150, 152
ElecMerAcctErrDesc, 136
ElecMerAcctErrInfoArray, 126, 136, 140
ElecMerAcctId, 152
ElecMerAcctIdArray, 151, 152
ElecMerAcctStat, 133
ElecMerAcctType, 5, 29, 30, 40, 42, 135, 147, 149
ElecMerAcctTypeDesc, 135
ElecMerAcctTypeInfoArray, 134, 147, 149
ElecMerAutoPmtAlw, 47, 133, 134, 146
ElecMerAutoSuspType, 145, 150
ElecMerBilPmt, 168, 200
ElecMerCredRegEx, 135, 147
ElecMerCredType, 135, 147
ElecMerCredTypeDesc, 135
ElecMerCredValue, 147
ElecMerPayeeCredInfoArray, 135, 147, 149, 150
ElecMerPayeeId, 132, 144, 149
ElecMerPayeeInfoRec, 131, 132, 139, 144
ElecMerPayeeOnly, 113, 114
ElecMerPayeeToS, 132
ElecMerPayeeToSStat, 132, 145, 149, 150
ElecMerPayeeURL, 132
ElecMerPendTerDt, 133
ElecMerSuspExpDt, 133
ElemCanocArray, 41
ElemCanocType, 41
ElemCanocVal, 41
ElemCanocValDesc, 41
ElemName, 38, 39, 41
EmailAddr, 58, 64, 69, 71, 76, 82, 88, 95, 101, 110, 131, 144, 176, 207
EmailArray, 58, 76, 82, 95
EmailType, 58, 64, 76, 82, 88, 95, 101, 110, 131, 144, 176, 207
EndDt, 217, 218
EnrollDt, 72, 79
EstArvDay, 118, 124
ExclNonAct, 113, 114
Fault Behaviors, 15
FeturAct, 49
FeturType, 48
FIAcctId, 108, 127, 142
FIAcctType, 108, 127, 142
FinInstName, 44
FirstAvlEstArvDt, 118, 124
FirstAvlProcDt, 118, 124
FirstName, 53, 57, 60, 61, 62, 71, 73, 74, 75, 80, 83, 85, 86, 93, 96, 97, 99, 120, 129, 169, 178,
201, 209
FIRtId, 108, 127, 142
FrontChkImg, 213
Bill Pay Services API – User Guide
iPay Solutions™
246
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
FrontChkImgLength, 213
Funding Accounts, 102
FundVerif, 45
FutPmtActualProcDt, 182
FutPmtAmt, 182
FutPmtChkMemo, 182
FutPmtCmnt, 182
FutPmtId, 182, 185, 186, 187, 192
FutPmtLastMainDt, 182
FutPmtModUsrID, 182
FutPmtOrigProcDt, 182
FutPmtPayFromAcctInfo, 183
FutPmtStat, 182
Handling Time Zones, 22
HidSubAssocUsrConsmCustId, 47
HidSubAssocUsrSubComId, 47
Identification, 17
IncChkImg, 204
InclDlt, 113, 114
IncXtendElemArray, 38, 40, 123, 131, 137, 172, 182, 204
Institution Draft Model, 44
InstRtId, 17
InvoiceAmtNeg, 160, 181, 190, 212
InvoiceAmtPos, 159, 181, 190, 212
InvoiceCat, 159, 181, 190, 212
InvoiceDesc, 159, 181, 190, 212
InvoiceId, 190
InvoiceID, 159, 181, 212
InvoiceInfoArray, 28, 159, 181, 190, 212
InvoiceNum, 159, 181, 190, 212
JHANull’ Attribute, 19
jXchangeHdr, 17
LastMainDt, 119
LastMainEndDt, 113, 114
LastMainStartDt, 113, 114
LastName, 53, 57, 60, 61, 63, 72, 73, 74, 75, 81, 84, 85, 86, 93, 96, 97, 99, 120, 129, 170, 178,
202, 209
MaxEmailDlyAmt, 45
MaxEmailPmtAmt, 45
MaxIndvDlyAmt, 46
MaxIndvPmtAmt, 45
MaxLenCharVal, 48
MaxPmtAmt, 45
MaxRec, 10, 21
MiddleName, 53, 57, 60, 61, 62, 71, 73, 74, 75, 81, 84, 85, 86, 93, 96, 97, 99, 120, 129, 169, 178,
202, 209
MinAlphaCharVal, 48
MinLenCharVal, 48
MinLowCaseVal, 48
MinNumCharVal, 48
Bill Pay Services API – User Guide
iPay Solutions™
247
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
MinPmtAmt, 181, 214, 220, 224
MinSpecCharVal, 48
MinUpCaseVal, 48
MktgOptInfoArray, 61, 64, 65, 85, 98, 101, 103
MktgOptType, 61, 64, 85, 88, 98, 101
MktgOptVal, 61, 64, 85, 88, 98, 101
MobBB, 58, 63, 76, 82, 87, 94, 100
MobDevResoType, 222
MobDevType, 222
MobPhoneInfo, 58, 63, 75, 82, 87, 94, 100
MobPrvdCode, 40, 42, 58, 63, 76, 82, 87, 94, 100
MobSendTestText, 58, 63, 76, 82, 87, 94, 100
Modification Behaviors, 22
MoreRec, 21
MthlyElecRiskLmt, 46
Nillable’ Attribute, 20
NonProcDt, 45
NonProcDtInfoArray, 45
Nulls, 19
OpenEnums, 19
Orientation, 223
P2PFilter, 164, 166, 196, 198
P2PType, 168, 200
Parallel Error Message Handling, 16
PayDtInstr, 158, 162, 179, 189, 211
Payee Add, 25, 106
Payee Add Behaviors, 111
Payee Inquiry, 25, 122
Payee Mod Behaviors, 148
Payee Modification, 25
Payee Modify, 139
Payee Search, 25, 113
PayeeAddr, 109, 130, 143, 156, 175, 187, 192, 207
PayeeAddrId, 130, 155, 175, 187, 192, 206
PayeeAddrInfo, 155, 175, 187, 206
PayeeAddrInfoArray, 109, 129, 143
PayeeAddrType, 109, 130, 143, 155, 175, 187, 207
PayeeCatName, 108, 113, 114, 116, 125, 141, 175
PayeeClsf, 28, 107, 111, 116, 125, 174, 206
PayeeEmailArray, 110, 131, 144, 176, 207
PayeeEmailSharedSecret, 26, 108, 112, 125
PayeeFIAcctInfo, 108, 127, 142
PayeeId, 64, 65, 66, 88, 89, 101, 102, 104, 112, 114, 115, 123, 139, 140, 155, 160, 164, 166, 167,
174, 186, 196, 198, 199, 205, 233
PayeeLastPdAmt, 116, 124
PayeeLastPdDt, 116, 124
PayeeName, 107, 115, 125, 141, 167, 174, 199, 205, 217, 218
PayeeNickname, 107, 116, 125, 141, 167, 174, 199, 205
PayeeP2PType, 108, 111, 112, 127, 142
PayeePhoneArray, 110, 130, 143, 176, 207
Bill Pay Services API – User Guide
iPay Solutions™
248
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PayeePmtMthd, 4, 26, 28, 32, 36, 116, 123, 164, 166, 174, 196, 198, 206
PayeeStat, 117, 124
PayFromAcctDft, 59, 83, 96, 119, 128, 169, 177, 183, 201, 208
PayFromAcctId, 4, 59, 69, 70, 72, 83, 95, 119, 128, 169, 177, 183, 201, 208
PayFromAcctInfo, 59, 82, 95, 119, 120, 128, 142, 168, 200
PayFromAcctInfoArray, 59, 82, 95
PayFromAcctName, 59, 83, 96, 119, 128, 169, 177, 183, 201, 208
PayFromAcctOwnAddr, 60, 74, 84, 96, 120, 129, 170, 178, 202, 209
PayFromAcctOwnName, 60, 74, 83, 96, 120, 129, 169, 177, 201, 209
PayFromAcctStat, 60, 83, 119, 128, 169, 177, 183, 201, 209
PayFromAcctType, 59, 73, 83, 95, 119, 128, 169, 177, 183, 201, 208
PayFromId, 59, 66, 83, 95, 104, 109, 119, 128, 142, 156, 168, 177, 183, 187, 201, 208
PayFromIntsRtId, 59, 73, 83, 96, 119, 128, 169, 177, 183, 201, 209
Payment Add, 25, 153
Payment Add Behaviors, 160
Payment Caps, 104
Payment History Inquiry, 25, 203
Payment History Search, 25, 196
PerCode, 40, 41, 42, 64, 88, 101
Permissions, 104
PersonName, 5, 29, 52, 57, 60, 61, 62, 69, 70, 71, 73, 74, 80, 81, 83, 85, 86, 92, 93, 96, 99, 103,
120, 129, 169, 177, 201, 209
PerValue, 64, 88, 101
Phone Type, 42
PhoneArray, 57, 75, 81, 93
PhoneExt, 58, 63, 75, 82, 87, 100
PhoneNum, 57, 58, 63, 69, 70, 75, 81, 87, 94, 100, 110, 130, 143, 176, 207
PhoneTime, 58, 63, 75, 81, 87, 100
PhoneType, 5, 29, 30, 40, 58, 63, 75, 81, 87, 94, 100, 110, 130, 143, 176, 207
PmtAmt, 134, 146, 154, 167, 173, 186, 199, 205
PmtAmtDue, 181, 214, 219, 224
PmtApprvReq, 5, 28, 29, 56, 80, 92, 160, 165, 167, 173, 235
PmtChkImgInfo, 213
PmtChkMemo, 155, 173, 186, 205
PmtChkNum, 212
PmtChkStat, 213, 215
PmtChkStatChngDt, 215
PmtChkTrakArray, 216
PmtChkTrakCarr, 215
PmtChkTrakCmnt, 216
PmtChkTrakDt, 216
PmtChkTrakId, 215
PmtChkTrakLoc, 216
PmtChkTrakRecInfo, 216
PmtChkTrakStat, 216
PmtChngBy, 215
PmtCmnt, 154, 173, 186, 205, 224, 228
PmtCrtDt, 173, 204
PmtCutoffTime, 44
PmtDayInfoArray, 158, 179, 189, 211
Bill Pay Services API – User Guide
iPay Solutions™
249
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
PmtDayofMonth, 158, 179, 189, 211
PmtDayOfWeek, 158, 179, 189, 210
PmtDtModel, 45
PmtDueDt, 180, 214, 219, 224
PmtEndDt, 164, 165, 196, 197
PmtEstArvDt, 154, 162, 167, 173, 186, 199, 205
PmtExcDesc, 215
PmtFinalAmt, 159, 180
PmtFreqUnits, 157, 168, 178, 188, 200, 210
PmtHighAmt, 165, 197
PmtId, 167, 171, 172, 184, 185, 194, 195, 203, 204
PmtID, 162, 163, 194, 199
PmtIntentType, 107, 116, 125, 141, 155, 166, 168, 174, 186, 198, 200, 205, 206
PmtLowAmt, 164, 165, 196, 197
PmtMthd, 28, 168, 173, 200, 205
PmtOccur, 158, 179, 189, 211
PmtPayeeInfo, 155, 174, 186, 205
PmtPayFromAcctInfo, 156, 177, 187, 208
PmtProcDt, 154, 162, 167, 173, 186, 199, 205
PmtRushOptInfo, 156, 176, 188, 208
PmtSerExpDt, 158, 179, 189, 211
PmtSerFinite, 158, 180, 189, 211
PmtStartDt, 6, 30, 32, 164, 165, 196, 197
PmtStat, 28, 164, 165, 167, 173, 196, 197, 199, 204, 214, 235
PmtStatChngDt, 215
PmtUseLastBusDay, 158, 179, 189, 211
PostalCode, 57, 60, 69, 71, 74, 81, 84, 93, 97, 109, 120, 129, 130, 143, 156, 170, 175, 178, 187,
202, 207, 209
PswdChgFreq, 56, 80, 81, 92, 93, 103
RecurFilter, 164, 166, 196, 198
RecurPmtInfo, 29, 157, 178, 188, 210
RetroToOrigPmtDt, 28, 159, 180, 190, 211
RsStat, 67, 105, 112, 151, 163, 193, 195, 228
Rstr’ Attribute, 20
RushOpt, 121, 137, 156, 162, 176, 188, 208
RushOptArray, 120, 137
RushOptFeeAmt, 121, 137, 176, 208
RushOptSurChg, 121, 137, 176, 208
Scheduled Payment Approval, 25, 194
Scheduled Payment Inquiry, 25, 171
Scheduled Payment Mod, 184
Scheduled Payment Mod Behaviors, 191
Scheduled Payment Modification, 25
Scheduled Payment Search, 25, 164
Search/Inquiry Behaviors, 20
Searches: Record Request/Response Behaviors:, 21
SecdPersonArray, 5, 29, 61, 75, 85, 97
SentRec, 21
Serial Error Message Handling, 16
Service Dictionary Search, 24, 38
Bill Pay Services API – User Guide
iPay Solutions™
250
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
SkipPmtOccur, 185, 192
SpecCharRstrArray, 48
SpecCharRstrType, 48
SrchAddr, 69, 70
SrchCity, 69, 70
StartChkNum, 59, 83, 96, 119, 128, 169, 177, 183, 201, 208
StartDt, 217, 218
StartPmtEstArvDt, 157, 178, 188, 210
StartPmtProcDt, 157, 178, 188, 210
StateCode, 57, 60, 73, 74, 81, 84, 93, 97, 109, 120, 129, 130, 143, 156, 170, 175, 178, 187, 202,
207, 209
StmtBal, 117, 126, 133, 134, 145, 146, 180, 214, 219, 224
StmtDt, 180, 214, 219, 224
StorMos, 44
StreetAddr1, 57, 60, 73, 74, 81, 84, 93, 96, 109, 120, 129, 130, 143, 156, 170, 175, 178, 187, 202,
207, 209
StreetAddr2, 57, 60, 73, 74, 81, 84, 93, 97, 109, 120, 129, 130, 143, 156, 170, 175, 178, 187, 202,
207, 209
SubAssocUsrCapInfoArray, 64, 89, 101
SubAssocUsrCmnt, 62, 86, 99
SubAssocUsrComId, 54, 62, 65, 86, 99
SubAssocUsrConsmCustId, 54, 62, 65, 86, 98
SubAssocUsrEmailArray, 64, 88, 100
SubAssocUsrId, 5, 17, 52, 62, 68, 72, 78, 85, 86, 90, 98, 195
SubAssocUsrIdInfoArray, 67
SubAssocUsrInfoArray, 54, 55, 59, 61, 62, 79, 82, 85, 89, 91, 95, 98
SubAssocUsrMktgOptInfoArray, 88
SubAssocUsrName, 62, 86, 99, 232
SubAssocUsrPerInfoArray, 64, 88, 101
SubAssocUsrPhoneArray, 63, 87, 99
SubAssocUsrRole, 62, 86, 98
SubAssocUsrTempPswd, 62, 86, 99
SubCmntToPayee, 155, 173, 182, 186, 205
SubComId, 26, 52, 54, 55, 65, 79, 91
SubConsmCustId, 26, 52, 54, 55, 65, 79, 91
SubId, 51, 52, 55, 67, 69, 70, 72, 77, 78, 90, 91, 106, 107, 114, 122, 123, 139, 140, 153, 154, 165,
171, 172, 184, 185, 194, 195, 197, 203, 204, 218, 221, 222, 226, 227
SubInActRsnType, 56, 80, 92
SubLogInIdRstr, 48
SubMerAcctId, 4, 5, 29, 31, 108, 116, 124, 125, 141, 152, 175, 206
SubMerPayerName, 108, 125, 141, 175, 206
SubModMerAcctId, 124
Subscriber Add, 24, 54
Subscriber Add Behaviors, 65
Subscriber Inquiry, 24, 77
Subscriber Lookup, 4, 17, 24, 26, 51, 55, 77, 78
Subscriber Mod Behaviors, 102
Subscriber Modification, 24
Subscriber Modify, 90
Subscriber Search, 24, 69
Bill Pay Services API – User Guide
iPay Solutions™
251
1999-2017 Jack Henry & Associates, Inc.®
Release 2017.4.01
Subscriber's Associated User, 103
SubStat, 52, 56, 61, 69, 70, 72, 79, 80, 92
SubType, 49, 55, 69, 70, 72, 79
SubTypeAccessFeturInfoArray, 49
SvcDictFilterArray, 38, 40
SvcDictInfoArray, 41
SvcDictName, 38, 39
SvcDictType, 38, 39
SvcFeeAmt, 131, 176, 212
SvcFeeDesc, 5, 29, 30, 40, 42, 131, 176, 212
TaxId, 55, 69, 71, 73, 80, 81, 92, 93, 103
TaxIdReq, 46
TempPswd, 29, 30, 31, 33, 55, 80
TokenExpTimeDt, 225
TotRec, 21
WebPgToken, 225
WebPgURL, 138, 224
WebPgURLNoToken, 225
x_CardFundedPayeeArray, 123, 137
x_ElecBilPmtInfo, 203, 204, 214
x_ElecMerPayeeInfo, 123, 131
x_FutPmtInfoArray, 172, 182
x_PmtChkStatHistArray, 203, 204, 215
x_PmtChkTrakInfo, 203, 204, 215
x_PmtStatHistArray, 203, 204, 214
x_SvcPrvdErrArray, 41
XferFilter, 166, 198
XtendElem, 123, 172
