Booking failure specification

Booking failure can happen at the stage of (1) creating a Lease, or (2) creating or updating a Booking.

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

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

  // (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.
    // See https://www.emvco.com/emv-technologies/3d-secure/
    message ThreeDS1Parameters {
      // The URL from which to load a form to present to the User for
      // authentication (required).
      string acs_url = 1;

      // A PaymentAuthentication Request.  To be posted to the ACSUrl form if
      // supplied.
      //  (optional).
      string pa_req = 2;

      // An identifier used by the ACS provider.  To be posted to the ACSUrl
      // form if supplied (optional).
      string transaction_id = 3;

      // Merchant data used by the ACS provider.  To be posted to the ACSUrl
      // for if supplied (optional).
      string md_merchant_data = 4;
    }


    // Parameters used by a RwG partner to initiate a 3DS1 authentication
    // protocol with the user.  Will be ignored unless BookingFailure.cause
    // is set to PAYMENT_REQUIRES_3DS1.
    ThreeDS1Parameters threeds1_parameters = 5;
  }


  // Information about payment failures.
  PaymentFailureInformation payment_failure = 4;
}

  // Information about payment failures.
  message PaymentFailureInformation {
    // Parameters requesting that RwG perform a 3DS1 challenge.
    //
    // The parameters are set by EMVCo's description of the 3DS1 protocol.
    // See https://www.emvco.com/emv-technologies/3d-secure/
    message ThreeDS1Parameters {
      // The URL from which to load a form to present to the User for
      // authentication (required).
      string acs_url = 1;

      // A PaymentAuthentication Request.  To be posted to the ACSUrl form if
      // supplied.
      //  (optional).
      string pa_req = 2;

      // An identifier used by the ACS provider.  To be posted to the ACSUrl
      // form if supplied (optional).
      string transaction_id = 3;

      // Merchant data used by the ACS provider.  To be posted to the ACSUrl
      // for if supplied (optional).
      string md_merchant_data = 4;
    }


    // Parameters used by a RwG partner 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;
  }

    // The parameters are set by EMVCo's description of the 3DS1 protocol.
    // See https://www.emvco.com/emv-technologies/3d-secure/
    message ThreeDS1Parameters {
      // The URL from which to load a form to present to the User for
      // authentication (required).
      string acs_url = 1;

      // A PaymentAuthentication Request.  To be posted to the ACSUrl form if
      // supplied.
      //  (optional).
      string pa_req = 2;

      // An identifier used by the ACS provider.  To be posted to the ACSUrl
      // form if supplied (optional).
      string transaction_id = 3;

      // Merchant data used by the ACS provider.  To be posted to the ACSUrl
      // for if supplied (optional).
      string md_merchant_data = 4;
    }