Sale Service ============ The sale service provides endpoints to purchase (virtual) items or physical cards for the user or for another person (i.e., a gift). .. contents:: Topics Flow For Non Logged In User --------------------------- .. image:: egift_sale_flow.png 1. A successful call to :http:get:`sale/saleConfig.json` will return a "Program" object which contains the shipping/payment methods available to the user and the customization options for the specified eGift program. 2. User will select an image/amount for the eGift and provide information about the gift recipient. 3. The call to :http:post:`sale/calculatePrice.json` includes the items ordered and the shipping method. The server applies per-item and per-order discounts and returns a summary of the sale order in a successful response. 4. The summary is displayed to the user and the user proceeds to checkout 5. Perform a call to :http:post:`sale/executeSale.json` with shipping, billing, and sale information. The successful response returns a summary of the completed sale. Endpoints --------- Get Sale Configuration for Program ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:get:: sale/saleConfig.json Returns information for the configuration and display of an "order" page. Codes and values in the response to this endpoint will be used when calling the :http:post:`sale/executeSale.json` endpoint. .. note:: This endpoint is typically used for non-logged-in users since some sale programs can be performed without having an account. See :http:get:`sale/saleConfigForAccount.json` for logged-in users. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` * :ref:`anonymous_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :query String programType: *(required)* Paytronix-assigned code. See :ref:`web_sale_program_type` for values. :query Integer cardTemplateCode: *(required)* Paytronix-assigned card template code identifying the card type of the user. :query Integer tierCode: *(required)* Paytronix-assigned tier code identifying the tier grouping of the user. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam Object program: *(required)* See :http:jsonentity:`Program` for format of the object. .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. Get Sale Configuration for Account ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:get:: sale/saleConfigForAccount.json Returns information for the configuration and display of an "order" page. Codes and values in the response to this endpoint will be used when calling the :http:post:`sale/executeSaleForAccount.json` endpoint. .. note:: This endpoint is used for logged-in users. See :http:get:`sale/saleConfig.json` for non-logged-in users. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` * :ref:`oauth_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :query String programType: *(required)* Paytronix-assigned code. See :ref:`web_sale_program_type` for values. :query String printedCardNumber: *(required)* The card of the user. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam Object program: *(required)* See :http:jsonentity:`Program` for format of the object. .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. Get Loyalty Card Sale Config ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:get:: sale/loyaltyCardSaleConfig.json Returns information for the configuration and display of an "order" page. Codes and values in the response to this endpoint will be used when calling the :http:post:`sale/executeSale.json` endpoint. This end point is specific for loyalty card sales. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` * :ref:`oauth_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam Object program: *(required)* See :http:jsonentity:`LoyaltyCardSaleProgramConfig` for format of the object. .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. Execute Sale Without an Account ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:post:: sale/executeSale.json Executes the sale for the specified program and input fields. .. note:: This endpoint is typically used for non-logged-in users since some sale programs can be performed without having an account. See :http:post:`sale/executeSaleForAccount.json` for logged-in users. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` * :ref:`anonymous_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam Integer cardTemplateCode: *(required)* Paytronix-assigned card template code identifying the card type of the user. :jsonparam Integer tierCode: *(required)* Paytronix-assigned tier code identifying the tier grouping of the user. :jsonparam String programType: *(required)* Paytronix-assigned code. See :ref:`web_sale_program_type` for values. :jsonparam Object billingContact: *(required)* See :http:jsonentity:`Contact` for format of the object. :jsonparam Object billingAddress: *(required)* See :http:jsonentity:`Address` for format of the object. :jsonparam Boolean shippingSameAsBilling: *(required)* If true, then the ``shippingContact`` and ``shippingAddress`` are optional and will be defaulted from ``billingContact`` and ``billingAddress``. :jsonparam Object shippingContact: *(required)* See :http:jsonentity:`Contact` for format of the object. :jsonparam Object shippingAddress: *(required)* See :http:jsonentity:`Address` for format of the object. :jsonparam Object paymentMethod: *(required)* See :http:jsonentity:`PaymentMethod` for format of the object. :jsonparam String shippingOptionCode: *(optional)* One of the shipping option codes returned by the :http:get:`sale/saleConfig.json` call if required by the chosen program. :jsonparam Decimal totalPrice: *(required)* This is the value returned by a previous :http:post:`sale/calculatePrice.json` call. It is used to confirm that none of the prices and discounts have changed since the user started the sale workflow. :jsonparam Int promotionItemCount: *(optional)* This is the value returned by a previous :http:post:`sale/calculatePrice.json` call. It is used to confirm that none of the promotional items have changed since the user started the sale workflow. **This value MUST match the promotionItemCount value returned in the calculatePrice response, otherwise the sale will be declined** :jsonparam Boolean hasGiftBox: *(optional)* If true and relevant to the program, then the items will be in a gift box. :jsonparam String activationStoreCode: *(optional)* If required by the program, then this will be the store to which newly created cards will be associated. :jsonparam List[Object] orderItemGroups: *(required)* See :http:jsonentity:`OrderItemGroup` for format of the objects. :jsonparam String originatingIP: *(optional)* The client IP of the person placing the order. :jsonparam String callingIp: *(optional)* The IP address of the integration making the request. :jsonparam String stripePaymentIntent: *(optional)* The stripe payment intent ID for a web sale program using a Stripe Checkout CC Processor. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam Object order: *(required)* See :http:jsonentity:`SaleOrder` for format of the object .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. Execute Sale With an Account ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:post:: sale/executeSaleForAccount.json Executes the sale for the specified program and input fields. .. note:: This endpoint is for logged-in users. See :http:post:`sale/executeSale.json` for non-logged-in users. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` * :ref:`oauth_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String programType: *(required)* See :ref:`web_sale_program_type` for values. :jsonparam String printedCardNumber: *(required)* The card of the user :jsonparam Object billingContact: *(required)* See :http:jsonentity:`Contact` for format of the object. :jsonparam Object billingAddress: *(required)* See :http:jsonentity:`Address` for format of the object. :jsonparam Boolean shippingSameAsBilling: *(required)* If true, then the ``shippingContact`` and ``shippingAddress`` are optional and will be defaulted from ``billingContact`` and ``billingAddress``. :jsonparam Object shippingContact: *(required)* See :http:jsonentity:`Contact` for format of the object. :jsonparam Object shippingAddress: *(required)* See :http:jsonentity:`Address` for format of the object. :jsonparam Object paymentMethod: *(required)* See :http:jsonentity:`PaymentMethod` for format of the object. :jsonparam String shippingOptionCode: *(optional)* One of the codes returned by the :http:get:`sale/saleConfig.json` call if required by the program. :jsonparam Decimal totalPrice: *(required)* This is the value returned by a previous :http:post:`sale/calculatePrice.json` call. It is used to confirm that none of the prices and discounts have changed since the user started the sale workflow. :jsonparam Boolean hasGiftBox: *(optional)* If true and relevant to the program, then the items will be in a gift box. :jsonparam String activationStoreCode: *(optional)* If required by the program, then this will be the store to which newly created cards will be associated. :jsonparam List[Object] orderItemGroups: *(required)* See :http:jsonentity:`OrderItemGroup` for format of the objects. :jsonparam String originatingIP: *(optional)* The client IP of the person placing the order. :jsonparam String callingIp: *(optional)* The IP address of the integration making the request. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam Object order: *(required)* See :http:jsonentity:`SaleOrder` for format of the object .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. Execute Loyalty Card Sale ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:post:: sale/executeLoyaltyCardSale.json Executes the sale for a loyalty card. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` * :ref:`oauth_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam Object billingContact: *(required)* See :http:jsonentity:`Contact` for format of the object. :jsonparam Object billingAddress: *(required)* See :http:jsonentity:`Address` for format of the object. :jsonparam Object shippingInformation: *(optional)* See :http:jsonentity:`ShippingAddress` for format of the object. :jsonparam String favoriteStoreCode: *(optional)* The store the user selects as their home location :jsonparam Object paymentMethod: *(required)* See :http:jsonentity:`PaymentMethod` for format of the object. :jsonparam Decimal totalPrice: *(required)* This is the value returned by a previous :http:post:`sale/calculatePrice.json` call. It is used to confirm that none of the prices and discounts have changed since the user started the sale workflow. :jsonparam List[Object] orderItems: *(required)* See :http:jsonentity:`LoyaltyCardItem` for format of the objects. :jsonparam String originatingIP: *(optional)* The client IP of the person placing the order. :jsonparam String callingIp: *(optional)* The IP address of the integration making the request. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam Object order: *(required)* See :http:jsonentity:`LoyaltyCardOrder` for format of the object .. http:response:: creditCardFailure :jsonparam String result: *(required)* ``creditCardFailure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. :jsonparam Map(String->List[String]) errorsByField: *(required)* A list of input validation errors grouped by field name. .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. Calculate Total Price of a Sale Without an Account ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:post:: sale/calculatePrice.json Calculates the total price the user will pay if they later execute the sale. The system may calculate per-item discounts and/or per-order discounts and return those in the response to be displayed to the user before executing the sale. .. note:: This endpoint is typically used for non-logged-in users since some sale programs can be performed without having an account. See :http:post:`sale/calculatePriceForAccount.json` for logged-in users. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` * :ref:`anonymous_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam Integer cardTemplateCode: *(optional)* Paytronix-assigned card template code identifying the card type of the user. :jsonparam Integer tierCode: *(optional)* Paytronix-assigned tier code identifying the tier grouping of the user. :jsonparam String shippingOptionCode: *(optional)* One of the codes returned by the :http:get:`sale/saleConfig.json` call if required by the program. :jsonparam Boolean hasGiftBox: *(optional)* If true and relevant to the program, then the items will be in a gift box. :jsonparam List[Object] orderItemGroups: *(required)* See :http:jsonentity:`OrderItemGroup` for format of the objects. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam Object order: *(required)* See :http:jsonentity:`SaleOrder` for format of the object .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. Calculate Total Price of a Sale With an Account ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:post:: sale/calculatePriceForAccount.json Calculates the total price the user will pay if they later execute the sale. The system may calculate per-item discounts and/or per-order discounts and return those in the response to be displayed to the user before executing the sale. .. note:: This endpoint is for logged-in users. See :http:post:`sale/calculatePrice.json` for non-logged-in users. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` * :ref:`oauth_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String programType: *(required)* See :ref:`web_sale_program_type` for values. :jsonparam String printedCardNumber: *(required)* The card of the user :jsonparam String shippingOptionCode: *(optional)* One of the codes returned by the :http:get:`sale/saleConfig.json` call if required by the program. :jsonparam Boolean hasGiftBox: *(optional)* If true and relevant to the program, then the items will be in a gift box. :jsonparam List[Object] orderItemGroups: *(required)* See :http:jsonentity:`OrderItemGroup` for format of the objects. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam Object order: *(required)* See :http:jsonentity:`SaleOrder` for format of the object .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. Calculate Reward Yourself Points Value For Items With an Account ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:post:: sale/calculateAccountPointsValueForItems.json Calculates the Reward Yourself Points Value For Menu Items. The system may calculate per-item Points Value and return those in the response to be displayed to the user before executing the sale. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` * :ref:`oauth_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String storeCode: *(required)* A store code to uniquely identify the store where this transaction occurred. :jsonparam String printedCardNumber: *(required)* The card of the user :jsonparam List[String] menuItemIds: *(required)* List of Identifiers for the menu items. This identifies the menu item in the Paytronix database, not the particular line item in the check. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam List[Object] pointsValueForItems: *(required)* Points Value to Redeem requested Items. See :http:jsonentity:`PointsValueForItem` for format of the object .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. Constant Values --------------- .. _card_type: ``cardType`` Values ~~~~~~~~~~~~~~~~~~~ ``AMEX`` American Express ``DINERS_CLUB`` Diners Club ``DISCOVER`` Discover ``JCB`` JCB ``MASTERCARD`` MasterCard ``VISA`` Visa .. _payment_method_type: ``paymentMethodType`` Values ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``CC`` Use a credit card ``ENCRYPTED_CC`` Use encrypted credit card ``SAVED_CC`` Use a previously saved credit card ``SV`` Use the stored value (i.e., dollars) wallet ``POINTS`` Use the points wallet ``SPREEDLY_TOKEN`` Use Spreedly Token, see :http:jsonentity:`SpreedlyTokenPaymentMethod` for more details ``SAVED_SPREEDLY_TOKEN`` Use previously saved Spreedly Token, see :http:jsonentity:`SavedSpreedlyTokenPaymentMethod` for more details .. _web_sale_item_type: ``webSaleItemType`` Values ~~~~~~~~~~~~~~~~~~~~~~~~~~ ``GIFT_OR_LOYALTY_CARD`` A Gift or Loyalty Card item ``SHIPPED_REWARD`` A Reward item that will be shipped ``ON_CARD_REWARD`` A Reward item that added to user's card ``SV_GIFT`` A Gift of Stored Value ``EGIFT`` An eGift item .. _web_sale_program_type: ``webSaleProgramType`` Values ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``REWARDS_FROM_POINTS`` Purchase Rewards using Points, only valid for account specific calls ``GIFT_CARD`` Purchase a gift card. ``EGIFT`` Send Virtual Gift Cards (eGift) using a Credit Card, only valid for calls that aren't account specific Reply Objects ------------- .. http:jsonentity:: SaleOrder :jsonparam Int orderNumber: *(required)* The order number for this sale. :jsonparam Decimal totalPrice: *(required)* This is the value actually charged to user. :jsonparam List[Object] saleGroups: *(required)* List of item groups sold. See :http:jsonentity:`SaleOrderGroup` for format of the objects. :jsonparam Object discount: *(required)* See :http:jsonentity:`Discount` for format of the objects. :jsonparam List[Object] promotionItems: *(required)* List of promotional items granted to the buyer for this sale. See :http:jsonentity:`PromotionItem` for format of the objects. :jsonparam Int promotionItemCount: *(required)* Number of promotion items granted to the buy for this sale. .. http:jsonentity:: SaleOrderGroup :jsonparam List[Object] groupNumber: *(required)* Sale order group number matching the groupNumber in one of the orderItemGroups in the request. :jsonparam List[Object] saleItems: *(required)* List of items in this sale group. See :http:jsonentity:`SaleOrderItem` for format of the objects. .. http:jsonentity:: SaleOrderItem :jsonparam Int itemNumber: *(required)* A unique number that identifies the order item within the same group. This is the echo of ``itemNumber`` in ``OrderItem`` from the request. :jsonparam Decimal price: *(required)* This is the total price for this item after, if applies, discount :jsonparam Object discount: *(required)* See :http:jsonentity:`Discount` for format of the object. :jsonparam String recipientMessage: *(required)* The message to be sent to the recipient by the client software. Currently used so the client software can implement Facebook delivery :jsonparam String deliveryUrl: *(required)* The URL through which one can retrieve the detailed information of purchased cards. .. http:jsonentity:: LoyaltyCardOrder :jsonparam Int orderNumber: *(required)* The order number for this sale. :jsonparam Decimal totalPrice: *(required)* This is the value actually charged to user. :jsonparam Object shippingOption: *(optional)* See :http:jsonentity:`ShippingOption` for format of the object. :jsonparam Object createdCard: *(required)* See :http:jsonentity:`CreatedCard` for format of the object. .. http:jsonentity:: CreatedCard :jsonparam String printedCardNumber: *(required)* Printed card number of the newly created card. :jsonparam String regCode: *(required)* Registration code of the newly created card, if applicable. .. http:jsonentity:: Program :jsonparam String programType: *(required)* Paytronix-assigned code. See :ref:`web_sale_program_type` for values. :jsonparam String label: *(required)* The name of the program. :jsonparam List[Object] itemConfigs: *(required)* See :http:jsonentity:`ItemConfig` for format of the objects. :jsonparam List[Object] paymentMethodTypes: *(required)* See :http:jsonentity:`PaymentMethodTypeEntry` for format of the objects. :jsonparam List[Object] shippingOptions: *(required)* See :http:jsonentity:`ShippingOption` for format of the objects. :jsonparam List[Object] cardTypes: *(required)* See :http:jsonentity:`CardTypeEntry` for format of the objects. :jsonparam Object currency: *(optional)* See :http:jsonentity:`Currency` for format of the object. .. http:jsonentity:: Currency :jsonparam String code: *(required)* Alphanumeric code according to the `ISO 4217 currency codes. `_ :jsonparam String symbol: *(required)* Symbol associated with currency. .. http:jsonentity:: LoyaltyCardSaleProgramConfig :jsonparam String label: *(required)* The name of the program. :jsonparam List[Object] itemConfigs: *(required)* See :http:jsonentity:`LoyaltyCardItemConfig` for format of the objects. :jsonparam List[Object] paymentMethodTypes: *(required)* See :http:jsonentity:`PaymentMethodTypeEntry` for format of the objects. :jsonparam List[Object] shippingOptions: *(optional)* See :http:jsonentity:`ShippingOption` for format of the objects. :jsonparam List[Object] cardTypes: *(required)* See :http:jsonentity:`CardTypeEntry` for format of the objects. .. http:jsonentity:: ItemConfig :jsonparam String itemType: *(required)* Paytronix-assigned code. See :ref:`web_sale_item_type` for values. :jsonparam String code: *(required)* The unique code of the item. :jsonparam String label: *(required)* The name of the item (e.g., "Iced Tea"). :jsonparam String plural: *(required)* The plural name of the item (e.g., "Iced Teas"). :jsonparam String description: *(required)* The long description of the item. :jsonparam String thumbnailImageUrl: *(required)* If available, a URL reference to retrieve the thumbnail image of the item. :jsonparam String imageUrl: *(required)* If available, a URL reference to retrieve the (full size) image of the item. :jsonparam Decimal price: *(required)* The price of the item. :jsonparam Boolean customerPriceEnabled: *(required)* If true, allows end user to specify an arbitrary amount, within priceRangeLow and priceRangeHigh if defined. Supported by EGIFT program type only. :jsonparam Decimal priceRangeLow: *(required)* If the price is not specified, then the item can have a varying price. In this case, this value specifies the minimum value of the price. :jsonparam Decimal priceRangeHigh: *(required)* If the price is not specified, then the item can have a varying price. In this case, this value specifies the maximum value of the price. :jsonparam Decimal initialPrice: *(required)* If the price is not specified, then the item can have a varying price. In this case, this value specifies the initial selection from one of the entries in the ``priceList`` list. :jsonparam List[Decimal] priceList: *(required)* If the price is not specified, then the item can have a varying price. In this case, this list specifies the permitted values for the price. :jsonparam List[Object] styles: *(required)* See :http:jsonentity:`Style` for format of the objects. :jsonparam Integer onCardRewardWalletCode: *(required)* The wallet code of the reward item (only present if ``itemType`` = ``ON_CARD_REWARD``). :jsonparam Decimal onCardRewardAmount: *(required)* The amount of the reward specified by the ``onCardRewardWalletCode`` above (only present if ``itemType`` = ``ON_CARD_REWARD``). :jsonparam Boolean onCardRewardGiftable: *(required)* True if the reward specified by the ``onCardRewardWalletCode`` above can be "gifted" to another user (only present if ``itemType`` = ``ON_CARD_REWARD``). .. http:jsonentity:: LoyaltyCardItemConfig :jsonparam String code: *(required)* The unique code of the item. :jsonparam String label: *(required)* The name of the item (e.g., "Iced Tea"). :jsonparam String plural: *(optional)* The plural name of the item (e.g., "Iced Teas"). :jsonparam String thumbnailImageUrl: *(optional)* If available, a URL reference to retrieve the thumbnail image of the item. :jsonparam Decimal price: *(required)* The price of the item. :jsonparam List[Object] favoriteStores: *(optional)* A list of favorite store options to present to the user. See :http:jsonentity:`FavoriteStore` for values. .. http:jsonentity:: FavoriteStore :jsonparam String code: *(required)* The unique code of the store. :jsonparam String name: *(required)* The name of the store. :jsonparam String state: *(optional)* The state of the store .. http:jsonentity:: Style :jsonparam String code: *(required)* The unique code of the style. :jsonparam String label: *(required)* The name of the item (e.g., "Red"). :jsonparam String description: *(required)* The long description of the style. :jsonparam String thumbnailImageUrl: *(required)* If available, a URL reference to retrieve the thumbnail image of the style. :jsonparam String imageUrl: *(required)* If available, a URL reference to retrieve the (full size) image of the style. .. http:jsonentity:: ShippingOption :jsonparam String code: *(required)* The unique code of the shipping method. :jsonparam String label: *(required)* The name of the shipping method. :jsonparam Decimal price: *(required)* The price of the shipping method. .. http:jsonentity:: PaymentMethodTypeEntry :jsonparam String code: *(required)* {{REST/Parameter/paymentMethodValues}} :jsonparam String label: *(required)* The name of the type. .. http:jsonentity:: CardTypeEntry :jsonparam String code: *(required)* {{REST/Parameter/cardTypeValues}} :jsonparam String label: *(required)* The name of the type. .. http:jsonentity:: Contact :jsonparam string firstName: *(required)* :jsonparam string lastName: *(required)* :jsonparam string email: *(required)* :jsonparam string phone: *(required)* :jsonparam Object externalAccount: *(required)* See :http:jsonentity:`ExternalAccount` for format of the object. .. http:jsonentity:: Address .. note:: Please refer to ``Supported Country Codes`` and ``Supported Country State/Province Codes`` under the Glossary for a list of appropriate values for the corresponding Address fields. :jsonparam string street: *(required)* :jsonparam string street2: *(required)* :jsonparam string city: *(required)* :jsonparam string stateProvince: *(required)* :jsonparam string postalCode: *(required)* :jsonparam string country: *(required)* .. http:jsonentity:: ShippingAddress :jsonparam String shippingOptionCode: *(required)* One of the codes returned by the :http:get:`sale/saleConfig.json`. :jsonparam Boolean shippingSameAsBilling: *(required)* If true, then the ``shippingContact`` and ``shippingAddress`` are optional and will be defaulted from ``billingContact`` and ``billingAddress``. :jsonparam Object shippingContact: *(required)* See :http:jsonentity:`Contact` for format of the object. :jsonparam Object shippingAddress: *(required)* See :http:jsonentity:`Address` for format of the object. .. http:jsonentity:: OrderItemGroup :jsonparam Int groupNumber: *(required)* The unique number that identify the order item group within the same order. This should be a sequencial number starts with 1. :jsonparam Object recipient: *(required)* See :http:jsonentity:`Contact` for format of the object. :jsonparam Date deliveryDate: *(required)* If the shipping date is not now, then this is the date in the future to ship the items. :jsonparam List[Object] orderItems: *(required)* See :http:jsonentity:`OrderItem` for format of the object. :jsonparam String personalizedFrom: *(required)* Name of gift sender (used with ``EGIFT`` program). :jsonparam String personalizedTo: *(required)* Name of gift recipient (used with ``EGIFT`` program). :jsonparam String personalizedMessage: *(required)* Personalized message associated with gift (used with ``EGIFT`` program). .. http:jsonentity:: OrderItem :jsonparam Int itemNumber: *(required)* The unique number that identify the item within the same order. This should be a sequencial number starts with 1. :jsonparam String code: *(required)* The unique code of the item. :jsonparam String styleCode: *(required)* If this sale item has styles, then this is the style code to use for this item, as returned by the :http:get:`sale/saleConfig.json` call endpoint. This element is required when ``programType`` is ``EGIFT`` :jsonparam Decimal quantity: *(required)* The quantity of these items :jsonparam Decimal value: *(required)* If the price of this item (from the ``ItemConfig``) did not have a predefined value (which means the value was entered or selected from the ``priceList`` by the user), then this is the value entered/selected. .. http:jsonentity:: LoyaltyCardItem :jsonparam String code: *(required)* The unique code of the item. .. http:jsonentity:: Discount :jsonparam String code: *(required)* The unique code of the item. If this is missing, then this discount applies to the entire order. :jsonparam Decimal amount: *(required)* The amount deducted from the original price of the item/order. :jsonparam Decimal price: *(required)* The final price of the item/order (after deducting amount). :jsonparam String description: *(required)* The description of the discount .. http:jsonentity:: PromotionItem :jsonparam String itemCode: *(required)* The unique code of the item(s) given by the promotion. :jsonparam String itemLabel: *(required)* The label of the item given by the promotion. :jsonparam String imageUrl: *(required)* If available, a URL reference to retrieve the (full size) image of the item(s) given by the promotion. :jsonparam Decimal quantity: *(required)* The quantity of the item(s) given. :jsonparam Decimal price: *(required)* The price of each item given. Typically, promotion items are free so the price will be zero. :jsonparam String promotionLabel: *(required)* The label of the promotion/reason for giving the item(s). :jsonparam String description: *(required)* The description of the promotion/reason for giving the item(s). .. http:jsonentity:: ExternalAccount :jsonparam String integration: *(required)* Paytronix-assigned code. Contact Paytronix to understand what the possible values are. :jsonparam String accountCode: *(required)* The external code of this user. :jsonparam String accessToken: *(required)* Future use. .. http:jsonentity:: PaymentMethod :jsonparam String paymentMethodType: *(required)* Paytronix-assigned code. See :ref:`payment_method_type` :jsonparam String savedCardCode: *(required)* Only required if ``paymentMethod`` is ``SAVED_CC``. This code was returned by the Payment Service endpoint ``savedCard``. :jsonparam String cardholderName: *(required)* Only required if ``paymentMethod`` is ``CC``. The name on the credit card. :jsonparam String cardType: *(required)* Paytronix-assigned code. See :ref:`card_type` :jsonparam String cardNumber: *(required)* Only required if ``paymentMethod`` is ``CC``. The credit card number (no spaces or punctuation). :jsonparam String lastFour: *(required)* Must be passed along with ``savedCardCode`` when ``paymentMethod`` is ``SAVED_CC`` :jsonparam Integer expirationMonth: *(required)* Only required if ``paymentMethod`` is ``CC``. The month of the expiration (0 = Jan, ..., 11 = Dec). :jsonparam Integer expirationYear: *(required)* Only required if ``paymentMethod`` is ``CC``. The year of the expiration (4 digits like: ``2019``) :jsonparam String cardSecurityCode: *(required)* Only required if ``paymentMethod`` is ``CC``. Also known as the CVV, CVV2, CVVC, or CSC code on the back of the credit card. :jsonparam Boolean saveCard: *(required)* Only required if ``paymentMethod`` is ``CC``. Save this credit card for future use as the default credit card for this account. Default: ``false`` .. http:jsonentity:: PointsValueForItem :jsonparam String menuItemId: *(required)* Identifier for the menu item. This identifies the menu item in the Paytronix database, not the particular line item in the check. :jsonparam Integer walletCode: *(required)* A numeric identifier for a specific type of discount, unique for a given merchant. :jsonparam Decimal points: *(required)* Points needed to redeem this reward. Error Codes ----------- The following are the possible codes and messages that can be returned by the Sale Service. There are other system-level errors which may be returned which are not documented here. The caller of the endpoint can use the returned message to display to the end user or, if different wording is desired, can provide their own mapping of code to message. +------------------------------------------------------+----------------------------------------------------------------+ | Code | Message | +======================================================+================================================================+ | ``config_failed.invalid_card_number`` | Invalid card number | +------------------------------------------------------+----------------------------------------------------------------+ | ``config_failed.invalid_card_template`` | Invalid card template | +------------------------------------------------------+----------------------------------------------------------------+ | ``config_failed.invalid_tier`` | Invalid tier | +------------------------------------------------------+----------------------------------------------------------------+ | ``config_failed.invalid_merchant_id`` | Invalid merchant id | +------------------------------------------------------+----------------------------------------------------------------+ | ``config_failed.invalid_program_type`` | Invalid program type | +------------------------------------------------------+----------------------------------------------------------------+ | ``config_failed.invalid_program`` | Invalid sale program | +------------------------------------------------------+----------------------------------------------------------------+ | ``config_failed.invalid_program_for_card`` | Invalid sale program for card | +------------------------------------------------------+----------------------------------------------------------------+ | ``config_failed.invalid_shipping_option`` | Invalid shipping option | +------------------------------------------------------+----------------------------------------------------------------+ | ``config_failed.shipping_options_failure`` | Shipping options failure | +------------------------------------------------------+----------------------------------------------------------------+ | ``config_failed.sale_items_failure`` | Sale items failure | +------------------------------------------------------+----------------------------------------------------------------+ | ``config_failed.no_item_for_sale`` | No item for sale | +------------------------------------------------------+----------------------------------------------------------------+ | ``config_failed.reward_promotions_failure`` | Reward promotions failure | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed`` | Sale failed due to unknown error | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.invalid_card_number`` | Invalid card number | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.invalid_card_template`` | Invalid card template | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.invalid_tier`` | Invalid tier | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.invalid_merchant_id`` | Invalid merchant id | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.invalid_program_type`` | Invalid program type | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.invalid_program`` | Invalid sale program | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.invalid_program_for_card`` | Invalid sale program for card | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.invalid_shipping_option`` | Invalid shipping option | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.invalid_order_item`` | Invalid order item | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.invalid_user_record`` | Invalid user record for card | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.invalid_address_record`` | Invalid address record for card | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.invalid_point_wallet`` | Invalid point wallet | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.invalid_recipient_info`` | Invalid recipient information | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.invalid_delivery_method`` | Invalid delivery method | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.shipping_options_failure`` | Shipping options failure | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.sale_items_failure`` | Sale items failure | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.no_item_for_sale`` | No item for sale | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.reward_promotions_failure`` | Reward promotions failure | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.web_store_failure`` | Web store failure | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.not_enough_point_balance`` | Not enough point balance available | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.price_changed`` | Price changed since last evaluation | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.locate_email_service_failure`` | Locate email service failure | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.locate_payment_service_failure`` | Locate payment service failure | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.invalid_billing_contact`` | Invalid billing contact information | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.invalid_billing_address`` | Invalid billing address information | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.invalid_cc_processor`` | Invalid cc processor | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.invalid_item_style`` | Invalid item style | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.zero_total_price`` | Order total price is zero | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.cc_auth_failed`` | CC auth failed | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.cc_capture_failed`` | CC capture failed | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.duplicate_group_number`` | Duplicate group number | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.duplicate_item_number`` | Duplicate item number within same group | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.sale_image_failure`` | Sale image failure | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.integration_service_failure`` | Integration service failure | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.activate_card_failure`` | Activate card failure | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.invalid_recipient_message_template`` | Invalid Recipient Message Template | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.invalid_email`` | Invalid email address | +------------------------------------------------------+----------------------------------------------------------------+ | ``sale_failed.facebook_disabled`` | Facebook delivery is temporarily disabled. Please use email. | +------------------------------------------------------+----------------------------------------------------------------+