Token Request

Tokenization is a powerful security that allows a merchant to support all of their existing business processes that require card data without the risk of holding card data and without any security implications therefore protecting the customers' confidential information. Tokenization substantially reduces the liability and costs associated with PCI compliance, and eliminates the risk of storing sensitive data.

Merchants set up for the tokenization service receive responses that include a token, if requested. The generated token is linked to a specific card number and not to a transaction. Furthermore, you can generate a token and save the token with associated information in Card Manager.

Card Manager enables merchants to tokenize and store sensitive payment information on Elavon's secure servers, simplifying their PCI-DSS compliance and payment processing for returning customers. Card Manager allows access to all tokens that have been generated from your integrated application or directly added to the integrated application.

Code Samples

CWS

Request

parameters
JSONObject | required
All relevant parameters for tokenization.
 
generateToken
boolean | optional
Generate Token Indicator
Indicates whether to tokenize or not the card number.
Valid values:
  • true
  • false (Default)
addToken
boolean | optional
Store Token Indicator
Indicates whether to store or not the token in Card Manager.
Valid values:
  • true
  • false (Default)

Response

data
JSONObject
Object holding various responses.
 
tokenizedCard
boolean
Token
Token generated for the card number.

Example

Request
{
  "method" : "startPaymentTransaction",
  "requestId" : "355383921",
  "targetType" : "paymentGatewayConverge",
  "version" : "1.0",
  "parameters" : {
    "paymentGatewayId" : "be02a77b-16f4-4bf7-98c3-fca61f9cb564",
    "transactionType" : "SALE",
    "tenderType" : "CARD",
  .....
    "generateToken" : true, 
    "addToken" : true,
  .....
  }
}
Response
{
  "requestId" : "355383949",
  "statusDetails" : "REQUEST_ACCEPTED",
  "data" : {
    "paymentGatewayCommand" : {
      "completed" : true,
      "eventQueue" : [ ],
      "chanId" : "55b28627-c74f-404f-be38-e883afc44a31",
      "paymentTransactionData" : {
        "result" : "APPROVED",
        "authCode" : "******",
        "resultMessage" : "APPROVED",
        "date" : "Mon Mar 07 11:12:53 MST 2016",
        "cardEntryType" : "SWIPE",
        "cardScheme" : "VISA",
        "amount" : {
          "currencyCode" : "USD",
          "value" : 2400
        },
        "id" : "070316D3A-EC405BF4-B2E5-4BEB-AF3A-58A93F74D85A",
        "transactionType" : "SALE",
        "approved" : "yes",
        "errors" : [ ],
        "maskedPan" : "******",
        "tokenizedCard" : "7643828574404243",
        "gratuityAmount" : {
          "currencyCode" : "USD",
          "value" : 0
        },
        "signatureBitmap" : {
          "data" : "`!*Q  (  !  0 _' _/ _& _& _'___ _&_____^ _'_____^________^_____^_________ _'_________ _'______ _' _/  )  0  (  (  (  (  )  (  (  (  0  (  (  (  (  (  (  (  ( _/  (  (  (  (  (p`%(+ _'_ X _'_ Y _'___ _'  ( _'  ( _'  ) _/  (  (  )  (  (  (  (  1  (  (  (  ) _'  )p`'*._ X _/ _' _' _' _' _' _' _' _' _' _' _&___ _' _& _' _& _' _& _'__^ _' _& _' _' _& _' _' _& _' _' _' _' _' _' _' _'p`)%0 _'  ! _'  !  (  )p`-)0______ _'_ X______ _'_____^ _'___ _' _'___ _' _' _' _' _/ _/  ( _/  0  )  (  )  (  1  )  )  )  1  *  )  )  *  !  *  !  \"  !  !  \"_ Y  \"_ X_ Y_ Y_ Y_ X_ Y_ X_ X_ X__Wp`1):_ X _'_ X____ X____ X___ _'_ X_________________^___ _' _/ _' _/ _/  0  (  (  0  0  )  0  1  1  0  )  1  )  1  *  )  )  \"  *  )  !  \"  \"  \"_ Y  \"_ Z  !_ R_ Y_ Y_ Y_ Q_ Y_ Qp",
          "format" : "SIG_BIN_2"
        },
        "tenderType" : "CARD",
        "balanceDue" : {
          "currencyCode" : "UNKNOWN",
          "value" : 0
        }
      }
    }
  }
}

Java

...
// we want a token to be generated
tender.setGenerateToken(true);

// If we want the token to be available with Card/Customer Manager in the Converge web site, set this to true. 
// Otherwise a token will still be generated and returned but will not be stored on server.
tender.setAddToken(true);
...
account.getTransactionProcessor().processTransaction(transaction, tender, transactionListener);
...
// When your transaction listener gets a transactionCompleted callback, you'll be able to get the token from it like this:
if (outcome instanceof ECLCardTransactionOutcome)
{
     ECLCardTransactionOutcome cardOutcome = (ECLCardTransactionOutcome)outcome;
     if (cardOutcome.getToken() != null && cardOutcome.getToken().length() > 0)
     {
         System.out.println("My cool token: " + cardOutcome.getToken());
     }
}

Objective-C

The following will show how to enable token generation and saving of token by setting certain properties on the card tender protocol. Using the same code from the Sale transaction with a card tender, the only addition we need to do before processing the transaction is:

/* If we want commerce to return a token we always have to set this to YES */
token.generateToken = YES;

/* If we want the token to be available with Card/Customer Manager in the Converge web site, you have to set this to YES. If this is NO, token will still be generated and returned but will not be stored on server */
token.addToken = YES;

When the transaction succeeds and your ECLTransctionProcessingDelegate::transactionDidSucceed method is called, the "outcome" parameter will be an instance of ECLCardTransactionOutcome and you can get the token from that.

if ([outcome isKindOfClass:[ECLCardTransactionOutcome class]]) {
    ECLCardTransactionOutcome *cardOutcome = (ECLCardTransactionOutcome *)outcome;
    NSString *generatedToken = cardOutcome.token;
}

C#

Request

PaymentArgs bea = new PaymentArgs();
...
bea.generateToken = true;
bea.addToken = false; /* Set to true if you want the token to be available for use with Card/Customer Manager in the Converge web site */
...
m_CWS.StartPaymentTransaction(bea, MyNotifyCWSEvent, MyPaymentComplete);

Response

public void MyPaymentComplete(PaymentTransactionResults ber)
{
    PaymentTransactionData betd = ber.PaymentTransactionData; 
    if (null != betd) 
    {
        if ((null != betd.tokenizedCard) && (0 < betd.tokenizedCard.Length))
            SaveToken(betd.tokenizedCard);

...