Proto Interface

// API v3 public interface declaration
syntax = "proto3";

package ext.maps.booking.partner.v3;

// +------+------------------------------+----------------------------------+
// | Verb |          HTTP Path           |      Request/Response Body       |
// +------+------------------------------+----------------------------------+
// | GET  | /v3/HealthCheck              | -                                |
// |      |                              | -                                |
// +------+------------------------------+----------------------------------+
// | POST | /v3/BatchAvailabilityLookup  | BatchAvailabilityLookupRequest   |
// |      |                              | BatchAvailabilityLookupResponse  |
// +------+------------------------------+----------------------------------+
// | POST | /v3/CheckAvailability        | CheckAvailabilityRequest         |
// |      |                              | CheckAvailabilityResponse        |
// +------+------------------------------+----------------------------------+
// | POST | /v3/CreateBooking            | CreateBookingRequest             |
// |      |                              | CreateBookingResponse            |
// +------+------------------------------+----------------------------------+
// | POST | /v3/UpdateBooking            | UpdateBookingRequest             |
// |      |                              | UpdateBookingResponse            |
// +------+------------------------------+----------------------------------+
// | POST | /v3/GetBookingStatus         | GetBookingStatusRequest          |
// |      |                              | GetBookingStatusResponse         |
// +------+------------------------------+----------------------------------+
// | POST | /v3/ListBookings             | ListBookingsRequest              |
// |      |                              | ListBookingsResponse             |
// +------+------------------------------+----------------------------------+
// | POST | /v3/SetMarketingPreference   | SetMarketingPreferenceRequest    |
// |      |                              | SetMarketingPreferenceResponse   |
// +------+------------------------------+----------------------------------+

// BatchAvailabilityLookup method

message BatchAvailabilityLookupRequest {
  // ID of the merchant.
  string merchant_id = 1;

  // Multiple slot times to be checked for availability. All queried times apply
  // to the same merchant_id and service_id.
  repeated SlotTime slot_time = 3;

  reserved 2;
}

// Response for the [ext.maps.booking.partner.v3.BatchAvailabilityLookupRequest]
// RPC with the availabilities of the appointment slots.
message BatchAvailabilityLookupResponse {
  // The availabilities for the requested SlotTime entries. There must be
  // exactly one slot_time_availability for each SlotTime entry in the
  // [ext.maps.booking.partner.v3.BatchAvailabilityLookupRequest].
  repeated SlotTimeAvailability slot_time_availability = 1;
}


// Identifies a Slot service_id and start time and optionally, the Slot duration
// and resources, for a specific merchant. Note that this differs from the
// definition of Slot, as it does not include merchant_id identifier.
message SlotTime {
  // ID of the service. (required)
  string service_id = 5;

  // Start time of the appointment slot in seconds of UTC time since Unix epoch
  // (required)
  int64 start_sec = 1;

  // Duration of the appointment slot in seconds (optional)
  int64 duration_sec = 2;

  // Opaque tag that identifies the availability slot and matches the value
  // provided in the availability feed (optional)
  string availability_tag = 3;

  // The set of resources that specifies the appointment slot, e.g. by
  // indicating the staff member and room selected by the user, or party size
  // for dining slots (optional)
  ResourceIds resource_ids = 4;

  // Indicates whether bookings of this slot will be confirmed
  // synchronously or asynchronously. (optional)
  // An UNSPECIFIED value will be interpreted as synchronous.
  ConfirmationMode confirmation_mode = 6;
}


message SlotTimeAvailability {
  // The SlotTime for which availability was checked.
  SlotTime slot_time = 1;

  // Whether the requested SlotTime is available
  bool available = 2;
}


// CheckAvailability method

// Request to check availability for a Slot.
message CheckAvailabilityRequest {
  // The appointment slot that is being checked (required)
  Slot slot = 1;
}

// Response for the CheckAvailability RPC with the availability of the
// appointment slot.
message CheckAvailabilityResponse {
  // The requested slot. (required)
  Slot slot = 1;

  // Number of available spots.
  // 0 indicates that the appointment slot is not available. (required)
  int32 count_available = 2;

  // If set, the last time (in seconds since the Unix epoch) that this specific
  // appointment slot can be cancelled through Reserve with Google. This field
  // will override any service-level cancellation rules. (optional)
  //
  // Deprecated: Use scheduling_rule_overrides.last_online_cancellable_sec
  // in the Availability feed instead.
  int64 last_online_cancellable_sec = 5 [deprecated = true];

  // This enum indicates what requirements exist for the user to acknowledge or
  // view the requested slots duration/end time.
  enum DurationRequirement {
    // The handling of the end time is not specified. This is the default.
    DURATION_REQUIREMENT_UNSPECIFIED = 0;

    // The end time is not shown to the user.
    DO_NOT_SHOW_DURATION = 1;

    // The end time has to be shown to the user before an appointment can be
    // made.
    MUST_SHOW_DURATION = 2;
  }

  // The requirement to show the slots duration and/or endtime. This field will
  // be ignored if the slot is unavailable. (optional)
  //
  // Deprecated: Use duration_requirement in the Availability feed instead.
  DurationRequirement duration_requirement = 3 [deprecated = true];

  // Optionally, the partner can return additional updated information about the
  // availability for this merchant if this information is present when
  // responding to the CheckAvailabilityRequest and if there is no negative
  // impact on the CheckAvailability request latency.
  // For instance an entire day of merchant availability for a superset of
  // resources can be returned here.
  AvailabilityUpdate availability_update = 4;
}


// An update to one ore more slots indicating that the availability for the
// associated time has potentially changed.
message AvailabilityUpdate {
  repeated SlotAvailability slot_availability = 1;
}


// An inventory slot and associated count of open spots.
message SlotAvailability {
  Slot slot = 1;

  // Number of available spots.
  // 0 indicates that the appointment slot is not available. (required)
  int32 count_available = 2;
}


// GetBookingStatus method

// Request to get booking status and prepayment status for a Booking.
message GetBookingStatusRequest {
  // ID of the existing booking (required)
  string booking_id = 1;
}

// Response for the GetBookingStatus RPC with booking status and prepayment
// status.
message GetBookingStatusResponse {
  // ID of the booking (required)
  string booking_id = 1;

  // Status of the booking (required)
  BookingStatus booking_status = 2;

  // Prepayment status of the booking (required)
  PrepaymentStatus prepayment_status = 3;
}


// CreateBooking method

// Request to create a Booking for an inventory slot. Consumes the lease if
// provided.
message CreateBookingRequest {
  // The inventory slot that is being requested to make this booking.
  // If lease_ref is provided, slot must match the lease; slot is provided for
  // the partner to verify the lease information.
  // If lease_ref is absent, then create the booking for the slot. (required)
  Slot slot = 1;


  // Personal information of the user making the appointment (required)
  UserInformation user_information = 3;

  // Information about payments. When payment authorizations are handled by
  // Google, if the booking request does not succeed, payment authorizations are
  // automatically canceled. (optional)
  PaymentInformation payment_information = 4;

  // The parameters to be used if the payment is processed by the partner
  // (i.e. payment_information.payment_processed_by is equal to
  // PROCESSED_BY_PARTNER). (optional)
  PaymentProcessingParameters payment_processing_parameters = 5;

  // Idempotency token for CreateBooking requests. (required)
  //
  // This uniquely identifies a booking request. Specifically:
  // - If a booking was already created for a CreateBooking request with this
  // idempotency token, that booking should be returned.
  // - If no booking has been created for a CreateBooking request with this
  // idempotency token, this should be considered to be a request for a new
  // booking, and **no previously-created booking may be returned**.
  //
  // If a partner considers the requested booking to be a duplicate of a
  // previously-created booking, this request should fail with reason
  // BookingFailure.OVERLAPPING_RESERVATION. The partner is responsible for
  // determining whether this duplicates a previous booking, but for example the
  // partner may consider a booking request to be a duplicate if an existing
  // booking has the same party size, time, and email address.
  string idempotency_token = 6;

  // A string from the user which contains any special requests or additional
  // information that they would like to notify the merchant about. (optional)
  string additional_request = 7;

  // Partner provided offer id associated with this slot. (optional)
  //
  // If the offer is no longer available, the booking should not be made, and in
  // response.booking_failure should be set to OFFER_UNAVAILABLE.
  string offer_id = 9;

}

// Response with the created Booking for an inventory slot.
message CreateBookingResponse {
  // The created booking (required)
  Booking booking = 1;

  // The updated user payment option used in this booking.
  // If a new payment option was purchased to pay for the booking, this should
  // be a newly created user payment option.
  // If an already purchased user payment option was used for this booking,
  // this should reflect an updated version of that user payment option.
  // (optional)
  UserPaymentOption user_payment_option = 2;

  // If creating a booking fails, this field should reflect the business logic
  // error (e.g., slot has become unavailable) and all other fields in the
  // CreateBookingResponse message are expected to be unset. (required if
  // failure occurs)
  BookingFailure booking_failure = 3;
}


// CreateLease method

// Request to create a Lease for a slot in the inventory.  The expiration time
// in the returned Lease may be modified by the backend, e.g. if the requested
// lease period is too long.
message CreateLeaseRequest {
  // The lease to be created with information about the appointment slot
  // (required)
  Lease lease = 1;
}

// Response for the CreateLease RPC with the created Lease.
message CreateLeaseResponse {
  // The created Lease (required)
  Lease lease = 1;

  // If creating a lease fails, this field should reflect the business logic
  // error (e.g., slot has become unavailable) and lease field is expected to be
  // unset. (required if failure occurs)
  BookingFailure booking_failure = 2;
}


// Temporary lease for an inventory slot
message Lease {
  // ID of the lease.
  // Not populated in CreateLeaseRequest. The value is chosen by the partner and
  // has to be returned in the response of CreateLease. (required)
  string lease_id = 1;

  // The appointment slot that the lease is created for. (required)
  Slot slot = 2;

  // Unique identifier for this lease, chosen by Reserve with Google. Serves as
  // an idempotency token for CreateLease requests. (required)
  string user_reference = 3;

  // Expiration time of the lease in UTC Timestamp (required)
  int64 lease_expiration_time_sec = 4;
}

// Reference to a Lease that has been created via CreateLease.
message LeaseReference {
  // Lease ID (required)
  string lease_id = 1;
}


// ListBookings method

// Request to list all bookings for a user
message ListBookingsRequest {
  // ID of the user (required)
  string user_id = 1;
}

// Response for the ListBookings RPC with all bookings for the requested user.
message ListBookingsResponse {
  // All bookings of the user (required)
  repeated Booking bookings = 1;
}


// UpdateBooking method

// Request to update a Booking.
message UpdateBookingRequest {
  // The booking to be updated
  // The following fields can be set in a booking:
  // - status, to cancel a booking.
  // - one of the following is required:
  //   - start_time AND duration in the slot, to reschedule a booking.
  //   - party_size (for dining reservations).
  Booking booking = 1;
}

// Response with the updated Booking.
message UpdateBookingResponse {
  // The updated booking (required)
  Booking booking = 1;

  // The updated user payment option originally used to pay for this booking.
  // This should be set if the UpdateBookingRequest results in a change to
  // the UserPaymentOption.
  // For instance, if the booking is canceled, the UserPaymentOption should
  // reflect an additional credit to the user. In the case of a multi-use
  // payment option, the current_count should be increased by one to
  // allow the user to create another booking with this payment option. In the
  // case of a single-use payment option, a new single-use user payment option
  // should be returned. (required if altered in update)
  UserPaymentOption user_payment_option = 2;

  // If updating a booking fails, this field should reflect the business logic
  // error (e.g., booking is not cancellable) (required if failure occurs)
  BookingFailure booking_failure = 3;
}


// SetMarketingPreference method

// Request to set the partner marketing preference for a user.
message SetMarketingPreferenceRequest {
  // Personal information of the user setting a marketing preference (required)
  UserInformation user_information = 1;

  // Whether the specified user has consented to receive marketing (required)
  bool user_to_receive_marketing = 2;
}

// Response with the user's set marketing preference
message SetMarketingPreferenceResponse {
  // Personal information of the user setting a marketing preference (required)
  UserInformation user_information = 1;

  // Whether the specified user has consented to receive marketing (required)
  bool user_to_receive_marketing = 2;
}


// Booking specification

// A booking for an inventory slot
message Booking {
  // ID of this booking, which must be unique across all bookings. (required)
  string booking_id = 1;

  // The appointment slot of this booking
  // (required for CreateBooking and UpdateBooking:modify,
  // but not UpdateBooking:cancel)
  Slot slot = 2;

  // Personal information of the user making the appointment (required for
  // CreateBooking)
  UserInformation user_information = 3;

  // Status of the booking (required for CreateBooking and UpdateBooking:cancel,
  // but not UpdateBooking:modify)
  BookingStatus status = 4;

  // Information about payment transactions that relate to the booking.
  // (optional)
  PaymentInformation payment_information = 5;

  // Information about virtual session related to this booking. (optional)
  VirtualSessionInfo virtual_session_info = 6;

  // Information about the Offer applied to this booking.
  //
  // Required in CreateBookingResponse if an offer_id was set on the
  // CreateBookingRequest that created the Booking.
  OfferInfo offer_info = 7;
}


// BookingStatus specification

// Status of a booking.
//
// Updating booking status does not change the status of the associated payment.
// Prepayment status updates should be done using the PrepaymentStatus enum.
enum BookingStatus {
  // Not specified.
  BOOKING_STATUS_UNSPECIFIED = 0;

  // Booking has been confirmed
  CONFIRMED = 1;

  // Booking is awaiting confirmation by the merchant before it can transition
  // into CONFIRMED status. Only applicable to non-payments Dining or
  // Beauty verticals.
  PENDING_MERCHANT_CONFIRMATION = 2;

  // Booking has been canceled on behalf of the user.
  // The merchant can still trigger a manual refund.
  CANCELED = 3;

  // User did not show for the appointment
  NO_SHOW = 4;

  // User did not show for the appointment in violation of the cancellation
  // policy.
  NO_SHOW_PENALIZED = 5;

  // Booking could not be completed by the async backend due to a failure.
  FAILED = 6;

  // Booking was asynchronously declined by the merchant. Only applicable to
  // non-payments Dining or Beauty verticals.
  DECLINED_BY_MERCHANT = 7;
}


// VirtualSessionInfo specification

// Information related to the virtual session which was booked.
message VirtualSessionInfo {
  // URL which was created for the virtual session. (optional)
  string session_url = 1;

  // The meeting id which was created for the virtual session. (optional)
  string meeting_id = 2;

  // Password required to access the session. (optional)
  string password = 3 [(datapol.semantic_type) = ST_ACCOUNT_CREDENTIAL];
}


// BookingFailure specification

// Status data that conveys why (1) creating a lease or (2) creating or updating
// a booking fails.
// BookingFailure is intended to primarily capture business logic errors.
message BookingFailure {
  enum Cause {
    // Default value: Don't use; amounts to an "unknown error"
    CAUSE_UNSPECIFIED = 0;

    // The referenced availability slot is not available any longer.
    SLOT_UNAVAILABLE = 1;

    // The user has already booked an appointment for the referenced
    // availability slot.
    SLOT_ALREADY_BOOKED_BY_USER = 2;

    // The lease (if provided) has expired and cannot be used any longer to
    // complete the requested booking.
    LEASE_EXPIRED = 3;

    // The requested cancellation cannot be performed at the current time due
    // to time restrictions in the merchant's cancellation policy. In other
    // words, the booking can no longer be canceled by the user.
    OUTSIDE_CANCELLATION_WINDOW = 4;

    // 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 = 5;

    // An error was encountered while processing the payment because the
    // provided credit card was declined.
    PAYMENT_ERROR_CARD_DECLINED = 6;

    // An error was encountered with the pack/membership used to pay for the
    // booking. There could be no valid uses left, it could have expired, etc.
    PAYMENT_OPTION_NOT_VALID = 7;

    // An error was encountered while processing the payment for this booking.
    // 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 = 8;

    // User cannot use the given payment option (e.g. user trying to use a
    // first time price for the second time).
    USER_CANNOT_USE_PAYMENT_OPTION = 9;

    // A booking that the user tried to cancel has already been cancelled.
    BOOKING_ALREADY_CANCELLED = 10;

    // A booking that the user tried to cancel is not cancellable.
    BOOKING_NOT_CANCELLABLE = 11;

    // User has an existing reservation too close to this time.
    OVERLAPPING_RESERVATION = 12;

    // Booking failed due to the user being over the aggregator's per-user
    // bookings limit.
    USER_OVER_BOOKING_LIMIT = 13;

    // Offer (previously "Deal") is unavailable for the provided slot. If the
    // slot itself is unavailable, use SLOT_UNAVAILABLE instead.
    OFFER_UNAVAILABLE = 16;
    DEAL_UNAVAILABLE = 14 [deprecated = true];

    // 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 PAYMENT_ERROR.
    PAYMENT_REQUIRES_3DS1 = 15;
  }

  // The reason why the booking failed. (required)
  Cause cause = 1;

  // (required only if cause is PAYMENT_ERROR_CARD_TYPE_REJECTED)
  CreditCardType rejected_card_type = 2;

  // This optional field is used for the partner to include additional
  // information for debugging purpose only. (optional)
  string description = 3;

  // 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;
  }

  PaymentFailureInformation payment_failure = 4;
}


// Used when booking/order failure cause is PAYMENT_ERROR_CARD_TYPE_REJECTED to
// indicate the type of credit card that was rejected.
enum CreditCardType {
  // Default value. Used if credit card type does not match to one below.
  CREDIT_CARD_TYPE_UNSPECIFIED = 0;
  VISA = 1;
  MASTERCARD = 2;
  AMERICAN_EXPRESS = 3;
  DISCOVER = 4;
  JCB = 5;
}


  // 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;
  }


    // 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;
    }


// 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 '[phone]'
  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;
}