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). |