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

Flow For Non Logged In User

../_images/egift_sale_flow.png
  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.

Note

Only the EGIFT programType is implemented.

The following authentication methods are allowed for this endpoint:

JSON 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) – (required) 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:

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

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:

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) – (required) 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) – (required) 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) – (required) If true and relevant to the program, then the items will be in a gift box.
  • activationStoreCode (String) – (required) 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.
"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:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • programType (String) – (required) 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.
  • shippingCode (String) – (required) 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) – (required) If true and relevant to the program, then the items will be in a gift box.
  • activationStoreCode (String) – (required) 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.
"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 Without an Account

POST sale/calculatePrice.json

Calculates the total price the user will pay if the 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:

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.
  • shippingOptionCode (String) – (required) One of the codes returned by the GET sale/saleConfig.json call if required by the program.
  • hasGiftBox (Boolean) – (required) 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 the 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:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • programType (String) – (required) See webSaleProgramType Values for values.
  • shippingOptionCode (String) – (required) One of the codes returned by the GET sale/saleConfig.json call if required by the program.
  • hasGiftBox (Boolean) – (required) 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.

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
SAVED_CC
Use a previously saved credit card
SV
Use the stored value (i.e., dollars) wallet
POINTS
Use the points wallet

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
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.
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.
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).
  • onCardRewardGiftable (Boolean) – (required) True if the reward specified by the onCardRewardWalletCode above can be “gifted” to another user (only present if itemType = ON_CARD_REWARD).
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
JSON Parameters:
 
  • street (string) – (required)
  • city (string) – (required)
  • stateProvince (string) – (required)
  • postalCode (string) – (required)
  • country (string) – (required)
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.
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

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.