Token conversion
Token conversion is a process of migrating protegrity format tokens of the cards to a new token service provider format called voltage.
Important: Used only if the terminal is set up with tokenization and token pilot options.
Merchant hosted tokens
There are three different ways for token conversion if you are hosting the tokens on your servers and not using the Converge Customers feature:
- API
- Converge UI
- Offline
API
Here are the following steps for the token conversion via API for existing merchants:
API transaction request (For example: ccsale) is submitted with a protegrity token for conversion.
Voltage token will be received in the transaction response.
For more details on the tokenization process, refer open_in_newa guide to payment tokenization for pilot merchantsLink opens new window support article.
Converge UI (Batch import process)
Merchant hosted card tokens can be converted and uploaded using the upload tokens feature available on Converge Payments UI.
important
- Non-pilot merchants upload their protegrity tokens using the upload tokens button when generate tokens is selected from the new payments drop-down menu. But the voltage tokens will not be displayed on the complete imported details and cannot be downloaded so they will use only protegrity tokens for uploading.
- For pilot merchants, the upload tokens button will not be visible when generate tokens is selected from the new payments drop-down menu so as to avoid uploading voltage tokens. But the voltage tokens will be displayed on the complete imported details and the downloads.
For more details on the tokens conversion process, refer to the open_in_newtoken conversionLink opens new window support article.
The tokens to be converted can be imported in a batch file using XML/CSV format.
XML format
The format of an XML batch file is as follows:
- The file contains a single
<txns>
element and multiple<txn>
(transaction) nested elements. - Every transaction is a set of XML tags.
- The number of
<txn>
corresponds to the number of transactions in the file. - All elements must be closed in the order that these were opened.
Example
<txns>
<txn>
<ssl_transaction_type>ccgettoken</ssl_transaction_type>
<ssl_token>8143146846014317</ssl_token>
</txn>
<txn>
<ssl_transaction_type>ccgettoken</ssl_transaction_type>
<ssl_token>85933057734836439</ssl_token>
</txn>
</txns>
CSV format
The format of a CSV batch file is as follows:
- Header
- First line of the file.
- Contains all the field names.
- Each field name is enclosed within double quotes and followed by a comma.
- Transaction Data
- Starts after the header line.
- Each transaction data is placed on a single line.
- Each transaction data is enclosed within double quotes and followed by a comma.
- The transaction data is placed in the same order of the field names.
Example
"ssl_transaction_type","ssl_token"
"ccgettoken","0000000000000000"
Fields
Field name | Description | Required | Length | Data type |
---|---|---|---|---|
ssl_transaction_type | Transaction type Value: ccgettoken | Required | 20 | alphanumeric |
[Card data] | ||||
ssl_token | Card token Important:
| Required | 20 | alphanumeric |
Converted tokens format
The converted tokens can be downloaded in either CSV or XML formats. Here is a XML format sample of the converted token values.
<?xml version='1.0' encoding='UTF-8'?>
<txnimportresponse responseFileName='example.xml' fileType='Convert Tokens' userID='user123' terminalName='Token Terminal' sortedBy='rowNumber' createdOn='09/15/2022 11:36:54 AM'>
<txn>
<item>1</item>
<tranType>gettoken</tranType>
<tokenValue>8143146846014317</tokenValue>
<voltageTokenValue/>
<tokenResponse>FAILURE</tokenResponse>
<result>Error</result>
<message>Invalid token</message>
</txn>
<txn>
<item>2</item>
<tranType>gettoken</tranType>
<tokenValue>85933057734836439</tokenValue>
<voltageTokenValue>5496743307546439</voltageTokenValue>
<tokenResponse>SUCCESS</tokenResponse>
<result>Success</result>
<message></message>
</txn>
</txnimportresponse>
Offline
Please contact your Relationship Manager or Elavon Software Technical Support for more information.
Converge hosted tokens (customers card list)
Converge automatically converts all of your protegrity tokens to voltage tokens and saves them to the Converge customers card list. The newly converted tokens can be retrieved using the following options:
- Transaction response
- Converge UI
- Token query
Transaction response
If ssl_get_token
is used in the request, then the token and token type will be received in your response using the fields ssl_token
and ssl_token_provider
.
Converge UI
You can retrieve information regarding the token and the token provider by downloading the reports from the card list view of the Converge customers feature.
Token query
The voltage token can be retrieved using token query - ccquerytoken