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*!

Contents: Click on one of the following topics to learn more!

 

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.

Back to the top
 

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.

Back to the top
 

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”

Request:
Sample XML Request Body for Account Data:

 
Sample JSON Body AccountData File:

 

Sample XML Request Body for Token Data:

 

Sample JSON Body TokenData File:

 

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=

 

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

Sample XML Response:

 

Sample JSON AccountData Response:

 

Sample JSON TokenData Response:

 

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=

Back to the top
 

SOAP API Reference

UploadAccountUpdaterRequestFile

Request:

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

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.

 

DownloadAccountUpdaterRequestFile

Request:

 
Response:

 
Base64 Decoded Contents from Download:

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.

Back to the top
 

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

 
Back to the top

 

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

 
Back to the top