Skip to main content

Deposit History Guide

Introduction

In this guide, we'll walk you through how to retrieve check deposit history, including check images.

note

History can be called any time after StartSession. It is important to note that for credit unions leveraging the Shared Branching network, each StartSession from Ensenta requires a call out to the Shared Branching network for a member inquiry. The credit union is charged a fee for every single member inquiry. For these credit unions, the mobile application should only call history when the End-User intentionally selects the deposit history menu (if offered). Some mobile applications display Ensenta’s deposit history when the End-User immediately accesses the deposit menu, which is acceptable for banks and credit unions not on the Shared Branching network.

Getting Started

Tasks covered in this guide

  • Retrieving deposit history
  • Retrieving check images

Required prerequisites before you continue

  • You are required to obtain your UAT PartnerId in order to work with any of the examples in this guide. If you don't already have a UAT PartnerId, then you can send an email to EPS.TechIntegrations@jackhenry.com to request one.
  • Review the authentication guide to understand how to authenticate to the EPS Ensenta Mobile API Partner Deposit web service using the EPS Ensenta Mobile API Partner SSO web service. This guide walks you through getting your UAT PartnerID, setting up your mobile API certificate, and how to use those to send your first StartSession request.
  • Review the Check Deposit Guide to understand how to submit a successful Multi check deposit.
  • Download the EPS Ensenta Mobile API WSDL file from the Downloads page.
Ensenta Mobile API Multi Check Deposit Workflow

Deposit History Diagram

Integrator Mobile Deposit Flow
Ensenta API3 Mobile Deposit Flow

EPS Web Service

1.

User selects deposit menu.

Send StartSession request.

Step 1 can be skipped if this workflow is called in the middle of an already active session.

StartSession response with list of accounts, SessionToken, SessionStateId, and optional deposit limit information.

2.

Send GetAccountTransactionHistory request.

Integrator displays list of transactions to user. User selects a transaction to view details. Integrator then displays transaction details, including list of check items.

GetAccountTransactionHistory response with array of transactions (i.e. deposit batches).

3.

User selects a check item to view check images.

Send GetAccountTransactionCheckImage request.

Display check images to user.

GetAccountTransactionCheckImage response.

4.

If user's session is complete, send EndSession request

EndSession response which invalidates SessionToken and SessionStateId

 

 

Authenticating the Session

Step 1 Using the EPS Ensenta Mobile API SSO web service, send a StartSession request with the following information:

  • AccountHolderNumber
  • AccountHolderName
  • Username
  • Email
  • List of accounts with the following information: AccountNumber, Description, AccountTypeCode, JointAccountHolderNames(optional)
  • AccountHolderAttributes
note
  • If no AccountHolderAttributes are being used, you will send a single attribute with a blank Name/Value pair
  • For more details on the required information above, see the StartSession API reference page.
  • Steps 1-2 can be skipped if this workflow is being called in the middle of an already active session where StartSession request has already been called.

StartSession' request example

<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:par="http://ensenta.com/ECPartnerDepositRequest/SingleSignon/PartnerSSORequest">
   <soapenv:Header/>
   <soapenv:Body>
      <par:StartSession>
         <par:request>
            <par:PartnerId>(your PartnerId here)</par:PartnerId>
            <par:LanguageId>9</par:LanguageId>
            <par:DepositorIpAddress>127.0.0.1</par:DepositorIpAddress>
            <par:DeviceIdentifier>B23CED0E</par:DeviceIdentifier>
            <par:LocalDateTime>2023-10-06T11:21:56.603Z</par:LocalDateTime>
            <par:TimeZone>PST -08:00</par:TimeZone>
            <par:Attributes>
               <par:Attribute>
               </par:Attribute>
            </par:Attributes>
            <par:AccountHolderNumber>12345</par:AccountHolderNumber>
            <par:AccountHolderName>John Doe</par:AccountHolderName>
            <par:Username>Jdoe</par:Username>
            <par:Email>test@jackhenry.com</par:Email>
            <par:Accounts>
               <par:Account>
                  <par:AccountNumber>55555</par:AccountNumber>
                  <par:Description>Checking</par:Description>
                  <par:AccountTypeCode>1</par:AccountTypeCode>
                  <par:JointAccountHolderNames>
                  <par:string>Jane Doe</par:string></par:JointAccountHolderNames>
                  <par:Tag>0</par:Tag>
               </par:Account>
               <par:Account>
                  <par:AccountNumber>4444444</par:AccountNumber>
                  <par:Description>Savings</par:Description>
                  <par:AccountTypeCode>0</par:AccountTypeCode>
                  <par:JointAccountHolderNames>
                  <par:string>Jane Doe</par:string></par:JointAccountHolderNames>
                  <par:Tag>0</par:Tag>
               </par:Account>
            </par:Accounts>
            <par:AccountHolderAttributes>
               <par:Attribute>
                  <par:Name>Tier</par:Name>
                  <par:Value>Gold</par:Value>
               </par:Attribute>
            </par:AccountHolderAttributes>
         </par:request>
      </par:StartSession>
   </soapenv:Body>
</soapenv:Envelope>

Step 2 Log the following information from the StartSession response for use in subsequent requests:

  • SessionToken
  • SessionStateId
  • Available accounts and their AccountNumberIndex
  • Deposit Limit Information (Optional)

StartSession response example

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
    <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
        <StartSessionResponse xmlns="http://ensenta.com/ECPartnerDepositRequest/SingleSignon/PartnerSSORequest">
            <StartSessionResult>
                <ResponseCode>00</ResponseCode>
                <ErrorResponseText/>
                <LocalizedMessageText/>
                <SessionToken>(your SessionToken here)</SessionToken>
                <SessionStateId>(your SessionStateId here)</SessionStateId>
                <SessionInfo>
                    <AccountKeys>
                        <AccountKey>
                            <AccountNumberIndex>0</AccountNumberIndex>
                            <Description>Checking</Description>
                            <Tag>1</Tag>
                        </AccountKey>
                        <AccountKey>
                            <AccountNumberIndex>1</AccountNumberIndex>
                            <Description>Savings</Description>
                            <Tag>2</Tag>
                        </AccountKey>
                    </AccountKeys>
                    <IsTermsAcceptanceRequired>true</IsTermsAcceptanceRequired>
                    <IsIntroPageEnabled>false</IsIntroPageEnabled>
                    <IsHelpEnabled>false</IsHelpEnabled>
                    <SkinCode>4</SkinCode>
                    <StartPage>3</StartPage>
                    <ReceiptEmail/>
                    <CustomizableMessages>
                        <CustomizableMessage>
                            <MessageTextCd>ECP281</MessageTextCd>
                            <LocalizedText>You have 25 deposits left of your 25 daily transaction limit.</LocalizedText>
                        </CustomizableMessage>
                        <CustomizableMessage>
                            <MessageTextCd>ECP282</MessageTextCd>
                            <LocalizedText>You have $10000.00 left of your $10000.00 business day deposit limit.</LocalizedText>
                        </CustomizableMessage>
                        <CustomizableMessage>
                            <MessageTextCd>ECP288</MessageTextCd>
                            <LocalizedText>You have $10000.00 left of your $10000.00 deposit limit.</LocalizedText>
                        </CustomizableMessage>
                    </CustomizableMessages>
                    <AreAcctPermissionsEnabled>false</AreAcctPermissionsEnabled>
                    <IssuerPolicy>
                        <IsPlainScannerAllowed>N</IsPlainScannerAllowed>
                        <IsCheckScannerAllowed>N</IsCheckScannerAllowed>
                        <IsDepositDescrDisplayed>N</IsDepositDescrDisplayed>
                        <IsMultChecksPerTxn>Y</IsMultChecksPerTxn>
                        <IsHistoryAllowed>Y</IsHistoryAllowed>
                        <IsIntroEnabled>N</IsIntroEnabled>
                        <IsHelpEnabled>N</IsHelpEnabled>
                        <ImageCaptureMethod>-1</ImageCaptureMethod>
                        <IsBatchTotalAllowed>N</IsBatchTotalAllowed>
                        <IsDepositConfirmEnabled>N</IsDepositConfirmEnabled>
                        <IsMicrDisplayEnabled>N</IsMicrDisplayEnabled>
                        <IsPlainScannerOptional>N</IsPlainScannerOptional>
                        <IsCheckScannerOptional>N</IsCheckScannerOptional>
                        <IsDepositDescrOptional>N</IsDepositDescrOptional>
                        <IsMultChecksPerTxnOptional>N</IsMultChecksPerTxnOptional>
                        <IsIntroOptional>N</IsIntroOptional>
                        <IsHelpOptional>N</IsHelpOptional>
                        <IsImageCaptureMethodOptional>N</IsImageCaptureMethodOptional>
                        <IsBatchTotalOptional>N</IsBatchTotalOptional>
                        <IsDepositConfirmOptional>N</IsDepositConfirmOptional>
                        <IsMicrDisplayOptional>N</IsMicrDisplayOptional>
                        <MaxCheckPerTxn>1</MaxCheckPerTxn>
                        <IsSettingsEnabled>N</IsSettingsEnabled>
                        <CheckGuaranteeMethod>1</CheckGuaranteeMethod>
                        <ImageCaptureTimeoutSeconds>30</ImageCaptureTimeoutSeconds>
                        <ScanMethods/>
                        <AlertMethods/>
                        <TerminalFirmwareMinVersion/>
                        <TerminalFirmwareMaxVersion/>
                        <TerminalConfigMinVersion/>
                        <TerminalConfigMaxVersion/>
                    </IssuerPolicy>
                </SessionInfo>
            </StartSessionResult>
        </StartSessionResponse>
    </s:Body>
</s:Envelope>
Retrieving History

Step 3 Send a GetAccountTransactionHistory request.

GetAccountTransactionHistory request example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="http://ensenta.com/ECPartnerDepositRequest">
    <soapenv:Header/>
    <soapenv:Body>
        <GetAccountTransactionHistory>
            <request>
                <PartnerId>{{partnerId}}</PartnerId>
                <LanguageId>9</LanguageId>
                <DepositorIpAddress>137.0.0.1</DepositorIpAddress>
                <DeviceIdentifier>B23CED0E</DeviceIdentifier>
                <LocalDateTime>2020-08-24T11:21:56.603Z</LocalDateTime>
                <TimeZone>PST -08:00</TimeZone>
                <Attributes>
                    <Attribute>
                    </Attribute>
                </Attributes>
                <SessionStateId>{{sessionStateId}}</SessionStateId>
                <SessionToken>{{sessionToken}}</SessionToken>
                <NumberOfDays>0</NumberOfDays>
                <MaxNumberOfTransactions>50</MaxNumberOfTransactions>
                <ViewType>0</ViewType>
                <RequestType>1</RequestType>
                <CheckImageViewType>-1</CheckImageViewType>
                <CheckImageType>-1</CheckImageType>
                <StatusList>
                    <int>0</int>
                    <int>1</int>
                    <int>2</int>
                    <int>3</int>
                    <int>5</int>
                    <!-- 5 is the unposted status-->
                </StatusList>
            </request>
        </GetAccountTransactionHistory>
    </soapenv:Body>
</soapenv:Envelope>

Step 4 Once you have sent the GetAccountTransactionHistory request, you'll receive a response with an array of deposit batches (called transactions here) and the associated check items in each deposit. Populate a list of deposit batches for the user to select from.

Step 5 User selects a depost to view detailed information.

Step 6 Display the detailed deposit information and items from the associated deposit.

note

It is important that the history can display multi-item deposit batches, as shared history may be enabled and the user may be able to see history from the API 3 multi-item web service.

GetAccountTransactionHistory response example

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
    <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
        <GetAccountTransactionHistoryResponse xmlns="http://ensenta.com/ECPartnerDepositRequest">
            <GetAccountTransactionHistoryResult>
                <ResponseCode>00</ResponseCode>
                <ErrorResponseText/>
                <LocalizedMessageText/>
                <TransactionList>
                    <TransactionSummary>
                        <TransactionId>(your TransactionId here)</TransactionId>
                        <TransactionDate>2023-12-12T08:37:02.303</TransactionDate>
                        <Description>Test Deposit</Description>
                        <ReceiptNumber>(your ReceiptNumber here)</ReceiptNumber>
                        <SubmittedAmount>0.00</SubmittedAmount>
                        <AdjustmentAmount>0.00</AdjustmentAmount>
                        <CurrentAmount>6.00</CurrentAmount>
                        <NumberofChecks>1</NumberofChecks>
                        <Status>Unposted</Status>
                        <AccountNumber>(last 4 of account number here)</AccountNumber>
                        <AccountHolderNumber/>
                        <TransactionType>Deposit</TransactionType>
                        <AcceptedByDescription>Mobile Test</AcceptedByDescription>
                        <ChannelType>7</ChannelType>
                        <ChannelTypeDescription>Mobile</ChannelTypeDescription>
                        <StatusId>5</StatusId>
                        <StatusDescription>Unposted</StatusDescription>
                        <StatusChangeDate>2023-12-12T08:37:02.303</StatusChangeDate>
                        <Username>Jdoe</Username>
                        <DepositItems>
                            <DepositHistoryItem>
                                <ItemNumber>1</ItemNumber>
                                <CheckNumber>000001</CheckNumber>
                                <AdjustmentAmount>0.00</AdjustmentAmount>
                                <SubmittedAmount>0.00</SubmittedAmount>
                                <CurrentAmount>6.00</CurrentAmount>
                                <StatusDescription>Unposted</StatusDescription>
                                <Check21ReturnReasonDescription>Not Applicable / Other</Check21ReturnReasonDescription>
                                <StatusId>5</StatusId>
                            </DepositHistoryItem>
                        </DepositItems>
                        <RedeemedDtTm>0001-01-01T00:00:00</RedeemedDtTm>
                        <PayerAccountNumber/>
                        <TransactionTypeId>0</TransactionTypeId>
                    </TransactionSummary>
                </TransactionList>
            </GetAccountTransactionHistoryResult>
        </GetAccountTransactionHistoryResponse>
    </s:Body>
</s:Envelope>

Step 7 The user selects a deposit item to view more details.

Step 8 Send a GetAccountTransactionCheckImage request with the associated item information to retrieve that item's images.

GetAccountTransactionCheckImage request example

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns="http://ensenta.com/ECPartnerDepositRequest">
    <s:Header/>
    <s:Body>
        <GetAccountTransactionCheckImage>
            <request>
                <PartnerId>(your PartnerId here)</PartnerId>
                <LanguageId>9</LanguageId>
                <DepositorIpAddress>137.0.0.1</DepositorIpAddress>
                <DeviceIdentifier>B23CED0E</DeviceIdentifier>
                <LocalDateTime>2020-08-24T11:21:56.603Z</LocalDateTime>
                <TimeZone>PST -08:00</TimeZone>
                <Attributes>
                    <Attribute>
                        <Name></Name>
                        <Value></Value>
                    </Attribute>
                </Attributes>
                <SessionToken>(your SessionToken here)</SessionToken>
                <SessionStateId>(your SessionStateId here)</SessionStateId>
                <TransactionId>(your TransactionId here)</TransactionId>
                <CheckImageType>2</CheckImageType>
                <CheckImageViewType>2</CheckImageViewType>
                <ReceiptNumber>(your ReceiptNumber here)</ReceiptNumber>
                <ItemNumber>1</ItemNumber>
            </request>
        </GetAccountTransactionCheckImage>
    </s:Body>
</s:Envelope>

Step 9 After you send the request, you'll receive a GetAccountTransactionCheckImageresponse with the check item front and back image strings in base64 format.

Step 10 Display the item info and images to the user.

note

Repeat steps 7-10 as necessary for each item the user wants to view.

GetAccountTransactionCheckImage response example

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
    <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
        <GetAccountTransactionCheckImageResponse xmlns="http://ensenta.com/ECPartnerDepositRequest">
            <GetAccountTransactionCheckImageResult>
                <ResponseCode>00</ResponseCode>
                <ErrorResponseText/>
                <LocalizedMessageText/>
                <CheckFrontImage>(your check front image here)</CheckFrontImage>
                <CheckBackImage>(your check back image here)</CheckBackImage>
            </GetAccountTransactionCheckImageResult>
        </GetAccountTransactionCheckImageResponse>
    </s:Body>
</s:Envelope>
Ending the Session

Step 11 Once the user has finished reviewing deposits/images, you will send an EndSession request.

note

If the user wishes to retrieve more check images, repeat steps 7-10. Alternatively, if the user wants to submit new deposits, proceed with the Check Deposit workflow.

EndSession request example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="http://ensenta.com/ECPartnerDepositRequest">
    <soapenv:Header/>
    <soapenv:Body>
        <EndSession>
            <request>
                <PartnerId>(your PartnerId here)</PartnerId>
                <LanguageId>9</LanguageId>
                <DepositorIpAddress>127.0.0.1</DepositorIpAddress>
                <DeviceIdentifier>B23CED0E</DeviceIdentifier>
                <LocalDateTime>2023-10-06T11:21:56.603Z</LocalDateTime>
                <TimeZone>PST -08:00</TimeZone>
                <Attributes>
                    <Attribute>
                        <Name></Name>
                        <Value></Value>
                    </Attribute>
                </Attributes>
                <SessionStateId>(your SessionStateId here)</SessionStateId>
                <SessionToken>(your SessionToken here)</SessionToken>
            </request>
        </EndSession>
    </soapenv:Body>
</soapenv:Envelope>

Step 12 You'll receive a response with the ResponseCode 00 indicating a successful logout from the API.

EndSession response example

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
    <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
        <EndSessionResponse xmlns="http://ensenta.com/ECPartnerDepositRequest">
            <EndSessionResult>
                <ResponseCode>00</ResponseCode>
                <ErrorResponseText/>
                <LocalizedMessageText/>
            </EndSessionResult>
        </EndSessionResponse>
    </s:Body>
</s:Envelope>
Handling Errors and Failed Requests

Not all requests will be successful, so we will run through a few common error messages you should be ready to handle.

note

For an exhaustive list of all other error responses click here.

  • Session Expired Error: This error is returned when your session times out. If this appears, have the user start the deposit over with a new session beginning from step 1.
                <ResponseCode>E51</ResponseCode>
                <ErrorResponseText>Single Sign On Session Expired</ErrorResponseText>
                <LocalizedMessageText>It appears your connection to us has expired. Please attempt the deposit again. [E51]</LocalizedMessageText>
  • Single Sign-On Session Not Found: The web serivce cannot find the session you are referencing in your request. Verify your SessionStateToken and/or SessionId and try the request again.
                <ResponseCode>E50</ResponseCode>
                <ErrorResponseText>Single Sign On Session Not Found</ErrorResponseText>
                <LocalizedMessageText>Single sign-on session not found.</LocalizedMessageText>
  • User Blocklisted: This error is returned when you try to send a StartSession request with an AccountHolderNumber that is currently on a blocklist. In order to proceed, remove the user from the list and then update the blocklist on EZAdmin.
                <ResponseCode>E77</ResponseCode>
                <ErrorResponseText>Your access has been suspended. Please contact your financial institution.</ErrorResponseText>
                <LocalizedMessageText>Your access has been suspended. Please contact your financial institution.</LocalizedMessageText>
  • Invalid Parameter: If you input an invalid parameter in any request, this error message may appear. Check the response to see which parameter is invalid, and then update that parameter in your request to a valid value.
                <ResponseCode>E500</ResponseCode>
                <ErrorResponseText>Invalid parameter. </ErrorResponseText>
                <LocalizedMessageText>SessionStateId</LocalizedMessageText>
  • Generic Error: This generic error informs you that something went wrong with the deposit, but it does not have a detailed error code. You will need to start the deposit over from step 1. If you continue to receive this error, please reach out to EPS Ensenta support.
                <ResponseCode>E99</ResponseCode>
                <ErrorResponseText>Unexpected error</ErrorResponseText>
                <LocalizedMessageText>We're sorry, there was an unexpected error. Please attempt the deposit again.</LocalizedMessageText>
Next steps
  • Review the API Reference This guide is a starting point to show a common use case scenario for making a successful Multi-check deposit. Please review the API Reference to see all API methods and their technical specifications.
  • Explore other guides We have other guides to show how to leverage our APIs in other common use cases. If your situation or question is not covered in the current guide, consult another resource.