Merchant Feed

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;

  // This field is deprecated, please use tax_rate instead.
  uint32 tax_rate_basis_points = 8 [deprecated = true];

  // The merchant's tax rate. If present this field overrides the deprecated
  // tax_rate_basis_points field. An empty message (i.e. tax_rate { }) will
  // reset the applied tax rate to zero.
  //
  // This field is required for payments integration. (optional)
  TaxRate tax_rate = 9;

  // Restrictions to the payment methods this merchant accepts. We assume no
  // restrictions exist if this field is not set. (optional)
  PaymentRestrictions payment_restrictions = 10;

  // Payment options available for this merchant. Services under this merchant
  // will be able to individually limit the payment options they allow.
  // (optional)
  repeated PaymentOption payment_option = 11;


  // Configuration for a tokenized payment processor, if the merchant has
  // support for it.
  TokenizationConfig tokenization_config = 15;

  // 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"
        }
      }
    }
  ]
}