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:

  1. API transaction request (For example: ccsale) is submitted with a protegrity token for conversion.

  2. Voltage token will be received in the transaction response.

For more details on the tokenization process, refer a 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 token 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 nameDescriptionRequiredLengthData type
ssl_transaction_typeTransaction type
Value:  ccgettoken
Required20alphanumeric
[Card data]
ssl_tokenCard token
Important:
  • Use only if the terminal is set up with tokenization and token pilot options.
Required20alphanumeric

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