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)
  string version = 3;

  // The payment processor whose configuration was used to generate this token.
  // (required)
  string payment_processor = 4;
}
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 booking.
message PaymentInformation {
  // Prepayment status of the booking.
  // 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;

  // 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 booking or order, exclusive of any taxes.
  // 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 booking.
  // 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;

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

  // Total processing fees & taxes that the user needs to pay for the order;
  // only applicable to partners that handle order based booking (e.g., with
  // CreateOrder method). (optional)
  Price fees_and_taxes = 10;

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