API Tokenization

Introduction

This guide provides implementation details to tokenize a credit card using an API call. The returned credit card token can be used for any further calls for processing transactions.

Credit card tokenization calls

HostedPCI API provides a two-step(setup and mapping) or single-step (direct) process to convert the credit card to a form compatible token.

The two steps process requires a call to set up a conversion call and then a mapping call to covert the credit card number. The request ID and response from the setup call need to be returned for the tokenization call.

The one-step direct call does not require the setup call and is recommended for most operations.

One Step – Direct Credit Card Tokenization Process

The one-step direct process only requires a single API call to convert the Credit Card number and CVV to HPCI Token.

API Endpoint:
https://< site specific api URL>/iSynSApp/mapCCNumAPI.action?apiVersion=1.0.1&userName=&userPassKey=&apiType=pxyhpci&callMode=direct&ccNum=4111111111111111&ccCVV=123
Parameter List
Parameter Name Parameter Value
Username [API Username]
userPassKey [API Userpasskey]
apiVersion 1.0.1
apiType pxyhpci
callMode direct
ccNum [Credit card number with any spaces and hyphens]
ccCVV Optional [Card verification code (CVV) for the credit card]

If the call is successful the following return parameters will be provided in a URL encoded result set:

Direct Call Successful Response
status=success&callMode=direct&mappedCC=4111000018801111&mappedCVV=200&ccBIN=411111
Response Parameter list
Response Parameter Name Response Parameter Values
status Success | error
callMode map | direct
mappedCC Mapped Credit Card Token for the future use.
mappedCVV Mapped CVV valid for use until the first call with the credit card token or 20 minutes. This value is available only if a valid value for CVV is provided in the map call.
ccBIN First 6 digits of the credit card (BIN Number).

Two-Step – Setup and Mapping Tokenization Process

The two steps process requires a call to set up a conversion call and then a mapping call to covert the credit card number. The request ID and response from the setup call need to be returned for the tokenization call.

Credit Card Conversion Setup call

API Endpoint:
https://< site specific api URL>/iSynSApp/mapCCNumAPI.action?apiVersion=1.0.1&callMode=setup&userPassKey=&userName=&apiType=pxyhpci
Parameter List
Parameter Name Parameter Value
Username [API Username]
userPassKey [API Userpasskey]
apiVersion 1.0.1
apiType pxyhpci
callMode direct

If the setup call is successful the following return parameters will be provided in a URL encoded result set:

Setup Call Successful Response
status=success&callMode=setup&requestId=&requestResp=
Response Parameter list
Response Parameter Name Response Parameter Values
status Success | error
callMode setup
requestID Request ID for Mapping Call
requestResp Request Response for Mapping Call.

After the setup call is successful and request ID and response are available make the mapping call once for every setup call.

Credit Card Mapping Call
API Endpoint:
https://< site specific api URL>/iSynSApp/mapCCNumAPI.action?apiVersion=1.0.1&callMode=map&userPassKey=&userName=&apiType=pxyhpci&ccCVV=123&requestResp=937927&requestId=8718426&ccNum=4111111111111111
Parameter List
Parameter Name Parameter Value
Username [API Username]
userPassKey [API Userpasskey]
apiVersion 1.0.1
apiType pxyhpci
callMode map
ccNum [Credit card number with any spaces and hyphens]
ccCVV Optional [Card verification code (CVV) for the credit card]
requestID [Request ID from setup call if using call mode “map”]
ccCVV [Request response from setup call if using call mode “map”]

If the mapping call is successful the following return parameters will be provided in a URL encoded result set:

Map Call Successful Response
status=success&callMode=map&mappedCC=4111000018801111&mappedCVV=200&ccBIN=411111
Response Parameter list
Response Parameter Name Response Parameter Values
status Success | error
callMode map | direct
mappedCC Mapped Credit Card Token for future use.
mappedCVV Mapped CVV valid for use until the first call
with the credit card token or 20 minutes. This
value is available only if a valid value for CVV
is provided in the map call.
ccBIN First 6 digits of the credit card (BIN Number).