updates RSS feed

Order with catalog products

Overview

The object below is returned directly or within a successful response from the following API requests:

Place orders with catalog product

Retrieve an order

Catalog order object

Parameters Type/Description
RefNo String
 

2Checkout generates unique reference numbers for all orders (purchases). You can use this parameter to retry authorizations for orders with failed transactions by changing the payment method.

 

NULL when you place new orders.
ChargebackResolution String
 

Chargeback status information. Possible values:

· OPEN (chargeback is in progress)

· WON (chargeback won by you)

· LOST (chargeback won by the customer)

· ACCEPTED (you agreed to repay the value of the order to the customer)

· NONE (no chargeback initiated for the order)

To manage chargeback notifications navigate to Control Panel Dashboard →Integrations → Webhooks and API, and click on the IPN settings tab.

In the General IPN Settings section, under Triggers, make sure to check the boxes next to the following options:

· chargeback open (2Checkout sends an IPN when shoppers open a chargeback dispute).

· chargeback closed - (2Checkout sends an IPN when the parties involved resolve a chargeback dispute).

Also, check the checkbox next to the CHARGEBACK_RESOLUTION parameter featured in the Response tags area.
ChargebackReasonCode String
 

Identifier for the chargeback dispute reason from the 2Checkout system. Empty for orders with no chargeback dispute initiated.

Possible values:

  • MERCHANDISE_NOT_RECEIVED - Order not fulfilled/not delivered
  • NOT_AS_DESCRIBED - Product(s) not as described/unfunctional
  • DUPLICATE_TRANSACTION - Duplicate order
  • FRAUD / NOT_RECOGNIZED - Fraud/Order not recognized
  • CREDIT_NOT_PROCESSED - Agreed refund not processed
  • NOT_RECOGNIZED - New/renewal order not recognized
  • AUTHORIZATION_PROBLEM - Authorization problem
  • INFO_REQUEST - Information request
  • UNKNOWN - Unknown
OrderNo String
  The consecutive order number 2Checkout associates with orders and displays in the Order search area of your account.
ExternalReference String
  Set external reference identifiers for orders. Enables you to replicate the functionality of the REF parameter included into Buy Links. Maximum 100 characters. If there is a need for longer references, you can apply an md5 hash for any string value, resulting in a 32 characters string. You can verify the hash after the order notification, on the client side.
Status String
 

The status of the order:

  • AUTHRECEIVED – 2Checkout blocks the amount corresponding to the transaction, but the process of collecting funds is incomplete.
  • PENDING - 2Checkout has yet to block the amount corresponding to the transaction or shoppers used an offline payment method like wire transfer.
  • COMPLETE – The shopper completed the transaction for the purchase and 2Checkout or you fulfilled the order (when required).
  • CANCELED – 2Checkout cancels orders for which shoppers fail to transfer funds in due time.
  • REVERSED – 2Checkout reverses order transactions that never reach the Complete/Finished stage. Shoppers never complete transactions for such purchases.
  • REFUND – 2Checkout refunds orders only after they reach the Complete/Finished stage and returns the funds collected to shoppers.
ApproveStatus String
 

The status of the order resulted from the evaluation by the 2Checkout anti-fraud system or by a member of the anti-fraud department. This status varies for new purchases and for orders requiring customers to make manual payments.

Possible values:

  • WAITING: The 2Checkout anti-fraud system or a member of the anti-fraud department has yet to approve the order.
  • OK: The 2Checkout anti-fraud system or a member of the anti-fraud department approved the order.
  • INVALIDDATA: Shopper-supplied data is invalid – 2Checkout did not approve the order.
  • FRAUD: The order is fraudulent.
VendorApproveStatus String
 

Shows if you approved or not a partner order. Possible values:

  • OK
  • WAITING
  • REJECTED
Language String
  ISO 639-1 two-letter code. Language used for the purchase process. Example: “en.”
OrderDate String
  Y-m-d H:i:s (2014-05-22 00:12:12) The datetime stamp (in the API time zone defined in cPanel) when customers place their orders.
FinishDate String
 

Y-m-d H:i:s (2014-05-22 00:12:12) The datetime stamp (in the API time zone defined in cPanel) when the order reach the Complete status.

 

NULL for order that did not reach the Complete/Finished stage.
Source String
 

The link source for the sale. Enables you to replicate the functionality of the SRC (separate link identifier) parameter when included into Buy Links. Use the SRC parameter to track sale sources.

Maximum length 255 characters. Cannot be null.
Affiliate Object
  Details below.
                   AffiliateCode String
  The unique code of the affiliate who refer orders.
                   AffiliateSource String
  The link source for affiliate referred sales. Similar to the functionality of the SRC (separate link identifier) parameter included into Buy Links, but controlled by the AFFSRC parameter. Affiliates use the AFFSRC parameter to track sale sources for their referrals. Maximum length 255 characters.
                   AffiliateName String
  Affiliate name.
                   AffiliateUrl String
  Affiliate website URL from the Affiliate Details.
HasShipping Boolean
  true or false, depending on whether the order requires shipping.
DeliveryFinalized Boolean
  true or false, depending on whether product delivery has been completed.
BillingDetails Object
    Details below. 
    FirstName String
      Shopper name.
    LastName String
      Shopper surname.
    CountryCode String
      Shopper country. ISO 3166 two-letter code.
    State String
      The state in the shopper's country. Mandatory when you set the Billing Country to US, Turkey, India and Romania. Use case insensitive utf8 strings for the full name, or just the two letter code.
    City String
      Shopper city.
    Address1 String
      Shopper address.
    Address2 String
      Shopper address.
    Zip String
      ZIP/ Postal code.
    Email String
      Shopper email address.
    Phone String
      Shopper phone number. Mandatory when you set Brazil as the Billing Country. Can be NULL.
    Company String
      Company name. Can be null for end users. When present, you also need to provide the FiscalCode.
  FiscalCode String 
   

• For companies, it needs to be the VAT ID. 2Checkout will validate the value provided and throw an error if the VAT ID is invalid/incorrect when calling setPaymentDetails. When present, you also need to provide the Company name.

• Mandatory when the Billing Country is set to Brazil. For Brazilian customers it represents the Fiscal Code (CPF/CNPJ).

• Mandatory when the Billing Country is set to India, and purchase is made by a Company.

• Can be null for end users.
DeliveryDetails

Object

Optional. When missing, 2Checkout uses the same details as for the BillingDetails object.
      Details below. 
    FirstNameFirstName   String
        Shopper name from the delivery details.
    LastName   String
        Shopper surname from the delivery details.
    CountryCode   String
        Shopper country. ISO 3166 two-letter code from the delivery details.
    State   String
        The state in the shopper's country from the delivery details. Mandatory when you set the Billing Country to US, Turkey and Romania. Use case insensitive utf8 strings for the full name, or just the two letter code.
    City   String
        Shopper city from the delivery details.
    Address1   String
        Shopper address from the delivery details.
    Address2   String
        Shopper address from the delivery details.
    Zip   String
        ZIP/ Postal code from the delivery details.
    Email   String
        Shopper email address from the delivery details.
    Phone   String
        Shopper phone number from the delivery details. Mandatory when you set Brazil as the Billing Country. Can be NULL.
    Company   String
        Company name from the delivery details. Can be null for end users. When present, you also need to provide the FiscalCode.
PaymentDetails Optional (Object)
  Adapt this object to the desired payment method.
  Type String
   

The payment method:

  • CC (credit/debit card - including local Brazilian cards).
  • PAYPAL
  • PAYPAL_EXPRESS
  • CCNOPCI (credit/debit card for non-PCI certified merchants).
  • TEST (for test orders).
  • PREVIOUS_ORDER (place new orders using the reference of a previous order).
  • EXISTING_PAYMENT_DATA  (use a card one of your customers already used to purchase from your account).
  • WIRE – the placeOrder response includes Wire payment details.
  • CHECK – the placeOrder response includes Check payment details.
  • PURCHASEORDER - use for orders with POs.
  • FREE – for 0 value orders for which you’re not requiring customers to provide payment details.
  • GOOGLE PAY
  • eCheck/ACH
  • Stored Credit
  Currency String
    The currency ISO code for the payment - ISO 4217. Example: “usd.”
  PaymentMethod Optional (object)
   

Object structure and parameters differ according to payment method selected and API method (placing orders (POST) vs. retrieving order data (GET)). For payments with credit cards, PalPay Express, previous order reference and purchase order use the objects below.

 

For payments with check and wire, send only the ‘CHECH’ and ‘WIRE’ strings.

 

null for 0 value orders for which you’re not requiring customers to enter payment details.
                 RecurringEnabled Boolean
    true or false, depending on whether the shoppers checked the subscription auto-renewal checkbox or not, during the purchase process.
    PaymentDetailsCard Optional (object)
        Details below. 
      CardType String
        visa, visaelectron, mastercard, maestro, amex, discover, dankort, cartebleue, jcb, hipercard, elo
      FirstDigits String
        First four digits of the credit card.
      LastDigits String
        Last four digits of the credit card.
      RecurringEnabled Boolean
        true or false, depending whether the order has active recurring options
      Vendor3DSReturnURL String
        URL to which customers are redirected after a successful 3DS process.
      Vendor3DSCancelURL String
        URL to which customers are redirected after a failed 3DS process.
      InstallmentsNumber Integer
        Number of installments used for paying the order.
  CheckPaymentDetails Optional (Object)
      Details below. 
    Beneficiary String
     

The beneficiary of the payment.

Can be NULL.
    CheckPostalAddress String
     

The address of the beneficiary.

Can be NULL.
    Amount Float
     

The total costs incurred by the customer for an order.

Can be NULL.
    Currency String
     

The currency ISO code of the order/payment - ISO 4217.

Can be NULL.
  PayPalExpress Object
        Details below. 
      Email String
        Email address customers use for their PayPal account.
      ReturnURL String
        The PayPal Express Checkout redirect URL returned by calling the getPayPalExpressCheckoutRedirectURL method. The return URL is the page on your website to which PayPal redirects your buyer's browser after the buyer logs into PayPal and approves the payment. Typically, this is a secure page (https://...) on your site.
      CancelURL String
        The cancel URL is the page on your website to which PayPal redirects your buyer's browser if the buyer does not approve the payment. Typically, this is the secure page (https://...) on your site from which you redirected the buyer to PayPal.
  WirePaymentDetails Object
      Details below. 
    Amount Float
     

The total costs customers incur.

Can be NULL.
    Currency String
     

The currency ISO code of the order - ISO 4217.

Can be NULL.
    PaymentReference String
     

Transaction identifier.

Can be NULL.
    RoutingNumber String
     

Identification number assigned to financial institutions.

Can be NULL.
    BankAccounts Optional (Array of objects)
        Details below. 
      Beneficiary String
       

The beneficiary of the payment.

Can be NULL.
      BankName String
       

The name of the beneficiary's bank.

Can be NULL.
      BankCountry String
       

The country of the beneficiary's bank.

Can be NULL.
      BankCity String
       

The city of the beneficiary's bank.

Can be NULL.
      BankAddress String
       

The address of the beneficiary's bank.

Can be NULL.
      BankAccount String
       

The number for the account in which customers transfer the funds.

Can be NULL.
      BankAccountIban String
       

The IBAN of the beneficiary's bank.

Can be NULL.
      BankAccountSwiftCode String
       

The Swift Code of the beneficiary's bank.

Can be NULL.
      Currency String
       

The currency ISO code for the bank account - ISO 4217.

Can be NULL.
  DIRECT_DEBIT_ACH Object
    Details below.
    AccountHolderName String
      Full name of the account holder.
    BankRoutingNumber String
      Bank Routing number with fixed 9 digit length.
    AccountNumber String
      Account number consisting of up to 17 digits.
    AccountType String
      Possible values are "S" for SAVINGS accounts or "C" for CHECKING accounts.
  CustomerIP String
    Shopper IP.
CustomerDetails

Object

2Checkout populates the parameters of the customer entity with information from the customer whose AvangateCustomerReference or ExternalCustomerReference you send during the purchase.
    Details below. 
  AvangateCustomerReference Integer
    System-generated 2Checkout customer reference. Aggregate subscriptions under the same Customer account if the products they're associated to are purchased by the same shopper by adding the AV_CUSTOMERID (case sensitive) parameter to buy links. The 2Checkout system generates default customer numerical (integer) IDs (AV_CUSTOMERID) automatically for all orders containing products that feature subscriptions.
  ExternalCustomerReference String
    The external customer reference you control. Aggregate subscriptions under the same Customer account if the products they're associated to are purchased by the same shopper by adding the CUSTOMERID (case sensitive) parameter  to buy links.
  FirstName String
    Customer's first name. 
  LastName String
    Customer's last name.
  CountryCode String
    Customer's country code (ISO 3166 two-letter code).
  State String
    Customer's state. For example, "Alabama","Alaska","Arizona".
  City String
    Customer's city.
  Address1 String
    Customer's address.
  Address2 String
    Customer's address.
  Zip String
    Zip code.
  Email String
    Customer's email.
  Phone String
    Customer's phone number.
  Company String
    Company name.
  FiscalCode String
   

For companies, it needs to be the VAT ID. 2Checkout validates this values and throws an error if the VAT ID is invalid/incorrect. When present, you need to also provide Company name.

 

Can be null for end users.
  Fax String
    Customer's fax number.
  Enabled Boolean
    true or false, depending on whether the customer account is active or inactive. An active customer account features at least one Active or Past due subscription.
  Trial Boolean
    true or false, depending on whether the customer account features only trials or also paid subscriptions.
  Language String
    ISO 639-1 two-letter code. Example: “en.”
  ExistingCards Array of objects
      Details below. 
    TransientToken Object
      Populated only when you retrieve customer information by SSOToken.
      Token String
        Token for the EXISTING_PAYMENT_DATA flow. Use it to charge customers using cards they used in the past for purchases from your 2Checkout account.
    CardType String
      visa, visaelectron, mastercard, maestro, amex, discover, dankort, cartebleue, jcb, hipercard, elo
    LastDigits String
      Last four digits of the credit card.
    ExpirationMonth String
      Card expiration month.
    ExpirationYear String
      Card expiration year.
    NameOnCard String
      Card holder name.
Origin String
 

2Checkout automatically tracks the source of purchases:

 

  • Web – When customers use the desktop version of the 2Checkout shopping cart.
  • API - When customers use a custom, API-based ordering interface.
  • Mobile - When customers use the mobile version of the 2Checkout shopping cart.
  • Automatic Billing – For auto-renewals and trial conversions.
AvangateCommission Optional (Int)
  2Checkout's commission for the order.
OrderFlow String
 

PURCHASE_ORDER - Sent only when shoppers used Purchase Orders.

REGULAR - Sent in all other cases.
GiftDetails Optional (object)
  Contains contact details for the recipient of a gift purchase.
  FirstName String
    First name of gift recipient.
  LastName String
    Last name of gift recipient.
  Email String
    Email of gift recipient. 2Checkout uses this email for the delivery/fulfillment process.
  GiftNote String
    Custom text shoppers provide as a message to the gift recipient.
PODetails Object (optional)
    Details below. 
  Status String
   

PO status. Possible values:

 

PO status API PO status cPanel
AWAITING_UPLOAD Awaiting form submission - Waiting for the customer to submit the PO form
TIME_EXPIRED Expired, form not received - The customer did not submit the PO form
AWAITING_MERCHANT Awaiting your confirmation - PO approved by 2Checkout, awaiting vendor confirmation
MERCHANT_TIME_EXPIRED Expired, PO not confirmed - You didn't confirm/reject the PO
AWAITING_MERCHANT Rejected - You rejected the PO
AWAITING_PAYMENT Awaiting payment - You approved the PO, waiting for payment
AWAITING_PAYMENT Expired, not paid - The customer did not complete the PO payment. 2Checkout accepts  payments up to 30 days after the PO payment interval expires
NOT_PAID Canceled, not paid - The customer did not complete the PO payment
NOT_PAID Canceled by 2Checkout - 2Checkout canceled the PO
NOT_PAID Canceled via API - You canceled the PO (via API)
PAID Complete - Customer paid the PO. The order is complete
  AutoApprove Boolean
  TRUE or FALSE, depending on whether you set POs to auto-approve or not.
  RequireDocumentUpload Boolean
  TRUE or FALSE, depending on whether require document upload or not.
  NetPaymentTerms Integer
  The term of net payment in days.
  CopyPreviousDocuments Boolean
  TRUE or FALSE, depending on whether copy documents from previous order or not.
  PdfFormUrl String
  URL of Purchase Order form which needs to be printed, signed and uploaded.
  InternalPONumber String
  Identifier that business customers use internally in their organization to track and manage Purchase Orders (PO). Can be NULL.
ExtraInformation Optional (Object)
  Details below. 
  PaymentLink String
   

Can be:

1. The PO doc upload link - If you set AutoApprove as FALSE on the original order and before shoppers upload the PO. 

2. Payment link for orders with POs. Business customers can use the PaymentLink to finalize payment for orders with POs. If you set AutoApprove as TRUE on the original order and if 2Checkout and you approve the PO. 
PaymentLink String
  In scenarios in which an issue blocks the transaction from finalizing, 2Checkout provides a retry link where shopper can complete their purchase by providing new payment details.
PartnerCode String
  Partner code you configured for your partner. NULL for eStore orders.
PartnerMargin Float
  Partner margin you set for the order. NULL for eStore orders.
PartnerMarginPercent Float
  The percentage of the partner margin from the net value of the products ordered, minus the value of any discounts. NULL for eStore orders.
ExtraMargin Float
  Extra margin you offer by editing partner orders. NULL for eStore orders.
ExtraMarginPercent Float
  The percentage of the extra partner margin from the net value of the products ordered, minus the partner margin and the value of any discounts. NULL for eStore orders.
ExtraDiscount Float
  Extra discount you offer by editing partner orders. NULL for eStore orders.
ExtraDiscountPercent Float
  The percentage of the partner margin from the net value of the products ordered, minus the value of any coupon discounts. NULL for eStore orders.
LocalTime String
 

Local shopper time in the following format: Y-m-d H:i:s.

This parameter can impact the fraud score of an order when it's missing, NULL or incorrectly formatted.
TestOrder Boolean
  True for test orders. False of regular orders.
Errors Array of strings
  Payment gateway processing errors.
Items Array of objects
    Details below. 
  ProductDetails Object
    Name String
      Product name.
    ShortDescription String
      Product short description.
    Tangible Boolean
      true or false, depending on product delivery type.
    IsDynamic Boolean
     

Possible values:

  • true - dynamic product information
  • false - catalog products
    ExtraInfo String
      The text entered in the Additional information field when generating Buy links, or via the INFO[PRODUCT_ID] parameter used in Buy links.
    RenewalStatus Boolean
     
  • true for orders renewing subscriptions.
  • false for all other orders: new purchases, upgrades.
    DeliveryInformation

Object

Details below
          Delivery   String
     

Possible values:

  • BY_VENDOR
  • NO_DELIVERY
  • BY_AVANGATE
          DownloadFile   Object
      Information related to the download file.
          DeliveryDescription   String
      Delivery description.
          CodesDescription   String
      Description of codes delivered.
          Codes   Array of strings
              Array with the codes delivered
    Subscriptions Object
      SubscriptionReference String
        Unique, system-generated subscription identifier.
      PurchaseDate String
       

The date time stamp when shoppers acquired their subscriptions corresponding to the moment when the 2Checkout system marks the purchase as finished. Format (YYYY-MM-DD HH:mm:ss). Default GMT+02:00.

 

e.g. 2015-08-11 15:18:52
      SubscriptionStartDate String
       

 

Example: 2015-09-29 17:57:59
      ExpirationDate String
       

The date time stamp of upcoming renewal/expiration for subscriptions not taking into account grace period settings.

 

Format (YYYY-MM-DD HH:mm:ss). Default GMT+02:00.

 

e.g. 2015-09-11 15:18:52
      Lifetime Boolean
       
  • true – For non-recurring, evergreen subscriptions.
  • false – For recurring subscriptions with a specific billing cycle from 7 days to 36 months.
      Trial Boolean
       
  • true – For trial subscriptions.
  • false – For non-trial, recurring subscriptions with a specific billing cycle from 7 days to 36 months.
      Enabled Boolean
       
  • true – For active and past due subscriptions.
  • false – For expired and cancelled subscriptions.
      RecurringEnabled Boolean
         
  PriceOptions Array of strings
    Array of price option codes.
    Code Strings
      Unique code that the 2Checkout system generates or that you set for each pricing options group.
    Required Boolean
     
  • true – you require shoppers to select the price option  through the way in which you configured pricing.
  • false – you do not require shoppers to select the price option.
    Options Array of strings
      The code you set or that the 2Checkout system generates for each price option child inside a pricing options group parent.
  Price Object
   

This object returns the price per unit at order line level.

 

In the case of trials, the object returns the costs for the trial to full subscription conversion.
    UnitNetPrice Float
      The value per product unit, excluding sales tax/VAT expressed in the payment currency.
    UnitGrossPrice Float
      Total value per product unit, including sales tax/VAT expressed in the payment currency. UnitGrossPrice does not reflect any discounts.
    UnitVAT Float
      Sales tax/VAT per product unit expressed in the payment currency.
    UnitDiscount Float
      Value of the discount per product unit expressed in the payment currency.
    UnitNetDiscountedPrice Float
      The value per product unit, expressed in the payment currency, excluding sales tax/VAT, from which 2Checkout deducts the unit discount.
    UnitGrossDiscountedPrice Float
      Total costs shoppers incur per product unit, expressed in the payment currency. This value includes sales tax/VAT, 2Checkout and affiliate commissions, but 2Checkout deducts the value of any discounts.
    UnitAffiliateCommission Float
     

Value of the affiliate commission per product unit calculated expressed in the payment currency.

 

2Checkout deducts discounts from the costs incurred by shoppers before calculating affiliate commissions.

 

2Checkout does not take into account shipping costs when calculating affiliate commissions.

 

NULL when 2Checkout does not apply an affiliate commission.
    Currency String
      The currency ISO code for the payment - ISO 4217. Example: usd.
    NetPrice Float
      The value per order line, excluding sales tax/VAT expressed in the payment currency.
    GrossPrice Float
      Total value per order line, including sales tax/VAT expressed in the payment currency. UnitGrossPrice does not reflect any discounts.
    NetDiscountedPrice Float
      The NetPrice value per order line (in the payment currency), excluding sales tax/VAT, from which 2Checkout deducts discounts.
    GrossDiscountedPrice Float
     

Total costs shoppers incur per order line, expressed in the payment currency. This value includes sales tax/VAT, 2Checkout and affiliate commissions, but 2Checkout deducts the value of any discounts.

 

Example:

  • UnitNetPrice: 99
  • UnitGrossPrice: 120.39
  • UnitVAT: 21.39
  • UnitDiscount: 9.9
  • UnitNetDiscountedPrice: 89.1
  • UnitGrossDiscountedPrice: 110.49
  • UnitAffiliateCommission: 22.28
  • Currency: "usd"
  • NetPrice: 198
  • GrossPrice: 240.77
  • NetDiscountedPrice: 178.2
  • GrossDiscountedPrice: 220.97
  • Discount: 19.8
  • VAT: 42.77
  • AffiliateCommission: 44.56
    Discount Float
      Value of the discounts per order line expressed in the payment currency.
    VAT Float
      Value of sales tax/VAT per order line expressed in the payment currency.
    AffiliateCommission Float
      Value of the affiliate commission per order line, calculated from the NetDiscountedPrice expressed in the payment currency. Or NULL. 2Checkout does not take into account shipping costs when calculating affiliate commissions.
    VATPercent Integer
      Percentage of the VAT/tax applied to the order.
    HandlingFeeNetPrice Integer
      Handling fee applied to the NET price configuration.
    HandlingFeeGrossPrice Integer
      Handling fee applied to the GROSS price configuration.
  LineItemReference String
    System-generated reference for the product item.
  PurchaseType String
   

Possible values:

  • PRODUCT
  • SHIPPING
  • TAX
  • COUPON
  Code String
    Unique product identifier your control. Max length 256 characters.
  Quantity Integer
    Number of units
  SKU String
    SKU identifier.
  CrossSell Object
      Details below. 
    ParentCode String
      The product code of the master product you set to trigger the campaign.
    CampaignCode String
      Unique, system-generated identifier for cross-sell campaigns.
  Trial Object
      Details below. 
    Period Integer
      The length of the trial subscription lifetime in days.
    GrossPrice Float
      Total trial price in the payment currency before 2Checkout deducts any taxes, discounts, etc.
    VAT Float
      The total value of taxes for the trial in the payment currency, before 2Checkout deducts any discounts.
    NetPrice Float
      Total trial price in the payment currency, not including taxes, before 2Checkout deducts any discounts.
  AdditionalFields Array of objects
      Details below. 
    Code String
      The alpha-numeric characters, underscores and dashes that are set as the field identifier.
    Text String
      Field text visible to shoppers in the cart.
    Value String
      Selected field value.
  Promotion Object
      Details below. 
    Name String
      Promotion name.
    Description String
      Promotion description.
    StartDate String
      The date when you set the promotion to start. NULL for promotions that start immediately after you create them.
    EndDate String
      The date when you set the promotion to end. NULL for promotions you want active indefinitely.
    MaximumOrdersNumber Integer
     

2Checkout only applies the promotion to a maximum number of orders you define.

 

Can be NULL if you want the promotion to apply to an unlimited number of orders.
    MaximumQuantity Integer
      Discount only applies to a maximum number of units purchased through a single order, smaller than the quantity you defined. Shoppers purchase any extra units at full price. Can be NULL if you want the promotion to apply to an unlimited number units.
    InstantDiscount Boolean
      The instant discount option auto-applies the discount for ALL selected products, without the need for shoppers to enter a discount coupon.
    Coupon String
      Promotion coupon/voucher.
    DiscountLabel String
      Discounts can be set as a percentage from the product price or as a fixed amount in the chosen currency.
    Enabled String
      true or false, depending on whether a promotion is active or disabled. 
    Type String
     
  • REGULAR – product/cart line level discounts.
  • ORDER – quantity discounts.
  • GLOBAL – order-level discounts.
  • AFFILIATE – for discounts created by affiliates.
Promotions Array of objects
    Details below. 
  Name String
    Promotion name.
  Description String
    Promotion description.
  StartDate String
    The date when you set the promotion to start. NULL for promotions that start immediately after you create them.
  EndDate String
    The date when you set the promotion to end. NULL for promotions you want active indefinitely.
  MaximumOrdersNumber Integer
   

2Checkout only applies the promotion to a maximum number of orders you define.

 

Can be NULL if you want the promotion to apply to an unlimited number of orders.
  MaximumQuantity Integer
    Discount only applies to a specific number of units purchased at once, smaller than the maximum quantity you defined. Shoppers purchase any extra units at full price. Can be NULL if you want the promotion to apply to an unlimited number units.
  InstantDiscount Boolean
    The instant discount option auto-applies the discount for ALL selected products, without the need for shoppers to enter a discount coupon.
  Coupon String
    Promotion coupon/voucher.
  DiscountLabel String
    Discounts can be set as a percentage from the product price or as a fixed amount in the payment currency.
  Enabled String
    true or false, depending on whether a promotion is active or disabled. 
  Type String
   
  • REGULAR – product/cart line level discounts.
  • ORDER – quantity discounts.
  • GLOBAL – order-level discounts.
  • AFFILIATE – for discounts created by affiliates.
AdditionalFields Array of objects
    Details below. 
  Code String
    The alpha-numeric characters, underscores and dashes that are set as the field identifier.
  Text String
    Field text visible to shoppers in the cart.
  Value String
    Selected field value.
Currency String
  The currency ISO code for the payment - ISO 4217. Example: usd.
NetPrice Float
  Order value excluding sales tax/VAT expressed in the payment currency.
GrossPrice Float
  Total order value, including sales tax/VAT expressed in the payment currency. GrossPrice does not reflect any discounts.
NetDiscountedPrice Float
  The NetPrice order value excluding sales tax/VAT, from which 2Checkout deducts discounts. NetDiscountedPrice is expressed in the payment currency.
GrossDiscountedPrice Float
 

Total costs shoppers incur, expressed in the payment currency. This value includes sales tax/VAT, 2Checkout and affiliate commissions, but 2Checkout deducts the value of any discounts.

 

For example:

  • Currency: "usd"
  • NetPrice: 396
  • GrossPrice: 486.29
  • NetDiscountedPrice: 376.2
  • GrossDiscountedPrice: 466.49
  • Discount: 19.8
  • VAT: 90.29
  • AffiliateCommission: 94.05
Discount Float
  Value of the discounts for an order expressed in the payment currency.
VAT Float
  Value of sales tax/VAT expressed in the payment currency.
AffiliateCommission Float
  Value of the affiliate commission for the order calculated from the NetDiscountedPrice expressed in the payment currency. Or NULL. 2Checkout does not take into account shipping costs when calculating affiliate commissions.
FxRate Integer
  Exchange rate used by 2Checkout for converting the order to your payout currency.
FxMarkup Integer
  Exchange rate markup for the order.
PayoutCurrency String
  The ISO code of your account's payout currency - ISO 4217.

Create price option groups

Overview

Use the addPriceOptionGroup method to create price options for your subscription plans/products.

  • Send options for each pricing group or 2Checkout throws an exception.
  • When adding an interval with no min/max values or overlapping values, 2Checkout throws an exception. 

Parameters

Parameters Type/Description

Parameters

Type/Description

sessionID

Required (string)

 

Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect.  The sessionID expires in 10 minutes.

PriceOptionsGroup

Required (object)

 

Use this object to create a new price option group for your account.

Response

bool(true)

Request

<?php

require ('PATH_TO_AUTH');

$PriceOptionGroup = new stdClass();
$PriceOptionGroup->Name = 'New Multi Users';
$PriceOptionGroup->Description = 'Quos aut ipsam ipsum omnis aut molestiae. Et quod molestias distinctio. Fugiat sit asperiores reprehenderit officia eaque quae quia. Aperiam quia quia illo eos nesciunt accusamus.';
$PriceOptionGroup->Translations = array();
$PriceOptionGroup->Translations[0] = new stdClass();
$PriceOptionGroup->Translations[0]->Name = 'xdrki7ljix';
$PriceOptionGroup->Translations[0]->Description = 'Beatae doloribus ipsam voluptatem et. Iure dignissimos non amet. Quibusdam fugiat dolor repudiandae temporibus harum.';
$PriceOptionGroup->Translations[0]->Language = 'en';
$PriceOptionGroup->Translations[1] = new stdClass();
$PriceOptionGroup->Translations[1]->Name = '37wr8ie2dj';
$PriceOptionGroup->Translations[1]->Description = 'Esse distinctio voluptatibus omnis et et quia dolor. Quibusdam dicta dolores odio consequatur velit voluptate. Laboriosam reiciendis libero vel quae molestiae ad.';
$PriceOptionGroup->Translations[1]->Language = 'ru';
$PriceOptionGroup->Type = 'RADIO';
$PriceOptionGroup->Options = array();
$PriceOptionGroup->Options[0] = new stdClass();
$PriceOptionGroup->Options[0]->Name = 'SingleUser';
$PriceOptionGroup->Options[0]->Description = 'Nisi ea autem a labore similique. Minus natus cumque nemo. Aut aliquam laboriosam dolorem ad.';
$PriceOptionGroup->Options[0]->Translations = array();
$PriceOptionGroup->Options[0]->Translations[0] = new stdClass();
$PriceOptionGroup->Options[0]->Translations[0]->Name = '0q2r3kcj0q';
$PriceOptionGroup->Options[0]->Translations[0]->Description = 'Voluptatem in vitae rerum ea tempore. Non cumque ullam optio quis. Laborum maxime sunt facere. Dolor fugit a fugiat quasi facere totam.';
$PriceOptionGroup->Options[0]->Translations[0]->Language = 'en';
$PriceOptionGroup->Options[0]->Translations[1] = new stdClass();
$PriceOptionGroup->Options[0]->Translations[1]->Name = 'dwfxuw4lrn';
$PriceOptionGroup->Options[0]->Translations[1]->Description = 'Debitis omnis maiores quia praesentium totam error corrupti. Consectetur eum magnam quam vero. Sit aperiam natus perspiciatis iusto sint ut fugit. Adipisci illum non voluptatem voluptas.';
$PriceOptionGroup->Options[0]->Translations[1]->Language = 'it';
$PriceOptionGroup->Options[0]->Code = 'singleuser1';
$PriceOptionGroup->Options[0]->SubscriptionImpact = new stdClass();
$PriceOptionGroup->Options[0]->SubscriptionImpact->Impact = 'Add';
$PriceOptionGroup->Options[0]->SubscriptionImpact->Months = 1;
$PriceOptionGroup->Options[0]->PriceImpact = new stdClass();
$PriceOptionGroup->Options[0]->PriceImpact->Method = 'FIXED';
$PriceOptionGroup->Options[0]->PriceImpact->Amounts = array();
$PriceOptionGroup->Options[0]->PriceImpact->Amounts[0] = new stdClass();
$PriceOptionGroup->Options[0]->PriceImpact->Amounts[0]->Currency = 'USD';
$PriceOptionGroup->Options[0]->PriceImpact->Amounts[0]->Amount = 90.61;
$PriceOptionGroup->Options[0]->PriceImpact->Amounts[1] = new stdClass();
$PriceOptionGroup->Options[0]->PriceImpact->Amounts[1]->Currency = 'EUR';
$PriceOptionGroup->Options[0]->PriceImpact->Amounts[1]->Amount = 6.70;
$PriceOptionGroup->Options[0]->PriceImpact->ImpactOn = 'BASE';
$PriceOptionGroup->Options[0]->PriceImpact->Impact = 'ADD';
$PriceOptionGroup->Options[0]->PriceImpact->Percent = 39;
$PriceOptionGroup->Options[0]->Default = false;
$PriceOptionGroup->Options[1] = new stdClass();
$PriceOptionGroup->Options[1]->Name = 'MultiUser';
$PriceOptionGroup->Options[1]->Description = 'Vero voluptatum fuga et repellendus sed qui. Dolores molestiae error non ad aperiam. In error quos eum quas repudiandae pariatur et suscipit.';
$PriceOptionGroup->Options[1]->Translations = array();
$PriceOptionGroup->Options[1]->Translations[0] = new stdClass();
$PriceOptionGroup->Options[1]->Translations[0]->Name = 'MultiUser';
$PriceOptionGroup->Options[1]->Translations[0]->Description = 'Debitis et saepe facere blanditiis. Tempore et nemo aut ullam possimus ipsum nisi. Ad libero et consequuntur aliquam libero. Rerum aut illum eveniet earum.';
$PriceOptionGroup->Options[1]->Translations[0]->Language = 'en';
$PriceOptionGroup->Options[1]->Translations[1] = new stdClass();
$PriceOptionGroup->Options[1]->Translations[1]->Name = 'dw5zgkcki9';
$PriceOptionGroup->Options[1]->Translations[1]->Description = 'Vel et excepturi veniam. In iusto eveniet pariatur hic labore. Et qui dolorem accusantium molestias iusto.';
$PriceOptionGroup->Options[1]->Translations[1]->Language = 'pt';
$PriceOptionGroup->Options[1]->Code = 'multiuser999';
$PriceOptionGroup->Options[1]->SubscriptionImpact = new stdClass();
$PriceOptionGroup->Options[1]->SubscriptionImpact->Impact = 'ADD';
$PriceOptionGroup->Options[1]->SubscriptionImpact->Months = 2;
$PriceOptionGroup->Options[1]->PriceImpact = new stdClass();
$PriceOptionGroup->Options[1]->PriceImpact->Method = 'FIXED';
$PriceOptionGroup->Options[1]->PriceImpact->Amounts = array();
$PriceOptionGroup->Options[1]->PriceImpact->Amounts[0] = new stdClass();
$PriceOptionGroup->Options[1]->PriceImpact->Amounts[0]->Currency = 'USD';
$PriceOptionGroup->Options[1]->PriceImpact->Amounts[0]->Amount = 65.03;
$PriceOptionGroup->Options[1]->PriceImpact->Amounts[1] = new stdClass();
$PriceOptionGroup->Options[1]->PriceImpact->Amounts[1]->Currency = 'EUR';
$PriceOptionGroup->Options[1]->PriceImpact->Amounts[1]->Amount = 64.58;
$PriceOptionGroup->Options[1]->PriceImpact->ImpactOn = 'BASE';
$PriceOptionGroup->Options[1]->PriceImpact->Impact = 'ADD';
$PriceOptionGroup->Options[1]->PriceImpact->Percent = 51;
$PriceOptionGroup->Options[1]->Default = true;
$PriceOptionGroup->Code = null;
$PriceOptionGroup->Required = false;

$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'addPriceOptionGroup',
'params' => array($sessionID, $PriceOptionGroup)
);

var_dump (callRPC((Object)$jsonRpcRequest, $host, true));

?>

Pay-per-Usage

Use this option to create and assign PAYPERUSE price options to your portfolio.

For non PAYPERUSAGE cases, the Usage and UsagePricingModel fields are not required.

 Request sample with PAYPERUSE

<?php
declare(strict_types=1);

class Configuration
{
    public const MERCHANT_CODE = '';
    public const MERCHANT_KEY = '';
    public const URL = 'http://api.2checkout.com/rpc/6.0';
    public const ACTION = 'addPriceOptionGroup';
    public const ADDITIONAL_OPTIONS = null;
    //array or JSON
    public const PAYLOAD = <<<JSON
{
    "Type": "INTERVAL",
    "Code": "PayPerUsage-CODE",
    "Required": false,
    "Name": "Pay per usage pricing option group",
    "Description": "Test option description",
    "Usage": "PAYPERUSAGE",
    "UsagePricingModel": "STEPPED",
    "Options": [
        {
            "Code": "9876545678",
            "ScaleMin": "1",
            "ScaleMax": "9",
            "SubscriptionImpact": {
                "Months": "0.00",
                "Impact": null
            },
            "PriceImpact": {
                "Amounts": {
                    "USD": {
                        "Currency": "USD",
                        "Amount": "1.00"
                    },
                    "EUR": {
                        "Currency": "EUR",
                        "Amount": "6.00"
                    }
                },
                "ImpactOn": null,
                "Method": "FIXED",
                "Percent": null,
                "Impact": null
            },
            "Default": false,
            "Name": "translation_5f90150268bef",
            "Description": "Translation value",
            "Translations": [
                {
                    "Name": "translation_5f90150268bf7",
                    "Description": "Translation value",
                    "Language": "RO"
                },
                {
                    "Name": "translation_5f90150268bef",
                    "Description": "Translation value",
                    "Language": "EN"
                },
                {
                    "Name": "translation_5f90150268bf9",
                    "Description": "Translation value",
                    "Language": "FR"
                },
                {
                    "Name": "translation_5f90150268bf5",
                    "Description": "Translation value",
                    "Language": "RU"
                }
            ]
        },
        {
            "Code": "98765456789",
            "ScaleMin": "10",
            "ScaleMax": "19",
            "SubscriptionImpact": {
                "Months": "0.00",
                "Impact": null
            },
            "PriceImpact": {
                "Amounts": {
                    "USD": {
                        "Currency": "USD",
                        "Amount": "1.00"
                    },
                    "EUR": {
                        "Currency": "EUR",
                        "Amount": "6.00"
                    }
                },
                "ImpactOn": null,
                "Method": "FIXED",
                "Percent": null,
                "Impact": null
            },
            "Default": false,
            "Name": "translation_5f90150268bef",
            "Description": "Translation value",
            "Translations": [
                {
                    "Name": "translation_5f90150268bf7",
                    "Description": "Translation value",
                    "Language": "RO"
                },
                {
                    "Name": "translation_5f90150268bef",
                    "Description": "Translation value",
                    "Language": "EN"
                },
                {
                    "Name": "translation_5f90150268bf9",
                    "Description": "Translation value",
                    "Language": "FR"
                },
                {
                    "Name": "translation_5f90150268bf5",
                    "Description": "Translation value",
                    "Language": "RU"
                }
            ]
        }
    ],
    "Translations": [
        {
            "Name": "Pay per usage pricing option group",
            "Description": "Test option description",
            "Language": "EN"
        }
    ]
}
JSON;
}

class Client
{
    private const LOGIN_METHOD = 'login';
    private $calls = 1;
    private $sessionId;


    private function generateAuth(): array
    {
        $merchantCode = Configuration::MERCHANT_CODE;
        $key = Configuration::MERCHANT_KEY;
        $date = gmdate('Y-m-d H:i:s');
        $string = strlen($merchantCode) . $merchantCode . strlen($date) . $date;
        $hash = hash_hmac('md5', $string, $key);

        return compact('merchantCode', 'date', 'hash');
    }


    public function login(string $url)
    {
        $payload = $this->generateAuth();
        $response = $this->call($url, array_values($payload), self::LOGIN_METHOD);
        $this->sessionId = $response['result'];
    }


    public function call(
        string $url = Configuration::URL,
        $payload = Configuration::PAYLOAD,
        string $action = Configuration::ACTION
    ): ?array {
        if (empty($this->sessionId) && $action !== self::LOGIN_METHOD) {
            $this->login($url);
        }
        if(is_string($payload)) {
            $payload = json_decode($payload, true);
        }
        if (!empty($this->sessionId)) {
            $payload = [$this->sessionId, $payload, Configuration::ADDITIONAL_OPTIONS];
        }
        $payload = array_filter($payload);

        $request = json_encode([
            'jsonrpc' => '2.0',
            'method' => $action,
            'params' => $payload,
            'id' => $this->calls++,
        ]);
        $curl = curl_init($url);
        curl_setopt($curl, CURLOPT_POST, 1);
        curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
        curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
        curl_setopt($curl, CURLOPT_SSLVERSION, 0);
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Accept: application/json', 'Cookie: XDEBUG_SESSION=PHPSTORM'));
        curl_setopt($curl, CURLOPT_POSTFIELDS, $request);
        $response = curl_exec($curl);
        if(empty($response)) {
            die('Server unavailable');
        }
        echo $response . '</br>';
        return json_decode($response, true);;
    }
}
$client = new Client();
$result = $client->call();
var_dump($result);

 Request sample without PAYPERUSE

<?php
declare(strict_types=1);

class Configuration
{
    public const MERCHANT_CODE = '';
    public const MERCHANT_KEY = '';
    public const URL = 'http://api.2checkout.com/rpc/6.0';
    public const ACTION = 'addPriceOptionGroup';
    public const ADDITIONAL_OPTIONS = null;
    //array or JSON
    public const PAYLOAD = <<<JSON
{
    "Type": "RADIO",
    "Code": "RADIO-CODE",
    "Required": false,
    "Name": "Radio pricing option group",
    "Description": "Test option description",
    "Options": [
        {
            "Code": "9876545678",
            "ScaleMin": "1",
            "ScaleMax": "9",
            "SubscriptionImpact": {
                "Months": "0.00",
                "Impact": null
            },
            "PriceImpact": {
                "Amounts": {
                    "USD": {
                        "Currency": "USD",
                        "Amount": "1.00"
                    },
                    "EUR": {
                        "Currency": "EUR",
                        "Amount": "6.00"
                    }
                },
                "ImpactOn": null,
                "Method": "FIXED",
                "Percent": null,
                "Impact": null
            },
            "Default": false,
            "Name": "translation_5f90150268bef",
            "Description": "Translation value",
            "Translations": [
                {
                    "Name": "translation_5f90150268bf7",
                    "Description": "Translation value",
                    "Language": "RO"
                },
                {
                    "Name": "translation_5f90150268bef",
                    "Description": "Translation value",
                    "Language": "EN"
                },
                {
                    "Name": "translation_5f90150268bf9",
                    "Description": "Translation value",
                    "Language": "FR"
                },
                {
                    "Name": "translation_5f90150268bf5",
                    "Description": "Translation value",
                    "Language": "RU"
                }
            ]
        },
        {
            "Code": "98765456789",
            "ScaleMin": "10",
            "ScaleMax": "19",
            "SubscriptionImpact": {
                "Months": "0.00",
                "Impact": null
            },
            "PriceImpact": {
                "Amounts": {
                    "USD": {
                        "Currency": "USD",
                        "Amount": "1.00"
                    },
                    "EUR": {
                        "Currency": "EUR",
                        "Amount": "6.00"
                    }
                },
                "ImpactOn": null,
                "Method": "FIXED",
                "Percent": null,
                "Impact": null
            },
            "Default": false,
            "Name": "translation_5f90150268bef",
            "Description": "Translation value",
            "Translations": [
                {
                    "Name": "translation_5f90150268bf7",
                    "Description": "Translation value",
                    "Language": "RO"
                },
                {
                    "Name": "translation_5f90150268bef",
                    "Description": "Translation value",
                    "Language": "EN"
                },
                {
                    "Name": "translation_5f90150268bf9",
                    "Description": "Translation value",
                    "Language": "FR"
                },
                {
                    "Name": "translation_5f90150268bf5",
                    "Description": "Translation value",
                    "Language": "RU"
                }
            ]
        }
    ],
    "Translations": [
        {
            "Name": "Radio pricing option group",
            "Description": "Test option description",
            "Language": "EN"
        }
    ]
}
JSON;
}

class Client
{
    private const LOGIN_METHOD = 'login';
    private $calls = 1;
    private $sessionId;


    private function generateAuth(): array
    {
        $merchantCode = Configuration::MERCHANT_CODE;
        $key = Configuration::MERCHANT_KEY;
        $date = gmdate('Y-m-d H:i:s');
        $string = strlen($merchantCode) . $merchantCode . strlen($date) . $date;
        $hash = hash_hmac('md5', $string, $key);

        return compact('merchantCode', 'date', 'hash');
    }


    public function login(string $url)
    {
        $payload = $this->generateAuth();
        $response = $this->call($url, array_values($payload), self::LOGIN_METHOD);
        $this->sessionId = $response['result'];
    }


    public function call(
        string $url = Configuration::URL,
        $payload = Configuration::PAYLOAD,
        string $action = Configuration::ACTION
    ): ?array {
        if (empty($this->sessionId) && $action !== self::LOGIN_METHOD) {
            $this->login($url);
        }
        if(is_string($payload)) {
            $payload = json_decode($payload, true);
        }
        if (!empty($this->sessionId)) {
            $payload = [$this->sessionId, $payload, Configuration::ADDITIONAL_OPTIONS];
        }
        $payload = array_filter($payload);

        $request = json_encode([
            'jsonrpc' => '2.0',
            'method' => $action,
            'params' => $payload,
            'id' => $this->calls++,
        ]);
        $curl = curl_init($url);
        curl_setopt($curl, CURLOPT_POST, 1);
        curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
        curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
        curl_setopt($curl, CURLOPT_SSLVERSION, 0);
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Accept: application/json', 'Cookie: XDEBUG_SESSION=PHPSTORM'));
        curl_setopt($curl, CURLOPT_POSTFIELDS, $request);
        $response = curl_exec($curl);
        if(empty($response)) {
            die('Server unavailable');
        }
        echo $response . '</br>';
        return json_decode($response, true);;
    }
}
$client = new Client();
$result = $client->call();
var_dump($result);

 

Cross-sell

Overview

Use this object to retrieve information about the cross-sell campaigns you configured for your account. 

Parameters

Parameter Type/Description

CrossSellCampaign

Object

MasterProducts

Array

 

Array of product codes for the items you set to trigger the cross-sell campaign.

DisplayType

String

 
  • cart – Shopping cart
  • review – Review page
  • finish – Thank you page

DisplayInEmail

Boolean

 

True or false depending on whether you set the cross-sell campaign to display in payment receipt emails or not.

Products

Array of objects

 

Details below

 

ProductCode

String

 

 

Product code for the item you set as recommended for the cross-sell campaign.

 

Discount

String

 

 

Value of the discount. This is a percentage.

 

DiscountType

String

 

 

PERCENT – you can only set discounts as a percentage from the product price.

CampaignCode

String

 

Unique, system-generated cross-sell campaign code.

Name

String

 

Campaign name.

StartDate

String

 

YYYY-MM-DD. The start date you set for the cross-sell campaign.

EndDate

String

 

YYYY-MM-DD. The end date you set for the cross-sell campaign.

 

Search subscriptions

Overview

Extract information on your account’s subscriptions. Use the searchSubscriptions method to retrieve details about your account’s subscriptions, based on a set of filters.

Subscriptions can be retrieved starting with 5 minutes after their orders are generated in the 2Checkout system.

Parameters

Parameters Type/Description

sessionID

Required (string)

 

Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect.  The sessionID expires in 10 minutes.

searchBy

Optional (Object)
  Contains any combination of the available additional search filters.

Additional search filters

SubscriptionSearchOptions Parameters Type/Description

CustomerEmail

Optional (string)

 

Customer email address. Can be NULL.

Note: The CustomerEmail parameter must be paired always with another reference pointing to the correct customer, such as the 2CheckoutCustomerReference parameter or the ExternalCustomerReference parameter. Otherwise, the search call will return partial hits on the customer email address.
ExactMatchEmail Optional (Boolean)
  Force search by email to perform exact match; recommended to keep this option set to true in order to avoid matching similar email addresses from multiple customers.

DeliveredCode

Optional (string)
 

Activation key/code. Can be NULL.

AvangateCustomerReference

Optional (int)

 

System-generated customer reference. Can be NULL.

ExternalCustomerReference

Optional (string)

 

External customer reference that you control. Can be NULL.

Aggregate

Optional (boolean)

 

true - search will work across all your aggregated 2Checkout accounts.

false - default value. You limit the search to the account whose details you used for authentication.

Can be NULL.

SubscriptionEnabled

Optional (boolean)

 

true for enabled subscriptions.

false for disabled subscriptions.

Can be NULL.

RecurringEnabled

Optional (StringArray)

 

true – 2Checkout charges customers using recurring billing for subscriptions.

false – customers need to make manual payments to renew their subscriptions.

Can be NULL.

ProductCodes

Optional (StringArray)

 

Product identifier that you control. Can be NULL.

CountryCodes

Optional (string)

 

Country code (ISO 3166 two-letter code). Can be NULL.
PartnerCode Optional (string)
  Can be NULL.

PurchasedAfter

Optional (string)

 

YYYY-MM-DD. Subscription search interval start. You can search for subscriptions purchased between the dates you set using PurchasedAfter and PurchasedBefore. Note: The default 2Checkout API time zone is GMT+02:00. Can be NULL.

PurchasedBefore

Optional (string)

 

YYYY-MM-DD. Subscription search interval end. You can search for subscriptions purchased between the dates you set using PurchasedAfter and PurchasedBefore. Note: The default 2Checkout API time zone is GMT+02:00. Can be NULL.

ExpireAfter

Optional (string)

 

YYYY-MM-DD. Search subscriptions set to expire after a specific date. Note: The default 2Checkout API time zone is GMT+02:00. Can be NULL.

ExpireBefore

Optional (string)

 

YYYY-MM-DD. Search subscriptions set to expire before a specific date. Note: The default 2Checkout API time zone is GMT+02:00. Can be NULL.
ModifiedAfter Optional (string)
  YYYY-MM-DD. Search subscriptions modified after a specific date.
ModifiedBefore Optional (string)
  YYYY-MM-DD. Search subscriptions modified before a specific date.

RenewedAfter

Optional (string)

 

YYYY-MM-DD. Search subscriptions renewed after a specific date. Note: The default 2Checkout API time zone is GMT+02:00. Can be NULL.

RenewedBefore

Optional (string)

 

YYYY-MM-DD. Search subscriptions renewed before a specific date. Note: The default 2Checkout API time zone is GMT+02:00. Can be NULL.

NotificationAfter

Optional (string)

 

YYYY-MM-DD. Search subscriptions for which the 2Checkout system sent out notifications after a specific date. Note: The default 2Checkout API time zone is GMT+02:00. Can be NULL.

NotificationBefore

Optional (string)

 

YYYY-MM-DD. Search subscriptions for which the 2Checkout system sent out notifications before a specific date Note: The default 2Checkout API time zone is GMT+02:00. Can be NULL.
NextBillingDateAfter Optional (string)
  YYYY-MM-DD. Search subscriptions with the next billing date after the specified date
NextBillingDateBefore Optional (string)
  YYYY-MM-DD. Search subscriptions with the next billing date before the specified date

Type

Optional (string)

 

trial - trial subscriptions.

regular - all generated subscriptions that are not trials.

regularfromtrial - subscriptions generated from a trial conversion.

Can be NULL.

TestSubscription

Optional (boolean)

 

true

false, depending on whether you want to include test subscriptions in the search or not. Can be NULL.

LifetimeSubscription

Optional (boolean)

 

true – evergreen subscriptions.

false - subscriptions with a limited recurring billing cycle, typically no larger than 36 months.

Can be NULL.

Page

Optional (int)

 

A specific page of search results. Default value is 1.

Can be NULL.

Limit

Optional (int)

 

Number of results (subscriptions) displayed per page. Default value is 10.

Can be NULL.

Response

Parameters Type/Description

Subscription

Array of objects

Request

<?php

require ('PATH_TO_AUTH');

$SubscriptionSearch = new stdClass();
$SubscriptionSearch->CustomerEmail  = 'example@email.com';
$SubscriptionSearch->DeliveredCode = null;
$SubscriptionSearch->AvangateCustomerReference = null;
$SubscriptionSearch->ExternalCustomerReference = null;
$SubscriptionSearch->Aggregate = false;
$SubscriptionSearch->SubscriptionEnabled = null; //true false null
$SubscriptionSearch->RecurringEnabled = null; // true - autorenewal, false - manual renewal, null = both(default)
$SubscriptionSearch->ProductCodes = null; //array('Product_Code1', 'Product_Code2');
$SubscriptionSearch->CountryCodes = null;//array ('au')
$SubscriptionSearch->PurchasedAfter = null;
$SubscriptionSearch->PurchasedBefore = null;
$SubscriptionSearch->ExpireAfter = null;
$SubscriptionSearch->ExpireBefore = null;
$SubscriptionSearch->LifetimeSubscription = null;
$SubscriptionSearch->Type = 'regular'; //'trial', 'regular', 'regularfromtrial'
$SubscriptionSearch->TestSubscription = null; 
$SubscriptionSearch->Pagination = new stdClass();
$SubscriptionSearch->Pagination->Page = 1;
$SubscriptionSearch->Pagination->Limit = 10;  //maximum value is 200;


try {
    $accountSubscriptions = $client->searchSubscriptions($sessionID, $SubscriptionSearch);
}
catch (SoapFault $e) {
    echo "accountSubscriptions: " . $e->getMessage();
    exit;
}
var_dump("accountSubscriptions", $accountSubscriptions);;

?>

Perform action

Overview

Use the performAction method via SOAP APIv6 to execute an action on the proposal.

Request parameters

Request parameters for the performAction method via SOAP APIv6

Action Parameters Type Required/Optional Description
  sessionId String Required Unique 2Checkout session ID code.

 

 

 

 

 

 

 

 

SEND

 proposalId String Required The unique merchant proposal ID generated by the 2Checkout system.
exirationDate Date Required The date at which the proposal expires; date-time ISO 8601 format
userId String Optional The unique user ID generated by the 2Checkout system.
action String Required The action to be executed on the proposal.
statusComment String Optional Free text comments that can accompany a status.
sentBy String Required Represents the account manager of the merchant.

FirstName

 String Required The first name of the email sender.

LastName

 String Required The last name of the email sender.

Email

 String Required The email address of the email sender.

 

ACCEPT

 action String Required The action to be executed on the proposal.
statusComment String Optional Free text comments that can accompany a status.

 

 

CLOSE

 action String Required The action to be executed on the proposal.
statusComment String Optional Free text comments that can accompany a status.
userId String Optional The unique user ID generated by the 2Checkout system.

 

 

DISCARD

 action String Required The action to be executed on the proposal.
statusComment String Optional Free text comments that can accompany a status.
userId String Optional The unique user ID generated by the 2Checkout system.

 

 

REOPEN

 action String Required The action to be executed on the proposal.
statusComment String Optional Free text comments that can accompany a status.
userId String Optional The unique user ID generated by the 2Checkout system.

 

DECLINE

 action String Required The action to be executed on the proposal.
statusComment String Optional Free text comments that can accompany a status.

Request sample

<?php

require ('PATH_TO_AUTH');

$proposalId = "0573e71d-38bb-4d61-88ca-b3c557517c68";

$actionPayload = new stdClass();
$actionPayload->ExpirationDate = "2021-01-05T17:21:42+00:00";
$actionPayload->UserId = "john.doe@email.com";
$actionPayload->action = "decline";
$actionPayload->StatusComment = "The price is too high for the first product";
$actionPayload->SentBy = new stdClass();
$actionPayload->SentBy->FirstName = "John";
$actionPayload->SentBy->LastName = "Doe";
$actionPayload->SentBy->Email = "john.doe@email.com";

try {
    $results = $soapClient->performAction($sessionID, $proposalId , $actionPayload);
    echo "Performing action: </br>", 
    var_dump($results);
}
catch (SoapFault $e) {
    echo "Could not perform action: " . $e->getMessage();
    exit;
}

Response

The performAction call via SOAP APIv6 returns the Proposal object.

Retrieve all campaigns

Overview

Use the searchCrossSellCampaigns method to extract information about the cross-sell campaigns you configured.

Parameters

Parameters 

Type 

Required

Description 

CampaignName 

String 

Optional 

The name of the campaign.

Status 

String 

Optional 

The status of the campaign; can be ACTIVE/INACTIVE.

Products 

Array of strings 

Optional 

Array of product codes to apply to this campaign. 

RecommendedProducts 

Array of strings 

Optional 

Array of product codes recommended to the shopper.

StartDate 

String 

Optional 

The date when the cross-sell campaign starts, formatted as YYYY-MM-DD 

EndDate 

String 

Optional 

The date when the cross-sell campaign ends, formatted as YYYY-MM-DD 
Type String Optional Can be MERCH/AFF.

Pagination 

Object 

Optional 

  

Page 

Int 

Optional 

The page number of the results.

Limit 

Int 

Optional 

The number of results per page.

Response

Parameters Type/Description
Items An array of CrossSellCampaign Objects
Pagination Pagination Object with the following parameters: Page, Limit, Count

Request

<?php

require ('PATH_TO_AUTH');

try {
    $AllCrossSellCampaigns = $client->searchCrossSellCampaigns($sessionID);
}

catch (SoapFault $e) {
    echo "AllCrossSellCampaigns: " . $e->getMessage();
    exit;
}

var_dump("AllCrossSellCampaigns", $AllCrossSellCampaigns);

Retrieve a customer

Overview

Use the getCustomerInformation method to retrieve the details of a customer entity from the 2Checkout system.

Parameters

Parameters

Type/Description

sessionID

Required (string)

 

Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect.  The sessionID expires in 10 minutes.

AvangateCustomerReference

Required (int)
 

System-generated customer reference. Required unless you prefer to use ExternalCustomerReference.

ExternalCustomerReference

Optional (string)

 

External customer reference that you control. Optional when you use AvangateCustomerReference. If you include it, it needs to belong to the same customer as the AvangateCustomerReference.

Response

Customer

Object

Request


<?php
$host   = "https://api.2checkout.com";
$client = new SoapClient($host . "/soap/6.0/?wsdl", array(
    'location' => $host . "/soap/6.0/",
    "stream_context" => stream_context_create(array(
        'ssl' => array(
            'verify_peer' => false,
            'verify_peer_name' => false
        )
    ))
));

function hmac($key, $data)
{
    $b = 64; // byte length for md5
    if (strlen($key) > $b) {
        $key = pack("H*", md5($key));
    }
    
    $key    = str_pad($key, $b, chr(0x00));
    $ipad   = str_pad('', $b, chr(0x36));
    $opad   = str_pad('', $b, chr(0x5c));
    $k_ipad = $key ^ $ipad;
    $k_opad = $key ^ $opad;
    return md5($k_opad . pack("H*", md5($k_ipad . $data)));
}
$merchantCode = "YOUR_MERCHANT_CODE";// your account's merchant code available in the 'System settings' area of the cPanel: https://secure.2checkout.com/cpanel/account_settings.php
$key = "YOUR_SECRET_KEY";// your account's secret key available in the 'System settings' area of the cPanel: https://secure.2checkout.com/cpanel/account_settings.php
$now          = gmdate('Y-m-d H:i:s'); //date_default_timezone_set('UTC')
$string = strlen($merchantCode) . $merchantCode . strlen($now) . $now;
$hash   = hmac($key, $string);
try {
    $sessionID = $client->login($merchantCode, $now, $hash);
}
catch (SoapFault $e) {
    echo "Authentication: " . $e->getMessage();
    exit;
}
$customerReference = 298084139;
$externalCustomerReference = 'Apitest123456'; //Optional, but if you include it it needs to belong to the same customer as the internal 2Checkout customer reference
try {
    $customerInfo = $client->getCustomerInformation($sessionID, $customerReference, $externalCustomerReference);
}
catch (SoapFault $e) {
    echo "customerInfo: " . $e->getMessage();
    exit;
}
var_dump("customerInfo", $customerInfo);

INS parameters

Overview

Depending on your INS settings, notifications contain all or a subset of the available parameters. 2Checkout sends INS parameters in the exact order listed in this article.

For each trigger enabled, you are able to select which URL endpoint receives the notification, as well as customize the list of parameters included in the notification. Read more about INS parameters here.

Note: 2Checkout continues to add new INS parameters on an ongoing basis. To include additional information in the notifications, enable new parameters in the INS settings page.

Parameter Description Type
message_type Indicates the type of message String
message_description The description of message_type String
timestamp Timestamp of event; format YYYY-MM-DD HH:MM:SS ZZZ Timestamp
md5_hash

Hash calculated for the notification.

Important: We recommend against using this, as we are in the process of decommissioning MD5.

 String
hash SHA2/SHA3 hash calculated for the notification. String
message_id This number is incremented for each message sent to a given seller Integer
key_count Indicates the number of parameters sent in a message Integer
vendor_id Merchant account number Integer
sale_id 2Checkout sale number Integer
sale_date_placed Date of sale; format YYYY-MM-DD Date
vendor_order_id Custom order id provided by seller, if available. (“merchant_order_id” can be passed into the checkout with the sale parameters) String
invoice_id 2Checkout invoice number; Each sale can have several invoices, most commonly one per installment billed on a recurring order. Integer
recurring recurring=1 if any item on the invoice is a recurring item, 0 otherwise Integer
payment_type Customer’s payment method. String
list_currency 3-Letter ISO code for seller currency String
cust_currency 3-Letter ISO code for customer currency String
auth_exp The date credit authorization will expire; format YYYY-MM-DD Date
invoice_status Status of a transaction (approved, pending, deposited, or declined) String
fraud_status Status of 2Checkout fraud review (pass, fail, or wait); Can be NULL. String
invoice_list_amount Total in seller pricing currency; format as appropriate to currency (2 decimal places for most, integer for JPY) Integer
invoice_usd_amount Total in US Dollars; format with 2 decimal places Integer
invoice_cust_amount Total in customer currency; format as appropriate to currency (2 decimal places for most, integer for JPY) Integer
customer_first_name Customer’s first name (may not be available on older sales) String
customer_last_name Customer’s last name (may not be available on older sales) String
customer_name Customer’s full name (name as it appears on credit card) String
customer_email Customer’s email address String
customer_phone Customer’s phone number; all but digits stripped out Integer
customer_ip Customer’s IP address at time of sale String
customer_ip_country Country of record for customer’s IP address at time of sale; Please note in some cases what is returned is not a country, Ex. Satellite Provider String
bill_street_address Billing street address String
bill_street_address2 Billing street address line 2 String
bill_city Billing address city String
bill_state Billing address state or province String
bill_postal_code Billing address postal code String
bill_country 3-Letter ISO country code of billing address String
ship_status Value will be not_shipped, shipped, or empty (if intangible / does not need shipped) String
ship_tracking_number Tracking Number as entered in Seller Admin String
ship_name Shipping Recipient’s name (as it should appears on shipping label) String
ship_street_address Shipping street address String
ship_street_address2 Shipping street address line 2 String
ship_city Shipping address city String
ship_state Shipping address state or province String
ship_postal_code Shipping address postal code String
ship_country 3-Letter ISO country code of shipping address String
item_count Indicates how many numbered sets of item parameters to expect Integer
item_name_# Product name String
item_id_# Seller product id String
item_list_amount_# Total in seller pricing currency; format as appropriate to currency (2 decimal places for most, integer for JPY) Integer
item_usd_amount_# Total in US Dollars; format with 2 decimal places Integer
item_cust_amount_# Total in customer currency; format as appropriate to currency (2 decimal places for most, integer for JPY) Integer
item_type_# Indicates if item is a bill or refund; Value will be bill or refund String
item_duration_# Product duration, how long it re-bills for Ex. 1 Year String
item_recurrence_# Product recurrence, how often it re-bills Ex. 1 Month String
item_rec_list_amount_# Product price; format as appropriate to currency (2 decimal places for most, integer for JPY) Integer
item_rec_status_# Indicates status of recurring subscription. Ex: canceled, completed String
item_rec_date_next_# Date of next recurring installment; Date
item_rec_install_billed_# The number of successful recurring installments successfully billed Integer
order_ref The reference number of the 2Checkout order. String
order_no The number of the 2Checkout order. Available only after the sale is risk approved. String

 Proposal Updated Parameters

Parameter Description Type
message_id The unique identifier of the proposal message. String
updated_date The date and time when then the proposal was last time updated; format YYYY-MM-DD HH:MM:SS ZZZ. Datetime
source The platform where the proposal was created. String
tac The Terms and Conditions content. String
accepted_date The date and time when then the proposal was accepted; format YYYY-MM-DD HH:MM:SS ZZZ. Datetime
status

The proposal status. Possible values:

  • opened
  • sent
  • closed_won
  • closed_lost
  • declined
  • expired
  • accepted
 String
message_type The type of message sent with the proposal. String
key_count Indicates the number of parameters sent in a message. Number
proposal_id Unique identifier of the proposal generating the offer. Can be found in Order additional information as text. String
created_by The unique external system user identifier that created the proposal. String
content The proposal content. String
type The type of proposal (new acquisition, renewal, upgrade). String
expiration_date The UTC expiration date for the proposal, set only when the status is changed to "sent". Datetime
message_description The description of message_type. String
version The proposal version. Integer
updated_by The external system user ID that performed the last update on the proposal. String
bill_to Billing details. String
sent_by The account manager who sent out the proposal. String
status_comment The associated comment on the status of the proposal. String
timestamp Timestamp of event; format YYYY-MM-DD HH:MM:SS ZZZ. Datetime
created_date The date and time when then the proposal was created; format YYYY-MM-DD HH:MM:SS ZZZ. Datetime
locked The proposal is locked to buy modifications. String
name The name of the proposal. String
links

The proposal links details. Can be:

  • Proposal User Interface Access URL
  • Download PDF URL
 String
sell_to The entity using the proposal service. String
md5_hash

Hash calculated for the notification.

Important: We recommend against using this, as we are in the process of decommissioning MD5.

 String
hash SHA2/SHA3 hash calculated for the notification. String

 

Order session content object

Overview

Use this object to retrieve session content and to guide shoppers through advanced payment flows, such as those of PayPal, PayPal Express, Wire, Check, etc. 

Attributes

Order session  contents

Type/Description

Errors

Optional (StringArray)

 

Payment gateway processing errors.

Items

Array of objects
    Details below. 

 

ProductDetails

Object
      Details below. 

 

 

Name

Optional (string)

 

 

 

Product name.

 

 

ExtraInfo

Optional (string)

 

 

 

The text entered in the Additional information field when generating Buy links, or via the INFO[PRODUCT_ID] parameter used in Buy links.

 

 

RenewalStatus

Optional (boolean)

 

 

 
  • true for orders renewing subscriptions.
  • false for all other orders: new purchases, upgrades.

 

 

Subscriptions

Object
        Details below. 

 

 

 

SubscriptionReference

Optional (string)

 

 

 

 

Unique, system-generated subscription identifier.

 

 

 

PurchaseDate

Optional (string)

 

 

 

 

The date time stamp when shoppers acquired their subscriptions corresponding to the moment when the Avangate system marks the purchase as finished. Format (YYYY-MM-DD HH:mm:ss). Default GMT+02:00.

 

e.g. 2015-08-11 15:18:52

 

 

 

SubscriptionStartDate

Optional (string)

 

 

 

 

 

Example: 2015-09-29 17:57:59

 

 

 

ExpirationDate

Optional (string)

 

 

 

 

The date time stamp of upcoming renewal/expiration for subscriptions not taking into account grace period settings.

 

Format (YYYY-MM-DD HH:mm:ss). Default GMT+02:00.

 

e.g. 2015-09-11 15:18:52

 

 

 

Lifetime

Optional (boolean)

 

 

 

 
  • true – For non-recurring, evergreen subscriptions.
  • false – For recurring subscriptions with a specific billing cycle from 7 days to 36 months.

 

 

 

Trial

Optional (boolean)

 

 

 

 
  • true – For trial subscriptions.
  • false – For non-trial, recurring subscriptions with a specific billing cycle from 7 days to 36 months.

 

 

 

Enabled

Optional (boolean)

 

 

 

 
  • true – For active and past due subscriptions.
  • false – For expired and cancelled subscriptions.

 

 

 

RecurringEnabled

Optional (boolean)

 

 

 

 

 

                    

PriceOptions

Optional (Array of strings)

 

 

Product price options.

 

Price

Object

 

 

This object returns the price per unit at order line level.

 

In the case of trials, the object returns the costs for the trial to full subscription conversion.

 

 

UnitNetPrice

Optional (double)

 

 

 

The value per product unit, excluding sales tax/VAT expressed in the payment currency.

 

 

UnitGrossPrice

Optional (double)

 

 

 

Total value per product unit, including sales tax/VAT expressed in the payment currency. UnitGrossPrice does not reflect any discounts.

 

 

UnitVAT

Optional (double)

 

 

 

Sales tax/VAT per product unit expressed in the payment currency.

 

 

UnitDiscount

Optional (double)

 

 

 

Value of the discount per product unit expressed in the payment currency.

 

 

UnitNetDiscountedPrice

Optional (double)

 

 

 

The value per product unit, expressed in the payment currency, excluding sales tax/VAT, from which Avangate deducts the unit discount.

 

 

UnitGrossDiscountedPrice

Optional (double)

 

 

 

Total costs shoppers incur per product unit, expressed in the payment currency. This value includes sales tax/VAT, Avangate and affiliate commissions, but Avangate deducts the value of any discounts.

 

 

UnitAffiliateCommission

Optional (double)

 

 

 

Value of the affiliate commission per product unit calculated expressed in the payment currency.

 

Avangate deducts discounts from the costs incurred by shoppers before calculating affiliate commissions.

 

Avangate does not take into account shipping costs when calculating affiliate commissions.

 

NULL when Avangate does not apply an affiliate commission.

 

 

Currency

Optional (string)

 

 

 

The currency ISO code for the payment - ISO 4217. Example: usd.

 

 

NetPrice

Optional (double)

 

 

 

The value per order line, excluding sales tax/VAT expressed in the payment currency.

 

 

GrossPrice

Optional (double)

 

 

 

Total value per order line, including sales tax/VAT expressed in the payment currency. UnitGrossPrice does not reflect any discounts.

 

 

NetDiscountedPrice

Optional (double)

 

 

 

The NetPrice value per order line, excluding sales tax/VAT, from which Avangate deducts discounts. NetDiscountedPrice is expressed in the payment currency.

 

 

GrossDiscountedPrice

Optional (double)

 

 

 

Total costs shoppers incur per order line, expressed in the payment currency. This value includes sales tax/VAT, Avangate and affiliate commissions, but Avangate deducts the value of any discounts.

 

Example:

  • UnitNetPrice: 99
  • UnitGrossPrice: 120.39
  • UnitVAT: 21.39
  • UnitDiscount: 9.9
  • UnitNetDiscountedPrice: 89.1
  • UnitGrossDiscountedPrice: 110.49
  • UnitAffiliateCommission: 22.28
  • Currency: "usd"
  • NetPrice: 198
  • GrossPrice: 240.77
  • NetDiscountedPrice: 178.2
  • GrossDiscountedPrice: 220.97
  • Discount: 19.8
  • VAT: 42.77
  • AffiliateCommission: 44.56

 

 

Discount

Optional (double)

 

 

 

Value of the discounts per order line expressed in the payment currency.

 

 

VAT

Optional (double)

 

 

 

Value of sales tax/VAT per order line expressed in the payment currency.

 

 

AffiliateCommission

Optional (double)

 

 

 

Value of the affiliate commission per order line, calculated from the NetDiscountedPrice expressed in the payment currency. Or NULL. Avangate does not take into account shipping costs when calculating affiliate commissions.

 

Code

Optional (string)

 

 

Unique product identifier your control. Max length 256 characters.

 

Quantity

Optional (integer)

 

 

Number of units

 

SKU

Optional (string)

 

 

SKU identifier.

 

CrossSell

Optional (Object)
      Details below. 

 

 

ParentCode

Optional (string)

 

 

 

The product code of the master product you set to trigger the campaign.

 

 

CampaignCode

Optional (string)

 

 

 

Unique, system-generated identifier for cross-sell campaigns.

 

Trial

Optional (Object)
      Details below. 

 

 

Period

Optional (integer)

 

 

 

The length of the trial subscription lifetime in days.

 

 

GrossPrice

Optional (double)

 

 

 

Total trial price in the payment currency before Avangate deducts any taxes, discounts, etc.

 

 

VAT

Optional (double)

 

 

 

The total value of taxes for the trial in the payment currency, before Avangate deducts any discounts.

 

 

NetPrice

Optional (double)

 

 

 

Total trial price in the payment currency, not including taxes, before Avangate deducts any discounts.

 

AdditionalFields

Optional (array of objects)
      Details below. 

 

 

Code

Optional (string)

 

 

 

The alpha-numeric characters, underscores and dashes that are set as the field identifier.

 

 

Text

Optional (string)

 

 

 

Field text visible to shoppers in the cart.

 

 

Value

Optional (string)

 

 

 

Selected field value.

 

Promotion

Optional (object)
      Details below. 

 

 

Name

Optional (string)

 

 

 

Promotion name.

 

 

Description

Optional (string)

 

 

 

Promotion description.

 

 

StartDate

Optional (string)

 

 

 

The date when you set the promotion to start. NULL for promotions that start immediately after you create them.

 

 

EndDate

Optional (string)

 

 

 

The date when you set the promotion to end. NULL for promotions you want active indefinitely.

 

 

MaximumOrdersNumber

Optional (integer)

 

 

 

Avangate only applies the promotion to a maximum number of orders you define.

 

Can be NULL if you want the promotion to apply to an unlimited number of orders.

 

 

MaximumQuantity

Optional (integer)

 

 

 

Discount only applies to a maximum number of units purchased through a single order, smaller than the quantity you defined. Shoppers purchase any extra units at full price. Can be NULL if you want the promotion to apply to an unlimited number units.

 

 

InstantDiscount

Optional (boolean)

 

 

 

The instant discount option auto-applies the discount for ALL selected products, without the need for shoppers to enter a discount coupon.

 

 

Coupon

Optional (string)

 

 

 

Promotion coupon/voucher.

 

 

DiscountLabel

Optional (string)

 

 

 

Discounts can be set as a percentage from the product price or as a fixed amount in the chosen currency.

 

 

Enabled

Optional (string)

 

 

 

true or false, depending on whether a promotion is active or disabled. 

 

 

Type

Optional (string)

 

 

 
  • REGULAR – product/cart line level discounts.
  • ORDER – quantity discounts.
  • GLOBAL – order-level discounts.

Promotions

Optional (Array of objects)
    Details below. 

 

Name

Optional (string)

 

 

Promotion name.

 

Description

Optional (string)

 

 

Promotion description.

 

StartDate

Optional (string)

 

 

The date when you set the promotion to start. NULL for promotions that start immediately after you create them.

 

EndDate

Optional (string)

 

 

The date when you set the promotion to end. NULL for promotions you want active indefinitely.

 

MaximumOrdersNumber

Optional (integer)

 

 

Avangate only applies the promotion to a maximum number of orders you define.

 

Can be NULL if you want the promotion to apply to an unlimited number of orders.

 

MaximumQuantity

Optional (integer)

 

 

Discount only applies to a specific number of units purchased at once, smaller than the maximum quantity you defined. Shoppers purchase any extra units at full price. Can be NULL if you want the promotion to apply to an unlimited number units.

 

InstantDiscount

Optional (boolean)

 

 

The instant discount option auto-applies the discount for ALL selected products, without the need for shoppers to enter a discount coupon.

 

Coupon

Optional (string)

 

 

Promotion coupon/voucher.

 

DiscountLabel

Optional (string)

 

 

Discounts can be set as a percentage from the product price or as a fixed amount in the payment currency.

 

Enabled

Optional (string)

 

 

true or false, depending on whether a promotion is active or disabled. 

 

Type

Optional (string)

 

 
  • REGULAR – product/cart line level discounts.
  • ORDER – quantity discounts.
  • GLOBAL – order-level discounts.

AdditionalFields

Optional (array of objects)
    Details below. 

 

Code

Optional (string)

 

 

The alpha-numeric characters, underscores and dashes that are set as the field identifier.

 

Text

Optional (string)

 

 

Field text visible to shoppers in the cart.

 

Value

Optional (string)

 

 

Selected field value.

Currency

Optional (string)

 

The currency ISO code for the payment - ISO 4217. Example: usd.

NetPrice

Optional (double)

 

Order value excluding sales tax/VAT expressed in the payment currency.

GrossPrice

Optional (double)

 

Total order value, including sales tax/VAT expressed in the payment currency. GrossPrice does not reflect any discounts.

NetDiscountedPrice

Optional (double)

 

The NetPrice order value excluding sales tax/VAT, from which Avangate deducts discounts. NetDiscountedPrice is expressed in the payment currency.

GrossDiscountedPrice

Optional (double)

 

Total costs shoppers incur, expressed in the payment currency. This value includes sales tax/VAT, Avangate and affiliate commissions, but Avangate deducts the value of any discounts.

 

For example:

  • Currency: "usd"
  • NetPrice: 396
  • GrossPrice: 486.29
  • NetDiscountedPrice: 376.2
  • GrossDiscountedPrice: 466.49
  • Discount: 19.8
  • VAT: 90.29
  • AffiliateCommission: 94.05

Discount

Optional (double)

 

Value of the discounts for an order expressed in the payment currency.

VAT

Optional (double)

 

Value of sales tax/VAT expressed in the payment currency.

AffiliateCommission

Optional (double)

 

Value of the affiliate commission for the order calculated from the NetDiscountedPrice expressed in the payment currency. Or NULL. Avangate does not take into account shipping costs when calculating affiliate commissions.

 

IPN triggers

Set IPN triggers and contents 

In your Control Panel account, navigate to Dashboard → Integrations → Webhooks and API and click on the IPN Settings tab. In the General IPN Settings section, under Triggers, select the events for which 2Checkout sends notifications.

Instant Payment Notification (IPN) provides automatic notifications for orders from the 2Checkout system, based on the following list of triggers you control:

IPN triggers

General

Trigger ORDERSTATUS Description
Pending orders PENDING Shopper places the order. 2Checkout is waiting for bank authorization.
  PURCHASE_PENDING

Shopper places the order using a Purchase Order (PO). 2Checkout approves the PO document and you also approve the PO document. Shopper has yet to finalize the payment.

 

Alternatively, you use the AutoApprove API flow and do not require a PO document but the shopper has yet to finalize the payment.
Orders waiting to be processed by 2Checkout system / Orders under 2Checkout review PENDING_APPROVAL Order is waiting for the 2Checkout system to process it or for anti-fraud review.
Authorized and approved orders (sent before electronic delivery) PAYMENT_AUTHORIZED The bank authorized the payment.
  PAYMENT_RECEIVED 2Checkout sends a notification when it receives payments for offline orders (e.g. Bank/Wire transfer) but only before fulfillment/delivery.
  PENDING_ORDER_APPROVAL 2Checkout sends this status for products/subscriptions configured with the “Requires delivery confirmation” setting.
Authorized and approved orders (sent after electronic delivery) PAYMENT_AUTHORIZED The bank authorized the payment.
  COMPLETE 2Checkout marks the order as finished and fulfilled.
Order approved for delivery PAYMENT_AUTHORIZED You approved an order for fulfillment/delivery.
Completed orders / Invoice generated COMPLETE

2Checkout marks the order as finished and fulfilled.

 

2Checkout can resend this notification when it generates invoices.
Order shipped (only for tangible products) PAYMENT_AUTHORIZED

You marked the order as shipped, and the delivery process has started.

2Checkout sends a notification to customers once orders are marked as shipped.

Refunds and chargebacks

Trigger ORDERSTATUS Description
Invalid orders INVALID Shopper provides invalid billing and/or delivery information. (Not available by default, contact 2Checkout directly to enable it)
Suspect orders SUSPECT The 2Checkout Risk department is reviewing the order for possible fraud. (Not available by default, contact 2Checkout directly to enable it)
Canceled orders CANCELED

The 2Checkout system can send out notifications for:

  • eStore orders canceled by 2Checkout representatives (only for orders that are not authorized/paid, otherwise a reverse or refund action is required).
  • Partner (Channel Manager) orders canceled by you.
  • Purchase Orders not approved/submitted in due time

 
Chargeback open COMPLETE ORDERSTATUS is COMPLETE for chargebacks. 2Checkout details information about disputes in the CHARGEBACK_RESOLUTION and CHARGEBACK_REASON_CODE fields.
Chargeback closed / Invoice generated COMPLETE

ORDERSTATUS is COMPLETE for chargebacks. 2Checkout details information about disputes in the CHARGEBACK_RESOLUTION and CHARGEBACK_REASON_CODE fields.

 

2Checkout can resend this notification when it generates chargeback invoices.
Reversed and refund orders REVERSED 2Checkout reverses transactions and releases funds back to shoppers for Authorized payments that never reach the Complete status.
  REFUND

2Checkout repays funds back to shoppers for Complete orders.

 

2Checkout can resend this notification when it generates refund invoices.

Purchase orders

Trigger ORDERSTATUS Description
Approved PURCHASE_PENDING You approve the PO document.
Rejected CANCELED You reject the PO document.
Completed COMPLETE Customer pays the PO.
Expired, not paid CANCELED You don’t approve nor reject the PO within time interval.
Canceled CANCELED You cancel the PO or 2Checkout cancels the order.

Channel manager

 

Trigger ORDERSTATUS Description
Pending approval orders from partners PENDING Resellers place order that await your approval.
Approved orders from partners PENDING You approve partner orders.
Delivered orders from partners PENDING 2Checkout fulfills partner orders.

Need help?

Do you have a question? If you didn’t find the answer you are looking for in our documentation, you can contact our Support teams for more information. If you have a technical issue or question, please contact us. We are happy to help.

Get in touch

Not yet a Verifone customer?

We’ll help you choose the right payment solution for your business, wherever you want to sell, in-person or online. Our team of experts will happily discuss your needs.

Contact sales Get Started
Verifone logo