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).

Topics

• Sale Service
  • Flow For Non Logged In User
  • Endpoints
    • Get Sale Configuration for Program
    • Get Sale Configuration for Account
    • Get Sale Configurations for Account
    • Get Loyalty Card Sale Config
    • Execute Sale Without an Account
    • Execute Sale With an Account
    • Execute Loyalty Card Sale
    • Calculate Total Price of a Sale Without an Account
    • Calculate Total Price of a Sale With an Account
    • Calculate Reward Yourself Points Value For Items With an Account
  • Constant Values
    • cardType Values
    • paymentMethodType Values
    • webSaleItemType Values
    • webSaleProgramType Values
  • Reply Objects
  • Error Codes

Flow For Non Logged In User

1. A successful call to 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 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 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

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 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 GET sale/saleConfigForAccount.json for logged-in users.

The following authentication methods are allowed for this endpoint:

• B2B authentication
• Anonymous authentication

Query Parameters:  

• merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
• programType (String) – (required) Paytronix-assigned code. See webSaleProgramType Values for values.
• cardTemplateCode (Integer) – (required) Paytronix-assigned card template code identifying the card type of the user.
• tierCode (Integer) – (optional) Paytronix-assigned tier code identifying the tier grouping of the user.

"result": "success"

JSON Parameters:  

• result (String) – (required) success
• program (Object) – (required) See Program for format of the object.

"result": "failure"

JSON Parameters:  

• result (String) – (required) failure
• errorCode (String) – (required) The error code of the failure.
• errorMessage (String) – (required) The (human readable) error message of the failure.

Get Sale Configuration for Account

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 POST sale/executeSaleForAccount.json endpoint.

Note

This endpoint is used for logged-in users. See GET sale/saleConfig.json for non-logged-in users.

The following authentication methods are allowed for this endpoint:

• B2B authentication
• OAuth authentication

Query Parameters:  

• merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
• programType (String) – (required) Paytronix-assigned code. See webSaleProgramType Values for values.
• printedCardNumber (String) – (required) The card of the user.

"result": "success"

JSON Parameters:  

• result (String) – (required) success
• program (Object) – (required) See Program for format of the object.

"result": "failure"

JSON Parameters:  

• result (String) – (required) failure
• errorCode (String) – (required) The error code of the failure.
• errorMessage (String) – (required) The (human readable) error message of the failure.

Get Sale Configurations for Account

GET sale/saleConfigsForAccount.json

Returns information for the configuration and display of an “order” page. Should only be used for merchants who have multiple web reward programs of the same type configured (e.g., two different REWARDS_FROM_POINTS programs). Codes and values in the response to this endpoint will be used when calling the POST sale/executeSaleForAccount.json endpoint.

Note

This endpoint is used for logged-in users. See GET sale/saleConfig.json for non-logged-in users.

The following authentication methods are allowed for this endpoint:

• B2B authentication
• OAuth authentication

Query Parameters:  

• merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
• programType (String) – (required) Paytronix-assigned code. See webSaleProgramType Values for values.
• printedCardNumber (String) – (required) The card of the user.

"result": "success"

JSON Parameters:  

• result (String) – (required) success
• programs (List[Object]) – (required) See Program for format of the object.

"result": "failure"

JSON Parameters:  

• result (String) – (required) failure
• errorCode (String) – (required) The error code of the failure.
• errorMessage (String) – (required) The (human readable) error message of the failure.

Get Loyalty Card Sale Config

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 POST sale/executeSale.json endpoint. This end point is specific for loyalty card sales.

The following authentication methods are allowed for this endpoint:

• B2B authentication
• OAuth authentication

Query Parameters:  

• merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.

"result": "success"

JSON Parameters:  

• result (String) – (required) success
• program (Object) – (required) See LoyaltyCardSaleProgramConfig for format of the object.

"result": "failure"

JSON Parameters:  

• result (String) – (required) failure
• errorCode (String) – (required) The error code of the failure.
• errorMessage (String) – (required) The (human readable) error message of the failure.

Execute Sale Without an Account

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 POST sale/executeSaleForAccount.json for logged-in users.

The following authentication methods are allowed for this endpoint:

• B2B authentication
• Anonymous authentication

JSON Parameters:  

• merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
• cardTemplateCode (Integer) – (required) Paytronix-assigned card template code identifying the card type of the user.
• tierCode (Integer) – (required) Paytronix-assigned tier code identifying the tier grouping of the user.
• programType (String) – (required) Paytronix-assigned code. See webSaleProgramType Values for values.
• billingContact (Object) – (required) See Contact for format of the object.
• billingAddress (Object) – (required) See Address for format of the object.
• shippingSameAsBilling (Boolean) – (required) If true, then the shippingContact and shippingAddress are optional and will be defaulted from billingContact and billingAddress.
• shippingContact (Object) – (required) See Contact for format of the object.
• shippingAddress (Object) – (required) See Address for format of the object.
• paymentMethod (Object) – (required) See PaymentMethod for format of the object.
• shippingOptionCode (String) – (optional) One of the shipping option codes returned by the GET sale/saleConfig.json call if required by the chosen program.
• totalPrice (Decimal) – (required) This is the value returned by a previous 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.
• promotionItemCount (Int) – (optional) This is the value returned by a previous 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
• hasGiftBox (Boolean) – (optional) If true and relevant to the program, then the items will be in a gift box.
• activationStoreCode (String) – (optional) If required by the program, then this will be the store to which newly created cards will be associated.
• orderItemGroups (List[Object]) – (required) See OrderItemGroup for format of the objects.
• originatingIP (String) – (optional) The client IP of the person placing the order.
• callingIp (String) – (optional) The IP address of the integration making the request.
• stripePaymentIntent (String) – (optional) The stripe payment intent ID for a web sale program using a Stripe Checkout CC Processor.

"result": "success"

JSON Parameters:  

• result (String) – (required) success
• order (Object) – (required) See SaleOrder for format of the object

"result": "failure"

JSON Parameters:  

• result (String) – (required) failure
• errorCode (String) – (required) The error code of the failure.
• errorMessage (String) – (required) The (human readable) error message of the failure.

Execute Sale With an Account

POST sale/executeSaleForAccount.json

Executes the sale for the specified program and input fields.

Note

This endpoint is for logged-in users. See POST sale/executeSale.json for non-logged-in users.

The following authentication methods are allowed for this endpoint:

• B2B authentication
• OAuth authentication

JSON Parameters:  

• merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
• programType (String) – (required) See webSaleProgramType Values for values.
• code (String) – (optional) Paytronix-assigned code representing the web sale program returned as programCode in GET sale/saleConfigsForAccount.json response.
• printedCardNumber (String) – (required) The card of the user
• billingContact (Object) – (required) See Contact for format of the object.
• billingAddress (Object) – (required) See Address for format of the object.
• shippingSameAsBilling (Boolean) – (required) If true, then the shippingContact and shippingAddress are optional and will be defaulted from billingContact and billingAddress.
• shippingContact (Object) – (required) See Contact for format of the object.
• shippingAddress (Object) – (required) See Address for format of the object.
• paymentMethod (Object) – (required) See PaymentMethod for format of the object.
• shippingOptionCode (String) – (optional) One of the codes returned by the GET sale/saleConfig.json call if required by the program.
• totalPrice (Decimal) – (required) This is the value returned by a previous 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.
• hasGiftBox (Boolean) – (optional) If true and relevant to the program, then the items will be in a gift box.
• activationStoreCode (String) – (optional) If required by the program, then this will be the store to which newly created cards will be associated.
• orderItemGroups (List[Object]) – (required) See OrderItemGroup for format of the objects.
• originatingIP (String) – (optional) The client IP of the person placing the order.
• callingIp (String) – (optional) The IP address of the integration making the request.

"result": "success"

JSON Parameters:  

• result (String) – (required) success
• order (Object) – (required) See SaleOrder for format of the object

"result": "failure"

JSON Parameters:  

• result (String) – (required) failure
• errorCode (String) – (required) The error code of the failure.
• errorMessage (String) – (required) The (human readable) error message of the failure.

Execute Loyalty Card Sale

POST sale/executeLoyaltyCardSale.json

Executes the sale for a loyalty card.

The following authentication methods are allowed for this endpoint:

• B2B authentication
• OAuth authentication

JSON Parameters:  

• merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
• billingContact (Object) – (required) See Contact for format of the object.
• billingAddress (Object) – (required) See Address for format of the object.
• shippingInformation (Object) – (optional) See ShippingAddress for format of the object.
• favoriteStoreCode (String) – (optional) The store the user selects as their home location
• paymentMethod (Object) – (required) See PaymentMethod for format of the object.
• totalPrice (Decimal) – (required) This is the value returned by a previous 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.
• orderItems (List[Object]) – (required) See LoyaltyCardItem for format of the objects.
• originatingIP (String) – (optional) The client IP of the person placing the order.
• callingIp (String) – (optional) The IP address of the integration making the request.

"result": "success"

JSON Parameters:  

• result (String) – (required) success
• order (Object) – (required) See LoyaltyCardOrder for format of the object

"result": "creditCardFailure"

JSON Parameters:  

• result (String) – (required) creditCardFailure
• errorCode (String) – (required) The error code of the failure.
• errorMessage (String) – (required) The (human readable) error message of the failure.
• errorsByField (Map(String->List[String])) – (required) A list of input validation errors grouped by field name.

"result": "failure"

JSON Parameters:  

• result (String) – (required) failure
• errorCode (String) – (required) The error code of the failure.
• errorMessage (String) – (required) The (human readable) error message of the failure.

Calculate Total Price of a Sale Without an Account

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 POST sale/calculatePriceForAccount.json for logged-in users.

The following authentication methods are allowed for this endpoint:

• B2B authentication
• Anonymous authentication

JSON Parameters:  

• merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
• cardTemplateCode (Integer) – (optional) Paytronix-assigned card template code identifying the card type of the user.
• tierCode (Integer) – (optional) Paytronix-assigned tier code identifying the tier grouping of the user.
• shippingOptionCode (String) – (optional) One of the codes returned by the GET sale/saleConfig.json call if required by the program.
• hasGiftBox (Boolean) – (optional) If true and relevant to the program, then the items will be in a gift box.
• orderItemGroups (List[Object]) – (required) See OrderItemGroup for format of the objects.

"result": "success"

JSON Parameters:  

• result (String) – (required) success
• order (Object) – (required) See SaleOrder for format of the object

"result": "failure"

JSON Parameters:  

• result (String) – (required) failure
• errorCode (String) – (required) The error code of the failure.
• errorMessage (String) – (required) The (human readable) error message of the failure.

Calculate Total Price of a Sale With an Account

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 POST sale/calculatePrice.json for non-logged-in users.

The following authentication methods are allowed for this endpoint:

• B2B authentication
• OAuth authentication

JSON Parameters:  

• merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
• programType (String) – (required) See webSaleProgramType Values for values.
• code (String) – (optional) Paytronix-assigned code representing the web sale program returned as programCode in GET sale/saleConfigsForAccount.json response.
• printedCardNumber (String) – (required) The card of the user
• shippingOptionCode (String) – (optional) One of the codes returned by the GET sale/saleConfig.json call if required by the program.
• hasGiftBox (Boolean) – (optional) If true and relevant to the program, then the items will be in a gift box.
• orderItemGroups (List[Object]) – (required) See OrderItemGroup for format of the objects.

"result": "success"

JSON Parameters:  

• result (String) – (required) success
• order (Object) – (required) See SaleOrder for format of the object

"result": "failure"

JSON Parameters:  

• result (String) – (required) failure
• errorCode (String) – (required) The error code of the failure.
• errorMessage (String) – (required) The (human readable) error message of the failure.

Calculate Reward Yourself Points Value For Items With an Account

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:

• B2B authentication
• OAuth authentication

JSON Parameters:  

• merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
• storeCode (String) – (required) A store code to uniquely identify the store where this transaction occurred.
• printedCardNumber (String) – (required) The card of the user
• menuItemIds (List[String]) – (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.

"result": "success"

JSON Parameters:  

• result (String) – (required) success
• pointsValueForItems (List[Object]) – (required) Points Value to Redeem requested Items. See PointsValueForItem for format of the object

"result": "failure"

JSON Parameters:  

• result (String) – (required) failure
• errorCode (String) – (required) The error code of the failure.
• errorMessage (String) – (required) The (human readable) error message of the failure.

Constant Values

cardType Values

AMEX

American Express

DINERS_CLUB

Diners Club

DISCOVER

Discover

JCB

JCB

MASTERCARD

MasterCard

VISA

Visa

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 SpreedlyTokenPaymentMethod for more details

SAVED_SPREEDLY_TOKEN

Use previously saved Spreedly Token, see SavedSpreedlyTokenPaymentMethod for more details

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

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

SaleOrder

JSON Parameters:  

• orderNumber (Int) – (required) The order number for this sale.
• totalPrice (Decimal) – (required) This is the value actually charged to user.
• saleGroups (List[Object]) – (required) List of item groups sold. See SaleOrderGroup for format of the objects.
• discount (Object) – (required) See Discount for format of the objects.
• promotionItems (List[Object]) – (required) List of promotional items granted to the buyer for this sale. See PromotionItem for format of the objects.
• promotionItemCount (Int) – (required) Number of promotion items granted to the buy for this sale.

SaleOrderGroup

JSON Parameters:  

• groupNumber (List[Object]) – (required) Sale order group number matching the groupNumber in one of the orderItemGroups in the request.
• saleItems (List[Object]) – (required) List of items in this sale group. See SaleOrderItem for format of the objects.

SaleOrderItem

JSON Parameters:  

• itemNumber (Int) – (required) A unique number that identifies the order item within the same group. This is the echo of itemNumber in OrderItem from the request.
• price (Decimal) – (required) This is the total price for this item after, if applies, discount
• discount (Object) – (required) See Discount for format of the object.
• recipientMessage (String) – (required) The message to be sent to the recipient by the client software. Currently used so the client software can implement Facebook delivery
• deliveryUrl (String) – (required) The URL through which one can retrieve the detailed information of purchased cards.

LoyaltyCardOrder

JSON Parameters:  

• orderNumber (Int) – (required) The order number for this sale.
• totalPrice (Decimal) – (required) This is the value actually charged to user.
• shippingOption (Object) – (optional) See ShippingOption for format of the object.
• createdCard (Object) – (required) See CreatedCard for format of the object.

CreatedCard

JSON Parameters:  

• printedCardNumber (String) – (required) Printed card number of the newly created card.
• regCode (String) – (required) Registration code of the newly created card, if applicable.

Program

JSON Parameters:  

• programType (String) – (required) Paytronix-assigned code. See webSaleProgramType Values for values.
• label (String) – (required) The name of the program.
• itemConfigs (List[Object]) – (required) See ItemConfig for format of the objects.
• paymentMethodTypes (List[Object]) – (required) See PaymentMethodTypeEntry for format of the objects.
• shippingOptions (List[Object]) – (required) See ShippingOption for format of the objects.
• cardTypes (List[Object]) – (required) See CardTypeEntry for format of the objects.
• currency (Object) – (optional) See Currency for format of the object.

Currency

JSON Parameters:  

• code (String) – (required) Alphanumeric code according to the ISO 4217 currency codes.
• symbol (String) – (required) Symbol associated with currency.

LoyaltyCardSaleProgramConfig

JSON Parameters:  

• label (String) – (required) The name of the program.
• itemConfigs (List[Object]) – (required) See LoyaltyCardItemConfig for format of the objects.
• paymentMethodTypes (List[Object]) – (required) See PaymentMethodTypeEntry for format of the objects.
• shippingOptions (List[Object]) – (optional) See ShippingOption for format of the objects.
• cardTypes (List[Object]) – (required) See CardTypeEntry for format of the objects.

ItemConfig

JSON Parameters:  

• itemType (String) – (required) Paytronix-assigned code. See webSaleItemType Values for values.
• code (String) – (required) The unique code of the item.
• label (String) – (required) The name of the item (e.g., “Iced Tea”).
• plural (String) – (required) The plural name of the item (e.g., “Iced Teas”).
• description (String) – (required) The long description of the item.
• thumbnailImageUrl (String) – (required) If available, a URL reference to retrieve the thumbnail image of the item.
• imageUrl (String) – (required) If available, a URL reference to retrieve the (full size) image of the item.
• price (Decimal) – (required) The price of the item.
• customerPriceEnabled (Boolean) – (required) If true, allows end user to specify an arbitrary amount, within priceRangeLow and priceRangeHigh if defined. Supported by EGIFT program type only.
• priceRangeLow (Decimal) – (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.
• priceRangeHigh (Decimal) – (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.
• initialPrice (Decimal) – (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.
• priceList (List[Decimal]) – (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.
• styles (List[Object]) – (required) See Style for format of the objects.
• onCardRewardWalletCode (Integer) – (required) The wallet code of the reward item (only present if itemType = ON_CARD_REWARD).
• onCardRewardAmount (Decimal) – (required) The amount of the reward specified by the onCardRewardWalletCode above (only present if itemType = ON_CARD_REWARD).
• expirationDays (Integer) – (optional) Relative number of days from sale after which the item will expire, if specified (only present if itemType = ON_CARD_REWARD).

LoyaltyCardItemConfig

JSON Parameters:  

• code (String) – (required) The unique code of the item.
• label (String) – (required) The name of the item (e.g., “Iced Tea”).
• plural (String) – (optional) The plural name of the item (e.g., “Iced Teas”).
• thumbnailImageUrl (String) – (optional) If available, a URL reference to retrieve the thumbnail image of the item.
• price (Decimal) – (required) The price of the item.
• favoriteStores (List[Object]) – (optional) A list of favorite store options to present to the user. See FavoriteStore for values.

FavoriteStore

JSON Parameters:  

• code (String) – (required) The unique code of the store.
• name (String) – (required) The name of the store.
• state (String) – (optional) The state of the store

Style

JSON Parameters:  

• code (String) – (required) The unique code of the style.
• label (String) – (required) The name of the item (e.g., “Red”).
• description (String) – (required) The long description of the style.
• thumbnailImageUrl (String) – (required) If available, a URL reference to retrieve the thumbnail image of the style.
• imageUrl (String) – (required) If available, a URL reference to retrieve the (full size) image of the style.

ShippingOption

JSON Parameters:  

• code (String) – (required) The unique code of the shipping method.
• label (String) – (required) The name of the shipping method.
• price (Decimal) – (required) The price of the shipping method.

PaymentMethodTypeEntry

JSON Parameters:  

• code (String) – (required) {{REST/Parameter/paymentMethodValues}}
• label (String) – (required) The name of the type.

CardTypeEntry

JSON Parameters:  

• code (String) – (required) {{REST/Parameter/cardTypeValues}}
• label (String) – (required) The name of the type.

Contact

JSON Parameters:  

• firstName (string) – (required)
• lastName (string) – (required)
• email (string) – (required)
• phone (string) – (required)
• externalAccount (Object) – (required) See ExternalAccount for format of the object.

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.

JSON Parameters:  

• street (string) – (required)
• street2 (string) – (required)
• city (string) – (required)
• stateProvince (string) – (required)
• postalCode (string) – (required)
• country (string) – (required)

ShippingAddress

JSON Parameters:  

• shippingOptionCode (String) – (required) One of the codes returned by the GET sale/saleConfig.json.
• shippingSameAsBilling (Boolean) – (required) If true, then the shippingContact and shippingAddress are optional and will be defaulted from billingContact and billingAddress.
• shippingContact (Object) – (required) See Contact for format of the object.
• shippingAddress (Object) – (required) See Address for format of the object.

OrderItemGroup

JSON Parameters:  

• groupNumber (Int) – (required) The unique number that identify the order item group within the same order. This should be a sequencial number starts with 1.
• recipient (Object) – (required) See Contact for format of the object.
• deliveryDate (Date) – (required) If the shipping date is not now, then this is the date in the future to ship the items.
• orderItems (List[Object]) – (required) See OrderItem for format of the object.
• personalizedFrom (String) – (required) Name of gift sender (used with EGIFT program).
• personalizedTo (String) – (required) Name of gift recipient (used with EGIFT program).
• personalizedMessage (String) – (required) Personalized message associated with gift (used with EGIFT program).

OrderItem

JSON Parameters:  

• itemNumber (Int) – (required) The unique number that identify the item within the same order. This should be a sequencial number starts with 1.
• code (String) – (required) The unique code of the item.
• styleCode (String) – (required) If this sale item has styles, then this is the style code to use for this item, as returned by the GET sale/saleConfig.json call endpoint. This element is required when programType is EGIFT
• quantity (Decimal) – (required) The quantity of these items
• value (Decimal) – (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.

LoyaltyCardItem

JSON Parameters:  

• code (String) – (required) The unique code of the item.

Discount

JSON Parameters:  

• code (String) – (required) The unique code of the item. If this is missing, then this discount applies to the entire order.
• amount (Decimal) – (required) The amount deducted from the original price of the item/order.
• price (Decimal) – (required) The final price of the item/order (after deducting amount).
• description (String) – (required) The description of the discount

PromotionItem

JSON Parameters:  

• itemCode (String) – (required) The unique code of the item(s) given by the promotion.
• itemLabel (String) – (required) The label of the item given by the promotion.
• imageUrl (String) – (required) If available, a URL reference to retrieve the (full size) image of the item(s) given by the promotion.
• quantity (Decimal) – (required) The quantity of the item(s) given.
• price (Decimal) – (required) The price of each item given. Typically, promotion items are free so the price will be zero.
• promotionLabel (String) – (required) The label of the promotion/reason for giving the item(s).
• description (String) – (required) The description of the promotion/reason for giving the item(s).

ExternalAccount

JSON Parameters:  

• integration (String) – (required) Paytronix-assigned code. Contact Paytronix to understand what the possible values are.
• accountCode (String) – (required) The external code of this user.
• accessToken (String) – (required) Future use.

PaymentMethod

JSON Parameters:  

• paymentMethodType (String) – (required) Paytronix-assigned code. See paymentMethodType Values
• savedCardCode (String) – (required) Only required if paymentMethod is SAVED_CC. This code was returned by the Payment Service endpoint savedCard.
• cardholderName (String) – (required) Only required if paymentMethod is CC. The name on the credit card.
• cardType (String) – (required) Paytronix-assigned code. See cardType Values
• cardNumber (String) – (required) Only required if paymentMethod is CC. The credit card number (no spaces or punctuation).
• lastFour (String) – (required) Must be passed along with savedCardCode when paymentMethod is SAVED_CC
• expirationMonth (Integer) – (required) Only required if paymentMethod is CC. The month of the expiration (0 = Jan, …, 11 = Dec).
• expirationYear (Integer) – (required) Only required if paymentMethod is CC. The year of the expiration (4 digits like: 2019)
• cardSecurityCode (String) – (required) Only required if paymentMethod is CC. Also known as the CVV, CVV2, CVVC, or CSC code on the back of the credit card.
• saveCard (Boolean) – (required) Only required if paymentMethod is CC. Save this credit card for future use as the default credit card for this account. Default: false

PointsValueForItem

JSON Parameters:  

• menuItemId (String) – (required) Identifier for the menu item. This identifies the menu item in the Paytronix database, not the particular line item in the check.
• walletCode (Integer) – (required) A numeric identifier for a specific type of discount, unique for a given merchant.
• points (Decimal) – (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.