Overview

The EVO Gift Card service supports closed loop gift card processing for US customers. This service supports Managed (host capture) processing.

Merchants can choose to use EVO Gift Card processing with or without credit card processing. Merchants using gift card processing with credit card processing will be boarded with the batch close options chosen for credit card processing (auto-close or merchant initiated close). Merchants using gift card processing without credit card processing will always be boarded with the auto-close option. There is no end of day process for gift card only processing; auto-close will be performed at 3 AM Eastern.

Supported Transactions

Gift card accounts must be activated as their first transaction. Accounts issued by EVO Gift Card Processing are considered native accounts. Accounts printed by another provider are considered imported accounts. The ManageAccount call with OperationType = “Activate” is used to activate a new gift card with an initial currency value. Once activated, cards may be used until the balance has been spent or until they are deactivated or reissued. When a customer buys a gift card, the clerk will ask for a form of payment for the value added to the card. When a credit card is used for payment:
  • If the gift card is activated first but the credit card payment is not approved, the ManageAccount transaction must be voided using Undo.
  • If the credit card is processed first but the gift card activation fails, the credit card transaction must be voided using Undo.
 

SOAP Example

Header
POST /2.1.33/TPS.svc HTTP/1.0

Host: api.cipcert.local

Content-Type: text/xml; charset=UTF-8

Content-Length: 12661

SOAPAction: "http://schemas.evosnap.com/CWS/v2.0/TransactionProcessing/ICwsTransactionProcessing/ManageAccount"



   
      
         PHNhbWw6QXNzZXJ0aW9uIE1ham9yVmVyc2lvbj0iMSIgTW...mF0dXJlPjwvc2FtbDpBc3NlcnRpb24+
         
            
               Merchant Code 1
               PO Number 1
            
            
               
                  ;5614760018074482170=3912000415?
               
            
            
               100.00
               USD
                2019-12-03T08:23:44 
               1
               Track2DataFromMSR
               Activate
               NotSet
            
         
         {applicationProfileId}
         {merchantProfileId}
         {serviceId}
      
   

 

REST Example

Request Uri https://api.cipcert.local/2.1.33/REST/TPS.svc/{serviceId}
Method POST
 
{
  "$type": "ManageAccount, http://schemas.evosnap.com/CWS/v2.0/Transactions/Rest",
  "Transaction": {
    "$type": "StoredValueTransaction, http://schemas.evosnap.com/CWS/v2.0/Transactions/StoredValue",
    "TenderData": {
      "$type": "StoredValueActivateTenderData, http://schemas.evosnap.com/CWS/v2.0/Transactions/StoredValue",
      "CardData": {
        "Track2Data": ";5614760018074482170=3912000415?"
      }
    },
    "TransactionData": {
      "Amount": 100.00,
      "EmployeeId": "7788",
      "CurrencyCode": "USD",
      "EntryMode": "Track2DataFromMSR",
      "OperationType": "Activate"
    }
  },
  "ApplicationProfileId": "{applicationProfileId}",
  "MerchantProfileId": "{merchantProfileId}"
}
AuthorizeAndCapture is used to subtract an amount from a gift card used for purchases. A sale may include a tip amount. If a tip amount is included, the StoredValueTransaction/Amount field must contain the total amount to be removed from the card, including the tip amount. The StoredValueTransaction/TipAmount field should contain only the tip amount portion of the total authorization.

SOAP Example

Header
POST /2.1.33/TPS.svc HTTP/1.0

Host: api.cipcert.local

Content-Type: text/xml; charset=UTF-8

Content-Length: 12826

SOAPAction: "http://schemas.evosnap.com/CWS/v2.0/TransactionProcessing/ICwsTransactionProcessing/AuthorizeAndCapture"



 
  
   PHNhbWw6QXNzZXJ0aW9uIE1h...c2FtbDpBc3NlcnRpb24+
   
    
     PO Number 4
    
    
     
      ;5614760018074482170=3912000415?
     
    
    
     5.00
     USD
     2019-12-03T08:23:53
     4
     Track2DataFromMSR
     OrderNum4
     NotSet
     NotCapable
    
   
   {applicationProfileId}
   {merchantProfileId}
   {serviceId}
  
 

 

REST Example

Request Uri https://api.cipcert.local/2.1.33/REST/TPS.svc/{serviceId}
Method POST
{
  "$type": "AuthorizeAndCaptureTransaction, http://schemas.evosnap.com/CWS/v2.0/Transactions/Rest",
  "Transaction": {
    "$type": "StoredValueTransaction, http://schemas.evosnap.com/CWS/v2.0/Transactions/StoredValue",
    "TenderData": {
      "CardData": {
        "Track2Data": ";5614760018074482170=3912000415?"
      }
    },
    "TransactionData": {
      "Amount": 5.00,
      "EmployeeId": "7788",
      "CurrencyCode": "USD",
      "EntryMode": "Track2DataFromMSR"
    }
  },
  "ApplicationProfileId": "{applicationProfileId}",
  "MerchantProfileId": "{merchantProfileId}"
}
In the Retail or Restaurant industry types, if the gift card will be used for a tip after an approved AuthorizeAndCapture, Resubmit with ResubmitReason = “TipAdjustment” may be used to process the tip without requiring a second swipe of the card. The ResubmitTransaction/TipAmount is required and must contain the amount of the tip. The ResubmitTransaction/Amount field is optional. It may contain the amount of the tip, the amount of the original authorization, or it may be empty since it is not used for processing. ResubmitTransaction/TipAmount is the value that will be removed from the card when the tip adjustment is processed. Only one tip adjustment will be submitted for an approved AuthorizeAndCapture transaction. If more than one Resubmit is sent, Snap* will reverse the original adjustment and submit a new adjustment. The StoredValueTransactionResponse/NewBalance for the subsequent Resubmit will reflect the result of the reversal and the new Resubmit. Please note that the Tip Adjustment workflow is limited to card present transactions only, and therefore is limited to only the Retail and Restaurant industry types since these are the only industries that utilize this particular workflow. If the tip amount was entered incorrectly, do not Undo the Resubmit TipAdjustment transaction. If a correction is needed, call Resubmit again and enter the correct amount as described above. Undo should only be used to remove the tip amount completely. If a “purchase” is only for a tip, then the StoredValueTransaction/Amount field and the StoredValueTransaction/TipAmount field will contain the same value.  

SOAP Example

Header
POST /2.1.33/TPS.svc HTTP/1.0

Host: api.cipcert.local

Content-Type: text/xml; charset=UTF-8

Content-Length: 12056

SOAPAction: "http://schemas.evosnap.com/CWS/v2.0/TransactionProcessing/ICwsTransactionProcessing/Resubmit"



   
      
         PHNhbWw6QXNzZXJ0aW9...c3NlcnRpb24+
         
            {TransactionId of Sale}
            TipAdjustment
            2.00
         
         {applicationProfileId}
         {serviceId}
      
   

 

REST Example

Request Uri https://api.cipcert.local/2.1.33/REST/TPS.svc/{serviceId}
Method POST
{
  "$type": "ResubmitTransaction, http://schemas.evosnap.com/CWS/v2.0/Transactions/Rest",
  "Transaction": {
    "TransactionId": "{TransactionId of Sale}",
    "ResubmitReason": "TipAdjustment",
    "TipAmount": 2.00
  },
  "ApplicationProfileId": "{applicationProfileId}",
  "MerchantProfileId": "{merchantProfileId}"
}
ManageAccount with OperationType = “Reload” is used to add additional currency value to an existing gift card. The same rules shown above for using credit cards as payment apply to this transaction.

SOAP Example

Header
POST /2.1.33/TPS.svc HTTP/1.0

Host: api.cipcert.local

Content-Type: text/xml; charset=UTF-8

Content-Length: 12611

SOAPAction: "http://schemas.evosnap.com/CWS/v2.0/TransactionProcessing/ICwsTransactionProcessing/ManageAccount"



   
      
         PHNhbWw6QXNzZXJ0aW9...pBc3NlcnRpb24+
         
            
               PO Number 15
            
            
               
                  ;5614760018074482170=3912000415?
               
            
            
               100.00
               USD
               2019-12-03T08:24:23
               15
               Track2DataFromMSR
               Reload
               NotSet
            
         
         {applicationProfileId}
         {merchantProfileId}
         {serviceId}
      
   

 

REST Example

Request Uri https://api.cipcert.local/2.1.33/REST/TPS.svc/{serviceId}
Method POST
{
  "$type": "ManageAccount, http://schemas.evosnap.com/CWS/v2.0/Transactions/Rest",
  "Transaction": {
    "$type": "StoredValueTransaction, http://schemas.evosnap.com/CWS/v2.0/Transactions/StoredValue",
    "TenderData": {
      "CardData": {
        "Track2Data": ";5614760018074482170=3912000415?"
      }
    },
    "TransactionData": {
      "Amount": 100.00,
      "EmployeeId": "7788",
      "CurrencyCode": "USD",
      "EntryMode": "Track2DataFromMSR",
      "OperationType": "Reload"
    }
  },
  "ApplicationProfileId": "{applicationProfileId}",
  "MerchantProfileId": "{merchantProfileId}"
}
QueryAccount is used to retrieve the current balance of a gift card.

SOAP Example

Header
POST /2.1.33/TPS.svc HTTP/1.0

Host: api.cipcert.local

Content-Type: text/xml; charset=UTF-8

Content-Length: 12373

SOAPAction: "http://schemas.evosnap.com/CWS/v2.0/TransactionProcessing/ICwsTransactionProcessing/QueryAccount"



   
      
         PHNhbWw6QXNzZX...3NlcnRpb24+
         
            
               PO Number 22
            
            
               
                  ;5614760018074482170=3912000415?
               
            
            
               2019-12-03T08:24:35
               22
               Track2DataFromMSR
               NotSet
            
         
         {applicationProfileId}
         {merchantProfileId}
         {serviceId}
      
   

 

REST Example

Request Uri https://api.cipcert.local/2.1.33/REST/TPS.svc/{serviceId}
Method POST
{
  "$type": "AuthorizeTransaction, http://schemas.evosnap.com/CWS/v2.0/Transactions/Rest",
  "Transaction": {
    "$type": "StoredValueTransaction, http://schemas.evosnap.com/CWS/v2.0/Transactions/StoredValue",
    "TenderData": {
        "CardData": {
        "Track2Data": ";5614760018074482170=3912000415?"
      }
    },
    "TransactionData": {
      "EmployeeId": "7788",
      "CurrencyCode": "USD",
      "EntryMode": "Track2DataFromMSR"
    }
  },
  "ApplicationProfileId": "{applicationProfileId}",
  "MerchantProfileId": "{merchantProfileId}"
}
ManageAccount with OperationType = “Deactivate” is used to deactivate an active gift card. The IsCashOut field must be set for all deactivation transactions. If the cardholder should receive the card’s remaining balance in cash, set the field to “true”. If a balance is not returned or does not exist, set the field to “false”. The Deactivate transaction cannot be reversed.  

SOAP Example

Header
POST /2.1.33/TPS.svc HTTP/1.0

Host: api.cipcert.local

Content-Type: text/xml; charset=UTF-8

Content-Length: 12510

SOAPAction: "http://schemas.evosnap.com/CWS/v2.0/TransactionProcessing/ICwsTransactionProcessing/ManageAccount"



   
      
         PHNhbWw6QXNzZ...c3NlcnRpb24+
         
            
               Merchant Code 31
               PO Number 31
            
            
               
                  ;5614760018074482170=3912000415?
               
            
            
               2019-12-03T08:25:00
               31
               Track2DataFromMSR
               Deactivate
               NotSet
               true
            
         
         {applicationProfileId}
         {merchantProfileId}
         {serviceId}
      
   

 

REST Example

Request Uri https://api.cipcert.local/2.1.33/REST/TPS.svc/{serviceId}
Method POST
{
  "$type": "ManageAccount, http://schemas.evosnap.com/CWS/v2.0/Transactions/Rest",
  "Transaction": {
    "$type": "StoredValueTransaction, http://schemas.evosnap.com/CWS/v2.0/Transactions/StoredValue",
    "TenderData": {
      "CardData": {
        "Track2Data": ";5614760018074482170=3912000415?"
      }
    },
    "TransactionData": {
      "EmployeeId": "7788",
      "CurrencyCode": "USD",
      "EntryMode": "Track2DataFromMSR",
      "OperationType": "Deactivate",
      "IsCashOut": true
    }
  },
  "ApplicationProfileId": "{applicationProfileId}",
  "MerchantProfileId": "{merchantProfileId}"
}
ManageAccount with OperationType = “BalanceTransfer” may be used to transfer a balance from one card to another. TenderData/SourceData/CardData must contain the card data from which a balance will be removed. TenderData/CardData must contain the card data for the card receiving the balance transfer. Please note that the Balance Transfer transaction type is limited to card present transactions only because this transaction type requires Track 2 Data, and therefore is limited to only the Retail and Restaurant industry types. Also, the Balance Transfer transaction cannot be reversed.  

SOAP Example

Header
POST /2.1.33/TPS.svc HTTP/1.0

Host: api.cipcert.local

Content-Type: text/xml; charset=UTF-8

Content-Length: 12896

SOAPAction: "http://schemas.evosnap.com/CWS/v2.0/TransactionProcessing/ICwsTransactionProcessing/ManageAccount"



   
      
         PHNhbWw6QXNzZXJ...c3NlcnRpb24+
         
            
               Merchant Code 32
               PO Number 32
            
            
               
                  ;5614760018706437196=3912000901?
               
               
                  Provided
                  901
               
               
                  
                     5614760018267778020
                  
               
            
            
               2019-12-04T08:16:56
               32
               Track2DataFromMSR
               BalanceTransfer
               NotSet
            
         
         {applicationProfileId}
         {merchantProfileId}
         {serviceId}
      
   

 

REST Example

Request Uri https://api.cipcert.local/2.1.33/REST/TPS.svc/{serviceId}
Method POST
{ 
   "$type":"ManageAccount, http://schemas.evosnap.com/CWS/v2.0/Transactions/Rest",
   "Transaction":{ 
      "$type":"StoredValueTransaction, http://schemas.evosnap.com/CWS/v2.0/Transactions/StoredValue",
      "TenderData":{
         "$type":"StoredValueBalanceTransferTenderData, http://schemas.evosnap.com/CWS/v2.0/Transactions/StoredValue",
         "SourceData":{ 
            "CardData":{ 
               "AccountNumber":"5614760018267778020"
            }
         },
         "CardData":{ 
            "Track2Data":";5614760018706437196=3912000901?"
         },
         "CardSecurityData":{ 
            "CVDataProvided":"Provided",
            "CVData":"901"
         }
      },
      "TransactionData":{ 
         "EmployeeId":"7788",
         "CurrencyCode":"USD",
         "EntryMode":"Track2DataFromMSR",
         "OperationType":"BalanceTransfer"
      }
   },
   "ApplicationProfileId": "{applicationProfileId}",
  "MerchantProfileId": "{merchantProfileId}"
}
Undo is used to reverse a previous transaction. Activate, Reload, Resubmit, and Sale transactions may be reversed. Balance Inquiry, Deactivate, and Balance Transfer cannot be reversed.  

SOAP Example

Header
POST /2.1.33/TPS.svc HTTP/1.0

Host: api.cipcert.local

Content-Type: text/xml; charset=UTF-8

Content-Length: 11753

SOAPAction: "http://schemas.evosnap.com/CWS/v2.0/TransactionProcessing/ICwsTransactionProcessing/Undo"



   
      
         PHNhbWw6QXNzZX...Bc3NlcnRpb24+
         
            {TransactionId of transaction to be reversed}
         
         {applicationProfileId}
         {serviceId}
      
   

 

REST Example

Request Uri https://api.cipcert.local/2.1.33/REST/TPS.svc/{serviceId}/{TransactionId of transaction to be reversed}
Method PUT
{
  "$type": "Undo, http://schemas.evosnap.com/CWS/v2.0/Transactions/Rest",
  "DifferenceData": {
    "$type": "Undo, http://schemas.evosnap.com/CWS/v2.0/Transactions",
    "TransactionId": "{TransactionId of transaction to be reversed}"
  	},
  "ApplicationProfileId": "{applicationProfileId}"
}

Note: the available balance on a gift card is returned in the StoredValueTransactionResponse/NewBalance field for all transaction types.

Card Verification Data (CVV)

Each EVO generated account has a random 3-digit CVV associated with it. When using a native account number, all transactions except Undo require the CVV unless the DeliberatelyBypass flag is used.

There is no CVResult in the response. If the CVData is missing or incorrect for a native card, the transaction will be declined with StoredValueTransactionResponse/StatusCode = “12”. Transactions may also be declined with StoredValueTransactionResponse/StatusMessage = “INVLD ACCT” if a native account does not include the CVData or one of the bypass values.

Please note that imported cards do not use CVV, and CVV will be ignored if present for those transactions.

Deactivated and Reused Gift Cards

Deactivated cards may be reactivated at any time. A merchant simply treats the deactivated card as if it were new.

A card can be reissued (via Balance Transfer) any time the remaining balance needs to be moved to a new card. Reasons for reissue include, but are not limited to, unreadable magnetic stripe or a lost or stolen card. The old card data must be keyed in and the new card data must be swiped in. The old card is then flagged as dead and may never be reactivated.

Please note that Deactivate and Balance Transfer transactions cannot be voided. Use caution when calling either of these transactions.

Duplicate Transaction Detection and Processing

Duplicate transactions are detected if they occur within 15 minutes of each other and meet one of the following criteria:

  • Same Terminal ID
  • Same Transaction Type
  • Same Account Number
  • Same Transaction Amount
  • Transaction was approved and not voided or reversed

Transactions identified as duplicates will be declined with an error message: StoredValueTransactionResponse/StatusCode will contain “18”; StoredValueTransactionResponse/StatusMessage will contain “AP DUPE”.

Processing a Duplicate Transaction

If the transaction was purposefully resent due to a timeout on the first attempt, the “AP DUPE” error message informs the merchant hat the transaction was received by the EVO host. The merchant should then contact customer support to obtain the original response. If the transaction is approved, then the original transaction was never received by the EVO host.

To process a duplicate transaction, resubmit the declined transaction by setting StoredValueTransaction/TransactionCode to “Override”. This resubmitted transaction should be identical to the original transaction except for the StoredValueTransaction/TransactionCode field. The override flag must be set by the merchant on all other transactions that return the “AP DUPE” response.

Please note that activations, deactivations, and balance transfers cannot be overridden.

 

Daily Transaction Limits

There is a daily transaction activity limit placed on each gift card for risk purposes. It is currently set to seven thousand five hundred dollars ($7,500.00) per 24 hour period. There is also a maximum balance amount on each card currently set to two thousand dollars ($2,000.00). Both of these values are configurable per EVO Client.

 

Partial Approvals

A partial approval transaction enables a merchant to receive approval for a gift card’s balance if that balance is less than the transaction request amount. A split tender transaction results when a partial approval of the total purchase amount is returned to the device in the transaction response. The device must then prompt for payment of the remaining balance due on the sale. The cardholder uses a different form of payment, such as another gift card, a credit card, cash, or a check, to complete the purchase. If the customer is not capable of completing the transaction, the partial approval must be reversed via the Undo method.

Processing a Partial Approval

The StoredValueTransaction/PartialApprovalCapable flag must be set to “Capable” on every AuthorizeAndCapture transaction for which a partial approval will be accepted. Not setting this flag will result in full approvals only, which may result in more declines.

The StatusCode returned for a partially approved transaction is the same as the one returned for a fully approved transaction. The StoredValueTransactionResponse/Amount field will contain the approved amount, and StoredValueTransactionResponse/IsPartialApproval will be set to “true”.

 

Refunds and Returns

Gift card processing does not include a Return transaction. The merchant may choose to refund the customer in cash, or they may process the return as a cash refund and then reload the refunded amount back onto the card, in which case only the Reload transaction would be submitted.

 

ReportingData/Referernce Truncation

For the ReportingData/Reference field, up to 17 upper or lower case letters, numbers, or spaces can be used. Merchants are allowed to send any sort of data they prefer in this field, however Snap* will remove any special characters that exist and will report only the last 17 characters of the string; for example, PO-12345678901234567890 will send out 45678901234567890, and ABC_123/R1C will send out ABC123R1C.

The value that is sent out is the value that is returned to the merchant in the StoredValueTransactionResponse/Reference field.

 

Account Expiration

A pool of accounts can be set to expire. Expiration can occur either on a specific date or on a number of days from an account’s issuance.

 

Response Codes

For information on EVO Gift response codes, please see here.