Terms of Service Guide
Introduction
In this guide, we will walk through how to get the terms of service for the end user to acknowledge using the PAPI3 Multi Flow web service. If you plan to have terms of service hosted by us, follow this guide.
note
Terms are typically only hosted by Ensenta for Consumer Mobile since the Account Holder Number represents the individual while for Business Mobile the Account Holder Number typically represents the Business (meaning for Business Mobile that the terms would only display to the first End-User that logged in with their Account Holder Number). For more information on Account Holder Number, StartSession request.
Getting Started
Tasks covered in this guide
- Send a request for the Terms of Service
- Allow the user to accept the Terms of Service
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 on how to authenticate to the EPS web service. This guide will walk you through sending a StartSession to ensure you are able to authenticate before moving forward.
- Download the PAPI3 Multi Flow WSDL file from the Downloads menu.
Ensenta Mobile API Multi Check Terms of Service Workflow
GetTerms Diagram
Integrator Mobile Deposit Flow | Ensenta API3 Mobile Deposit Flow | ||||
EPS Web Service | |||||
| 1. | |||||
| 2. | |||||
| 3. | |||||
End-user is presented with terms from GetTerms response and presses a button to accept the terms | |||||
| |||||
Verifying That Terms Were Accepted
Step 1 The first task in this process is to aquire some user information and use it to build the StartSession request. For the example code below, the test user has the following information.
- Account Holder Number: 123123123
- Account Holder Name: John Smith
- Username: johnsmith
- Account Number: 56789
- Account Type Code: 0
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>
<Accounts>
<Account>
<AccountNumber>56789</AccountNumber>
<Description>Checking</Description>
<AccountTypeCode>0</AccountTypeCode>
<JointAccountHolderNames></JointAccountHolderNames>
<Tag>0</Tag>
</Account>
</Accounts>
<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. There is a key field that is important for Terms of Service feature.
- IsTermsAcceptanceRequired - If you are using our Terms of Service feature and the user hasn't accepted the Terms, you will receive a value of True in this field.
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>237a6fbb-0e11-4ff9-8882-cb6887025c81</SessionToken>
<SessionStateId>00bd8318-9b36-4ff0-9efc-eb72bb5db793</SessionStateId>
<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 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>
Getting Terms of Service
Step 3 After receiving a value of True for IsTermsAcceptanceRequired, you will need to send a GetTerms request.
GetTerms request example.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns="http://ensenta.com/ECPartnerDepositRequest">
<soap:Header/>
<soap:Body>
<GetTerms>
<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 -8:00 America/Redwood_Shores</TimeZone>
<Attributes>
<Attribute>
<Name></Name>
<Value></Value>
</Attribute>
</Attributes>
<SessionStateId>00bd8318-9b36-4ff0-9efc-eb72bb5db793</SessionStateId>
<SessionToken>237a6fbb-0e11-4ff9-8882-cb6887025c81</SessionToken>
</request>
</GetTerms>
</soap:Body>
</soap:Envelope>
Step 4 Once this request is sent to the endpoint, you should get a successful response. You will receive your Terms of Service that can be displayed to the user.
- TermsXhtml - The Terms of Service that you have setup returned in a Xhtml format.
GetTerms 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">
<GetTermsResponse xmlns="http://ensenta.com/ECPartnerDepositRequest">
<GetTermsResult>
<ResponseCode>00</ResponseCode>
<ErrorResponseText/>
<LocalizedMessageText/>
<TermsXhtml>Example TOS Text</TermsXhtml>
</GetTermsResult>
</GetTermsResponse>
</s:Body>
</s:Envelope>
Accepting Terms of Service
Step 5 After the Terms of Service appear, the user is given the option to accept the terms. When the user accepts the terms, you will need to send an AcceptTerms request.
AcceptTerms request example.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns="http://ensenta.com/ECPartnerDepositRequest">
<soap:Header/>
<soap:Body>
<AcceptTerms>
<request>
<PartnerId>{{partnerId}}</PartnerId>
<LanguageId>9</LanguageId>
<DepositorIpAddress>127.0.0.2</DepositorIpAddress>
<DeviceIdentifier>B23CED0E</DeviceIdentifier>
<LocalDateTime>2020-08-24T11:21:56.603Z</LocalDateTime>
<TimeZone>PST -8:00 America/Redwood_Shores</TimeZone>
<Attributes>
<Attribute>
<Name></Name>
<Value></Value>
</Attribute>
</Attributes>
<SessionStateId>{{sessionStateId}}</SessionStateId>
<SessionToken>{{sessionToken}}</SessionToken>
</request>
</AcceptTerms>
</soap:Body>
</soap:Envelope>
Step 6 Once this request is sent to the endpoint, you should get a successful response. With the terms now accepted, the user can continue to the deposit workflow.
AcceptTerms 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">
<AcceptTermsResponse xmlns="http://ensenta.com/ECPartnerDepositRequest">
<AcceptTermsResult>
<ResponseCode>00</ResponseCode>
<ErrorResponseText/>
<LocalizedMessageText/>
</AcceptTermsResult>
</AcceptTermsResponse>
</s:Body>
</s:Envelope>
Handling Errors and Failed Requests
Not all requests will be successful, so we will need to 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, confirm that the accounts field in the StartSession request isn't empty. If the field isn't empty, please reach out to EPS Ensenta Support to check your account filtering settings.
<ResponseCode>E12</ResponseCode>
<ErrorResponseText>No eligible account(s) found.</ErrorResponseText>
<LocalizedMessageText>No eligible account(s) found.</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>
- 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 in Allow List: 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>
- 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 getting and accepting Terms of Service. 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.