Phone Session API Guide

This guide provides implementation details to setup a telephonic call session and get the mapped credit card for the credit card entered via the telephone.

Prerequisite

API UsernameProvided by HPCI after the activation of the HPCI account.
API PasskeyPass Keys are created for individual telephone agent Username through the HostedPCI portal.
API URLProvided 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 NameParameter value
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 user based session key, 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.]
  • 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.

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 NameParameter 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=
Required Parameters:
Parameter NameParameter value
userNameAPI username from HostedPCI
userPassKeyAPI passkey from HostedPCI
cmdshowprogress
selectedPcsId7 digit session id that was received when IVR session was created

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 NameParameter 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://<site-specific-api-url>/iSynSApp/manageCCMapPhoneAPI.action?cmd=clearcvv&userName=<userName>&userPassKey=<userPasskey>&selectedPcsId=<sessionId>

Required Parameters:
Parameter NameParameter value
userNameAPI username from HostedPCI
userPassKeyAPI passkey from HostedPCI
cmdclearcvv
selectedPcsId7 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 NameParameter 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 terminate 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 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 NameParameter value
userNameAPI username from HostedPCI
userPassKeyAPI passkey from HostedPCI
cmdterminatesession
selectedPcsId7 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 NameParameter 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.