Enriched Transactions

Overview

Use this guide to learn how to match a location with a specific merchant and display detailed merchant information.

When you issue abbreviated transaction statements like "ACMEHCORP", your customers can find this hard to understand. This can lead to disputed charges and extra support costs for you. Instead, it's better to supply the full merchant name, such as Acme Housewares.

Enriched Transactions makes it easier for you to provide intuitive transaction information, including merchant's full name, business category, storefront image, and contact and location details. This increases transparency, improves Net Promoter Scores (NPS), and results in more time spent in your app.

Sample mobile screens comparing raw transaction statements with enriched merchant details
Enriched transactions sample screens (click to enlarge)

Enable APIs

To implement Enriched Transactions, you must enable the following APIs in the Google Cloud console. The following links open the Google Cloud console so you can enable each API for your selected project:

For more information about setup, see Getting started with Google Maps Platform.

Implementation guide sections

The following implementations and customizations are covered in this guide:

Match merchants with Google Maps Platform Associate a merchant in transaction history with a place in Google Maps Platform.
Display merchant details Show data-rich transactions with helpful information about the merchant so customers can quickly recognize the transaction.
Add a map of the merchant location Add a map of the merchant location with an advanced marker.

Match merchants with Google Maps Platform

This example uses: Places API (New) Also available: JavaScript

The following flowchart shows how your application matches merchant transactions to return a result using place details from an existing database of merchants or through a Text Search request:

Flowchart for matching merchant transaction records with place IDs and place details
Merchant matching flow matrix (click to enlarge)

Get Google Maps Platform place IDs

You might have a database of merchants with basic information like the business name and its address. To get information that Google Maps Platform has about that place, including contact details and customer-contributed ratings, find the place ID that corresponds to each merchant in your database.

To get the place ID for a business, make a call to the Text Search (New) endpoint in Places API (New) and request only the places.id field in the field mask, which triggers the Text Search Essentials (IDs Only) SKU. If the merchant has multiple locations, include the city or street name along with the merchant name in your query. Validate the returned results to confirm that they match the merchant.

The following example requests the place ID for the Google Taipei office using the merchant name and city:

curl -X POST -d '{
  "textQuery" : "Google Taipei"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: places.id' \
'https://places.googleapis.com/v1/places:searchText'

Store place IDs

To store information from Google Maps Platform about the merchant for future requests, you can store the place ID indefinitely in your database as an attribute of the merchant's record. You need to run the Text Search (New) request only once for each merchant, or you can search for the place ID whenever a customer requests transaction details.

To keep your stored place IDs accurate, refresh place IDs every 12 months by making a Place Details (New) request that specifies only the id field in the field mask.

If the place details you display don't match the merchant where the customer completed the transaction, Google recommends letting customers submit feedback about the quality of the merchant match.

Display merchant details

This example uses: Places API (New) Also available: Places SDK for Android | Places SDK for iOS | Places Library, Maps JavaScript API

You can share the place details customers need after they visit a merchant location. After calling the Place Details (New) endpoint in Places API (New), you can filter and render the response in an info window, a web sidebar, or a mobile detail view within the limits of the Google Maps Platform Terms of Service.

Mobile transaction detail view displaying merchant name, address, map, and contact details
Sample merchant details screen (click to enlarge)

To issue a request to the Place Details endpoint, you need the place ID for each location. See Get Google Maps Platform place IDs to retrieve the place ID of a merchant location.

The following Place Details (New) request returns the display name, formatted address, coordinates, website, phone number, icon, opening hours, and rating in JSON format for the Google Taipei 101 place ID:

curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: displayName,formattedAddress,location,websiteUri,nationalPhoneNumber,iconMaskBaseUri,regularOpeningHours,rating' \
'https://places.googleapis.com/v1/places/ChIJraeA2rarQjQRyAqIxkx2vN8'

If you're building a web application with the Maps JavaScript API, you can also use the Place class to fetch the same fields on the client:

const place = new google.maps.places.Place({
  id: "ChIJraeA2rarQjQRyAqIxkx2vN8",
});

await place.fetchFields({
  fields: [
    "displayName",
    "formattedAddress",
    "location",
    "websiteURI",
    "nationalPhoneNumber",
    "regularOpeningHours",
    "rating",
  ],
});

Add a map of the merchant location

This example uses: Maps JavaScript API | Geocoding API | Maps Static API Also available: Android | iOS

Determine the merchant's location

You can place a marker on a map using geographic coordinates from place details. If your merchant database has street addresses without geographic coordinates and you aren't requesting place details, you can use the Geocoding API to convert street addresses to latitude and longitude coordinates on the server side, store those coordinates in your database, and refresh them at least once every 30 days.

The following example uses the Geocoding API to get the latitude and longitude for the Google Taipei office place ID:

```html
https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJraeA2rarQjQRyAqIxkx2vN8&key=YOUR_API_KEY
```

Add an advanced marker on a web map

Because customers view the map to confirm transactions rather than browse or navigate, configure your map with limited interactivity and place an advanced marker at the merchant's location. Advanced markers require a map ID and the marker library (libraries=marker).

First, load the Maps JavaScript API with libraries=marker and add a container div for the map:

<script defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=marker&callback=initMap"></script>
<div id="map" style="height: 300px; width: 100%;"></div>

Next, initialize the map with gestureHandling: "none" and zoomControl: false to limit interactivity, provide your mapId, and create a google.maps.marker.AdvancedMarkerElement at the merchant's coordinates:

function initMap() {
  const merchantLocation = { lat: 25.033976, lng: 121.5645389 };
  const map = new google.maps.Map(document.getElementById("map"), {
    center: merchantLocation,
    zoom: 16,
    mapId: "DEMO_MAP_ID",
    gestureHandling: "none",
    zoomControl: false,
  });

  new google.maps.marker.AdvancedMarkerElement({
    map,
    position: merchantLocation,
    title: "Google Taipei",
  });
}

You can also customize your advanced markers by changing the pin background, border, or glyph color, or by supplying a custom graphic image for the merchant's category.

Add a static map image

If you prefer a non-interactive map image for desktop or mobile web, create a Maps Static API URL with a single marker at the merchant's latitude and longitude coordinates or address. The Maps Static API returns an image version of a map using the parameters you specify.

The following request returns a roadmap with a size of 640x480 pixels, centered on a red marker at the Google Taipei office with a cloud-based map style:

```html
https://maps.googleapis.com/maps/api/staticmap?size=640x480&markers=color:red%7C25.033976%2C121.5645389&map_id=b224095f76859890&key=YOUR_API_KEY&signature=BASE64_SIGNATURE
```

The following table describes each section of the request:

API URL https://maps.googleapis.com/maps/api/staticmap?
Image size size=640x480
Merchant location markers (using URL encoding) markers=color:red%7C25.033976%2C121.5645389
Cloud-based map style map_id=b224095f76859890
API key key=YOUR_API_KEY
Digital signature (learn how to digitally sign your request) signature=BASE64_SIGNATURE

The request produces the following static map image:

Map centered on the Google Taipei office with a red location marker

You can also pass an address as the marker location:

```html
https://maps.googleapis.com/maps/api/staticmap?size=640x480&markers=color:green%7CTaipei%20101%20Tower%2CNo.%207信義路五段信義區台北市%20Taiwan%20110&map_id=b224095f76859890&key=YOUR_API_KEY&signature=BASE64_SIGNATURE
```

For additional parameter options, see the Maps Static API documentation.

Add a map on your mobile application

If you're using the Maps SDK for Android or Maps SDK for iOS, you can place an advanced marker using coordinates from place details.

Because customers view the map to confirm transactions rather than browse or navigate, configure a map with limited interactivity: