OrderFailure specification

Order failure can happen at the stage of creating or updating an Order.

OrderFailure Definition

// Status data that conveys why creating an order fails.
// OrderFailure is intended to primarily capture business logic errors.
message OrderFailure {
  enum Cause {
    // Default value: Don't use; amounts to an "unknown error"
    CAUSE_UNSPECIFIED = 0;
    // The order is no longer fulfillable.
    ORDER_UNFULFILLABLE = 1;
    // An error was encountered while processing the payment because the
    // provided credit card type was not accepted by the merchant. The credit
    // card type must be supplied in rejected_card_type.
    PAYMENT_ERROR_CARD_TYPE_REJECTED = 2;
    // An error was encountered while processing the payment because the
    // provided credit card was declined.
    PAYMENT_ERROR_CARD_DECLINED = 3;
    // An error was encountered while processing the payment for this order.
    // Use this value to indicate a general payment related error, only if the
    // error does not match to a specific payment error above.
    PAYMENT_ERROR = 4;
    // The fee total in the request is incorrect or not up-to-date.
    INCORRECT_FEE_TOTAL = 5;
    // Set when payment is rejected because you are requesting that the
    // transaction be tried again, but this time after undergoing 3DS1
    // challenge/response.  Note that the current transaction's failure state
    // will stay failed.  The retry will be completely separate.
    //
    // When this is the failure reason, payment_failure.3DS1_parameters
    // MUST be set.  If it is not, then the current cause will be treated as
    // if it were AGGREGATOR_PAYMENT_ERROR.
    PAYMENT_REQUIRES_3DS1 = 6;
  }
  // The reason why the order failed. (required)
  Cause cause = 1;

  // (required only if cause is ORDER_UNFULFILLABLE)
  OrderFulfillability fulfillability = 2;

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

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

  // Information about payment failures.
  message PaymentFailureInformation {
    // Parameters requesting that RwG perform a 3DS1 challenge.
    //
    // The parameters are set by EMVCo's description of the 3DS1 protocol.
    message ThreeDS1Parameters {
      // The URL from which to load a form to present to the User for
      // authentication.
      string acs_url = 1;
      // A PaymentAuthentication Request.  To be posted to the ACSUrl form if
      // supplied.
      string pa_req = 2;
      // An identifier used by the ACS provider.  To be posted to the ACSUrl
      // form if supplied.
      string transaction_id = 3;
      // Merchant data.  To be posted to the ACSUrl form if supplied.
      string md_merchant_data = 4;
    }

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

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

CreditCardType Definition

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