Skip to main content

Confirmable Risk Factor Guide

Introduction

In this guide, we'll walk you through how to handle risk factors that are marked as IsConfirmable. The IsConfirmable field in the risk factors object determines whether or not the risk factor is one that the end user can fix by updating one or more details of the check item. We will go through how to determine if a check item has triggered any confirmable risk factors, and how to enable the end user to resolve those risk factors.

Getting Started

Tasks covered in this guide

  • Creating a check deposit batch
  • Adding a single item to your open batch
  • Retrieving the batch and item details to determine if any confirmable risk factors were triggered
  • Retrieving check item images (optional)
  • Displaying issues to end user and giving them the option to update the check item information or continue with the deposit as is
  • Updating check item (if user elected to update check information)
  • Closing and submitting your single-check batch
  • Using the GetSessionInfo request to retrieve session info like accounts, limits, etc. (optional)

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 single check deposit.
  • Download the EPS Ensenta Mobile API WSDL file from the Downloads page.
Ensenta Mobile API Single Check Confirmable Workflow

Single Check Confirmable Workflow 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.

User selects account.

Send CreateDepositBatch request.

3

User captures front and back image and enters check amount.

CreateDepositBatch response with DepositBatchId.

Send AddDepositItem request to add check item to open batch.

AddDepositItem response.

4.

Send GetDepositBatchSummary request to obtain deposit batch information.

GetDepositBatchSummary response with ItemCount.

5.

Send GetDepositItem request to obtain item information, including risk factors triggered.

ItemCount must be equal to 1. If ItemCount is 0, wait 2-5 seconds then repeat the last request. Repeat this step as necessary until ItemCount equals 1.

6.

If any risk factor was triggered with the IsConfirmable field marked as true, then the integrator should display the RiskFactorLocalizedDescription of each confirmable risk factor to the end user. Integrator should then give end user the option to update the check items or proceed with deposit as is. If end user chooses to proceed as is, then skip to step 8.

GetDepositItem response with risk factor information, including confirmable risk factors.

7.

Integrator will collect updated check item information from end user to populate UpdateDepositItems request.

Send UpdateDepositItems request.

UpdateDepositItems response including updated risk factor information.

8.

Send PostDepositBatch request to submit the deposit

If the response shows that there are still confirmable risk factors being triggered, repeat steps 6-7 until the user has either fixed all confirmable risk factors, or decides to proceed with deposit as is.

PostDepositBatch response

9.

Send GetCheckImage request (optional)

Integrator's app should display the check images

GetCheckImage response with front and back check image strings

10.

Send GetSessionInfo request (optional)

GetSessionInfo response with updated deposit limits

11.

If user's session is complete, send EndSession request

User can optionally start a new batch within the same session by skipping step 11 and repeating the workflow from step 2

EndSession response which invalidates SessionToken and SessionStateId

 

 

Creating a Check Deposit Batch

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>

Step 3 Display the list of accounts from the StartSession response and have the user select an account to deposit to. Once the user has selected an account, send a CreateDepositBatch request with the appropriate AccountNumberIndex from the selected account. This opens a new deposit batch that you will use in subsequent requests to contain your check deposit item.

CreateDepositBatch request example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="http://ensenta.com/ECPartnerDepositRequest">
    <soapenv:Header/>
    <soapenv:Body>
        <CreateDepositBatch>
            <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>
                <DepositToAccountNumberIndex>0</DepositToAccountNumberIndex>
                <ItemCount>1</ItemCount>
                <Amount>10.00</Amount>
                <Description>Test Deposit</Description>
                <Scanner>
                    <SerialNumber>1</SerialNumber>
                    <Make>Mobile</Make>
                    <Model>Mobile</Model>
                    <ScannerTypeId>34</ScannerTypeId>
                </Scanner>
            </request>
        </CreateDepositBatch>
    </soapenv:Body>
</soapenv:Envelope>

Step 4 Once you have sent the CreateDepositBatch request, you'll receive a response with the DepositBatchId. Save this DepositBatchId to use in subsequent requests, specifying which batch you want to perform further actions on.

CreateDepositBatch 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">
        <CreateDepositBatchResponse xmlns="http://ensenta.com/ECPartnerDepositRequest">
            <CreateDepositBatchResult>
                <ResponseCode>00</ResponseCode>
                <ErrorResponseText/>
                <LocalizedMessageText/>
                <DepositBatchId>12345</DepositBatchId>
            </CreateDepositBatchResult>
        </CreateDepositBatchResponse>
    </s:Body>
</s:Envelope>
Adding a Check Deposit Item

Step 5 Have the user enter the check amount and then capture the check images within your app.

Step 6 Convert the check images to the proper format (Base64 string).

Step 7 Populate an AddDepositItem request with the check amount, front and back images, and DepositBatchId.

note

For details on Mitek image requirements, see the Mitek programmer's guide (you should have recevied this during your project kickoff).

AddDepositItem request example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="http://ensenta.com/ECPartnerDepositRequest">
    <soapenv:Header/>
    <soapenv:Body>
        <AddDepositItem>
            <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>
                <DepositBatchId>12345</DepositBatchId>
                <ItemNumber>1</ItemNumber>
                <IsFirstItem>true</IsFirstItem>
                <TenderType>1</TenderType>
                <Amount>10.00</Amount>
                <CheckImageCategory>1</CheckImageCategory>
                <ImagePreprocessState>2</ImagePreprocessState>
                <FrontBase64Image><(your Base64 front image string here)/FrontBase64Image>
                <BackBase64Image>(your Base64 back image string here)</BackBase64Image>
            </request>
        </AddDepositItem>
    </soapenv:Body>
</soapenv:Envelope>

Step 9 After you send the request, you'll receive an AddDepositItem response with the response code "00" to indicate that the item was successfully added to the batch.

AddDepositItem 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">
        <AddDepositItemResponse xmlns="http://ensenta.com/ECPartnerDepositRequest">
            <AddDepositItemResult>
                <ResponseCode>00</ResponseCode>
                <ErrorResponseText/>
                <LocalizedMessageText/>
            </AddDepositItemResult>
        </AddDepositItemResponse>
    </s:Body>
</s:Envelope>

Step 10 After receiving a successful response, you will send a GetDepositBatchSummary request with the appropriate DepositBatchId to review the batch details.

GetDepositBatchSummary request example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="http://ensenta.com/ECPartnerDepositRequest">
    <soapenv:Header/>
    <soapenv:Body>
        <GetDepositBatchSummary>
            <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>
                <DepositBatchId>12345</DepositBatchId>
            </request>
        </GetDepositBatchSummary>
    </soapenv:Body>
</soapenv:Envelope>

Step 11 You will receive a GetDepositBatchSummary response. At this point, check the ItemCount to ensure that it shows an integer of 1. If it shows an integer of 0, wait approximately 2-5 seconds, and then repeat step 7. Repeat this step as necessary until the ItemCount shows an integer of 1.

note

It is crucial that the ItemCount matches your expected item count of 1, or the GetItem request will fail until it does. This is why it is important to repeat this request until the ItemCount equals 1.

GetDepositBatchSummary 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">
        <GetDepositBatchSummaryResponse xmlns="http://ensenta.com/ECPartnerDepositRequest">
            <GetDepositBatchSummaryResult>
                <ResponseCode>00</ResponseCode>
                <ErrorResponseText/>
                <LocalizedMessageText/>
                <ItemCount>1</ItemCount>
                <OkItemCount>1</OkItemCount>
                <NeedReviewItemCount>0</NeedReviewItemCount>
                <ItemNumbers>
                    <int>1</int>
                </ItemNumbers>
                <Amount>6.00</Amount>
                <UserItemCount>0</UserItemCount>
                <UserAmount>0.00</UserAmount>
                <UserDescription>Test Deposit</UserDescription>
                <DepositToAccountNumberIndex>0</DepositToAccountNumberIndex>
            </GetDepositBatchSummaryResult>
        </GetDepositBatchSummaryResponse>
    </s:Body>
</s:Envelope>
Reviewing and Fixing Confirmable Risk Factors

Step 12 After receiving a successful GetDepositBatchSummary response with an ItemCount of 1, you will send a GetDepositItem request with the appropriate ItemNumber to review the item details, including any risk factors that the item has triggered.

GetDepositItem request example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="http://ensenta.com/ECPartnerDepositRequest">
    <soapenv:Header/>
    <soapenv:Body>
        <GetDepositItem>
            <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>
                <DepositBatchId>12345</DepositBatchId>
                <ItemNumber>1</ItemNumber>
            </request>
        </GetDepositItem>
    </soapenv:Body>
</soapenv:Envelope>

Step 13 You will receive a GetDepositItem response with item details, including generic funds availability text and an array of any risk factors that the item may have triggered.

Step 14 Display the RiskFactorLocalizedDescription of any risk factor marked as IsConfirmable to the end user.

Step 15 Give the end user the choice to either fix the issues or proceed with the deposit as is. If the end user has decided to proceed with the deposit as is, then skip to step 19.

GetDepositItem 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">
        <GetDepositItemResponse xmlns="http://ensenta.com/ECPartnerDepositRequest">
            <GetDepositItemResult>
                <ResponseCode>00</ResponseCode>
                <ErrorResponseText/>
                <LocalizedMessageText/>
                <DepositItem>
                    <ItemNumber>1</ItemNumber>
                    <Micr>(your check micr here)</Micr>
                    <CheckNumber>000001</CheckNumber>
                    <OcrAmount>1.23</OcrAmount>
                    <UserAmount>6.00</UserAmount>
                    <Amount>6.00</Amount>
                    <Status>0</Status>
                    <FundsAvailabilityText>Funds availability: Funds deposited to your account may not be available immediately based on your Credit Union's Hold Policies. Please contact your Credit Union regarding the Hold Policies on your account.</FundsAvailabilityText>
                    <RiskFactors>
				        <RiskFactor>
                            <RiskFactorId>12</RiskFactorId>
                            <RiskFactorDescription>Date Not Recognized By OCR</RiskFactorDescription>
                            <RiskFactorLocalizedDescription>The check date is between 2/8/2018 and 8/8/2018.</RiskFactorLocalizedDescription>
                            <Severity>1</Severity>
                            <IsFixable>false</IsFixable>
                            <IsConfirmable>true</IsConfirmable>
                            <DepositFields>
                                <int>16</int>
                            </DepositFields>
                        </RiskFactor>
                        <RiskFactor>
                            <RiskFactorId>11</RiskFactorId>
                            <RiskFactorDescription>Payee Does Not Match Acct Holder or Institution</RiskFactorDescription>
                            <RiskFactorLocalizedDescription>Payee Does Not Match Acct Holder or Institution</RiskFactorLocalizedDescription>
                            <Severity>1</Severity>
                            <IsFixable>false</IsFixable>
                            <IsConfirmable>true</IsConfirmable>
                            <DepositFields>
                                <int>5</int>
                            </DepositFields>
                        </RiskFactor>
			        </RiskFactors>
                </DepositItem>
            </GetDepositItemResult>
        </GetDepositItemResponse>
    </s:Body>
</s:Envelope>

Step 16 After reviewing the check details, have the user update the amount and/or the check images and then send an UpdateDepositItem request with the updated check info.

UpdateDepositItem request example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="http://ensenta.com/ECPartnerDepositRequest">
    <soapenv:Header/>
    <soapenv:Body>
        <UpdateDepositItems>
            <request>
                <PartnerId>(your partnerId here)</PartnerId>
                <LanguageId>9</LanguageId>
                <DepositorIpAddress>127.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>
                <SessionStateId>(your sessionStateId here)</SessionStateId>
                <SessionToken>(your sessionToken here)</SessionToken>
                <DepositBatchId>(your depositBatchId here)</DepositBatchId>
                <DepositItemCorrections>
	                <DepositItemCorrection>
                        <ItemNumber>1</ItemNumber>
                        <Amount>6.00</Amount>
                        <Micr></Micr>
                        <IsConfirmed>false</IsConfirmed>
                        <IsDeleted>false</IsDeleted>
                        <CheckImageCategory>1</CheckImageCategory>
                        <ImagePreprocessState>2</ImagePreprocessState>
                        <FrontBase64Image>(your base64 front check image string here)</FrontBase64Image>
                        <BackBase64Image>(your base64 back check image string here)</BackBase64Image>
                        </DepositItemCorrection>
	                </DepositItemCorrections>
	                <DepositItemStatus>-1</DepositItemStatus>
            </request>
        </UpdateDepositItems>
    </soapenv:Body>
</soapenv:Envelope>

Step 17 You will receive a response with a response code of 00, showing that the deposit item has been successfully updated. The response will also include deposit item details and an array of risk factors that are still being triggered.

Step 18 If any risk factors are still being triggered and have the IsConfirmable filed marked as true, repeat step 14-17 until either all confirmable risk factors have been fixed, or the user elects to proceed with the deposit as is.

UpdateDepositItem 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">
        <UpdateDepositItemsResponse xmlns="http://ensenta.com/ECPartnerDepositRequest">
            <UpdateDepositItemsResult>
                <ResponseCode>00</ResponseCode>
                <ErrorResponseText/>
                <LocalizedMessageText/>
                <UpdateItemStatusList>
                    <UpdateDepositItemStatus>
                        <ItemNumber>1</ItemNumber>
                        <ResponseCode>00</ResponseCode>
                    </UpdateDepositItemStatus>
                </UpdateItemStatusList>
                <DepositItems>
                    <DepositItem>
                        <ItemNumber>1</ItemNumber>
                        <Micr>(your check micr here)</Micr>
                        <CheckNumber>000001</CheckNumber>
                        <OcrAmount>1.23</OcrAmount>
                        <UserAmount>6.00</UserAmount>
                        <Amount>6.00</Amount>
                        <Status>0</Status>
                        <FundsAvailabilityText>Funds availability: Funds deposited to your account may not be available immediately based on your Credit Union's Hold Policies. Please contact your Credit Union regarding the Hold Policies on your account.</FundsAvailabilityText>
                        <RiskFactors>
                            <RiskFactor>
                                <RiskFactorId>11</RiskFactorId>
                                <RiskFactorDescription>Payee Does Not Match Acct Holder or Institution</RiskFactorDescription>
                                <RiskFactorLocalizedDescription>Review and confirm check is payable to a signer on this account.</RiskFactorLocalizedDescription>
                                <Severity>1</Severity>
                                <IsFixable>true</IsFixable>
                                <IsConfirmable>false</IsConfirmable>
                                <DepositFields>
                                    <int>5</int>
                                </DepositFields>
                            </RiskFactor>
                        </RiskFactors>
                    </DepositItem>
                </DepositItems>
            </UpdateDepositItemsResult>
        </UpdateDepositItemsResponse>
    </s:Body>
</s:Envelope>
Posting the Deposit Batch

Step 19 After reviewing the check details, you can submit the deposit by sending a PostDepositBatch request.

PostDepositBatch request example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="http://ensenta.com/ECPartnerDepositRequest">
    <soapenv:Header/>
    <soapenv:Body>
        <PostDepositBatch>
            <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>
                <DepositBatchId>(your DepositBatchId here)</DepositBatchId>
                <ItemNumbers>
                    <int>1</int>
                </ItemNumbers>
            </request>
        </PostDepositBatch>
    </soapenv:Body>
</soapenv:Envelope>

Step 20 You will receive a response with a response code of 00, showing that the deposit has been successfully submitted.

PostDepositBatch 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">
        <PostDepositBatchResponse xmlns="http://ensenta.com/ECPartnerDepositRequest">
            <PostDepositBatchResult>
                <ResponseCode>00</ResponseCode>
                <ErrorResponseText/>
                <LocalizedMessageText/>
                <TransactionSummary>
                    <TransactionId>(your TransactionId here)</TransactionId>
                    <TransactionDate>2023-10-24T07:16:31.21</TransactionDate>
                    <Description>Test Deposit</Description>
                    <ReceiptNumber>(Your ReceiptNumber here)</ReceiptNumber>
                    <SubmittedAmount>6.00</SubmittedAmount>
                    <AdjustmentAmount>0.00</AdjustmentAmount>
                    <CurrentAmount>6.00</CurrentAmount>
                    <NumberofChecks>1</NumberofChecks>
                    <Status>Submitted</Status>
                    <AccountNumber>x5555</AccountNumber>
                    <AccountHolderNumber/>
                    <TransactionType>Deposit</TransactionType>
                    <AcceptedByDescription>Travis Mobile Test</AcceptedByDescription>
                    <ChannelType>7</ChannelType>
                    <ChannelTypeDescription>Mobile</ChannelTypeDescription>
                    <StatusId>0</StatusId>
                    <StatusDescription>Submitted</StatusDescription>
                    <StatusChangeDate>2023-10-24T07:16:31.21</StatusChangeDate>
                    <Username/>
                    <DepositItems>
                        <DepositHistoryItem>
                            <ItemNumber>1</ItemNumber>
                            <CheckNumber>000001</CheckNumber>
                            <AdjustmentAmount>0.00</AdjustmentAmount>
                            <SubmittedAmount>6.00</SubmittedAmount>
                            <CurrentAmount>6.00</CurrentAmount>
                            <StatusDescription>Submitted</StatusDescription>
                            <Check21ReturnReasonDescription>Not Applicable / Other</Check21ReturnReasonDescription>
                            <StatusId>0</StatusId>
                        </DepositHistoryItem>
                    </DepositItems>
                    <RedeemedDtTm>0001-01-01T00:00:00</RedeemedDtTm>
                    <PayerAccountNumber/>
                    <TransactionTypeId>0</TransactionTypeId>
                </TransactionSummary>
            </PostDepositBatchResult>
        </PostDepositBatchResponse>
    </s:Body>
</s:Envelope>
Optional Steps

Step 21 (optional) Send a GetCheckImage request and you will receive a GetCheckImage response. Use the data from the GetCheckImage response to display the check images to the end user for review.

GetCheckImage request example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="http://ensenta.com/ECPartnerDepositRequest">
    <soapenv:Header/>
    <soapenv:Body>
        <GetCheckImage>
	<request>
		<PartnerId>(your partnerId here)</PartnerId>
		<LanguageId>9</LanguageId>
		<DepositorIpAddress>203.0.113.0</DepositorIpAddress>
		<DeviceIdentifier>21d182e6-10b1-48e2-8c53-1b72674836c1</DeviceIdentifier>
		<LocalDateTime>2020-08-24T11:21:56.603Z</LocalDateTime>
		<TimeZone>PST -8:00 PST</TimeZone>
		<Attributes>
		   <Attribute>
			  <Name></Name>
			  <Value></Value>
		   </Attribute>
		</Attributes>
        <SessionStateId>(your sessionStateId here)</SessionStateId>
        <SessionToken>(your sessionToken here)</SessionToken>
		<ItemNumber>1</ItemNumber>
		<CheckImageViewType>2</CheckImageViewType>
		<CheckImageType>2</CheckImageType>
	</request>
</GetCheckImage>
    </soapenv:Body>
</soapenv:Envelope>

GetCheckImage 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">
        <GetCheckImageResponse xmlns="http://ensenta.com/ECPartnerDepositRequest">
            <GetCheckImageResult>
                <ResponseCode>00</ResponseCode>
                <ErrorResponseText/>
                <LocalizedMessageText/>
                <CheckImages>
                    <CheckImageInfo>
                        <CheckImage>(check image string here)</CheckImage>
                        <CheckImageViewType>0</CheckImageViewType>
                    </CheckImageInfo>
                    <CheckImageInfo>
                        <CheckImage>(check image string here)</CheckImage>
                        <CheckImageViewType>1</CheckImageViewType>
                    </CheckImageInfo>
                </CheckImages>
            </GetCheckImageResult>
        </GetCheckImageResponse>
    </s:Body>
</s:Envelope>

Step 22 (optional) You can send a GetSessionInfo request to retrieve the current details of your session, such as updated deposit limit information.

GetSessionInfo request example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="http://ensenta.com/ECPartnerDepositRequest">
    <soapenv:Header/>
    <soapenv:Body>
        <GetSessionInfo>
            <request>
                <PartnerId>(your partnerId here)</PartnerId>
                <LanguageId>9</LanguageId>
                <DepositorIpAddress>127.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>
                <SessionStateId>(your sessionStateId here)</SessionStateId>
                <SessionToken>(your sessionToken here)</SessionToken>
            </request>
        </GetSessionInfo>
    </soapenv:Body>
</soapenv:Envelope>

Step 23 The GetSessionInfo response will return information about the current session, including updated deposit limit information (if you have set up the deposit limit messages in EPS Ensenta EZAdmin™).

GetSessionInfo 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">
        <GetSessionInfoResponse xmlns="http://ensenta.com/ECPartnerDepositRequest">
            <GetSessionInfoResult>
                <ResponseCode>00</ResponseCode>
                <ErrorResponseText/>
                <LocalizedMessageText/>
                <SessionToken>(your SessionToken here)</SessionToken>
                <PartnerId>(your PartnerId here)</PartnerId>
                <ChannelTypeId>7</ChannelTypeId>
                <SessionInfo>
                    <AccountKeys>
                        <AccountKey>
                            <AccountNumberIndex>0</AccountNumberIndex>
                            <Description>Checking</Description>
                            <Tag>0</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 24 deposits left of your 25 daily transaction limit.</LocalizedText>
                        </CustomizableMessage>
                        <CustomizableMessage>
                            <MessageTextCd>ECP282</MessageTextCd>
                            <LocalizedText>You have $9994.00 left of your $10000.00 business day deposit limit.</LocalizedText>
                        </CustomizableMessage>
                        <CustomizableMessage>
                            <MessageTextCd>ECP288</MessageTextCd>
                            <LocalizedText>You have $9994.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>
            </GetSessionInfoResult>
        </GetSessionInfoResponse>
    </s:Body>
</s:Envelope>
Ending the Session

Step 24 Once the user has finished creating the deposits they want to submit within this session, you will send an EndSession request.

note

If the user wishes to submit more deposits or retrieve within the same session, do not proceed with an EndSession request, but repeat the workflow from step 3. Alternatively, if the user wishes to retrieve transaction history, proceed with the transaction history workflow before ending the session.

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 25 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>
  • Deposit Item Not Found: This error message appears when you send a GetDepositItem request with an invalid ItemNumber. Send a GetDepositBatchSummary request to determine if the ItemCount is equal to 1. If the ItemCount does not equal 1, wait 2-5 seconds and then repeat the GetDepositBatchSummary request until the ItemCount equals 1.
                <ResponseCode>E88</ResponseCode>
                <ErrorResponseText>Deposit Item Not Found</ErrorResponseText>
                <LocalizedMessageText>Deposit Item Not Found</LocalizedMessageText>
  • Deposit Limit Error: This error message appears when you send a PostDepositBatch request with an amount that exceeds a deposit limit.
                <ResponseCode>EL1</ResponseCode>
                <ErrorResponseText>The calendar day deposit limit of %1 will be exceeded. You may deposit up to %2.</ErrorResponseText>
                <LocalizedMessageText>The calendar day deposit limit of $1.00 will be exceeded. You may deposit up to $1.00.</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 single-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.