// 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 sup&ported 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" } < // tokenizati>on_parameter { key: "stripe:publishableKey" value: "pk_1234" } // // Adyen example: // tokenization_parameter { key: "gateway" value: "adyen" } // tokenization_parameter { key: "gatewayMerchantId" value: "yourId" } mapstring, 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; }
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2024-11-26。
[null,null,["最后更新时间 (UTC):2024-11-26。"],[[["This API outlines methods for booking management, including checking availability, creating bookings, and updating or canceling existing ones."],["It defines data structures like `Slot`, `Booking`, and `UserInformation` to represent appointment slots, booking details, and user information respectively."],["The API supports payment processing through `PaymentInformation` and various `PaymentOptionTypes` including single-use, multi-use, and unlimited options."],["It incorporates features for error handling through `BookingFailure` messages and includes structures for managing user marketing preferences via `SetMarketingPreferenceRequest/Response`."],["Developers can leverage this API to integrate their applications with the booking system, enabling programmatic access to booking-related functionalities."]]],[]]