Skip to main content

Large Account List Guide

Introduction

In this guide, we will walk you through adding a large list of accounts using the PAPI3 Multi Flow web service. This alternate single sign-on sequence was implemented specifically for the use case involving a financial instituion that has Business RDC customers with more than 500 deposit accounts. It is expected that all of those accounts are to be available to the End User within the deposit session.

note
  • This workflow is optional. The existing StartSession sequence is still viable and recommended for most implementations.
  • Note to Partner integrations: The single sign-on sequence is financial institution-specific. For existing financial institution relationships, their existing StartSession sequence can remain unchanged with this alternate single sign-on sequence being implemented for the specific financial institution(s) meeting this use case.
Getting Started

Tasks covered in this guide

  • Send a large list of accounts using the AddAccounts method

Required prerequisites before you continue

  • You will want to obtain your test credentials in order to try any of the examples in this guide. You should have received these from your Integration Project Lead.
  • Review the Authentication guide for an understanding of how to authenticate to the EPS web service. This guide walks you through sending a StartSession to ensure you are able to authenticate before moving forward.
  • Download the PAPI3 Large Account List WSDL file from the Downloads menu.
Large Account List Workflow

Large Account List Diagram

Starting the Deposit Session

Step 1 To authenticate, send a StartSession request without any account information.

note

Don't send the account information at this point, as that will be handled in a later step. Additionally, this will help prevent the StartSession request from becoming too large.

StartSession request example.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="http://ensenta.com/ECPartnerDepositRequest/SingleSignon/PartnerSSORequest">
    <soapenv:Header/>
    <soapenv:Body>
        <StartSession>
            <request>
                <PartnerId>Your PartnerId</PartnerId>
                <LanguageId>9</LanguageId>
                <DepositorIpAddress>127.0.0.2</DepositorIpAddress>
                <DeviceIdentifier>B23CED0E</DeviceIdentifier>
                <LocalDateTime>2020-08-24T11:21:56.603Z</LocalDateTime>
                <TimeZone>PST -08:00 America/Redwood_Shores</TimeZone>
                <Attributes>
                    <Attribute>
                        <Name></Name>
                        <Value></Value>
                    </Attribute>
                </Attributes>
                <AccountHolderNumber>123123123</AccountHolderNumber>
                <AccountHolderName>John Smith</AccountHolderName>
                <Username>johnsmith</Username>
                <Email>test@test.com</Email>
                <AccountHolderAttributes>
                    <Attribute>
                        <Name>ECPhoneType</Name>
                        <Value>Android</Value>
                    </Attribute>
                    <Attribute>
                        <Name>ECPhoneOS</Name>
                        <Value>Android</Value>
                    </Attribute>
                    <Attribute>
                        <Name>ECPhoneOsVersion</Name>
                        <Value>Oreo 8.1</Value>
                    </Attribute>
                    <Attribute>
                        <Name>ECPartnerVersion</Name>
                        <Value>1.0</Value>
                    </Attribute>
                    <Attribute>
                        <Name>ECAppDeviceMake</Name>
                        <Value>Samsung</Value>
                    </Attribute>
                    <Attribute>
                        <Name>ECAppDeviceModel</Name>
                        <Value>Galaxy S9</Value>
                    </Attribute>
                </AccountHolderAttributes>
            </request>
        </StartSession>
    </soapenv:Body>
</soapenv:Envelope>

Step 2 Once this request is sent to the endpoint, you should get a successful response. You will not receive any account information back in the response. Account information will be handled in the following step.

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>8f11b7cc-cc2a-4776-8cc0-513a62ab4cfa</SessionToken>
                <SessionStateId>6503bd69-8fb7-4308-82f5-8e780e4ff1fc</SessionStateId>
                <SessionInfo>
                    <IsTermsAcceptanceRequired>true</IsTermsAcceptanceRequired>
                    <IsIntroPageEnabled>false</IsIntroPageEnabled>
                    <IsHelpEnabled>false</IsHelpEnabled>
                    <SkinCode>4</SkinCode>
                    <StartPage>3</StartPage>
                    <ReceiptEmail/>
                    <CustomizableMessages>
                        <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>Y</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>99</MaxCheckPerTxn>
                        <IsSettingsEnabled>N</IsSettingsEnabled>
                        <CheckGuaranteeMethod>-1</CheckGuaranteeMethod>
                        <ImageCaptureTimeoutSeconds>30</ImageCaptureTimeoutSeconds>
                        <ScanMethods/>
                        <AlertMethods/>
                        <TerminalFirmwareMinVersion/>
                        <TerminalFirmwareMaxVersion/>
                        <TerminalConfigMinVersion/>
                        <TerminalConfigMaxVersion/>
                    </IssuerPolicy>
                </SessionInfo>
            </StartSessionResult>
        </StartSessionResponse>
    </s:Body>
</s:Envelope>
Adding the Accounts

Step 3 Use the customer's account information to build and send the AddAccounts request.

note
  • In the example AddAccounts request below, we only show a few accounts being added, but the method can hold up to 500 accounts.
  • Please note the following for this interaction:
  • If there are one or more valid accounts in the request, we will return the '00' success response.
  • We recommend completing all AddAccounts Request/Response messaging before allowing the user to proceed with deposit activity, to ensure that all accounts are available to the user.
  • Subsequent AddAccounts calls will only append new accounts. Any accounts that were added to the session by previous AddAccounts calls will be ignored in new calls.

AddAccounts request example.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="http://ensenta.com/ECPartnerDepositRequest">
    <soapenv:Header/>
    <soapenv:Body>
        <AddAccounts>
            <request>
                <PartnerId>Your PartnerId</PartnerId>
                <LanguageId>9</LanguageId>
                <DepositorIpAddress>127.0.0.1</DepositorIpAddress>
                <DeviceIdentifier>B23CED0E</DeviceIdentifier>
                <SessionStateId>6503bd69-8fb7-4308-82f5-8e780e4ff1fc</SessionStateId>
                <SessionToken>8f11b7cc-cc2a-4776-8cc0-513a62ab4cfa</SessionToken>
                <Accounts>
                    <Account>
                        <AccountNumber>1234</AccountNumber>
                        <Description>Checking 34</Description>
                        <AccountTypeCode>1</AccountTypeCode>
                        <JointAccountHolderNames>
                            <string>Jane Smith</string>
                        </JointAccountHolderNames>
                    </Account>
                    <Account>
                        <AccountNumber>5678</AccountNumber>
                        <Description>Savings 78</Description>
                        <AccountTypeCode>0</AccountTypeCode>
                        <JointAccountHolderNames>
                            <string>Jane Smith</string>
                        </JointAccountHolderNames>
                    </Account>
                    <Account>
                        <AccountNumber>5432</AccountNumber>
                        <Description>Checking 32</Description>
                        <AccountTypeCode>1</AccountTypeCode>
                        <JointAccountHolderNames>
                            <string>Jane Smith</string>
                        </JointAccountHolderNames>
                    </Account>
                </Accounts>
            </request>
        </AddAccounts>
    </soapenv:Body>
</soapenv:Envelope>

Step 4 Once this request is sent to the endpoint, you should get a successful response. You may notice that no account imformation is returned in the response. You will need to send another request to get the account information.

note

If the customer has more accounts that needs to be sent, you can loop back to Step 3 to add more accounts.

AddAccounts 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">
        <AddAccountsResponse xmlns="http://ensenta.com/ECPartnerDepositRequest">
            <AddAccountsResult>
                <ResponseCode>00</ResponseCode>
                <ErrorResponseText/>
                <LocalizedMessageText/>
            </AddAccountsResult>
        </AddAccountsResponse>
    </s:Body>
</s:Envelope>
Getting the Account Information

Step 5 When you are finished adding accounts and you've received a successful AddAccounts response, you will need to send a GetSessionInfo request.

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</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 America/Redwood_Shores</TimeZone>
                <Attributes>
                    <Attribute>
                        <Name></Name>
                        <Value></Value>
                    </Attribute>
                </Attributes>
                <SessionStateId>6503bd69-8fb7-4308-82f5-8e780e4ff1fc</SessionStateId>
                <SessionToken>8f11b7cc-cc2a-4776-8cc0-513a62ab4cfa</SessionToken>
            </request>
        </GetSessionInfo>
    </soapenv:Body>
</soapenv:Envelope>

Step 6 Once this request is sent to the endpoint, you should get a successful response. You will receive the customer's account information and be able to continue with the normal remote deposit flow.

note

Use the AccountNumberIndex fields in the response for making deposits to a specific account.

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>c2d8863a-8f0e-44d3-80ae-30064d6dc252</SessionToken>
                <PartnerId>15147</PartnerId>
                <ChannelTypeId>7</ChannelTypeId>
                <SessionInfo>
                    <AccountKeys>
                        <AccountKey>
                            <AccountNumberIndex>0</AccountNumberIndex>
                            <Description>Checking 34</Description>
                        </AccountKey>
                        <AccountKey>
                            <AccountNumberIndex>1</AccountNumberIndex>
                            <Description>Savings 78</Description>
                        </AccountKey>
                        <AccountKey>
                            <AccountNumberIndex>2</AccountNumberIndex>
                            <Description>Checking 32</Description>
                        </AccountKey>
                    </AccountKeys>
                    <IsTermsAcceptanceRequired>true</IsTermsAcceptanceRequired>
                    <IsIntroPageEnabled>false</IsIntroPageEnabled>
                    <IsHelpEnabled>false</IsHelpEnabled>
                    <SkinCode>4</SkinCode>
                    <StartPage>3</StartPage>
                    <ReceiptEmail/>
                    <CustomizableMessages>
                        <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>Y</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>99</MaxCheckPerTxn>
                        <IsSettingsEnabled>N</IsSettingsEnabled>
                        <CheckGuaranteeMethod>-1</CheckGuaranteeMethod>
                        <ImageCaptureTimeoutSeconds>30</ImageCaptureTimeoutSeconds>
                        <ScanMethods/>
                        <AlertMethods/>
                        <TerminalFirmwareMinVersion/>
                        <TerminalFirmwareMaxVersion/>
                        <TerminalConfigMinVersion/>
                        <TerminalConfigMaxVersion/>
                    </IssuerPolicy>
                </SessionInfo>
            </GetSessionInfoResult>
        </GetSessionInfoResponse>
    </s:Body>
</s:Envelope>
Handling Errors and Failed Requests

Not all requests will be successful, so we will run through a few common errors you should be prepared to handle.

  • No eligible accounts found: This error is returned if there are no eligible accounts in your StartSession. If you receive this error during this workflow, the entity you are using isn't set up properly. A setting change is needed to use this workflow. Please reach out to EPS Ensenta Support for assistance with this setting.
                <ResponseCode>E12</ResponseCode>
                <ErrorResponseText>No eligible account(s) found.</ErrorResponseText>
                <LocalizedMessageText>No eligible account(s) 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 in 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>
  • User Not on AllowList: This error is returned when you try to send a StartSession request with an AccountHolderNumber that is currently not on an allowlist. In order to proceed, add the user to the list and then update the allowlist in EZAdmin.
                <ResponseCode>E78</ResponseCode>
                <ErrorResponseText>You have not been authorized to use this service. Please contact your financial institution for further information.</ErrorResponseText>
                <LocalizedMessageText>We're sorry, you have not been authorized to use this service. Please contact us for further information.</LocalizedMessageText>
  • Session Expired Error: This error is returned when your session times out. To resolve the error, have the user start a new session.
                <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>
  • 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 request, but it does not have a detailed error code. You will need to start 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 the use case scenario for adding a large list of accounts for an end user to make deposits with. Please review the API Reference to see all APIs 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.
  • Get certified and move into production - Ready to put your new code into production use? Refer to this process guide that explains our certification steps and how to contact us to get started.