// API v3 public interface declaration
syntax = "proto3";
package ext.maps.booking.partner.v3;
// +------+------------------------------+----------------------------------+
// | Verb | HTTP Path | Request/Response Body |
// +------+------------------------------+----------------------------------+
// | GET | /v3/HealthCheck | - |
// | | | - |
// +------+------------------------------+----------------------------------+
// | POST | /v3/CheckOrderFulfillability | CheckOrderFulfillabilityRequest |
// | | | CheckOrderFulfillabilityResponse |
// +------+------------------------------+----------------------------------+
// | POST | /v3/CreateOrder | CreateOrderRequest |
// | | | CreateOrderResponse |
// +------+------------------------------+----------------------------------+
// | POST | /v3/ListOrders | ListOrdersRequest |
// | | | ListOrdersResponse |
// +------+------------------------------+----------------------------------+
// CheckOrderFulfillability method
// Request to check the fulfillability of an order.
message CheckOrderFulfillabilityRequest {
// The merchant that this order is intended for. (required)
string merchant_id = 1;
// The line items in this order. All services requested must belong to the
// specified merchant. (required)
repeated LineItem item = 2;
// An identifier for the contents of this cart (optional).
// This will be the same as the idempotency token in CreateorderRequest.
// This field can be ignored if you aren't setting an expiration time for
// the contents of the cart.
string cart_id = 3;
}
// Response for the CheckOrderfulfillabilityRequest.
message CheckOrderFulfillabilityResponse {
// Fulfillability status of the order, potentially contains updated
// availabilities and prices of the requested line item.
OrderFulfillability fulfillability = 1;
// Total processing fees & taxes that need to be paid for this order
// (required if fees and taxes will be charged on this order). This field
// will be deprecated; new users should populate fees instead.
Price fees_and_taxes = 2;
// Breakdown of the specific per-ticket and per-order fees and taxes.
Fees fees = 3;
// Time at which the cart will expire and its contents will no longer be
// available, in unix epoch time (optional).
// If not set, a default value will be used and the cart will not expire.
int64 cart_expiration_sec = 4;
}
// Breakdown of the specific, partner-named per-ticket and per-order fees and
// taxes.
message Fees {
// Fees and taxes that must be paid for each ticket the user purchases.
repeated SpecificPerTicketFee per_ticket_fee = 1;
// Fees and taxes that must be paid once per order, regardless of the number
// of tickets purchased.
repeated SpecificPerOrderFee per_order_fee = 2;
}
// The specific partner-named fees that must be paid for each ticket the user
// purchases.
message SpecificPerTicketFee {
// ID of a ticket type.
string ticket_id = 1;
// ID of the parent service of this ticket_type.
string service_id = 4;
// A localized partner-provided name for this fee or tax.
string fee_name = 2;
// The amount of the fee or tax.
Price fee_amount = 3;
}
// The specific partner-named fees that must be paid once per order, regardless
// of number of tickets.
message SpecificPerOrderFee {
// A localized partner-provided name for this fee or tax.
string fee_name = 1;
// The amount of the fee or tax.
Price fee_amount = 2;
}
// CreateOrder method
// Request to create an order.
message CreateOrderRequest {
// The order to create. (required)
Order order = 1;
// The parameters to be used if the payment is processed by the partner
// (i.e. order.payment_information.payment_processed_by is equal to
// PROCESSED_BY_PARTNER). (required if payment is processed by the partner)
PaymentProcessingParameters payment_processing_parameters = 2;
// Idempotency token for CreateOrder requests. (required)
string idempotency_token = 3;
}
// Response for the CreateOrderRequest.
message CreateOrderResponse {
// All line items in an order either fail or succeed together.
// This means that if some of the items cannot be fulfilled, the entire
// order must fail, the booking must not be made for any item, and the user
// must not be charged.
oneof result {
// The order created.
Order order = 1;
// If creating an order fails, this field should reflect the business logic
// error (e.g., slot has become unavailable or price has changed).
OrderFailure order_failure = 2;
}
}
// ListOrders method
// Request to list orders.
message ListOrdersRequest {
message OrderIds {
repeated string order_id = 1;
}
// Request of orders either by user ID, or by order ID.
oneof ids {
// If set, return all orders belong to the user.
string user_id = 1;
// If set, return the specified orders.
OrderIds order_ids = 2;
}
}
// Response for the ListOrders RPC.
message ListOrdersResponse {
// All requested orders (required)
repeated Order order = 1;
}
// Order specification
// An order for service appointments with a merchant.
message Order {
// ID of this Order, chosen by the booking partner who handles the order
// (required in CreateOrderResponse and ListOrdersResponse, must not be set in
// CreateOrderRequest)
string order_id = 1;
// Personal information of the user making the order (required)
UserInformation user_information = 2;
// Information about payment transactions that relate to the Order.
// (optional)
PaymentInformation payment_information = 3;
// The merchant that all services in this Order belong to.
string merchant_id = 4;
// Line items in this order.
repeated LineItem item = 5;
}
// A single item in an Order--the booking of a single service in a single time
// slot.
message LineItem {
// ID of the merchant Service. (required)
string service_id = 1;
// Start time of the appointment slot in seconds of UTC time since Unix epoch.
// (required)
int64 start_sec = 2;
// Duration of the appointment slot in seconds. (required)
int64 duration_sec = 3;
message OrderedTickets {
string ticket_id = 1;
int32 count = 2;
}
// Number of tickets ordered by Ticket Type.
repeated OrderedTickets tickets = 4;
// The price should be updated to the correct value if the line item can be
// fulfilled but the value from the request has changed. The updated price
// should align with the enum in the 'warning_reason' field below, otherwise
// the booking will be considered as failure. (required)
Price price = 5;
// Status of the Line Item. (required in CreateOrderResponse and
// ListOrdersResponse; should not be set in requests)
BookingStatus status = 6;
// The user's answers to merchant questions for this services.
// If there are both service level and per-ticket answers, this message will
// be ordered with service level answers first and per-ticket answers after.
// Will not be set in CheckOrderFulfillabilityRequest.
IntakeFormAnswers intake_form_answers = 7;
enum WarningReason {
UNSPECIFIED_WARNING_REASON = 0;
// This Line Item can be fulfilled and has increased in price.
PRICE_INCREASE = 1;
// This Line Item can be fulfilled and has decreased in price.
PRICE_DECREASE = 2;
}
// If the total price is different from the price in the request, please use
// this field to indicate a price change. The enum has to be aligned with the
// actual price change, otherwise the booking will be considered as failure.
WarningReason warning_reason = 8;
}
// User's answers to merchant questions.
message IntakeFormAnswers {
repeated IntakeFormFieldAnswer answer = 1;
}
message IntakeFormFieldAnswer {
// This id should be the same as the id of the corresponding question.
string id = 1;
// The response given by the user.
// One string for MULTIPLE_CHOICE, DROPDOWN, SHORT_ANSWER, and PARAGRAPH
// One string ("true" or "false") for BOOLEAN
// One or more strings for CHECKBOXES.
// For MULTIPLE_CHOICE, DROPDOWN or CHECKBOXES, the string would match exactly
// one of the (possibly localized) strings sent by partner in choice_text in
// the ServiceIntakeForm.
// For LOCATION_SEARCH, the response could be:
// 1. Matches one of the "location_id" in the "location" field in the
// service feed.
// 2. User input answer containing location information that are not
// provided in the feed.
repeated string response = 2;
}
// Status data that conveys why creating an order fails.
// OrderFailure is intended to primarily capture business logic errors.
message OrderFailure {
enum Cause {
// Default value: Don't use; amounts to an "unknown error"
CAUSE_UNSPECIFIED = 0;
// The order is no longer fulfillable.
ORDER_UNFULFILLABLE = 1;
// An error was encountered while processing the payment because the
// provided credit card type was not accepted by the merchant. The credit
// card type must be supplied in rejected_card_type.
PAYMENT_ERROR_CARD_TYPE_REJECTED = 2;
// An error was encountered while processing the payment because the
// provided credit card was declined.
PAYMENT_ERROR_CARD_DECLINED = 3;
// An error was encountered while processing the payment for this order.
// Use this value to indicate a general payment related error, only if the
// error does not match to a specific payment error above.
PAYMENT_ERROR = 4;
// The fee total in the request is incorrect or not up-to-date.
INCORRECT_FEE_TOTAL = 5;
// Set when payment is rejected because you are requesting that the
// transaction be tried again, but this time after undergoing 3DS1
// challenge/response. Note that the current transaction's failure state
// will stay failed. The retry will be completely separate.
//
// When this is the failure reason, payment_failure.3DS1_parameters
// MUST be set. If it is not, then the current cause will be treated as
// if it were AGGREGATOR_PAYMENT_ERROR.
PAYMENT_REQUIRES_3DS1 = 6;
}
// The reason why the order failed. (required)
Cause cause = 1;
// (required only if cause is ORDER_UNFULFILLABLE)
OrderFulfillability fulfillability = 2;
// (required only if cause is PAYMENT_ERROR_CARD_TYPE_REJECTED)
CreditCardType rejected_card_type = 3;
// This optional field is used for the partner to include additional
// information for debugging purpose only. (optional)
string description = 4;
// Information about payment failures.
message PaymentFailureInformation {
// Parameters requesting that RwG perform a 3DS1 challenge.
//
// The parameters are set by EMVCo's description of the 3DS1 protocol.
message ThreeDS1Parameters {
// The URL from which to load a form to present to the User for
// authentication.
string acs_url = 1;
// A PaymentAuthentication Request. To be posted to the ACSUrl form if
// supplied.
string pa_req = 2;
// An identifier used by the ACS provider. To be posted to the ACSUrl
// form if supplied.
string transaction_id = 3;
// Merchant data. To be posted to the ACSUrl form if supplied.
string md_merchant_data = 4;
}
// Parameters used by a RwG aggregator to initiate a 3DS1 authentication
// protocol with the user. Will be ignored unless BookingFailure.cause
// is set to PAYMENT_REQUIRES_3DS1.
ThreeDS1Parameters threeds1_parameters = 5;
}
// Information about payment failures.
PaymentFailureInformation payment_failure = 5;
}
// OrderFulfillability specification
message OrderFulfillability {
// The result of an order fulfillability check.
enum OrderFulfillabilityResult {
// Default value: Don't use.
ORDER_FULFILLABILITY_RESULT_UNSPECIFIED = 0;
// The order can be fulfilled.
CAN_FULFILL = 1;
// The order cannot be fulfilled due to one or more unfulfillable line
// item(s).
UNFULFILLABLE_LINE_ITEM = 2;
// The combination of the line items requested cannot be fulfilled.
UNFULFILLABLE_SERVICE_COMBINATION = 3;
// The order cannot be fulfilled due to reasons that do not fall into the
// categories above.
ORDER_UNFULFILLABLE_OTHER_REASON = 4;
}
OrderFulfillabilityResult result = 1;
// Fulfillability results of all line items in this order (required).
repeated LineItemFulfillability item_fulfillability = 2;
// Additional description of the reason if the item is unfulfillable.
// (optional)
string unfulfillable_reason = 3;
}
// Fulfillability of a line item.
message LineItemFulfillability {
// The line item of question. (required)
LineItem item = 1;
// The result of a line item fulfillability check.
enum ItemFulfillabilityResult {
// Default value: Don't use.
ITEM_FULFILLABILITY_RESULT_UNSPECIFIED = 0;
// This line item can be fulfilled.
CAN_FULFILL = 1;
// No adequate availability for the slot requested.
SLOT_UNAVAILABLE = 2;
// Child tickets cannot be booked without an adult ticket.
CHILD_TICKETS_WITHOUT_ADULT = 6;
// The combination of ticket types requested cannot be fulfilled.
UNFULFILLABLE_TICKET_COMBINATION = 3;
// The total price of this line item is not correct.
INCORRECT_PRICE = 4;
// The line item cannot be fulfilled since a ticket constraint specified by
// the partner has been violated.
TICKET_CONSTRAINT_VIOLATED = 7;
// The line item cannot be fulfilled for reasons that do not fall into
// the categories above.
ITEM_UNFULFILLABLE_OTHER_REASON = 5;
}
// (required)
ItemFulfillabilityResult result = 2;
// Additional description of the reason if the item is unfulfillable.
// (optional)
string unfulfillable_reason = 3;
// Updated availability for this slot can be piggybacked in
// CheckOrderFulfillabilityResponse.
message UpdatedAvailability {
// Number of available spots for the given slot. 0 indicates no
// availability. (required)
int32 spots_open = 1;
}
// (optional)
UpdatedAvailability availability = 4;
// If the item can be fulfilled and any ticket in the booking has changed from
// the price in the request at the individual ticket level, please use this
// field to return updated ticket types.
// Ticket type is required only when the actual price of individual tickets
// changed from the price in the request. Ticket type is NOT required for
// price decrease because of deals or promotions, combo tickets, group
// tickets, reduced price for special group of users. In this case, the
// individual ticket price has not changed but there is a price decrease for
// the booking.
// If the price of a single ticket type changes, please return the following:
// 1. Populate 'ticket_type' message for every distinct ticket_type_id
// specified in the request.
// -- Required fields in the TicketType message: 'ticket_type_id', 'price'
// -- Optional fields in the TicketType message: 'fees_and_tax',
// 'localized_short_description', 'localized_option_description',
// 'option_description', 'short_description'
// 2. Updated price in the LineItem.
// 3. Corresponding warning reason enum.
// Ticket is the quantity unit of a given service at a certain time slot that
// users can make reservations for. For example, a spot on a raft trip or an
// admission to a museum. TicketType is used to differentiate among tickets
// with different prices and/or availabilities due to different user types or
// different service attributes. If non-empty, all available ticket types for
// this slot with up-to-date prices should be listed without omitting any.
// (optional)
repeated TicketType ticket_type = 5;
// This proto will represent all the constraints violated by the user.
// Below are all the ways in which a violated_constraint can be represented.
//
// 1 : Constraint violation for the entire line item.
// { violated_ticket_constraint : { min_ticket_count : 5 } }
//
// 2 : Constraint violation for a ticket type within a line item.
// { violated_ticket_constraint : { min_ticket_count : 5, ticket_id : "ttd1"}}
//
// 3 : Constraint violation for multiple ticket types within a line item.
// { violated_ticket_constraint : { min_ticket_count : 3, ticket_id : "ttd1"}}
// { violated_ticket_constraint : { min_ticket_count : 4, ticket_id : "ttd2"}}
//
// 4 : Constraint violation for entire line item as well as an override
// for multiple ticket types within the availability slot.
// { violated_ticket_constraint : { min_ticket_count : 8 } }
// { violated_ticket_constraint : { min_ticket_count : 3, ticket_id : "ttd1"}}
// { violated_ticket_constraint : { min_ticket_count : 4, ticket_id : "ttd2"}}
//
message ViolatedTicketConstraint {
oneof value {
int32 min_ticket_count = 1;
int32 max_ticket_count = 2;
}
reserved 3;
// The absence of this field indicates that the constraint applies to
// the entire line item.
string ticket_id = 4;
}
// This must be set if ItemFulfillabilityResult is TICKET_CONSTRAINT_VIOLATED.
repeated ViolatedTicketConstraint violated_ticket_constraint = 6;
}
// TicketType is used to differentiate among tickets (where a ticket can be a
// spot on a raft trip, an admission to a museum, etc.) with different prices
// and/or availabilities due to different user types or different service
// attributes.
// Only add new ticket types when at least one of the following differs:
// (1) short_description (2) option_description (3) price
message TicketType {
// The ticket id is used to differentiate among different ticket types of the
// same service, and is only expected to be unique within a service.
string ticket_type_id = 1;
// This can be user visible, e.g., “adult”, "child", “veteran”, “Row J”, etc.
// Deprecated, use `localized_short_description` instead.
string short_description = 2 [deprecated = true];
// This can be user visible, e.g., “adult”, "child", “veteran”, “Row J”, etc.
// The field can be supplied in multiple locales.
Text localized_short_description = 6;
// The price of a single ticket of this type, exclusive of any taxes. The tax
// rate of Service is applied to its tickets.
Price price = 3;
// Additional fees for purchasing this ticket. (optional)
PerTicketFee per_ticket_fee = 5;
// Description of any additional option which this ticket type represents, if
// any. Deprecated, use `localized_option_description` instead.
string option_description = 4 [deprecated = true];
// Description of any additional option which this ticket type represents, if
// any. The field can be supplied in multiple locales.
//
// This is useful when the ticket type represents multiple dimensions.
//
// Example: an admission ticket with different types 'adult', 'child' and
// language as an additional option, the expected TicketType list would be:
// - { ticket_type_id: "ticket_type_1"
// localized_short_description { value: "adult" }
// localized_option_description { value: "english" }
// }
// - { ticket_type_id: "ticket_type_2"
// localized_short_description { value: "adult" }
// localized_option_description { value: "spanish" }
// }
// - { ticket_type_id: "ticket_type_3"
// localized_short_description { value: "child" }
// localized_option_description { value: "english" }
// }
// - { ticket_type_id: "ticket_type_4"
// localized_short_description { value: "child" }
// localized_option_description { value: "spanish" }
// }
//
// Optional, but if any ticket type within the service has this field set, we
// expect all other ticket types to have this field set as well (a default
// option_description could be used). E.g.
// [{ticket_type_1, adult, english}, {ticket_type_1, adult, ''}] is not a
// valid list.
//
// Only two HTML formatting tags are supported: <em> and <br>. They are
// intended to be used for specifying options with both a title and
// detailed description, for example: "<em>Premium Seating</em><br>This option
// offers seating at the private boxes including fully cushioned seats,
// private TVs, in-seat food and beverage service. These seats provide
// picturesque views of the field."
Text localized_option_description = 7;
}
// Fees that must be paid for each ticket the user purchases. These fields
// must add up to the total per ticket fee.
message PerTicketFee {
// An extra charge assessed for a service.
Price service_charge = 1;
// A fee that goes to the venue/facility.
Price facility_fee = 2;
// Per ticket taxes.
Price taxes = 3;
}
// 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;
}
// 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;
}
// Other specifications
// Resource specification that disambiguates an appointment slot
message ResourceIds {
// The staff ID as provided in the feed or empty if not applicable or no staff
// was selected. (optional)
string staff_id = 1;
// The room ID as provided in the feed or empty if not applicable or no room
// was selected. (optional)
string room_id = 2;
// For Dining Reservations only: the number of seats requested in the booking.
// (optional)
int32 party_size = 3;
}
// Information about an Offer applied to a booking.
message OfferInfo {
// The ID of the Offer.
string offer_id = 1;
}
// Payment specification
message PaymentProcessingParameters {
enum PaymentProcessor {
PAYMENT_PROCESSOR_UNSPECIFIED = 0;
PROCESSOR_STRIPE = 1;
PROCESSOR_BRAINTREE = 2;
}
// The payment processor used to process payment for a given booking.
// (required)
//
// Replaced by the payment_processor field.
PaymentProcessor processor = 1 [deprecated = true];
// The token representing the payment method that will be used to pay
// for this booking. This token can be only used once. This token can be
// only used for the merchant associated with this booking.
//
// Each processor may choose its own format for this field.
// An example of Stripe's token is "tok_1C3orL2eZvKYlo2CxReMgS4K".
//
// Replaced by unparsed_payment_method_token, which contains
// payment_method_token as one of its fields.
// For example, for Stripe, unparsed_payment_method_token is a serialized
// JSON object documented at https://stripe.com/docs/api#token_object.
// payment_method_token is the 'id' field parsed out of that.
string payment_method_token = 2 [deprecated = true];
// The full token received from Google Payments. This is typically a
// serialized JSON object. See documentation from Google Payments and your
// payment processor for the JSON format of the token for your processor.
// https://developers.google.com/pay/api/#participating-google-pay-processors
//
// This token can only be used once, and only for the merchant associated with
// this booking.
string unparsed_payment_method_token = 5
;
// The payment processor API version that the given payment token is valid
// for.
//
// Each processor may choose its own format for this field.
// Stripe uses a date (e.g. "2017-06-15"). (required if and only if the
// payment processor has a tokenization parameter for version)
// This is deprecated in favor of tokenization_parameters.
string version = 3 [deprecated = true];
// The payment processor whose configuration was used to generate this token.
// (required)
// This is deprecated in favor of tokenization_parameters.
string payment_processor = 4 [deprecated = true];
// The tokenization_config supplied in the Merchant feed that was used
// to generate unparsed_payment_method_token.
TokenizationConfig tokenization_config = 6;
}
enum PaymentOptionType {
PAYMENT_OPTION_TYPE_UNSPECIFIED = 0;
PAYMENT_OPTION_SINGLE_USE = 1;
PAYMENT_OPTION_MULTI_USE = 2;
PAYMENT_OPTION_UNLIMITED_USE = 3;
}
// This describes a payment option, such as a pack, membership, or
// single-session pass after it has been purchased by a user. It includes an
// identifier for the user payment option, as well as some information about
// the payment option with which it is associated.
message UserPaymentOption {
// A unique identifier for the user payment option. This Id MUST be unique
// for all UserPaymentOptions across all merchants and users. (required)
string user_payment_option_id = 1;
// The user payment option will be valid (usable) between start_time and
// end_time set in UTC. Attempts to use a user payment option to make a
// booking outside of this interval will fail. (both optional)
int64 valid_start_time_sec = 2;
int64 valid_end_time_sec = 3;
// The type of the payment option associated with this user payment option.
// This can be unlimited for a membership or subscription, multi-use for a
// pack, or single-use. (required)
PaymentOptionType type = 4;
// The original number of uses for this user payment option when it was
// purchased. This value is ignored for unlimited payment options. (required)
int32 original_count = 5;
// The number of uses remaining for this user payment option. If this number
// is 0 for a pack, attempts to use this payment option to make a booking will
// fail. (required)
int32 current_count = 6;
// The id of the payment option that has been used to purchase this user
// payment option. (required)
string payment_option_id = 7;
}
// Payment details that are sent when creating a new transaction (which could be
// a booking, order, or parking session).
message PaymentInformation {
// Prepayment status of the transaction.
// If the prepayment_status is PREPAYMENT_PROVIDED, then
// payment_transaction_id contains the associated unique transaction id for
// the purchase.
// If the prepayment status is PREPAYMENT_REFUNDED, then
// payment_transaction_id contains the associated unique transaction id for
// the refund. (required)
PrepaymentStatus prepayment_status = 1;
// Unique identifier for a payment transaction associated with the booking.
// If the payment is PROCESSED_BY_GOOGLE, this field will be set by Google.
// If the payment is PROCESSED_BY_PARTNER, this field will be left empty in
// Google's CreateBooking or CreateOrder requests to the partner, and it must
// be set by the partner in their responses.
string payment_transaction_id = 2;
// For bookings or orders, these fields must match the service price
// (specified in the Services feed) or the PaymentOption corresponding with
// this service. They are included in the booking request and response to
// verify that the price indicated in the feed has not changed since the last
// feed update.
//
// The price of the transaction, exclusive of any taxes and fees.
// Existence of price or taxes does not imply that they have been paid,
// prepayment_state should be used for that purpose. (required)
Price price = 3;
// Taxes that are calculated to be paid for this transaction.
// This field can only be absent in one of the following cases:
// (1) the price is exempt from or already inclusive of applicable taxes; or
// (2) the break down between taxes and fees is not available.
// (required when neither of the above holds)
Price tax_amount = 4;
// Additional fees associated with this transaction, if any.
//
// The use of this field should be consistent with other pricing related
// fields:
// - if a {price, tax, fees} breakdown is provided for service or
// availability, use the same breakdown {price, tax, fees} here.
// - if the price field for service or availability already includes taxes
// or fees, keep using price field to includes taxes or fees and avoid
// setting the tax_amount or fees fields here.
// Note: this is only supported for non-order based transactions.
Price fees = 14;
// Total processing fees & taxes that the user needs to pay for the order;
// only applicable to partners that handle order based transactions.
// If the order would incur non-zero fees based on
// the partner's response during CheckOrderFulfillability, Google would set
// this field during CreateOrder; otherwise, the field would be unset.
// The partner should verify this value, in addition to the `price` value,
// before charging the user.
Price fees_and_taxes = 10;
// Defines how a deposit may be charged to the user. If there is a deposit,
// this field should be set. (optional)
Deposit deposit = 8;
// Defines a no show fee that may be charged to the user. If the user can be
// charged a no show fee, this field should be set. (optional)
NoShowFee no_show_fee = 9;
// Who handles payment processing?
// If payment is processed by the partner, CreateBooking request will
// include additional parameters (PaymentProcessingParameters) indicating
// the payment method to be used to process the payment.
enum PaymentProcessedBy {
PAYMENT_PROCESSED_BY_UNSPECIFIED = 0;
PROCESSED_BY_GOOGLE = 1;
PROCESSED_BY_PARTNER = 2;
}
// Whether the partner or Google processed the payment. (required)
PaymentProcessedBy payment_processed_by = 5;
// The id of the payment option or user payment option associated with the
// booking.
// If a payment option is purchased as part of a booking, payment_option_id
// will be set with the id of that payment option.
// If an already purchased user payment option is being used to pay for a
// booking, user_payment_option_id will be set with the id of that user
// payment option.
// When included as part of a response proto, the user_payment_option_id
// should be set and must match the UserPaymentOption that is returned in the
// RPC response (e.g. the user_payment_option returned in
// CreateBookingResponse). (one of these required)
oneof payment_id {
// The id of the payment option associated with this booking. If this field
// is populated, price (and tax_amount, if applicable) must be populated as
// well.
string payment_option_id = 6;
// The id of the user payment option used to pay for this booking.
string user_payment_option_id = 7;
}
// Fraud signals that are sent to the partner as per agreement with Google.
// The signals are sent via a serialized JSON blob.
string fraud_signals = 11;
// After we engage in a 3DS1 protocol gaining further authentication
// information from a user, this payload is returned to us from an ACS
// provider, and it should be used by the partner to complete the 3DS1
// protocol.
string pa_response = 12;
// After we engage in a 3DS1 protocol gaining further authentication
// information from a user, this payload may be returned to us from an ACS
// provider, and if provided, it should be used by the partner to complete the
// 3DS1 protocol.
string md_merchant_data = 13;
}
// Prepayment status of a booking.
// Updating payment status will trigger an update on the payment status of the
// associated booking (if applicable).
// Currently, the only supported transition is from PREPAYMENT_PROVIDED to
// PREPAYMENT_REFUNDED, which will initiate a non-reversible refund on the
// associated payment transaction.
enum PrepaymentStatus {
// Not specified, defaults to PREPAYMENT_NOT_PROVIDED.
PREPAYMENT_STATUS_UNSPECIFIED = 0;
// The fee for the booking has been paid in advance.
PREPAYMENT_PROVIDED = 1;
// The fee for the booking has not been paid in advance.
PREPAYMENT_NOT_PROVIDED = 2;
// The fee was previously PREPAYMENT_PROVIDED but has now been refunded.
PREPAYMENT_REFUNDED = 3;
// The fee was previously PREPAYMENT_PROVIDED but now has been credited
// (user given a UserPaymentOption as a voucher for the booking).
// If this is set, the response should also include the updated
// UserPaymentOption.
PREPAYMENT_CREDITED = 4;
}
// The price of a service or a fee.
message Price {
// The price in micro-units of the currency.
// For example: 1.95 USD is 1950000 in micro-units.
// If your price contains fractions of the smallest currency unit, then it
// will be rounded using nearest even rounding (e.g. 2.5 cents rounded
// to 2 cents, 3.5 cents rounded to 4 cents, 0.5 cents rounded to 0 cents,
// 2.51 cents rounded to 3 cents). (required)
int64 price_micros = 1;
// The currency of the price that is defined in ISO 4217. (required)
string currency_code = 2;
// An optional and opaque string that identifies the pricing option that is
// associated with the extended price. (optional)
string pricing_option_tag = 3;
}
// Defines how a total price is determined from an availability.
enum PriceType {
// The price is for a fixed amount. This is the default value if the field is
// not set.
//
// Examples:
// $50 deposit to reserve a table; $20 no show fee for a yoga class
FIXED_RATE_DEFAULT = 0;
// The price specified is per person, and the total price is calculated
// according to the party size specified in Resources as price_micros *
// party_size. A PER_PERSON price must be accompanied by a party size in the
// availability resources. If it is not, a party size of one is used.
//
// Examples:
// $10 each for tickets to a museum
PER_PERSON = 1;
}
// A fee that a user may be charged if they have made a booking but do not
// show up.
message NoShowFee {
// The amount the user may be charged if they do not show up for their
// reservation.
Price fee = 1;
// Defines how the fee is determined from the availability.
PriceType fee_type = 3;
}
// A deposit that the user may be charged or have a hold on their credit card
// for.
message Deposit {
// Deposit amount.
Price deposit = 1;
// Minimum advance cancellation for the deposit.
int64 min_advance_cancellation_sec = 2;
// Defines how the deposit is determined from the availability.
PriceType deposit_type = 3;
}
// TokenizationConfig specification
// 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;
}
// Restrictions to the credit card types this merchant accepts.
message CreditCardRestrictions {
// A credit card type.
enum CreditCardType {
// Unused.
CREDIT_CARD_TYPE_UNSPECIFIED = 0;
// A Visa credit card.
VISA = 1;
// A Mastercard credit card.
MASTERCARD = 2;
// An American Express credit card.
AMERICAN_EXPRESS = 3;
// A Discover credit card.
DISCOVER = 4;
// A JCB credit card.
JCB = 5;
}
// A list of supported credit cards. No credit cards are supported if empty.
// (optional)
repeated CreditCardType credit_card_type = 1;
}
// ConfirmationMode specification
// Mode by which bookings for an availability slot are confirmed.
//
enum ConfirmationMode {
// The confirmation mode was not specified.
// Synchronous confirmation will be assumed.
CONFIRMATION_MODE_UNSPECIFIED = 0;
// Bookings for this availability will be confirmed synchronously.
CONFIRMATION_MODE_SYNCHRONOUS = 1;
// Bookings for this availability will be confirmed asynchronously.
CONFIRMATION_MODE_ASYNCHRONOUS = 2;
}
// Slot specification
// An inventory slot
message Slot {
// ID of the merchant for the slot (required for CreateBooking)
string merchant_id = 1;
// ID of the merchant Service (required for CreateBooking)
string service_id = 2;
// Start time of the appointment slot in seconds of UTC time since Unix epoch.
// (required for CreateBooking)
int64 start_sec = 3;
// Duration of the appointment slot (required for CreateBooking)
int64 duration_sec = 4;
// Opaque tag that identifies the availability slot and matches the value
// provided in the availability feed (optional)
string availability_tag = 5;
// The set of resources that disambiguates the appointment slot, e.g. by
// indicating the staff member and room selected by the user (optional)
ResourceIds resources = 6;
// Indicates whether bookings of this slot will be confirmed
// synchronously or asynchronously. (optional)
// An UNSPECIFIED value will be interpreted as synchronous.
ConfirmationMode confirmation_mode = 7;
}
// User specification
// Personal information about the person taking action (e.g. making a
// booking, an order, or creates a parking session).
message UserInformation {
// Unique ID of the user to the partner, chosen by Reserve with Google.
// (required)
string user_id = 1;
// Given name of the user (maximum 40 characters) (required)
string given_name = 2;
// Family name of the user (maximum 40 characters) (required)
string family_name = 3;
// Address of the user (optional)
PostalAddress address = 4;
// Phone number of the user (required)
// Consistent with the international definition in ITU-T E.123 recommendation.
// However, local conventions are also followed, such as using '-' instead of
// a space as separator. For example, a phone number in the US can be
// written as '+1 415-736-0000'
string telephone = 5;
// Email address of the user (required except for waitlists)
string email = 6;
// User's language code, in IETF BCP 47 format. It is sent only if a partner
// is allowed to use this feature. Please contact Reserve with Google team
// to be added to the allowlist and receive this code. (optional)
string language_code = 7;
reserved 8;
}
// 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;
}
Proto bundle
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2020-09-24 UTC.