Mobile Location Confirmation Documentation

Ready to start coding?

Things To Know

Mobile Location Confirmation delivers value by providing Visa card issuers an enhanced Visa Advanced Authorization score and a Location Match Indicator in the VisaNet authorization message. The Mobile Location Confirmation APIs can be used by any developer in the sandbox, however, since the enhanced score and Location Match Indicator is delivered to issuers in the VisaNet authorization message, only Visa issuers can sign up for Mobile Location Confirmation and use the APIs in production.

When you sign up for Mobile Location Confirmation, Visa provides the Mobile Location Agent to capture and report mobile device geolocation. Currently, only Visa issuers are given access to the Mobile Location Agent. You can use this within your mobile apps to capture location data for fraud detection purposes only. If you elect to use and retain location data reported from the Mobile Location Agent for fraud detection purposes outside of Mobile Location Confirmation, you must do so consistent with regulatory and legal considerations, including any other cardholder disclosures as may be required by law or industry practice. In addition, you are responsible for ensuring the accuracy of location data submitted to Visa and compliance with all applicable privacy laws and regulations.

The sandbox environment currently does not have VisaNet connectivity, so you cannot validate the receipt of an authorization message with the enhanced VAA score and Location Match Indicator in the sandbox. Refer to the Service Activation Requirements section for information about alternatives for testing VisaNet connectivity.

Mobile Location Confirmation works wherever Visa cards are accepted, for all Visa product types, and for all card-present transactions that are processed by VisaNet. In the future, Visa intends to extend this capability to card-not-present transactions when device IP address location is available.

Availability

The following table lists the regional availability for Mobile Location Confirmation. To view availability of all products, refer to the Availability Matrix.

Available in entire region

Limited availability in region

Not available

Product Name Availability Notes
Mobile Location Confirmation
Product Name Availability Notes
Mobile Location Confirmation
Product Name Availability Notes
Mobile Location Confirmation
Product Name Availability Notes
Mobile Location Confirmation
Product Name Availability Notes
Mobile Location Confirmation

Getting Started

Mobile Location Confirmation helps improve the consumer experience by helping you have more confidence to approve payment transactions when your cardholders travel.  With Mobile Location Confirmation, Visa can tell you at the time of purchase whether your cardholder is near a  merchant requesting payment authorization. You can include this information in your decision to approve a transaction that might otherwise have appeared too risky to approve.

The first step in getting started with Mobile Location Confirmation is to understand how it works, the role of its APIs, and the role the Mobile Location Agent plays in the delivery of the service.

Cardholders enroll in Mobile Location Confirmation using your mobile app. You notify Visa of cardholder participation by calling the Cardholder Enrollment API after cardholders provide consent to participate in Mobile Location Confirmation. When you receive a success response from Visa, the Mobile Location Agent embedded in your app begins to capture and report location to Visa. When you sign up for Mobile Location Confirmation, Visa provides the Mobile Location Agent in source code format so you can integrate the code into your mobile app.

When a cardholder transacts in a store using their enrolled card, Visa derives a Location Match Indicator for the transaction by comparing the merchant location in the authorization request to the location of the cardholder’s mobile phone. Visa then forwards the Location Match Indicator and an enhanced Visa Advanced Authorization score to you in the authorization request so that you can use these in your decision to approve or decline the transaction.

How Does it Work?

Mobile Location Confirmation is a service that provides information about whether or not an enrolled cardholder’s mobile phone is located near the merchant requesting authorization for a purchase. Visa sends this information to you as part of the real-time authorization request. There are four main components of the Mobile Location Confirmation service:

  1. Cardholder Enrollment
    Cardholders will enroll in Mobile Location Confirmation via your mobile app, which must be enhanced to allow cardholders to enroll their eligible card(s) and mobile phone in the service. Within the mobile app, cardholders must explicitly opt in to the collection of geolocation information.
  2. Location Updates
    Once a cardholder enrolls in the Mobile Location Confirmation via your mobile app, the app begins regularly collecting approximate location from the cardholder’s mobile phone and sending that to Visa.
  3. Location Match
    When a cardholder transacts with their Mobile Location Confirmation-enrolled card, Visa compares the location of the merchant in the authorization request to the location of the cardholder’s mobile phone. Based on this comparison, Visa derives a Location Match Indicator, which informs you whether the mobile phone is located near the merchant. Visa then sends this Location Match Indicator and an enhanced Visa Advanced Authorization (VAA) score to you in the outgoing authorization request.
  4. Authorization Decision
    You can receive the Location Match Indicator and enhanced VAA score from Visa and use those as part of an approval or decline decision.

Why Use It?

Fewer Inaccurate Transaction Declines

Geolocation intelligence allows you to authorize transactions more confidently and keep your travelling customers happy.

Reduced Costs

Mobile Location Confirmation can help save operational costs associated with false positive declines and pre-travel notification calls.

Features Included

Cardholder Enrollment

The Cardholder Enrollment API allows you to enroll and deenroll your Visa cardholder's account number and mobile device for Mobile Location Confirmation.

Mobile Location Agent

The Mobile Location Agent is downloadable source code that enables your mobile app to capture and report mobile phone geolocation to Visa.

Other Features

Location Updates

If you optionally route mobile geolocation reported by the Mobile Location Agent to your server, the Location Update API allows you to send location updates to Visa.

Using the 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.

Mobile

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.

Security and Authentication Requirements

The Cardholder Enrollment and Location Update APIs use mutual SSL authentication and channel encryption, which requires that you obtain a user ID and password as well as install a PKI certificate issued by Visa. Test credentials can be obtained online in the Project Console for sandbox testing. Production credentials will be supplied to you as part of the production on-boarding process. Contact developer@visa.com for more information or to begin the production on-boarding process.

Service Activation Requirements

Cardholder Disclosure Requirements

You must implement Mobile Location Confirmation in accordance with applicable law and are responsible for gathering necessary authorization and consent from your cardholders to enroll them in Mobile Location Confirmation. For Visa requirements related to cardholder disclosures, refer to the Mobile Location Confirmation Service Description. To request a copy of the Mobile Location Confirmation Service Description, contact developer@visa.com.

Activation Requirements

You must sign up for the service with Visa by signing a Fraud Risk Products Agreement, indicating Mobile Location Confirmation as a service for participation. After signing an agreement, Visa will assign you an Implementation Manager who will be your main point of contact at Visa during implementation. They will provide you with a project plan for implementing Mobile Location Confirmation and required onboarding forms.

You must inform your processor that you have signed up for Mobile Location Confirmation and will start receiving the Location Match Indicator in Field 104 Dataset ID 6C Tag 02. If your processor requires testing or if you do not already support Field 104, Usage 2 in TLV format, you are required to complete testing with Visa in the VCMS environment. This ensures that you and your processor can properly receive and process the Location Match Indicator in Field 104.

Before deploying Mobile Location Confirmation widely, Visa also recommends that you complete “Friends and Family” testing in production with a limited set of live cards and devices to verify enrollment on the mobile app, enrollment with Visa, receipt and processing of location updates, in-store transactions, and deenrollment.

For a full list of activation requirements, refer to the Mobile Location Confirmation Service Description. For a copy of the Mobile Location Confirmation Service Description or Fraud Risk Products Agreement, contact developer@visa.com.

Best Practices and Tips for Using Mobile Location Confirmation

As a best practice prior to Mobile Location Confirmation deployment, Visa recommends that you conduct a review of your existing fraud risk strategies to determine how to incorporate the Location Match Indicator sent in the authorization message and how best to take advantage of the enhanced VAA score.

Mobile Location Confirmation is intended to help you approve transactions that might otherwise be declined due to suspected fraud. A location mismatch does not necessarily indicate fraud. For example, the cardholder may have left their phone at home while travelling or there may be inaccurate merchant location data in the authorization message. Therefore, Visa recommends that you consider other indicators of fraud when assessing a transaction for risk and not decline a transaction solely because of a reported location mismatch.