Authentication Guide
Introduction
PAPI3 Multi Flow authentication is handled with a combination of a SessionToken, a SessionStateId, and an x509 certificate. PAPI3 uses these to securely expose two services: Single Sign-On API (PartnerSSORequest3) for authentication and Deposit Request (PartnerDepositRequest3) API for deposits. The x509 certificate is passed over SSL in the StartSession method from the Single Sign-On API to authenticate the session. The response returns a time-sensitive SessionToken and SessionStateID. The SessionToken and SessionStateID are then used in each subsequent request. Incoming requests must support the retention of the SessionStateID and SessionToken.
In support of mutual authentication, the SSL request must have a previously generated x509 certificate attached as part of the http request level, to successfully call this method. The x509 certificate passed to EPS Ensenta will be validated by us as the correct certificate for that Partner ID and environment.
Certificates are not cross compatible between the environments. A certificate is required for both UAT and Prod.
To obtain a certificate, navigate to the Downloads section and download the Mobile Certificate Request zip file. The file contains a certificate request document for UAT and Production, along with instructions on creating the certificate request and installing the certificate. Follow the instructions to create a UAT and Production certificate request. When your requests are created, send them to EPS Tech Integrations. The requests will be used to create the certificates. Once you received the certificates, they will need to be installed before they can be used.
The certificate must be installed on the machine that created the certificate requests before you can distribute it to another machine.
Getting Started
Tasks covered in this guide
- Authenticate a customer in the PAPI3 Multi Flow workflow
Required prerequisites before you continue
- You will need to obtain your UAT PartnerID and certificate in order to try any of the examples in this guide. You should receive these from the Integrations team near the start of your project.
- Download the PAPI3 Multi Flow WSDL file from the Downloads menu.
StartSession Steps and Example
Step 1 Create a request using the PartnerId you received.
Note that the StartSession is comprised of multiple fields. Most of these fields are required for the deposit workflow. For authenticating, the most important field is the PartnerID. The PartnerId indicates which entity you will be trying to connect to.
Step 2 Send the StartSession request along with the certificate you received.
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 3 Log the SessionStateId and SessionToken from the response.
- Note that the response provided multiple fields. Most of the fields are related to the end user and features that will be used during the deposit workflow.
- After receiving a successful response, the end user is authenticated. The reamining requests for this session will use the PartnerID, SessionToken, and SessionStateID until the session ends or expires.
- A session expires after 15 minutes of inactivity. Each successful request refreshes the session.
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>
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>
- User Blocklisted: This error is returned when you try to send a StartSession request with an AccountHolderNumber that is currently on a blocklist. 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 in an allowlist. To proceed, add the user to the list and then update the allowlist on 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 just a starting point to show how to authenticate. 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, you may want to 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.