Phone Session API Guide
- This guide provides implementation details to set up a telephonic call session and get the mapped credit card for the credit card entered via the telephone.
- The HostedPCI token provided back by the IVR can be stored within your system for future use. The token will remain active for 18 months from the last time it is used.
Prerequisite
| PARAMETER NAME | PARAMETER VALUE |
|---|---|
| API Username | Provided by HPCI after the activation of the HPCI account. |
| API Passkey | Pass-Keys are created for individual telephone agent Username through the HostedPCI portal. |
| API URL | Provided by HPCI after the activation of the HPCI account. |
* The individual UserName / PassKey combination of the agent in question should be used to create each session.
Call Session Setup Service
- HostedPCI phone session setup service is called to initiate a session on the online portal so that it can be used by the telephonic call.
- This call should be made only once for every phone call.
A session setup service call to HostedPCI requires the following parameters posted to the URL:
http:///iSynSApp/manageCCMapPhoneAPI.action?cmd=createsession&userName=&userPassKey=&promptLang=&cvvEntry=&sessionKeyType=&userMarker1=&userMarker2=&userMarker3=
| PARAMETER NAME | PARAMETER VALUE |
|---|---|
| apiVersion | 1.0.1 |
| apiType | pxyhpci |
| userName | [API username from HostedPCI] |
| userPassKey | [API passkey from HostedPCI] |
| cmd | [createsession] |
| promptLang | [en_US] |
| cvvEntry | [Default value: request, possible values: request | skip] |
| sessionKeyType | [Default value: user, possible values: user | venue] |
| userMarker1 | [Optional parameter for the user-based session key, the required parameter for venue based session key. Setup user identifying marker for venue based session key to assign sessions handled by a client user.] |
| userMarker2 | [Optional parameter. Setup user identifying marker for venue based session key to assign sessions handled by a client user.] |
| userMarker3 | [Optional parameter. Setup user identifying marker for venue based session key to assign sessions handled by a client user.] |
| ccExpiry | [Default value: skip, possible values: request | skip] |
- The venue-based phone sessions can be created by the phone session API user ID/passkey combination.
- AT least one user marker is necessary to successfully create a venue session and assign the phone session to the user handling the call bridge.
- The API user-id caller handles the responsibility of assigning suitable unique user markers using available user marker fields 1,2, or 3 on the phone session setup API.
- The CVV and Expiry can be collected during the IVR call if the Merchant requires them. To enable this feature please send cvvEntry=request and ccExpiry=request in the API call.
If the call is successful the following return parameters will be provided in a URL encoded result set:
status=success&sessionId=125040&sessionType=ccmap&sessionStatus=open&sessionKey=2034025040&sessionTaskCount=1&sessionTask[1].type=sessionsetup&sessionTask[1].status=created&sessionTask[1].promptCode=created_entersession&sessionTask[1].completionCode=waiting&sessionTask[1].completionCode=waiting&sessionTask[1].exceptionMsg=&sessionTask[1].comment=&sessionTask[1].paramName=&sessionTask[1].paramValue=&sessionTask[1].createTS=
| PARAMETER NAME | PARAMETER VALUE |
|---|---|
| status | [success|error] |
| sessionId | [7 digit session id that is used to identify the IVR session] |
| sessionType | [Ccmap] |
| sessionStatus | [open] |
| sessionKey | [Session key to be entered by the telephone operator over the phone call] |
| sessionTaskCount | [Task count list for the session] |
| sessionTask.type | [sessionsetup| ccmapsetup | cccvvsetup] |
| sessionTask.status | [Created | success | failed] |
| sessionTask.promptCode | [Created_session | created_enterccnum | created_entercccvv] |
| sessionTask.completionCode | [waiting | success | error] |
| sessionTask.exceptionMsg | [Message for the exception] |
| sessionTask.comment | [Comments] |
| sessionTask.createTS | [Create time for the session] |
Call Session Status Service
- HostedPCI phone session status service is called to check the progress of a session so the interaction on the phone service can be reported Periodically.
- This can be invoked multiple times per phone session.
A Session status update service call to HostedPCI requires the following parameters posted to the URL:
http:///iSynSApp/manageCCMapPhoneAPI.action?cmd=showprogress&userName=&userPassKey=&selectedPcsId=
| PARAMETER NAME | PARAMETER VALUE |
|---|---|
| userName | API username from HostedPCI |
| userPassKey | API passkey from HostedPCI |
| cmd | showprogress |
| selectedPcsId | 7 digit session-id that was received when IVR session was created |
Required Parameters:
If the call is successful the following return parameters will be provided based on the progress of the session:
status=success&sessionId=&sessionType=ccmap&sessionStatus=complete&sessionKey= &sessionTaskCount=3&sessionTask[1].type=sessionsetup&sessionTask[1].status=success&sessionTask[1].promptCode=created_entersession&sessionTask[1].completionCode=success&sessionTask[1].completionCode=success&sessionTask[1].respToken1=&sessionTask[1].respToken2=&sessionTask[1].respToken3=&sessionTask[1].exceptionId=&sessionTask[1].exceptionMsg=&sessionTask[1].comment=&sessionTask[1].paramName=&sessionTask[1].paramValue=&sessionTask[1].createTS= &sessionTask[2].type=ccmapsetup&sessionTask[2].status=success&sessionTask[2].promptCode=created_enterccnum&sessionTask[2].completionCode=success&sessionTask[2].completionCode=success&sessionTask[2].respToken1=&sessionTask[2].respToken2=&sessionTask[2].respToken3=&sessionTask[2].exceptionId=&sessionTask[2].exceptionMsg=&sessionTask[2].comment=&sessionTask[2].paramName=mappedcc&sessionTask[2].paramValue= &sessionTask[2].createTS=<>createTime&sessionTask[3].type=cccvvsetup&sessionTask[3].status=success&sessionTask[3].promptCode=created_entercccvv&sessionTask[3].completionCode=success&sessionTask[3].completionCode=success&sessionTask[3].respToken1=100&sessionTask[3].respToken2=&sessionTask[3].respToken3=&sessionTask[3].exceptionId=&sessionTask[3].exceptionMsg=&sessionTask[3].comment=Masked+CVV%3A100&sessionTask[3].paramName=&sessionTask[3].paramValue=&sessionTask[3].createTS=
| PARAMETER NAME | PARAMETER VALUE |
|---|---|
| status | [success|error] |
| sessionid | [7 digit session id that is used to identify the IVR session] |
| sessionType | [Ccmap] |
| sessionStatus | [open|closed|terminate] |
| sessionKey | [Session key to be entered by the telephone operator over the phone call] |
| sessionTaskCount | [Task count list for the session] |
| sessionTask.type | [sessionsetup| ccmapsetup | cccvvsetup] |
| sessionTask.status | [Created | success | failed] |
| sessionTask.promptCode | [Created_session | created_enterccnum | created_entercccvv] |
| sessionTask.completionCode | [waiting | success | error] |
| respToken1 | [Extra details for the response. This field will contain the mapped CVV token for task type cccvvsetup] |
| respToken2 | [Extra details for the response.] |
| respToken3 | [Extra details for the response] |
| sessionTask.exceptionMsg | [Message for the exception] |
| sessionTask.exceptionId | [ID for the exception] |
| sessionTask.comment | [Comments] |
| sessionTask.createTS | [Create time for the session] |
| sessionTask.paramName | [Mappedcc] |
| sessionTask.paramValue | [Tokenized credit card number] |
Clear Call CVV Service
- HostedPCI phone CVV clearing service is called to clear any stored CVV values for the session.
- This call should be made only once for every phone call.
- This call is not required, the CVV will be cleared after it is used for the Authorize or Sale call or at the end of session expiry.
A CVV clearing service call to HostedPCI requires the following parameters posted to the URL:
http:///iSynSApp/manageCCMapPhoneAPI.action?cmd=clearcvv&userName= &userPassKey= &selectedPcsId=
Required Parameters:
| PARAMETER NAME | PARAMETER VALUE |
|---|---|
| userName | API username from HostedPCI |
| userPassKey | API passkey from HostedPCI |
| cmd | clearcvv |
| selectedPcsId | 7 digit session-id that was received when IVR session was created |
If the call is successful the following return parameters will be provided in a URL encoded result set:
status=success&sessionId=125040&sessionType=ccmap&sessionStatus=open&sessionKey=2034025040& sessionTaskCount=1&sessionTask[1].type=sessionsetup&sessionTask[1].status=created& sessionTask[1].promptCode=created_entersession&sessionTask[1].completionCode=waiting& sessionTask[1].completionCode=waiting&sessionTask[1].exceptionMsg=&sessionTask[1].comment=& sessionTask[1].paramName=&sessionTask[1].paramValue=&sessionTask[1].createTS=
| PARAMETER NAME | PARAMETER VALUE |
|---|---|
| status | [success|error] |
| sessionId | [7 digit session id that is used to identify the IVR session] |
| sessionType | [Ccmap] |
| sessionStatus | [open|closed|terminate] |
| sessionKey | [Session key to be entered by the telephone operator over the phone call] |
| sessionTaskCount | [Task count list for the session] |
| sessionTask.type | [sessionsetup| ccmapsetup | cccvvsetup] |
| sessionTask.status | [Created | success | failed] |
| sessionTask.promptCode | [Created_session | created_enterccnum | created_entercccvv] |
| sessionTask.completionCode | [waiting | success | error] |
| sessionTask.exceptionMsg | [Message for the exception] |
| sessionTask.comment | [Comments] |
| sessionTask.createTS | [Create time for the session] |
Terminate Call Session Service
- HostedPCI phone session terminates service is called to terminate the phone session by administrator request.
- The Phone session will be terminated when ‘#’ Key is entered on the phone session.
- This call should be made only once for every call.
- This call is not required, the call can progress to a natural completion.
A session termination service call to HostedPCI requires the following parameters posted to the URL:
http:///iSynSApp/manageCCMapPhoneAPI.action?cmd=terminatesession&userName=&userPassKey=&selectedPcsId=
Required Parameters
| PARAMETER NAME | PARAMETER VALUE |
|---|---|
| userName | API username from HostedPCI |
| userPassKey | API passkey from HostedPCI |
| cmd | terminatesession |
| selectedPcsId | 7 digit session-id that was received when IVR session was created |
If the call is successful the following return parameters will be provided in a URL encoded result set:
status=success&sessionId=125040&sessionType=ccmap&sessionStatus=terminate&sessionKey=2034025040& sessionTaskCount=1&sessionTask[1].type=sessionsetup&sessionTask[1].status=created& sessionTask[1].promptCode=created_entersession&sessionTask[1].completionCode=waiting& sessionTask[1].completionCode=waiting&sessionTask[1].exceptionMsg=&sessionTask[1].comment=& sessionTask[1].paramName=&sessionTask[1].paramValue=&sessionTask[1].createTS=
| PARAMETER NAME | PARAMETER VALUE |
|---|---|
| status | [success|error] |
| sessionid | [7 digit session id that is used to identify the IVR session] |
| sessionType | [Ccmap] |
| sessionStatus | [terminate] |
| sessionKey | [Session key to be entered by the telephone operator over the phone call] |
| sessionTaskCount | [Task count list for the session] |
| sessionTask.type | [sessionsetup| ccmapsetup | cccvvsetup] |
| sessionTask.status | [Created | success | failed] |
| sessionTask.promptCode | [Created_session | created_enterccnum | created_entercccvv] |
| sessionTask.completionCode | [waiting | success | error] |
| sessionTask.exceptionMsg | [Message for the exception] |
| sessionTask.comment | [Comments] |
| sessionTask.createTS | [Create time for the session] |
Phone API Error Codes
The following status or error codes may be returned by HPCI Phone API calls. Errors will be returned in the sessionTask.exceptionMsg field.
Status Codes / Messages
- MCMP_ACT_1 – Session created
- MCMP_ACT_3 – Session cleared, CVV removed from cache on request
Errors Codes / Messages
- MCMP_ACT_2 – Packet replay error
- MCMP_ACT_4 – Phone session not found
- MCMP_ACT_5 – Unknown command
Creating an API Passkey Through the HPCI Portal
To create an individual user passkey, login to the production HPCI portal for the user name in question (the phone agent) and navigate to account Update Passkey
Enter the password of the agent again and click “Generate key”. You will get a success message.
To view the passkey, enter the agent password again and click on “View key”. The key can be stored and used in the application used to generate call sessions through the API for the HostedPCI IVR solution.