Merchant Feed

AI-generated Key Takeaways

The Merchant Feed is a JSON or Protobuf file containing merchant metadata and a list of merchants, used for services like Reserve with Google and Google Pay.
Each Merchant entry requires a unique ID, name, geographical information, and category, with optional fields for contact details, payment, and service specifics.
TokenizationConfig, BillingAddressParameters and other structures support secure payment processing and detailed billing information for various card networks.
Terms, MerchantMatchingHints, and ServiceAttribute allow defining service terms, assisting Google Maps matching, and providing detailed service descriptions.
The comprehensive structure enables flexible representation of merchant data, ensuring smooth integration with Google's platforms for booking and payment functionalities.

MerchantFeed Definition

message MerchantFeed {
  FeedMetadata metadata = 1;
  repeated Merchant merchant = 2;
}

Merchant Definition

// Info about a merchant that is on the aggregator's platform.
// A merchant feed should be a list of this message.
message Merchant {
  // An opaque string generated by the partner that identifies a merchant.
  // Must be unique across all merchants.
  // Strongly recommended to only include URL-safe characters. (required)
  string merchant_id = 1;

  // The name, telephone, url and geo are used to support matching partner
  // inventory with merchants already present on Google Maps. This information
  // will not be displayed.
  //
  // The name of the merchant. (required)
  string name = 2;

  // The contact telephone number of the merchant including its country and area
  // codes, e.g. +14567891234. Highly recommended. (optional)
  string telephone = 3;

  // The url of the merchant's public website. Highly recommended. (optional)
  string url = 4;

  // The Geo info of the merchant, including latitude, longitude, and address.
  // (required)
  GeoCoordinates geo = 5;

  // The category of the business in aggregator's platform. (required)
  // You should categorize this business as you categorize it in your inventory.
  // We will use your provided category as a parameter in trying to determine
  // the best location match to the physical business.
  string category = 6;


  // The specific merchant's Terms and Conditions displayed to the user when a
  // service is being booked through Reserve with Google.
  // In addition to these the aggregator partner's Terms and Conditions are
  // always displayed to the user and must not be provided here. (optional)
  Terms terms = 13;

  // An opaque string that identifies the consumer-facing brand to use when
  // displaying partner attribution. This field allows partners with multiple
  // consumer-facing brands to provide merchants for all brands within the same
  // feed.
  //
  // A brand consists of consumer-facing properties like the name, logo, Terms
  // of Service, and Privacy Policy.
  //
  // If there is only one consumer-facing partner brand, this field does not
  // need to be set and can be ignored.
  //
  // If the partner...
  //
  //   Does not have multiple consumer-facing brands?
  //     --> Ignore this field
  //
  //   Has Multiple Brands that are configured?
  //
  //       If this field is set
  //         --> Associated consumer-facing brand attribution is used
  //
  //       If this field is unset or the empty string
  //         --> Default consumer-facing brand attribution is used
  //
  // Careful Note: most partners do not need to set this field. If a partner
  // wishes to use this field, they must contact us first to configure separate
  // brands, including the default brand.
  string brand_id = 14;

  // Hints to help Google match a merchant to a place on Google Maps.
  // Note: Typically, this field does not need to be set, as Google will match
  // merchants to places on Google Maps using the information provided above.
  // (optional)
  MerchantMatchingHints matching_hints = 16;

  // Definitions for any service attributes used to describe the Services for
  // this Merchant. (optional)
  repeated ServiceAttribute service_attribute = 17;



  // An action URL with associated language, list of countries restricted to,
  // type, and optional platform that indicates which platform this action
  // should be performed on. This action link is specifically for the merchant,
  // please use the ActionLink in the service feed to link to a specific
  // service.
  repeated ActionLink action_link = 20;

  // The linkout template that specifies how Google should generate the
  // partner's URL to reserve a table on their platform.
  //
  // Note that currently only the first one will be used if multiple are
  // provided.
  //
  // The URI template has support for fields which will be populated based
  // on the user's reservation selections, all required fields are needed to
  // build a reservation URL successfully:
  // * (required) party_size, int: The size of the party for which the user is
  // requesting a reservation.
  // * (required) selected_date_time, ISO 8601 datetime
  // (https://en.wikipedia.org/wiki/ISO_8601): The time the user is requesting a
  // reservation for.
  // * (optional) merchant_id, string: The ID of the Merchant the user is
  // requesting a reservation with, not needed if template already includes a
  // merchant identifier.
  // * (optional) room_id, string: The id of the room the user is requesting a
  // reservation for.
  repeated LinkoutTemplate reservation_linkout_template = 21;

  // General advisements from a specific merchant for a user joining a waitlist
  // through Reserve with Google. Individual text fields in the advisement
  // should be limited to 100 bytes in length.
  Advisement waitlist_advisement = 22;

  // Economic Operator information associated to this specific merchant, if
  // applicable for an end to end payments integration.
  // For further info, refer to:
  // https://developers.google.com/actions-center/verticals/reservations/e2e/partner-portal/testing/regulatory-requirements#economic-operator
  //
  // (optional)
  EconomicOperator economic_operator = 23;
}

GeoCoordinates Definition

// The Geo data of a location, including latitude, longitude, and address.
// At least one of [lat/lng or address] should be provided (or both).
message GeoCoordinates {
  // [-90, +90] degrees (inclusive). (optional)
  double latitude = 1;

  // [-180, +180] degrees (inclusive). (optional)
  double longitude = 2;

  // Address for a location, could either be structured or unstructured.
  oneof addresses {
    // Postal address of the location, preferred.
    PostalAddress address = 3;

    // An unstructured address could also be provided as a fallback.
    // E.g. "1600 amphitheatre parkway mountain view, ca 94043"
    string unstructured_address = 4;
  }
}

PostalAddress Definition

// The postal address for a merchant.
message PostalAddress {
  // The country, using ISO 3166-1 alpha-2 country code, e.g. "US" (required)
  string country = 1;

  // The locality/city, e.g. "Mountain View". (required)
  string locality = 2;

  // The region/state/province, e.g. "CA". This field is only required in
  // countries where region is commonly a part of the address. (optional)
  string region = 3;

  // The postal code, e.g. "94043". (required)
  string postal_code = 4;

  // The street address, e.g. "1600 Amphitheatre Pkwy". (required)
  string street_address = 5;
}

TaxRate Definition

// A tax rate applied when charging the user for a service, and which can be set
// on either a per merchant, or per service basis.
message TaxRate {
  // A tax rate in millionths of one percent, effectively giving 6 decimals of
  // precision. For example, if the tax rate is 7.253%, this field should be set
  // to 7253000.
  //
  // If this field is left unset or set to 0, the total price charged to a user
  // for any service provided by this merchant is the exact price specified by
  // Service.price. The service price is assumed to be exempt from or already
  // inclusive of applicable taxes. Taxes will not be shown to the user as a
  // separate line item.
  //
  // If this field is set to any nonzero value, the total price charged to a
  // user for any service provided by this merchant will include the service
  // price plus the tax assessed using the tax rate provided here. Fractions of
  // the smallest currency unit (for example, fractions of one cent) will be
  // rounded using nearest even rounding. Taxes will be shown to the user as a
  // separate line item. (required)
  int32 micro_percent = 1;
}

TimeRange Definition

// A closed-open time range, i.e. [begin_sec, end_sec)
message TimeRange {
  // Seconds of UTC time since Unix epoch (required)
  int64 begin_sec = 1;

  // Seconds of UTC time since Unix epoch (required)
  int64 end_sec = 2;
}

TokenizationConfig Definition

// A configuration for payment-processor tokenization, set up on a per-Merchant
// basis.
message TokenizationConfig {
  // A tokenization configuration will typically have one
  // tokenization_parameter whose key is "gateway" and whose value is the
  // name of the processor.
  //
  // The rest of the parameters are dependent on the processor.  See
  // documentation from Google Pay and your processor for further information.
  // https://developers.google.com/pay/api/web/object-reference# \
  //   PaymentMethodTokenizationSpecification
  // https://developers.google.com/pay/api/#participating-google-pay-processors
  //
  // Braintree example:
  // tokenization_parameter { key: "gateway" value: "braintree" }
  // tokenization_parameter { key: "braintree:apiVersion" value: "v1" }
  // tokenization_parameter { key: "braintree:sdkVersion" value: "2.30.0" }
  // tokenization_parameter { key: "braintree:merchantId" value: "abcdef" }
  // tokenization_parameter { key: "braintree:clientKey"
  //                          value: "production_xxx_yyy" }
  //
  // Stripe example:
  // tokenization_parameter { key: "gateway" value: "stripe" }
  // tokenization_parameter { key: "stripe:version" value: "2018-02-28" }
  // tokenization_parameter { key: "stripe:publishableKey" value: "pk_1234" }
  //
  // Adyen example:
  // tokenization_parameter { key: "gateway" value: "adyen" }
  // tokenization_parameter { key: "gatewayMerchantId" value: "yourId" }
  map<string, string> tokenization_parameter = 1;

  // The following field controls how much billing information to include in the
  // payment token. Verification of billing information is the responsibility of
  // Google Pay upon entry of Form Of Payment (FOP). If the FOP is currently in
  // Google Pay without the requested level of billing information, the user
  // will not see their FOP as a choice, and they will have to enter the FOP and
  // required information according to the current Google Pay UI.
  //
  // Some merchants like to keep the requested information minimal because
  // requesting more information can lead to lower conversion rates.
  //
  // Note that they can also go to payments.google.com to enhance an FOP but
  // most users will not know to do so.

  // How much of the Billing Address to require of the user and include in the
  // token. The enum values correspond to parameters in the Google Pay API (see
  // https://developers.google.com/pay/api/web/reference/object\
  //  #BillingAddressParameters).
  enum BillingInformationFormat {
    BILLING_INFORMATION_FORMAT_UNSPECIFIED = 0;

    // name, country code, and postal code (GPay default setting).
    MIN = 1;

    // name, street address, locality, region, country code, and postal code
    FULL = 2;
  }

  // Include in the payment token the user's billing information as entered into
  // Google Pay with their FOP (see above).
  BillingInformationFormat billing_information_format = 2;

  // Name of the Merchant Of Record (MOR).  This user-visible name will be shown
  // in 3DS2 challenges.  In some cases, this is the Merchant, in others this is
  // the Aggregator.
  string merchant_of_record_name = 3;

  // Country where transaction will be processed, in ISO 3166-1 alpha-2 form.
  string payment_country_code = 4;

  // Per CardNetwork Processing information.
  message CardNetworkParameters {
    // The Card Network that these parameters are about
    CreditCardRestrictions.CreditCardType card_network = 1;

    // The Bank Identification Number of the acquiring bank used for processing
    // of the card.
    //
    // If this value is not known to you, you should ask your acquirer or
    // merchant processor representative.
    string acquirer_bin = 2;

    // The merchant identifier assigned by the acquirer to the merchant for use
    // in transaction authorization (for Visa and American Express
    // transactions).
    //
    // If this value is not known to you, you should ask the acquirer or
    // merchant processor representative.
    string acquirer_merchant_id = 3;
  }

  // Per-Card Network processing parameters.
  //
  // These are currently only required for PSD2
  // (https://en.wikipedia.org/wiki/Payment_Services_Directive)
  // processing when payment_country_code is a European country where PSD2 is in
  // effect.  They are also only currently required for VISA and
  // AMERICAN_EXPRESS.
  repeated CardNetworkParameters card_network_parameters = 5;

  // Fields supported to authorize a card transaction.
  //
  // See the GPay documentation at
  // https://developers.google.com/pay/api/web/reference/object#CardParameters
  enum AuthMethod {
    AUTH_METHOD_UNSPECIFIED = 0;

    // This authentication method is associated with payment cards stored on
    // file with the user's Google Account. Returned payment data includes
    // personal account number (PAN) with the expiration month and the
    // expiration year.
    PAN_ONLY = 1;

    // This authentication method is associated with cards stored as Android
    // device tokens. Returned payment data includes a 3-D Secure (3DS)
    // cryptogram generated on the device.
    CRYPTOGRAM_3DS = 2;
  }

  // Defines types of cardholder data that are accepted by the gateway.
  // If not specified, no restrictions are applied.
  //
  // Note that partners who use commercial gateways should leave this
  // empty unless their gateway provider has specified otherwise.  Restricting
  // allowed_auth_methods is most useful in the scenario that a partner
  // integrates with GPay as a gateway themselves.
  repeated AuthMethod allowed_auth_methods = 6;
}

Terms Definition

// A set of rules and guidelines that are displayed to the
// user in order to make a booking through Reserve with Google.
message Terms {
  // The URL to the Terms and Conditions. (optional)
  string url = 1;

  // The text to be displayed to the user.
  // Use localized_text below for new integrations.
  string text = 2;

  // The localized text to be displayed to the user. (required)
  Text localized_text = 3;
}

Text Definition

// A possibly-localized text payload. Some Text fields may contain marked-up
// content.
message Text {
  // Required. Text value in an unknown locale, which will be displayed if
  // `localized_value` for the user locale is empty or missing. The locale for
  // this value may depend on the partner or service provider, and it should not
  // be assumed to be any specific language.
  string value = 1;

  // Per-locale text values. Required.
  repeated LocalizedString localized_value = 2;
}

LocalizedString Definition

// Instance of a string in one locale.
message LocalizedString {
  // IETF BCP 47 language code, such as "en", "mas", "zh-Hant", "de-CH-1901".
  // See http://www.w3.org/International/articles/language-tags/.
  string locale = 1;

  // Message in the locale above (UTF-8).
  string value = 2;
}

MerchantMatchingHints Definition

// Hints used to help Google match a merchant to a place on Google Maps.
message MerchantMatchingHints {
  // The Place ID for a place in the Google Places database and on Google Maps.
  // See https://developers.google.com/places/place-id for more about Place IDs.
  // If this is provided, Google will use it as a hint when matching, and
  // prioritize the hint over other candidates.
  string place_id = 1;

}

ServiceAttribute Definition

// Service attributes are partner-defined categories that describe the Services
// for a Merchant. For example, a bank may define an "Account Type"
// service attribute with possible values of "Personal" and "Business", while a
// hair salon may define a "Service Type" service attribute with possible
// values of "Haircut", "Color", and "Style".
message ServiceAttribute {
  // An identifier that uniquely identifies this service attribute among others
  // for the same merchant, e.g. "account-type".
  string attribute_id = 1;

  // A user-visible name for this attribute, e.g. "Account Type".
  string attribute_name = 2;

  // Represents a possible value for a particular service attribute.
  message Value {
    // An identifier that uniquely identifies this value among others for
    // this service attribute, e.g. "personal".
    string value_id = 1;

    // A user-visible name for the value, e.g. "Personal".
    string value_name = 2;
  }

  // All possible values for this service attribute.
  repeated Value value = 3;
}

Merchant Feed Sample

Merchant Feed

      
{
  "metadata": {
    "processing_instruction": "PROCESS_AS_COMPLETE",
    "shard_number": 0,
    "total_shards": 1,
    "generation_timestamp": 1534731312
  },
  "merchant": [
    {
      "name": "Madison Square Garden",
      "telephone": "+1 123-456-7890",
      "merchant_id": "10000001",
      "geo": {
        "address": {
          "locality": "New York",
          "country": "US",
          "region": "NY",
          "street_address": "4 Pennsylvania Plaza",
          "postal_code": "10001"
        }
      }
    },
    {
      "name": "AT&T Stadium",
      "telephone": "+1 123-456-7891",
      "merchant_id": "10000002",
      "geo": {
        "address": {
          "locality": "Arlington",
          "country": "US",
          "region": "TX",
          "street_address": "1 AT&T Way",
          "postal_code": "76011"
        }
      }
    },
    {
      "name": "Prince of Wales Theatre",
      "merchant_id": "10000003",
      "geo": {
        "address": {
          "locality": "London",
          "country": "UK",
          "region": "London",
          "street_address": "Coventry St",
          "postal_code": "W1D 6AS"
        }
      }
    }
  ]
}

Merchant Feed Stay organized with collections Save and categorize content based on your preferences.

AI-generated Key Takeaways

MerchantFeed Definition

Merchant Definition

GeoCoordinates Definition

PostalAddress Definition

TaxRate Definition

TimeRange Definition

TokenizationConfig Definition

Terms Definition

Text Definition

LocalizedString Definition

MerchantMatchingHints Definition

ServiceAttribute Definition

Merchant Feed Sample

Merchant Feed

Merchant Feed