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.

 

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://<site-specific-api-url>/iSynSApp/manageCCMapPhoneAPI.action?cmd=createsession&userName=<userName>&userPassKey=<userPasskey>&promptLang=<promptLang>&cvvEntry=<cvvEntry>&sessionKeyType=<sessionType>&userMarker1=<userIdentifier1>&userMarker2=<userIdentifier2>&userMarker3=<userIdentifier3>
Parameter Name Parameter 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.

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=<createTime>

The individual user ID / pass key combination for the telephone agent in question should be used to create each session. Pass keys can be created for individual telephone agent user ID’s though the HostedPCI portal.

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.

 

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 that interaction on the phone service can be reported periodically. This call 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://<site-specific-api-url>/iSynSApp/manageCCMapPhoneAPI.action?cmd=showprogress&userName=<userName>&userPassKey=<userPassKey>&selectedPcsId=<sessionId>
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

If the call is successful the following return parameters will be provided based on the progress of the session:

status=success&sessionId=<sessionId>&sessionType=ccmap&sessionStatus=complete&sessionKey=<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=<createTime>&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=<ccTokenValue>&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=<createTime>
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://<site-specific-api-url>/iSynSApp/manageCCMapPhoneAPI.action?cmd=clearcvv&userName=<userName>&userPassKey=<userPasskey>&selectedPcsId=<sessionId>
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=<createTime>
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 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 phone 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://<site-specific-api-url>/iSynSApp/manageCCMapPhoneAPI.action?cmd=terminatesession&userName=<userName>&userPassKey=<userPasskey>&selectedPcsId=<sessionId>
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=<createTime>
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.