How to Use Mobile Location Confirmation

Using Cardholder Enrollment API

Cardholders provide their consent to participate in Mobile Location Confirmation through your mobile app. Therefore, you must add functionality to your mobile app that enables cardholders to enroll in this service. When cardholders enroll via your mobile app, call the Cardholder Enrollment API in order to enroll them in this service.

In adding functionality to the mobile app, note that your design for the user’s Mobile Location Confirmation experience must comply with the Cardholder Disclosure Requirements listed in the Service Activation Requirements.

It is up to you to determine exactly what the user experience will be for the cardholder and how best to incorporate it into your mobile app. Visa suggests that an effective method is to include Mobile Location Confirmation enrollment on a screen where cardholders can manage other optional features, such as transaction alerts. Cardholders can navigate to this screen, turn Mobile Location Confirmation on or off, access more information about the service, and agree to location capture using the app.

Refer to the figures below that provide sample screens for enrolling and de-enrolling cardholders in the Mobile Location Confirmation service that may be useful as you plan your user experience strategy.

Using the Cardholder Enrollment API to Enroll a New Account/Device

Once you have collected the required information and consent from the cardholder, you can send an enrollment request to Visa using the Cardholder Enrollment API. You can find the technical details on the Documentation tab, but the primary components of the Cardholder Enrollment API request are:

  • Primary Account Number (PAN). This is the primary account number that the cardholder has chosen to enroll.
  • Issuer-Defined Device ID. This is a unique identifier you need to generate when a cardholder enrolls a new device. It must be a 32-character field that is globally-unique across all Mobile Location Confirmation issuers and enrollees. To ensure global uniqueness, Visa suggests using a UUID Version 1 (MAC Address, Date and Time) or similar generation scheme, but you can use any ID generation scheme that meets your needs. You are responsible for securely storing this ID on the cardholder’s mobile phone so that the Mobile Location Agent can access it. The Cardholder Enrollment API will check for global uniqueness and will return an error in the event a duplicate is detected.
  • Issuer ID. This is a 6-digit numeric identifier that Visa assign to you when your project is on-boarded for production. A test Issuer ID can be obtained from the Project Console for use in sandbox testing. You are responsible for securely storing the Issuer ID on the cardholder’s mobile phone so that the Mobile Location Agent can access it.

The following business rules apply to using the Cardholder Enrollment API:

  • The PAN must be eligible to participate in Mobile Location Confirmation. You must ensure that you have previously established the BINs that are eligible for enrollment (during production onboarding you will fill out and submit a Client Information Questionnaire listing the BINs eligible to enroll in the service). The API will return an error if the PAN provided in the request is not eligible to enroll.
  • Multiple PANs may be enrolled using the same Device ID. For example, the cardholder may elect to enroll both a credit and a debit account in Mobile Location Confirmation. Each PAN/Device ID combination requires a separate request to the Cardholder Enrollment API.
  • The same PAN may be enrolled on up to four different devices. For example, the cardholder may elect to enroll a PAN on both their personal phone and work phone. Each device must be assigned its own unique Device ID. Each PAN/Device ID combination requires a separate request to the Cardholder Enrollment API.

Using the Cardholder Enrollment API to Enroll a Reissued Account Number

Due to loss, theft, or expiration, a cardholder may receive a replacement account number for a PAN that had previously been enrolled in Mobile Location Confirmation. You can determine whether to automatically enroll the replacement PAN or to first seek approval from the cardholder. If you decide to automatically enroll replacement PANs, you must inform cardholders of this practice in the service’s Terms and Conditions. In either case, you must add the appropriate functionality to your mobile app.

To replace a previously-enrolled PAN with a reissued account number, you must:

  • Send a deenrollment request to the Cardholder Enrollment API for the old PAN. If the PAN is enrolled on multiple devices, send separate deenrollment requests with each Device ID.
  • Send an enrollment request to the Cardholder Enrollment API for the new PAN. If the PAN needs to be enrolled on multiple devices, send separate enrollment requests for each Device ID. 

Using the Cardholder Enrollment API to Deenroll an Account and/or Device

You must send a deenroll request to the Cardholder Enrollment API if:

  • The cardholder elects to deenroll one or more PANs from Mobile Location Confirmation via the mobile app. Send a separate deenroll request for each PAN/Device ID combination selected by the cardholder.
  • The cardholder informs you that an enrolled device has been lost, stolen, or is no longer in use by the cardholder. Send a separate deenroll request for every PAN previously enrolled with that Device ID.
  • An enrolled PAN has been closed. Send a deenroll request for each Device ID with which the closed PAN was enrolled.
  • Your host system has not received a location update from an enrolled device in an amount of time not considered acceptable by you. Send a separate deenroll request for every PAN previously enrolled with the Device ID of the unresponsive device. A device may have stopped sending location updates for a variety of reasons, including due to the cardholder deleting your app from the device.

You may enable cardholders to deenroll through channels other than the mobile app, such as with a call to the issuer’s Call Center. In that case, issuer customer service system must capture the necessary information from the cardholder and then send an appropriate deenroll request to the Cardholder Enrollment API. The system must also inform the mobile app so that its Mobile Location Agent can be instructed to stop sending location updates and the app user interface displays that the device is no longer enrolled in the service.

Note: Issuers may opt-in to utilize Mobile Location Confirmation's Visa Account Updater (VAU) feature to automatically process card updates that are submitted to VAU. For card reissuance events reported to VAU, MLC automatically changes an existing enrollment from the old PAN to the new PAN. For account closures reported to VAU, MLC automatically de-enrolls the closed account from MLC.

Using the Mobile Location Agent

The Mobile Location Agent is an SDK that Visa provides in source code format that you embed within your mobile app to capture and report mobile device geolocation to Visa. To initiate location capture by the Mobile Location Agent, your mobile app must call the startService method. To stop location capture by the Mobile Location Agent, your mobile app must call the stopService method. The startService method must only be called after you successfully enroll a PAN/Device ID combination using the Cardholder Enrollment API. Your app must immediately call the stopService method after a cardholder has deenrolled all PANs from a given device.

(Note: You should not call stopService if any PANs are still enrolled for a given Device ID).

Out of consideration for cardholder privacy, the Mobile Location Agent applies logic to determine whether a location change is significant enough to report to Visa. This filtering logic takes into account the distance travelled, whether the device is in its Home Area, and whether the device has not sent an update in longer than the Location Pulse Interval.

Each time the Mobile Location Agent detects a significant location change, it reports the new location to Visa.

The Mobile Location Agent supports mobile apps running on iOS 6.0 and above and Android 2.3 and above.

Currently, the Mobile Location Agent is available only to Visa issuers and is not available for download directly from the Visa Developer website. Contact developer@visa.com to obtain instructions for downloading the Mobile Location Agent SDK and the Mobile Location Agent Programmer’s Toolkit. The Toolkit contains the Mobile Location Agent Programmer’s Guide and Reference, source code libraries for the Mobile Location Agent (iOS and Android), and a sample Android app that you can use as a starting point for your integration.

Note: Visa reserves the right to modify and or replace the Mobile Location Agent source code.

Using the Location Update API (Optional)

You can optionally implement the Mobile Location Agent to report mobile geolocation to your host system instead of directly to Visa. Your host system is then responsible for forwarding the location update to Visa using the Location Update API. The information below is only relevant if you have chosen to route location reported by the Mobile Location Agent to your host system instead of directly to Visa.

You can find the technical details on the Documentation tab, but the primary components of the Location Update API request are:

  • Issuer-Defined Device ID. This is the issuer-assigned ID that identifies the device reporting its location. The API will return an error if it receives a request with a Device ID not previously enrolled in Mobile Location Confirmation using the Cardholder Enrollment API.
  • Issuer ID. This is the identifier assigned to the issuer by Visa when the issuer signed up for the Mobile Location Confirmation service.
  • Geolocation Coordinates. These are the latitude and longitude coordinates of the device reported by the Mobile Location Agent.
  • Time Stamp. This is the date and time that the latitude and longitude coordinates were captured by the Mobile Location Agent.

A successful Location Update API response will include:

Home Area. This is derived by Visa for the device and represents the circular area in which the device most typically transmits its location. The Home Area enables the Mobile Location Agent to limit the number of location updates reported from a given device while the device stays within its Home Area. During the first few weeks of enrollment, the Home Area for a given device will not be defined yet and the values will be blank.

Home Area Expiration. This is a date and time after which a re-verification of the Home Area by Visa is required. After reaching this date and time, the Mobile Location Agent will send more frequent location updates until a new Home Area can be determined.

Location Pulse Interval. This is the elapsed time threshold, which if exceeded, triggers the Mobile Location Agent to report a new location. This ensures that the location reported by the Mobile Location Agent is current enough for use in fraud risk assessment.

Your host system must send the Home Area and Location Pulse Interval to the Mobile Location Agent embedded in your app on the particular device that corresponds to the Device ID in the Location Update API request. Visa passes the Home Area and Location Pulse Interval in every API response even if the values have not changed since the previous update. You can choose to forward Home Area and/or Location Pulse updates to the Mobile Location Agent each time or only when the values have changed.

Understanding the Location Match Indicator

When a cardholder transacts in a store using their enrolled card and mobile phone location data is available, Visa derives the Location Match Indicator for the transaction by comparing the merchant location in the authorization request to the location of the cardholder’s mobile phone. The precision of the Location Match Indicator depends upon where the transaction occurs. Visa sends you the Location Match Indicator via the Visa Advanced Authorization Score and in the authorization message.

Issuers who use Visa Risk Manager’s Real-Time Decisioning or Case Creation rules can make authorization decisions using the new Location Match Indicator parameters available in rule definition. Issuers using other fraud risk systems can access the Location Match Indicator in Field 104, Usage 2, Dataset 6C Tag 02 of the authorization message.

You will need to work with your processor to ensure they can forward you Field 104, Usage 2, Dataset 6C Tag 02. You will also need to make sure your internal systems can appropriately use the Location Match Indicator sent in in Field 104.

For further details on using the Location Match Indicator, refer to the Mobile Location Confirmation Service Description. For details on implementing the Location Match Indicator, refer to Article 4.7 of Visa’s April 2015 Global Technical Letter. To request a copy of the Mobile Location Confirmation Service Description or the April 2015 Global Technical Letter, contact developer@visa.com.