Check Reject Guide

Introduction

In this guide, we'll walk you through how to handle rejected items in multi check batches. You should already have a good understanding of the basic deposit workflow, if not, then see the link to the Check Deposit Guide in the pre-requisites below.

Getting Started

Tasks covered in this guide

Creating a check deposit batch
Adding items to your open batch
Handling item rejects (including in app messaging)

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 Reject Workflow

Multi Check Reject 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 and their severity	ItemCount field must match the integrator's expected item count. If ItemCount does not match expected item count, wait 2-5 seconds then repeat the last request. Repeat this step as necessary until ItemCount matches the expected item count.
		GetDepositItem response with risk factor information and associated severity
	Integrator should display the RiskFactorLocalizedDescription from the GetDepositItemResponse to the end user in their app UI	If any risk factor was triggered with an associated severity of 3, then the item is automatically rejected.
6.	Integrator sends UpdateDepositItems request with the IsDeleted field marked true
7.	If user's session is complete, send EndSession request
	User can optionally start a new batch within the same session by skipping step 6 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.

note

The amount field is not used. Please send an amount of 0.00.

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>2</ItemCount>
                <Amount>0.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.

note

A success on the AddItemResponse only means that the item has been successfully added to the batch, but it doesn't mean the item will not be rejected. You will need to retrieve the item information using the GetDepositItem request to determine if the item has been rejected or not.

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 AddDepositItem 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 matches your current expected item count (eg if this is your 3rd check but you have deleted one, then the ItemCount should equal 2, if this is your 4th check, ItemCount should equal 4, etc). If it shows anything other than your expected item count, wait approximately 2-5 seconds, and then repeat step 7. Repeat this step as necessary until the ItemCount matches your expected item count.

note

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

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>2</ItemCount>
                <OkItemCount>2</OkItemCount>
                <NeedReviewItemCount>0</NeedReviewItemCount>
                <ItemNumbers>
                    <int>1</int>
                    <int>2</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 the Rejected Item

Step 12 After receiving a successful GetDepositBatchSummary response with an ItemCount that matches your expected item count, 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>2</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. Each triggered risk factor will be represented by an object that contains all the details for the risk factor, including the severity. If any risk factor shows a severity of 3, then that means the item has been rejected.

Step 14 Your app should display a message in the UI to the end user to inform them of the reject reason(s). The reject reason messaging should come from the RiskFactorLocalizedDescription for any risk factor with an associated severity of 3.

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>2</ItemNumber>
                    <Micr/>
                    <CheckNumber/>
                    <OcrAmount>0.00</OcrAmount>
                    <UserAmount>6.00</UserAmount>
                    <Amount>6.00</Amount>
                    <Status>1</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>58</RiskFactorId>
                            <RiskFactorDescription>Back Looks Like Front</RiskFactorDescription>
                            <RiskFactorLocalizedDescription>Back image appears to be check front. Please take a new photo of the back of your check.</RiskFactorLocalizedDescription>
                            <Severity>3</Severity>
                            <IsFixable>false</IsFixable>
                            <IsConfirmable>false</IsConfirmable>
                            <DepositFields>
                                <int>18</int>
                            </DepositFields>
                        </RiskFactor>
                    </RiskFactors>
                </DepositItem>
            </GetDepositItemResult>
        </GetDepositItemResponse>
    </s:Body>
</s:Envelope>

Optional Steps

Step 15 (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>

Removing the Check Deposit Item

Step 16 To remove the rejected item from the batch, send a UpdateDepositItems request with the item number of the rejected item. This will delete the rejected item from the batch.

UpdateDepositItems 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>192.168.1.1</DepositorIpAddress>
	<DeviceIdentifier>test</DeviceIdentifier>
	<LocalDateTime>2024-02-09T08:45:58.000-07:00</LocalDateTime>
	<TimeZone>PST -8:00 America/Redwood_Shores</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>2</ItemNumber>
		  <Amount>6.00</Amount>
		  <Micr></Micr>
		  <IsConfirmed>false</IsConfirmed>
		  <IsDeleted>true</IsDeleted>
		  <CheckImageCategory>1</CheckImageCategory>
		  <ImagePreprocessState>2</ImagePreprocessState>
		  <FrontBase64Image></FrontBase64Image>
		  <BackBase64Image></BackBase64Image>
	   </DepositItemCorrection>
	</DepositItemCorrections>
	<DepositItemStatus>-1</DepositItemStatus>
 </request>
</UpdateDepositItems>
    </soapenv:Body>
</soapenv:Envelope>

Step 17 After you send the request, you'll receive an UpdateDepositItem response with the response code "00" to indicate that the item was successfully deleted from the batch. The user can continue adding additional items to their batch, or post the batch and end the session.

UpdateDepositItems 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>2</ItemNumber>
                        <ResponseCode>00</ResponseCode>
                    </UpdateDepositItemStatus>
                </UpdateItemStatusList>
                <DepositItems>
                    <DepositItem>
                        <ItemNumber>1</ItemNumber>
                        <Micr>(your 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>
                    <DepositItem>
                        <ItemNumber>2</ItemNumber>
                        <Micr>(your Micr here))</Micr>
                        <CheckNumber>000001</CheckNumber>
                        <OcrAmount>1.23</OcrAmount>
                        <UserAmount>6.00</UserAmount>
                        <Amount>6.00</Amount>
                        <Status>2</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>

Ending the Session

Step 18 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 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 19 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>

Reject Due to Deposit Policy: This error returns if your environment isn't enabled for Multi Flow. To resolve this issue, please reach out to EPS Ensenta support.

                <ResponseCode>E35</ResponseCode>
                <ErrorResponseText>Could not verify check. Please remove check and try again.</ErrorResponseText>
                <LocalizedMessageText>Reject due deposit policy. Reject level risks found.</LocalizedMessageText>

Next steps

Review the API Reference This guide is a starting point to show a common use case scenario for handling rejects in Multi-check deposits. 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.