EVO Account Updater

  1. Home
  2. Commerce Web Services
  3. Workflows
  4. Value Added Services
  5. EVO Account Updater

Overview

EVO Account Updater works to ensure that the card data on file is the most up to date and accurate, helping reduce merchant risk of losing revenue. This service will assist merchants in updating account information without the time-consuming task of reaching out to customers to manually update account information stored on file. By updating subscription tokens automatically, scaling and throttling account updates, creating efficient infrastructure for easy Wallet account management, and supporting Visa, MasterCard, and Discover card types, EVO Account Updater makes updating and keeping track of card data a Snap*!

A quick start guide is available for download with more information. Download here.

How it Works

For merchants using the Snap* Platform Subscription Service and Snap* Tokenization:

If the merchant is using the EVO Snap* platform subscription service, the Snap* Account Updater Internal Service is launched once a day to trigger a CMS query for wallet/subscription tokens for payments that are going to be processed within the next three days. From that information, card data is assembled and then passed through the Account Management Service (AMS) to the supported card networks to check that the card data is valid. Finally, EVO sends back an encrypted response file containing the updated card information.

Some merchants use their own applications to handle their subscription or recurring payments processing, and thus can choose to use Snap* tokenization as part of this processing or not.

For merchants using Snap* Tokenization Only and their own billing engine:

If a merchant decides to use their own software application to manage recurring payments and use the Snap* platform to support tokenization, the merchant application will compile a list of wallet/subscription tokens. The merchant will then pass those tokens to the Snap* platform, which uses AMS to check that the tokens are accurate and up to date. Then, a file with the updated account data information is created, which the merchant application can retrieve.

For merchants storing Card Data and leveraging their own billing engine:

If a merchant chooses to use neither the Snap* platform subscription service nor Snap* tokenization, the merchant can send the information for an account update request as a list of card data, which the Snap* platform can process and return as a list of updated card data

Integration

  1. Merchants will first enroll in EVO Account Manager with their EVO Relationship Manager.
    Note: Merchants must enroll in all three supported card brands (Visa, MasterCard, and Discover) in order to utilize the Account Updater service.
  2. Once merchants are enrolled, EVO boarding systems will push their unique Account Updater Merchant IDs to the Snap* platform automatically.
  3. Merchants develop their code and will work with EVO Implementation Support as needed to resolve outstanding issues or questions, and once they are ready to test their code and connectivity, they can begin testing via their given certification environment.
    Note: No testing is to be done in the Production environment.
  4. Once all parties are satisfied that the requirements for certification have been met and successfully tested, a Production environment is set up. Notification is sent to the merchant once the Production environment is ready for use.
  5. When Snap* receives an Account Updater request from a merchant, the platform uses the credentials that were assigned and pushed from the enrollment process.
    • There is a limit of once per day for Account Updater requests. Requests submitted after 7 AM MST will be included in the next day’s request.

API Reference

Note: This section only applies to merchants who are using their own recurring billing engine.

REST API Reference

UploadAccountUpdaterRequestFile
RequestUri https://api.cipcert.goevo.com/2.1.29/REST/DataServices/AMS.svc/Upload?merchantProfileId= &AUServiceId=&fileFormat=
Method POST
Note:
  • FileFormat needs to be set based on the format and content of the file being uploaded:
    • If the file is raw card data in XML format, FileFormat must be set to “AccountData”
    • If the file is encrypted tokens in XML format, FileFormat must be set to “SnapToken”
    • If the file is raw card data in JSON format, FileFormat must be set to “AccountDataJson”
    • If the file is encrypted tokens in JSON format, FileFormat must be set to “SnapTokenJson”
 

Sample Request:



  
    
      0000000000
      5657646586846813
      1215
      MasterCard
      MerchantId1
    
    
      0000000001
      4273253134375833
      1215
      Visa
      MerchantId1
    
    
      0000000002
      6739475637815659
      1215
      Discover
      MerchantId1
    
    .
    .
    .
    
      0000000499
      6725563870129679
      1215
      Discover
      MerchantId2
    
  
  
    1500
    
      
         xyz
         MerchantId1
         1000
      
      
         xyz
         MerchantId2
         500
      
    
    
      
        MasterCard
        883
      
      
        Visa
        322
      
      
        Discover
        295
  
{
              "Summary" : {
                                "MerchantSummaries" : [{
                                                          "MerchantProfileId" : "MerchantId1",
                                                          "TotalItems" : 5
                                                }
                                ],
                                "CardTypeSummaries" : [{
                                                          "TotalItems" : 3,
                                                          "CardType" : "MasterCard"
                                                }, {
                                                          "TotalItems" : 1,
                                                          "CardType" : "Visa"
                                                }, {
                                                          "TotalItems" : 1,
                                                          "CardType" : "Discover"
                                                }
                                ],
                                "TotalItems" : 5
                },
                "Data" : [{
                                                "AccountExpiration" : "1119",
                                                "MerchantReferenceId" : 0000000000,
                                                "AccountNumber" : "5315424430768215",
                                                "MerchantProfileId" : "MerchantId1",
                                                "CardType" : "MasterCard"
                                }, {
                                                "AccountExpiration" : "1221",
                                                "MerchantReferenceId" : 0000000001,
                                                "AccountNumber" : "4875691479823331",
                                                "MerchantProfileId" : "MerchantId1",
                                                "CardType" : "Visa"
                                }, {
                                                "AccountExpiration" : "0420",
                                                "MerchantReferenceId" : 0000000002,
                                                "AccountNumber" : "6712654065840296",
                                                "MerchantProfileId" : "MerchantId1",
                                                "CardType" : "Discover"
                                },{
                                                "AccountExpiration" : "0622",
                                                "MerchantReferenceId" : 0000000003,
                                                "AccountNumber" : "2649126955256078",
                                                "MerchantProfileId" : "MerchantId1",
                                                "CardType" : "MasterCard"
                                }, {
                                                "AccountExpiration" : "0122",
                                                "MerchantReferenceId" : 0000000004,
                                                "AccountNumber" : "2263659360861463",
                                                "MerchantProfileId" : "MerchantId1",
                                                "CardType" : "MasterCard"
                                }
                ]              
}
  


  
    3
    
      
        MyServiceKey
        MerchantId1
        3
      
    
    
      
        Visa
        3
      
    
  
  
    
       0000000001
       c61b1dcb-9c6b-4700-a0cc-df997cc6d9c2160fcd54-5df2-4969-9342-9fa7f3f2732c
       Visa
       MerchantId1
    
    
       0000000002
       c61b1dcb-9c6b-4700-a0cc-df997cc6d9c2160fcd54-5df2-4969-9342-9fa7f3f2732c
       Visa
       MerchantId1
    
    
       0000000003
       c61b1dcb-9c6b-4700-a0cc-df997cc6d9c2160fcd54-5df2-4969-9342-9fa7f3f2732c
       Visa
       MerchantId1
    
{
                "Summary" : {
                                "TotalItems" : 5,
                                "MerchantSummaries" : [{
                                                                "MerchantProfileId" : "MyProfileId1",
                                                                "TotalItems" : 5
                                                }
                                ],
                                "CardTypeSummaries" : [{
                                                                "TotalItems" : 2,
                                                                "CardType" : "Visa"
                                                }, {
                                                                "TotalItems" : 2,
                                                                "CardType" : "MasterCard"
                                                }, {
                                                                "TotalItems" : 1,
                                                                "CardType" : "Discover"
                                                }
                                ]
                },
                "Data" : [{
                                                "MerchantProfileId" : "MyProfileId1",
                                                "CardType" : "Visa",
                                                "TokenId" : "ecbcf378-8f33-4a60-86b4-75c319b899469b5b89cc-d0ae-461c-b008-edaa636f88e9",
                                                "MerchantReferenceId" : 0000000000
                                }, {
                                                "MerchantProfileId" : "MyProfileId1",
                                                "CardType" : "Visa",
                                                "TokenId" : "f7df1650-8345-4f9b-915b-2f4b29e1646a8ce1aafd-ffcf-455b-acfe-7f11c0161317",
                                                "MerchantReferenceId" : 0000000001
                                }, {
                                                "MerchantProfileId" : "MyProfileId1",
                                                "CardType" : "MasterCard",
                                                "TokenId" : "573b359c-875c-4a74-b9ec-b6709a32b79898b265ba-4c77-4da6-84f8-2a0a657a286c",
                                                "MerchantReferenceId" : 0000000002
                                }, {
                                                "MerchantProfileId" : "MyProfileId1",
                                                "CardType" : "MasterCard",
                                                "TokenId" : "25934448-cf85-4acc-b554-36d0df7397db9f3dd8d3-a6c2-4baf-89d3-f639deeb6b18",
                                                "MerchantReferenceId" : 0000000003
                                }, {
                                                "MerchantProfileId" : "MyProfileId1",
                                                "CardType" : "Discover",
                                                "TokenId" : "c5e16206-2e40-4e6d-828e-a2c624e9729dd9ea9795-a5fa-4e6d-bd69-0c382011fa35",
                                                "MerchantReferenceId" : 0000000004
                                }
                ]
}
Note:
  • The MerchantProfile must be enrolled in Account Updater for one of the three card brands Visa, MasterCard, and Discover (saved on the MerchantProfile)
    • All merchant profiles used in the file need to be enrolled in Account Updater
  • Merchants need to specify the “accept” header when using JSON to POST messages – if the accept header is not specified, it will default to “application/xml”
    • If a merchant is using both XML and an octet-stream, the content type must be set to “content-type: application/octet-stream”
  • MerchantReferenceId is unique by file and is restricted to 10 characters
 

The table below specifies the different header scenarios and options:

 
Scenario #1: Upload a file stream using XML, get an XML response
Headers:
  • Content-type: “application/octet-stream”
  • Accept: “application/xml”
  • Authorization: Basic UEhOaGJXdzZRWE56Wlh….. zTmxjblJwYjI0Kzo=
Scenario #2: Upload a file stream using JSON, get a JSON response
Headers:
  • Content-type: “application/octet-stream”
  • Accept: “application/json”
  • Authorization: Basic UEhOaGJXdzZRWE56Wlh…..zTmxjblJwYjI0Kzo=
 

Sample Response:

The response returns two pieces of data:

  1. The expected date when the response file will be available for download
  2. The RequestId, which is a GUID that the Merchant will use to download the response file
  


                2018-11-03T00:00:00+00:00
                847F2A3273234A79A646CBB5E23EEB40
    
{
                "Summary" : {
                                "TotalItems" : 5,
                                "MerchantSummaries" : [{
                                                               "MerchantProfileId" : "MerchantId1",
                                                               "TotalItems" : 4
                                                }
                                ],
                                "CardTypeSummaries" : [{
                                                               "CardType" : "MasterCard",
                                                               "TotalItems" : 2
                                                }, {
                                                               "CardType" : "Visa",
                                                               "TotalItems" : 1
                                                }, {
                                                               "CardType" : "Discover",
                                                               "TotalItems" : 1
                                                }
                                ]
                },
                "UpdatedData" : [{
                                                "MerchantReferenceId" : "0000000002",
                                                "OldAccountNumber" : "671265XXXXXX0296",
                                                "NewAccountNumber" : "",
                                                "OldAccountExpiration" : "0420",
                                                "NewAccountExpiration" : "",
                                                "ReasonCode" : "Error",
                                                "PreviouslySentFlag" : false,
                                                "ErrorMessage" : "Not enrolled.",
                                                "CardBrandResponseFile" : "Discover"
                                }, {
                                                "MerchantReferenceId" : "0000000001",
                                                "OldAccountNumber" : "4875691479823331",
                                                "NewAccountNumber" : "4875691479823331",
                                                "OldAccountExpiration" : "1221",
                                                "NewAccountExpiration" : "1221",
                                                "ReasonCode" : "AccountVerified",
                                                "PreviouslySentFlag" : true,
                                                "ErrorMessage" : null,
                                                "CardBrandResponseFile" : "Visa"
                                }, {
                                                "MerchantReferenceId" : "0000000000",
                                                "OldAccountNumber" : "5315424430768215",
                                                "NewAccountNumber" : "5213365441254451",
                                                "OldAccountExpiration" : "1119",
                                                "NewAccountExpiration" : "1119",
                                                "ReasonCode" : "AccountNumberUpdate",
                                                "PreviouslySentFlag" : false,
                                                "ErrorMessage" : null,
                                                "CardBrandResponseFile" : "MasterCard"
                                }, {
                                                "MerchantReferenceId" : "0000000003",
                                                "OldAccountNumber" : "2649126955256078",
                                                "NewAccountNumber" : "2649126955256078",
                                                "OldAccountExpiration" : "0622",
                                                "NewAccountExpiration" : "0624",
                                                "ReasonCode" : "ExpirationDateUpdate",
                                                "PreviouslySentFlag" : false,
                                                "ErrorMessage" : null,
                                                "CardBrandResponseFile" : "MasterCard"
                                }
                ]
}

{
                "Summary" : {
                                "TotalItems" : 5,
                                "MerchantSummaries" : [{
                                                                "MerchantProfileId" : "MerchantId1",
                                                                "TotalItems" : 5
                                                }
                                ],
                                "CardTypeSummaries" : [{
                                                                "CardType" : "Visa",
                                                                "TotalItems" : 2
                                                }, {
                                                                "CardType" : "MasterCard",
                                                                "TotalItems" : 2
                                                }, {
                                                                "CardType" : "Discover",
                                                                "TotalItems" : 1
                                                }
                                ]
                },
                "UpdatedData" : [{
                                                "MerchantReferenceId" : "0000000004",
                                                "OldMaskedAccountNumber" : "661734XXXXXX6039",
                                                "NewMaskedAccountNumber" : "",
                                                "OldAccountExpiration" : "0722",
                                                "NewAccountExpiration" : "",
                                                "ReasonCode" : "Error",
                                                "PreviouslySentFlag" : false,
                                                "ErrorMessage" : "Not enrolled.",
                                                "TokenId" : null,
                                                "CardBrandResponseFile" : "Discover"
                                }, {
                                                "MerchantReferenceId" : "0000000000",
                                                "OldMaskedAccountNumber" : "434032XXXXXX0702",
                                                "NewMaskedAccountNumber" : "434032XXXXXX0702",
                                                "OldAccountExpiration" : "0421",
                                                "NewAccountExpiration" : "0421",
                                                "ReasonCode" : "AccountVerified",
                                                "PreviouslySentFlag" : true,
                                                "ErrorMessage" : null,
                                                "TokenId" : "ecbcf378-8f33-4a60-86b4-75c319b899469b5b89cc-d0ae-461c-b008-edaa636f88e9",
                                                "CardBrandResponseFile" : "Visa"
                                }, {
                                                "MerchantReferenceId" : "0000000001",
                                                "OldMaskedAccountNumber" : "494034XXXXXX9162",
                                                "NewMaskedAccountNumber" : "482614XXXXXX5678",
                                                "OldAccountExpiration" : "0818",
                                                "NewAccountExpiration" : "0818",
                                                "ReasonCode" : "AccountNumberUpdate",
                                                "PreviouslySentFlag" : true,
                                                "ErrorMessage" : null,
                                                "TokenId" : "f7df1650-8345-4f9b-915b-2f4b29e1646a8ce1aafd-ffcf-455b-acfe-7f11c0161317",
                                                "CardBrandResponseFile" : "Visa"
                                }, {
                                                "MerchantReferenceId" : "0000000002",
                                                "OldMaskedAccountNumber" : "592735XXXXXX2010",
                                                "NewMaskedAccountNumber" : "592735XXXXXX2010",
                                                "OldAccountExpiration" : "0818",
                                                "NewAccountExpiration" : "0521",
                                                "ReasonCode" : "ExpirationDateUpdate",
                                                "PreviouslySentFlag" : false,
                                                "ErrorMessage" : null,
                                                "TokenId" : "573b359c-875c-4a74-b9ec-b6709a32b79898b265ba-4c77-4da6-84f8-2a0a657a286c",
                                                "CardBrandResponseFile" : "MasterCard"
                                },{
                                                "MerchantReferenceId" : "0000000003",
                                                "OldMaskedAccountNumber" : "556952XXXXXX5068",
                                                "NewMaskedAccountNumber" : "556952XXXXXX5068",
                                                "OldAccountExpiration" : "0222",
                                                "NewAccountExpiration" : "0222",
                                                "ReasonCode" : "AccountVerified",
                                                "PreviouslySentFlag" : false,
                                                "ErrorMessage" : null,
                                                "TokenId" : "25934448-cf85-4acc-b554-36d0df7397db9f3dd8d3-a6c2-4baf-89d3-f639deeb6b18",
                                                "CardBrandResponseFile" : "MasterCard"
                                }
                ]
}
Note:
  • If the FileFormat on the Request is either “AccountData” or “SnapToken” the response returned will be XML.
  • If the FileFormat on the Request is either “AccountDataJson” or “SnapTokenJson” the response returned will be JSON.
DownloadAccountUpdaterResponseFile
RequestUri https://api.cipcert.goevo.com/2.1.29/REST/DataServices/AMS.svc/Download//
Method GET
 

Request:

  • The MerchantProfile must be enrolled in Account Updater for card brands Discover, Visa, or MasterCard (Saved on the MerchantProfile)
    • All merchant profiles used in the file need to be enrolled in Account Updater
  • The RequestId is returned on the upload, and it will correspond to the response file when it is available for download – if a merchant tries to download before the response file is available, they will get a message saying the file is unavailable.
  • The stream format returned on the download will depend on what the FileFormat was on the upload.
    • If the FileFormat was “AccountData” or “SnapToken”, the stream will be XML
    • If the FileFormat was “AccountDataJson” or “SnapTokenJson”, the stream will be JSON
  • The structure of the response stream will be the same structure of the request files.
  • Merchants need to specify the “accept” header when using JSON to GET messages – if the accept header is not specified, it will default to “application/xml”.
    • If a merchant is using both XML and an octet-stream, the content type must be set to “content-type: application/octet-stream”
 

The table below specifies the different header scenarios and options:

 
Scenario #1: Request download using XML, get a file stream
Headers:
  • Content-type: “application/xml”
  • Accept: “application/octet-stream”
  • Authorization: Basic UEhOaGJXdzZRWE56Wlh….. zTmxjblJwYjI0Kzo=
Scenario #2: Request download using JSON, get a file stream
Headers:
  • Content-type: “application/json”
  • Accept: “application/octet-stream”
  • Authorization: Basic UEhOaGJXdzZRWE56Wlh….. zTmxjblJwYjI0Kzo=

SOAP API Reference

Request:


ABCDE00001AccountDataMerchantId1PHNhbWw6QXN...NlcnRpb24+ 
              
                     PD94bWwgdmV...0RmlsZT4=
Note:
  • SessionToken, MerchantProfileId, FileFormat are set on the SOAP header.
  • The file is base 64 encoded onto the body of the request, in “Contents”.
  

Response




  2018-05-18T00:00:00+00:00
  30C5A25D119344DA8C6DC3ACFC0E750D
  00000000-0000-0000-0000-000000000000
Note:
  • The returned base-64 encoded file can be very large, thus merchants should ensure their settings are set up appropriately to handle such a large value.

Request:



                
                                MerchantId1
                                30C5A25D119344DA8C6DC3ACFC0E750D
                                PHNhbWw6...cnRpb24+
  Response: 



  0001-01-01T00:00:00


  
   PD94bWwgdm...RmlsZT4=
 

Base64 Decoded Contents from Download:



  
    5
    
      
        MerchantId1
        4
      
    
    
      
        MasterCard
        2
      
      
        Visa
        1
      
      
        Discover
        1
      
    
  
  
    
      0000000002
      4274886428819819
      4274886428819819
      1215
      1215
      AccountVerified
      true
      Visa
    
    
      0000000001
      2080101322490441
      2080101322490441
      1215
      1215
      AccountVerified
      false
      MasterCard
    
    
      0000000000
      3626723647197736
      3626723647197736
      1215
      1215
      AccountVerified
      false
      MasterCard
    
    
      0000000003
      2665164434400619
      2665164434400619
      1215
      1215
      AccountVerified
      false
      Discover
Note:
  • The returned base-64 encoded file can be very large, thus merchants should ensure their settings are set up appropriately to handle such a large value.

Sandbox Plugins

Account Updater Sandbox plugins allow the merchants to test account data going back into XDT. Certain trigger values exist that allow the user to return specific card responses.

The following table defines the current Sandbox plugin trigger values:

 

Condition Returned VISA PAN MasterCard PAN Discover PAN
Account Number Update 4111-1111-1111-1111 5111-1111-1111-1111 6111-1111-1111-1111
Account Closed 4222-2222-2222-2222 5222-2222-2222-2222 6222-2222-2222-2222
Expiration Date Update 4333-3333-3333-3333 5333-3333-3333-3333 6333-3333-3333-3333
Account Verified 4444-4444-4444-4444 5444-4444-4444-4444 6444-4444-4444-4444
Cardholder Withheld Updates 4555-5555-5555-5555 5555-5555-5555-5555 6555-5555-5555-5555

Release Notes

Below, you will find release notes related to the Account Updater service. Click on one to learn about our new or updated features and more!

Release Notes Production Date
Account Updater Release Notes June 2018