Tokenization and Digital Wallet

 

Tokenization

Tokenization is a value-added service provided free to all of our API consumers.  By tokenizing payment data, EVO Snap reduces the burden of PCI compliance on merchants by eliminating the need to store cardholder account data locally with their commerce solutions.

Tokenization allows the merchant application to store and send only the token, rather than sending consumer account data for new transactions that use the Authorize and AuthorizeAndCapture operations. It should be noted that tokens cannot be used for PIN Debit transactions.

When raw payment data is sent in on a request, the platform encrypts and securely stores the payment data.  A unique token is then returned to the requesting application in the transaction response message, where it can be stored locally with other non-sensitive customer data. The token that has been returned may then be used in subsequent transaction requests for that customer.

To support saved account payments using tokenization, you will need to implement functionality that allows the application to store and retrieve tokens from a customer’s account profile stored in a local application database. The tokens returned from the platform are unique for each customer credit card, which allows a customer to have multiple credit cards associated with their account.

With the addition of Customer Management Service (CMS) endpoint to the platform, you now have the ability to send in your unique Customer ID on a transaction.  The platform will automatically associate any new cards to the customer.

AuthorizeAndCapture with Token
Header POST /2.1.29/REST/TPS.svc/39C6700001 HTTP/1.1
Accept application/json
User-Agent EVO Snap API/1.0
Authorization Basic UEhOaGJXdzZ… Note: This is the session token passed in with each request.
Content-Type application/json; charset=utf-8
Host api.cipcert.goevo.com
Content-Length 2547
Expect 100-continue
 

Request:

{
	"$type": "AuthorizeAndCaptureTransaction, http://schemas.evosnap.com/CWS/v2.0/Transactions/Rest",
	"Transaction": {
		"$type": "BankcardTransactionPro, http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard/Pro",
		"InterchangeData": null,
		"ApplicationConfigurationData": null,
		"TenderData": {
			"CardData": null,
			"CardSecurityData": null,
			"EcommerceSecurityData": null,
			"PaymentAccountDataToken": "d1580ff1-2f80-4acb-bb62-26fd1e58227d8123222c-a7f8-49cf-b6d1-59dd3d6341f5",
			"SecurePaymentAccountData": null,
			"EncryptionKeyId": null,
			"CardholderIdType": "NotSet",
			"SwipeStatus": null,
			"TenderType": "NotSet",
			"DeviceSerialNumber": null,
			"DeviceTypeIndicator": "NotSet",
			"EMVEncryptionKeyId": null,
			"TokenInformation": null,
			"MACEncryptionKeyId": null,
			"VoucherApprovalCode": null,
			"SecureEMVData": null,
			"VoucherNumber": null,
			"SecureMACData": null,
			"VendorId": null,
			"Wallet": null
		},
		"TransactionData": {
			"$type": "BankcardTransactionDataPro, http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard/Pro",
			"ManagedBilling": null,
			"AccountType": "NotSet",
			"AlternativeMerchantData": null,
			"ApprovalCode": null,
			"CashBackAmount": "0.00",
			"CustomerPresent": "Ecommerce",
			"EmployeeId": null,
			"EntryMode": "Keyed",
			"GoodsType": "DigitalGoods",
			"InternetTransactionData": null,
			"InvoiceNumber": null,
			"OrderNumber": "12345",
			"SignatureCaptured": false,
			"TerminalId": null,
			"TipAmount": "0.00",
			"Amount": "10.00",
			"CurrencyCode": "EUR",
			"TransactionDateTime": "2018-08-10T08:11:09.4079816-06:00",
			"Level2Data": null,
			"LineItemDetails": null,
			"PINlessDebitData": null,
			"CampaignId": null,
			"IIASData": null,
			"Reference": null,
			"DiscountData": null,
			"Geolocation": null,
			"BatchAssignment": null,
			"IsPartialShipment": false,
			"FeeAmount": "0.00",
			"LaneId": null,
			"PartialApprovalCapable": "NotSet",
			"ScoreThreshold": null,
			"IsQuasiCash": false,
			"TransactionCode": "NotSet",
			"Is3DSecure": false,
			"CardholderAuthenticationEntity": "NotSet",
			"CardPresence": false,
			"ContractNumber": null,
			"IsQuickPaymentService": false,
			"ProductIndicator": null,
			"EBTType": "NotSet"
		},
		"CustomerData": null,
		"ReportingData": null,
		"Addendum": null,
		"IsOffline": false
	},
	"ApplicationProfileId": "715835",
	"MerchantProfileId": "PracticeOnTestMerchant"
}

Response:

{
	"AdviceResponse": "NotSet",
	"Amount": 10.00,
	"Status": "Successful",
	"CommercialCardResponse": "NotSet",
	"CardType": "MasterCard",
	"StatusCode": "00",
	"ReturnedACI": "NotSet",
	"FeeAmount": 0.00,
	"StatusMessage": "Approved or completed successfully",
	"ApprovalCode": "2O4RAV",
	"TransactionId": "A15C41BE10324CAAA0C9966BB9DADF3A",
	"AVSResult": {
		"ActualResult": "H",
		"AddressResult": "Match",
		"StateResult": "NotSet",
		"CountryResult": "NotSet",
		"PostalCodeResult": "Match",
		"PhoneResult": "NotSet",
		"CardholderNameResult": "NotSet",
		"CityResult": "NotSet"
	},
	"OriginatorTransactionId": "102",
	"BatchId": "",
	"ServiceTransactionId": "102",
	"CVResult": "NotSet",
	"ServiceTransactionDateTime": {
		"Date": "2016-10-19",
		"Time": "14:42:48.184",
		"TimeZone": "+00:00"
	},
	"CardLevel": "",
	"Addendum": null,
	"DowngradeCode": "",
	"CaptureState": "Captured",
	"MaskedPAN": "549999XXXXXX6781",
	"TransactionState": "Captured",
	"PaymentAccountDataToken": "a15c41be-1032-4caa-a0c9-966bb9dadf3a719fe997-1f33-4da4-b34b-9758c50dd4fe",
	"IsAcknowledged": false,
	"RetrievalReferenceNumber": "7Z7BV3V5ZSRS7QRXGP6W5W0CX7TC78E8",
	"Reference": "25",
	"Resubmit": "NotSet",
	"TransmissionNumber": "",
	"SettlementDate": "2016-10-19T00:00:00",
	"TransactionCode": "",
	"FinalBalance": 0.00,
	"HostMessageId": "",
	"OrderId": "3",
	"CashBackAmount": 0.00,
	"PrepaidCard": "NotSet",
	"Expire": "1225",
	"ErrorType": null,
	"AuthorizationServerUrl": "",
	"PaymentAuthorizationRequest": "",
	"ProcessedAs3D": false,
	"EMVDataResponse": null,
	"Level3Added": "NotSet",
	"LastPANDigits": "",
	"BatchAmount": 0.00,
	"MessageAuthenticationCode": "",
	"TokenInformation": null,
	"ForcePostCode": "",
	"MerchantId": "123456789012",
	"TerminalId": "10203040"
}
AuthorizeAndCapture with Token
Header POST /2.1.30/TPS.svc HTTP/1.1
Content-Type text/xml; charset=utf-8
SOAP-Action "http://schemas.evosnap.com/CWS/v2.0/TransactionProcessing/ICwsTransactionProcessing/AuthorizeAndCapture"
Host api.cipcert.goevo.com
Expect 100-continue
Accept-Encoding gzip, deflate
Content-Length 10866
 

Request:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <AuthorizeAndCapture xmlns="http://schemas.evosnap.com/CWS/v2.0/TransactionProcessing">
      <sessionToken><strong>PHNhbWw6QXNzZ…</strong></sessionToken>
      <transaction i:type="b:BankcardTransactionPro" xmlns:a="http://schemas.evosnap.com/CWS/v2.0/Transactions" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:b="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard/Pro"> 
        <a:CustomerData> 
          <a:BillingData i:nil="true" /> 
          <a:CustomerId>123543</a:CustomerId> 
          <a:CustomerTaxId i:nil="true" /> 
          <a:ShippingData i:nil="true" /> 
        </a:CustomerData> 
        <a:ReportingData i:nil="true" /> 
        <a:Addendum i:nil="true" /> 
        <a:IsOffline>false</a:IsOffline> 
        <ApplicationConfigurationData i:nil="true" xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard" /> 
        <TenderData i:type="b:BankcardTenderDataPro" xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard"> 
          <a:PaymentAccountDataToken>d1580ff1-2f80-4acb-bb62-26fd1e58227d8123222c-a7f8-49cf-b6d1-59dd3d6341f5</a:PaymentAccountDataToken> 
          <a:SecurePaymentAccountData i:nil="true" /> 
          <a:EncryptionKeyId i:nil="true" /> 
          <a:SwipeStatus i:nil="true" /> 
          <a:DeviceSerialNumber i:nil="true" /> 
          <a:EMVEncryptionKeyId i:nil="true" /> 
          <a:MACEncryptionKeyId i:nil="true" /> 
          <a:SecureEMVData i:nil="true" /> 
          <a:SecureMACData i:nil="true" /> 
          <a:VendorId i:nil="true" /> 
          <a:Wallet i:nil="true" /> 
          <CardData i:nil="true" /> 
          <CardSecurityData i:nil="true" /> 
          <EcommerceSecurityData i:nil="true" /> 
          <CardholderIdType>NotSet</CardholderIdType> 
          <TenderType>ProcessAsCredit</TenderType> 
          <DeviceTypeIndicator>NotSet</DeviceTypeIndicator> 
          <TokenInformation i:nil="true" /> 
          <VoucherApprovalCode i:nil="true" /> 
          <VoucherNumber i:nil="true" /> 
          <b:EMVData i:nil="true" /> 
        </TenderData> 
        <TransactionData i:type="b:BankcardTransactionDataPro" xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard"> 
          <a:Amount>10.00</a:Amount> 
          <a:CurrencyCode>USD</a:CurrencyCode> 
          <a:TransactionDateTime>2019-01-03T09:44:19.718-07:00</a:TransactionDateTime> 
          <a:CampaignId i:nil="true" /> 
          <a:Reference i:nil="true" /> 
          <a:DiscountData i:nil="true" /> 
          <a:Geolocation i:nil="true" /> 
          <AccountType>NotSet</AccountType> 
          <AlternativeMerchantData i:nil="true" /> 
          <ApprovalCode i:nil="true" /> 
          <CashBackAmount>0</CashBackAmount> 
          <CustomerPresent>Ecommerce</CustomerPresent> 
          <EmployeeId>1234</EmployeeId> 
          <EntryMode>Keyed</EntryMode> 
          <GoodsType>NotSet</GoodsType> 
          <InternetTransactionData i:nil="true" /> 
          <InvoiceNumber i:nil="true" /> 
          <OrderNumber>123543</OrderNumber> 
          <SignatureCaptured>true</SignatureCaptured> 
          <TerminalId i:nil="true" /> 
          <TipAmount>0</TipAmount> 
          <BatchAssignment i:nil="true" /> 
          <IsPartialShipment>false</IsPartialShipment> 
          <FeeAmount>0</FeeAmount> 
          <LaneId>1</LaneId> 
          <PartialApprovalCapable>NotSet</PartialApprovalCapable> 
          <ScoreThreshold i:nil="true" /> 
          <IsQuasiCash>false</IsQuasiCash> 
          <TransactionCode>NotSet</TransactionCode> 
          <Is3DSecure>false</Is3DSecure> 
          <CardholderAuthenticationEntity>NotSet</CardholderAuthenticationEntity> 
          <CardPresence>false</CardPresence> 
          <ContractNumber i:nil="true" /> 
          <IsQuickPaymentService>false</IsQuickPaymentService> 
          <ProductIndicator i:nil="true" /> 
          <EBTType>NotSet</EBTType> 
          <CardOnFileInfo i:nil="true" /> 
          <b:ManagedBilling i:nil="true" /> 
          <b:LineItemDetails i:nil="true" /> 
          <b:PINlessDebitData i:nil="true" /> 
          <b:IIASData i:nil="true" /> 
        </TransactionData> 
        <b:InterchangeData> 
          <b:BillPayment>NotSet</b:BillPayment> 
          <b:RequestCommercialCard>Enable</b:RequestCommercialCard> 
          <b:ExistingDebt>NotSet</b:ExistingDebt> 
          <b:RequestACI>NotSet</b:RequestACI> 
          <b:TotalNumberOfInstallments>0</b:TotalNumberOfInstallments> 
          <b:CurrentInstallmentNumber>0</b:CurrentInstallmentNumber> 
          <b:RequestAdvice>NotSet</b:RequestAdvice> 
          <b:InstallmentDetails i:nil="true" xmlns:c="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard" /> 
        </b:InterchangeData> 
      </transaction> 
<applicationProfileId>715973</applicationProfileId>
      <merchantProfileId>987654321605 </merchantProfileId>
      <workflowId>39C6700001</workflowId>
    </AuthorizeAndCapture>
  </s:Body>
</s:Envelope>
 
Note: the entity sessionToken is the session token passed in with each request.
 

Response:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <AuthorizeAndCaptureResponse xmlns="http://schemas.evosnap.com/CWS/v2.0/TransactionProcessing">
      <AuthorizeAndCaptureResult i:type="b:BankcardTransactionResponsePro" xmlns:a="http://schemas.evosnap.com/CWS/v2.0/Transactions" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:b="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard/Pro">
        <a:Status>Successful</a:Status>
        <a:StatusCode>1</a:StatusCode>
        <a:StatusMessage>APPROVED</a:StatusMessage>
        <a:TransactionId>055E38B9F2F54E5E9E11BFBF8A5F0CA4</a:TransactionId>
        <a:OriginatorTransactionId>959</a:OriginatorTransactionId>
        <a:ServiceTransactionId>49395880</a:ServiceTransactionId>
        <a:ServiceTransactionDateTime>
          <a:Date>2019-01-03</a:Date>
          <a:Time>17:04:41.337</a:Time>
          <a:TimeZone>-06:00</a:TimeZone>
        </a:ServiceTransactionDateTime>
        <a:Addendum i:nil="true" />
        <a:CaptureState>Captured</a:CaptureState>
        <a:TransactionState>Captured</a:TransactionState>
        <a:IsAcknowledged>false</a:IsAcknowledged>
        <a:Reference />
        <a:TransmissionNumber />
        <a:TransactionCode />
        <a:HostMessageId />
        <a:Geolocation i:nil="true" />
        <Amount xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard">10.00</Amount>
        <CardType xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard">Visa</CardType>
        <FeeAmount xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard">0.00</FeeAmount>
        <ApprovalCode xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard">3JIQN1</ApprovalCode>
        <AVSResult xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard">
          <ActualResult>0</ActualResult>
          <AddressResult>NotVerified</AddressResult>
          <CountryResult>NotSet</CountryResult>
          <StateResult>NotSet</StateResult>
          <PostalCodeResult>NotVerified</PostalCodeResult>
          <PhoneResult>NotSet</PhoneResult>
          <CardholderNameResult>NotSet</CardholderNameResult>
          <CityResult>NotSet</CityResult>
        </AVSResult>
        <BatchId xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard">1903</BatchId>
        <CVResult xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard">NotProcessed</CVResult>
        <CardLevel xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard" />
        <DowngradeCode xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard" />
        <MaskedPAN xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard">411111XXXXXX1111</MaskedPAN>
        <PaymentAccountDataToken xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard">d1580ff1-2f80-4acb-bb62-26fd1e58227d8123222c-a7f8-49cf-b6d1-59dd3d6341f5</PaymentAccountDataToken>
        <RetrievalReferenceNumber xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard">117150900047</RetrievalReferenceNumber>
        <Resubmit xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard">NotSet</Resubmit>
        <SettlementDate xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard">0001-01-01T00:00:00</SettlementDate>
        <FinalBalance xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard">0.00</FinalBalance>
        <OrderId xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard">728</OrderId>
        <CashBackAmount xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard">0.00</CashBackAmount>
        <PrepaidCard xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard">NotSet</PrepaidCard>
        <Expire xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard">1218</Expire>
        <ErrorType i:nil="true" xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard" />
        <AuthorizationServerUrl xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard" />
        <PaymentAuthorizationRequest xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard" />
        <ProcessedAs3D xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard">false</ProcessedAs3D>
        <EMVDataResponse i:nil="true" xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard" />
        <Level3Added xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard">NotSet</Level3Added>
        <BatchAmount xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard">0.00</BatchAmount>
        <LastPANDigits xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard">1111</LastPANDigits>
        <MessageAuthenticationCode xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard" />
        <TokenInformation i:nil="true" xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard" />
        <ForcePostCode xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard" />
        <MerchantId xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard">123456789012</MerchantId>
        <TerminalId xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard">987654321605</TerminalId>
        <BankResponseCode xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard" />
        <InitialEncryptionKeys i:nil="true" xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard" xmlns:c="http://schemas.evosnap.com/CWS/v2.0/Transactions/Encryption" />
        <IsPartialApproval xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard">false</IsPartialApproval>
        <EBTAvailableBalance xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard">
          <CashAvailableBalance>0.00</CashAvailableBalance>
          <SNAPAvailableBalance>0.00</SNAPAvailableBalance>
        </EBTAvailableBalance>
        <IndustryType xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard">Retail</IndustryType>
        <ThreeDSecureInformation i:nil="true" xmlns="http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard" />
        <b:AdviceResponse>NotSet</b:AdviceResponse>
        <b:CommercialCardResponse>NotSet</b:CommercialCardResponse>
        <b:ReturnedACI>NotSet</b:ReturnedACI>
      </AuthorizeAndCaptureResult>
    </AuthorizeAndCaptureResponse>
  </s:Body>
</s:Envelope>
 

 

Digital Wallet/Tokenized Payments

(**Last updated: 15 July 2020)
A digital wallet, also called an e-wallet, refers to a service that securely stores a cardholder’s payment information and allows that cardholder to submit payments using services like Apple Pay or Android Pay. Wallet payments are often submitted through a mobile phone app but may also exist in a variety of other formats or on a personal computer.

To process digital wallet/tokenized payments through the EVO Snap* platform, the following information must obtained from the wallet service and be submitted in TenderData/TokenInformation. This data will replace the TenderData/CardData values for the transaction.

  • TenderData/TokenInformation/Token (PAN-like value returned by the wallet service that replaces the card’s PAN)
  • TenderData/TokenInformation/TokenExpirationDate (the token’s expiration date returned by the service, in MMYY format)
  • TenderData/TokenInformation/TokenIndicator (3 digit value like 103, 216, or CTP – this is the Wallet Id returned by the service)
    • TokenIndicator is required if there is no 3DS authentication data being submitted BankcardTransaction/BankcardTenderData/EcommerceSecurityData/
  • TenderData/TokenInformation/TokenCardType (Visa, MasterCard, etc.)
  • TenderData/TokenInformation/TokenAuthenticationValue (the MasterCard cryptogram/Visa TAVV value returned by the service)
  • TenderData/TokenInformation/WalletECI – Required for MasterCard
    • MasterCard service will return and ECI of “02” or “01”; if it is not received from the wallet service, an “02” must be sent