updates RSS feed

Copy payment info

Overview

Copy card-on-file data available in the 2Checkout system from a source subscription to an imported target subscription. 2Checkout uses the existing payment information to charge customers as a part of the recurring billing (renewal) process.

Use the copyPaymentInfo method.

Requirements

The imported target subscription and the source subscription must belong to the same customer. The 2Checkout system checks to make sure that the 2Checkout Customer Reference (internal identifier) coincides for the customer accounts associated to the target and source subscriptions.

Availability

Please contact 2Checkout directly if you wish to take advantage of this feature.

How does this method work?

  1. Customer A purchases Subscription A using a VISA credit card and you import Subscription B for the same customer with no data or with an AMEX card.
  2. When 2Checkout renews Subscription A, it charges Customer A using the VISA, while using the AMEX (if the data was provided) for Subscription B charges.
  3. When you copy the payment data from Subscription A to Subscription B, the 2Checkout system uses the VISA credit card to renew both subscriptions according with their respective recurring billing cycles. 2Checkout charges customers during the recurring billing process for the imported target subscription using the payment method they used to purchase the source subscription.

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.

TargetSubscriptionReference

Required (string)
 

The 2Checkout Subscription Reference of the imported target subscription, to which 2Checkout copies the payment on file data associated with the source subscription.

SubscriptionReference

Required (string)

 

The 2Checkout Subscription Reference of the source subscription whose attached payment on file data 2Checkout copies to the target subscription.

Response

Parameter Type/Description

Boolean

true or false depending on whether or not the operation succeeded.

Request

<?php

require ('PATH_TO_AUTH');

$TargetSubscription = 'FFAE3C9429';
$SourceSubscription = '9F4154733C';

try {
    $payInfo = $client->copyPaymentInfo($sessionID, $TargetSubscription, $SourceSubscription);
}
catch (SoapFault $e) {
    echo "payInfo: " . $e->getMessage();
    exit;
}
var_dump("payInfo", $payInfo);

 

Order search options

Overview

Use the orderSearchOptions object to configure your search order options via SOAP API 6.0.

Object parameters

Parameter name Type Required/Optional Description

ApproveStatus

String

Optional

The desired approved status. Available values: WAITING, OK, FRAUD, INVALIDDATA.

Newer

String

Optional

Needed timestamp. If not provided, will return by default the data for the last 7 days.

Status

String

Optional

Order status. Some of the available options are COMPLETE, PENDING, CANCELED, REFUND.

StartDate

String

Optional

Start date in format Y-m-d. Will overwrite Newer if provided.

EndDate

String

Optional

End date in format Y-m-d.

PartnerOrders

Boolean

Optional

Decide if it will also include partner orders.

ExternalRefNo

String

Optional

The external reference number of the order.
IncludeTestOrders String Optional

Should test orders be included in the result:

Values:

  • YES -  test orders are included
  • NO - test orders are not included
  • ONLY - only the test orders are included
Pagination

Object

Optional

Existing shipping class object with the structure detailed below.

Limit

 Int Optional The number of results to be returned.

Page

 Int Optional The page number.

 

 

Order object

Overview

Use this object to create new orders and collect payments from shoppers. 

Supported payment methods

  1. Credit/Debit cards: Visa, Visa Electron, MasterCard, Maestro, Amex, Discover, Dankort, Carte Bancaire, JCB. 2Checkout supports local Brazilian cards.
  2. PayPal and PayPal Express
  3. Purchase Order
  4. Wire
  5. Check
  6. WeChat Pay
  7. iDEAL
  8. Previous order references - In addition to the payment methods enumerated above, 2Checkout also supports 1-click purchase flows in which you use valid previous order references belonging to returning customers to pay for new orders with their previously used cards and PayPal accounts. 

Object parameters

 

Parameters   Type/Description
RefNo   Optional (string)
   

Unique, system-generated, order reference number.

 

Do not include it when placing new orders or send it as NULL.
Currency   Optional (string)
    The currency ISO code for the payment - ISO 4217. Example: “usd.”
Country   Optional (string)
    Shopper country. ISO 3166 two-letter code. Example: “us.”
Language   Optional (string)
    ISO 639-1 two-letter code. Language used for the purchase process. Example: “en.”
ExternalReference   Optional (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.
Source   Optional (string)
   

The link source for the sales. 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.
Affiliate   Object/Optional
  AffiliateCode String/Required
    The affiliate unique code (as returned by the affiliates API methods).
  AffiliateSource String/Optional
    The affiliate source.
CustomerReference   Optional (Int)
    System-generated 2Checkout customer reference. Aggregate subscriptions under the same Customer account 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.
MachineId   Optional (string)
    Unique, system generated code for each unique customer, identifying returning customers.
Items   Required (array of objects)
    Details below. 
  OrderItem   Object
        Details below. 
    Code   Required (string)
        Unique product identifier your control. Max length 256 characters.
    Quantity   Required (integer)
        Number of units
    PriceOptions   Optional (array of strings)
        Array of price option codes.
    SKU   Optional (string)
        SKU identifier.
    Price   Object - Can be NULL
        OrderPrice Object - Can be NULL
        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. GrossPricedoes not reflect any discounts.
        NetDiscountedPrice Optional (double)
              The NetPrice order value excluding sales tax/VAT, from which 2Checkout 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, 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

 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 NetDiscountedPriceexpressed in the payment currency. Or NULL. 2Checkout does not take into account shipping costs when calculating affiliate commissions.
        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 2Checkout 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, 2Checkout and affiliate commissions, but 2Checkout deducts the value of any discounts.
        UnitAffiliateCommission Optional (double)
           

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.
    CrossSell   Object – Can be NULL
          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) – Can be NULL
          Details below. 
      Period   Optional (integer)
          The length of the trial subscription lifetime in days.
      Price   Optional (double)
          Total trial price in the payment currency before 2Checkout deducts any taxes, discounts, etc.
    AdditionalFields   Optional (array of objects) – Can be NULL
      AdditionalFieldSet   Optional (Object) – Can be NULL
        Code   Optional (string)
            The alpha-numeric characters, underscores and dashes that are set as the field identifier.
        Value   Optional (string)
            Selected field value.
    SubscriptionStartDate   Optional (string)
       

Specify the date time stamp when the subscription becomes active. Format 2016-07-02 22:22:22 (YYYY-MM-DD HH:mm:ss). Available for JSON-RPC and REST.

Send empty or NULL to activate subscriptions on the same date when customers purchase them.

You can exclude HH:mm:ss when sending the date and include only YYYY-MM-DD. In this case, 2Checkout uses 00:00:01. Default time zone GMT+02:00.
    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)
         

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   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.
BillingDetails   Required (Object)
      Details below. 
  Person   Object
      Details below. 
    FirstName Required (string)
      Shopper name.
    LastName Required (string)
      Shopper surname.
    CountryCode Optional (string)
      Shopper country. ISO 3166 two-letter code.
    State

Optional (string) – Required for US, Brazil, India and Romania

The state in the shopper's country. Mandatory when you set the Billing Country to US, Brazil, India and Romania. Use case insensitive utf8 strings for the full name, or just the two letter code.
     
    City Optional (string)
      Shopper city.
    Address1 Optional (string)
      Shopper address.
    Address2 Optional (string)
      Shopper address.
    Zip Optional (string)
      ZIP/ Postal code.
    Email Optional (string)
      Shopper email address.
    Phone Optional (string)
      Shopper phone number. Mandatory when you set Brazil as the Billing Country. Can be NULL.
    Company Optional (string)
      Company name. Can be null for end users. When present, you also need to provide the FiscalCode.
    TaxExemptionId  Optional (string)
      Tax Exempt Certification id used to deduct taxes for US orders
Example: 1b80eecc349v
  FiscalCode Optional (string) – Required for Brazil
   

• 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 you set Brazil as the Billing Country. For Brazilian customers it represents the Fiscal Code (CPF/CNPJ).

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

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

The payment method:

  • CC (credit/debit card - including local Brazilian cards).
  • ENCRYPTED_PAYMENT_DATA (client-side encryption)
  • 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.
  • WE_CHAT_PAY (for WeChat payments).
  • IDEAL (for iDEAL payments).
  • PURCHASEORDER - use for orders with POs.
  • FREE – for 0 value orders for which you’re not requiring customers to provide payment details.

 
  Currency   Optional (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)).

 

NULL for 0 value orders for which you’re not requiring customers to enter payment details.
                                                         RecurringEnabled   Optional (boolean)
     

true – shopper checks the auto-renewal checkbox and 2Checkout charges subscription renewals using a recurring billing process.

false – shopper doesn’t check the auto-renewal checkbox.
      CardPayment   Optional (object)
            Details below. 
        CardNumber   Optional (string)
            The credit/debit card number.
        CardType   Optional (string)
            visa, visaelectron, mastercard, maestro, amex, discover, dankort, cartebleue, jcb, hipercard, elo
        ExpirationYear   Optional (string)
            The year in which the card expires.
        ExpirationMonth   Optional (string)
            The month in which the card expires.
        HolderName   Optional (string)
            Card holder name.
        CCID   Optional (string)
            Credit Card Identification - an extra ID printed on the card, usually a 3-4 digit number, the CVC2/CVV2.
        HolderNameTime Optional (float)
           

The interval of time in seconds in which shoppers enter their name in the HolderName field. An abnormally short interval is usually a red flag for fraud attempts.

Can be NULL, but not a negative number.
        CardNumberTime Optional (float)
           

The interval of time in seconds in which shopper enter their card number in the CardNumber field. An abnormally short interval is usually a red flag for fraud attempts.

Can be NULL, but not a negative number.
        InstallmentsNumber  Optional (Int)
            Number of installments. Available only when customers un Brazil pay with Visa or MasterCard using Brazilian Real as the order currency. Use 1 or exclude the parameter for full payments. 
      PayPalExpress   Optional (object)
            Details below. 
        Email   Optional (string)
            Email address customers use for their PayPal account.
        ReturnURL   Optional (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   Optional (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.
      PreviousOrder   Optional (Object)
            Details below. 
        RefNo   Optional (string)
           

Order reference a previous purchase which reached the Approved/Complete status. You can use order for which customers paid with credit/debit cards or with PayPal. The status of order should be AUTHRECEIVED or COMPLETE.

 

Check the validity of references with the isValidOrderReference method.

 

The 2Checkout system blocks you from using references for fraudulent or potentially fraudulent orders.
      PurchaseOrderPaymentDetails   Optional (Object)
            Details below. 
        InternalPONumber Optional (string)
            Identifier that business customers use internally in their organization to track and manage Purchase Orders (PO). Can be NULL.
        AutoApprove   Optional (boolean)
           

TRUE - requires activation of the PO AutoApprove package (If the package is inactive 2Checkout returns an error). Please contact 2Checkout. When AutoApprove is TRUE, 2Checkout no longer requires that business customers upload a PO document. As such, PO orders are automatically approved for your account, without a PO doc. 2Checkout sets the PURCHASE_PENDING status for auto-approved PO orders.

FALSE - Default. Send this if the PO AUtoApprove package is not available for your account. 2Checkout uses the same flow as cart purchases with Purchase Orders for business customers placing orders with POs via API. This means that customers receive the same emails as if they made the purchase using the cart and need to update the PO document, which is reviewed by 2Checkout and that you need to approve. 2Checkout sets the AVAITING_UPLOAD status for POs andUnfinished for their orders.

 

Can be NULL.
      WE_CHAT_PAY   Optional (string)
          Details below
        ReturnURL   Optional (string)
            The return URL is the page to which your customers are redirected after their successful payment.
        CancelURL   Optional (string)
            The cancel URL is the page to which your customers are redirected after their failed payment attempt.
      IDEAL   Optional (string)
          Details below
        ReturnURL   Optional (string)
            The return URL is the page to which your customers are redirected after their successful payment.
        CancelURL   Optional (string)
            The cancel URL is the page to which your customers are redirected after their failed payment attempt.
        BankCode   Required (string)
            String contains the SWIFT code of the bank, the plus sign "+", and the first 3 characters from the bank name. E.q.: in the case of Rabobank, code parameter is "RABONL2U+RAB".
      EXISTING_PAYMENT_DATA   Optional (Object)
          By using EXISTING_PAYMENT_DATA you no longer require shoppers to enter any payment details.
        TransientToken   Optional (string)
            Returned as a part of the process of retrieving customer information by SSOToken.
  CustomerIP   Required (string)
      Shopper IP.
Promotions   Optional (Array of strings)
    Array of promotion codes.
AdditionalFields    
      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.
LocalTime   Optional (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.
GiftDetails   Optional (object)
    Contains contact details for the recipient of a gift purchase.
  FirstName   Optional (string)
      First name of gift recipient.
  LastName   Optional (string)
      Last name of gift recipient.
  Email   Optional (string)
      Email of gift recipient. 2Checkout uses this email for the delivery/fulfillment process.
  GiftNote   Optional (string)
      Custom text shoppers provide as a message to the gift recipient.

Pricing options

Overview

Use this object to add/create and edit/update price options for your account.

Parameters

Parameters Type/Description

PriceOptionsGroup

Object

Name

String

 

Price option group name. Use this parameter when adding a new price options group. To edit the name of a price option group use the Name parameter under the Translations object.

Description

String

 

Pricing option group description.

Translations

Array of objects

 

Details below.

 

Name

String

 

 

Product pricing options group name, localized under Options.

 

Description

String

 

 

Product pricing options group description, localized under Options.

 

Language

String

 

 

ISO language code. (ISO 639-1 two-letter code).

Code

String

 

Unique code that The 2Checkout system generates or set for each pricing options group.

Type

String

 

The type of the pricing options group. Possible values:

· RADIO

· CHECKBOX

· INTERVAL

· COMBO

Options

Array of objects

 

Details below.

 

Name

String

 

 

Pricing option child name.

 

Description

String

 

 

Pricing option child description.

 

Translations

Array of objects

 

 

Details above.

 

 

Name

String

 

 

 

Localized product pricing options group name under PriceOptionGroup.

Localized pricing option child name under Options.

 

 

Description

String

 

 

 

Localized product pricing options group description under PriceOptionGroup.

Localized pricing option child description under Options.

 

 

Language

String

 

 

 

ISO language code. (ISO 639-1 two-letter code).

 

Value

String

 

 

The code you set or that the 2Checkout system generated for each pricing option child inside a pricing options group parent.

 

ScaleMin

Int

 

 

The minimum value of a scale interval set for each pricing option child inside a pricing options group parent of the type INTERVAL.

 

ScaleMax

Int

 

 

The maximum value of a scale interval set for each pricing option child inside a pricing options group parent of the type INTERVAL.

 

SubscriptionImpact

Object

 

 

Details below.

 

Months

String

 

 

The value in months the 2Checkout system adds or subtracts from the initial billing cycle of a subscription.

 

Impact

String

 

 

Possible values:

· ADD

· SUBTRACT

· LIFETIME

 

PriceImpact

Object

 

 

Details below.

 

 

ImpactOn

String

 

 

 

Possible values:

  • BASE corresponding to impact on base price
  • GLOBAL for impact on calculated sum.

 

 

Impact

String

 

 

 

Impact on price per unit:

  • ADD
  • SUBTRACT

 

 

Percent

String

 

 

 

The value of the percentage out of the price per product unit, when you use PERCENT for Method.

 

 

Method

String

 

 

 

Possible values:

· PERCENT

· FIXED

 

 

Amounts

Array of objects.

 

 

 

Details below.

 

 

 

Currency

String

 

 

 

 

Currency ISO code - ISO 4217.

 

 

 

Amount

String

 

 

 

 

The amount defined for each specific currency active for your account, when you use FIXED for Method.

 

Default

Boolean

 

 

TRUE for preselected options.

Missing for options that are not preselected.

 

Account Payouts

Overview

Retrieve the account balance from your current payout period, detailed for each billing currency.

You can also search for the historical transfers issued by 2Checkout for your account, and filter the results based on payment date, method or invoice paid.

 

 

Product group

Overview

Use the ProductGroup object to create/add and update/edit product groups.

Parameters

Parameters Type/Description

Name

Required (string)

 

The name of the product group.

TemplateName

Optional (string)

 

Leave empty to assign the Default Template to the product.

 

Or use the name of an active shopping cart template.

Description

Optional (string)

 

The description of the product group.

 

Configure upselling campaigns

Overview

Use 2Checkout's built in upselling capabilities to give your customers the chance to purchase superior offerings once they add specific products to cart. Extra options, feature-rich SKUs, newer product versions, enhanced support and other recommendations bring additional value to customers while boosting your revenue.

Note: Since upselling recommendations are traditionally more expensive than the products initially added to cart by the shoppers, make sure that the offerings come with incremental value justifying the extra cost.

Requirements

In order to configure an upselling campaign you need to have at least one product set in the 2Checkout Control Panel.

Basic upselling campaigns

You can create basic upselling campaigns for products that do not feature any pricing options.

  1. To set up an upselling campaign, once you defined at least one product, go to the Upselling area under Marketing tools and click Create new campaign.
  2. Select the Primary product. This is the offering that will trigger the campaign when shoppers add it to cart and start the purchase processes. Note: The upselling tool is available for the Shopping Cart page only.
  3. Select a Recommended product. This is the offering suggested to your shoppers by 2Checkout once the campaign triggers.

You can define specific start and end dates for your upselling campaigns. This feature ensures that you can schedule a campaign by configuring the interval of time during which it will be active. Leave the Start date and End date fields empty to have the upselling campaign apply indefinitely.

An active upselling campaign will only be triggered during the interval you configure. The campaign remains active even after the end date is reached, but it will no longer trigger.

To start a campaign immediately, leave the start date empty. If you don't set an end date, the campaign stops when you disable it.

Note: The upselling recommendation is triggered only once per browser session, for every product upsell combination defined (closing the browser window will reset the browser session). 2Checkout sets cookies once an upselling campaign triggers and the recommended product is displayed to a shopper. Adding the Primary product to cart a second time while the initial browser session is still active does not cause the campaign to be triggered again.

In addition to selecting the primary and recommended product, you can also define their respective quantities. If you want the campaign to trigger regardless of the primary product's quantity found in the cart, check the Any quantity checkbox.

IMPORTANT: If you specify a primary product quantity that is lower than the minimum quantity configured in that product's page, you will get a notification informing you about this issue. You can still save the campaign, but it only triggers if you modify the quantity accordingly.

To offer the same quantity of the recommended product as the primary product to the shopper, check the Match quantity checkbox in the Recommended quantity section.

Upselling campaigns with advanced pricing options

You can create upselling campaigns for products with pricing options. You can define pricing options under Pricing configuration when creating/editing products under the Pricing tab.

The necessary steps to set up an upselling campaign with advanced pricing options are the same as described above. However, in addition to defining product quantities, you need to configure the pricing options of both the Primary and the Recommended offerings.

Upselling discounts

Use the Discount field to reduce the price of recommended products part of the up-selling campaign.

The discount will impact the price per unit of recommended products. A $20 discount for a $100 product will become $40 if the quantity of products added to cart is increased to 2.

You can create 2 types of discounts:

Percent

A percentage from 0 to 100% of the price per unit of the recommended product is discounted. Note: Only integer values are supported, i.e. 10% and not 10.5%.

Fixed

A fixed amount is deducted from the price per unit of the recommended product added to cart. You need to select the default currency and configure its associated discount. Note: the value of the discount needs to be a positive number larger than 0, or the field can be left blank.

Fixed discount values can be set:

  • Individually, for each currency. In this scenario, shoppers will see the discount you configured in accordance with the currency used in the shopping cart Note: the display currency does not impact the discount. For example, if the promotion you created offers $10, 15EUR and £5 discounts, shoppers in the US and those selecting US dollars as the cart currency will get $10 off. Similarly, customers buying your products using Euro will get a 15 EUR discount, while those transacting in £ will get £5 discounts.
  • Default promotional value. Upsell discount will be triggered regardless of the cart currency. The 2Checkout system will automatically convert the value of the promotion for all customers making payments in non-default currencies.
  • For the default currency and a selection of other currencies. Shoppers will get either:
  • Specific discount you configured if the cart currency is the same as the default discount currency;
  • Value of the discount configured for the default currency converted to the non-default currency used in the cart.

Upselling description

Add text and HTML tags in the field under the Upselling description area for each up-selling campaign to have a custom message displayed to shoppers. Furthermore, you can customize the message in a number of languages, according to your account settings.

Upselling display type

In the Upselling area, scroll down to change the way your campaigns are displayed to customers.

Two options are available:

  • Interstitial webpage - The recommended product is displayed in an interstitial window, the shopper has to add the offering to cart to continue the purchase process.
  • Overlay window - The recommended product is displayed in a pop-up window, the shopper never leaves the shopping cart. When the recommended product is added to cart, the page in the background is refreshed to reflect the new selection.

Both options offer customers the chance to replace the initial product or stick with it and move on with the ordering process. As clearly visible in the screenshots above, the Replace Product call to action is more prominent compared to the alternative.

Upselling scenarios

1. Primary product without pricing options in Default pricing configuration - Recommended product without pricing options in Default pricing configuration

Upselling

Up-selling campaign will always start. Note: the quantity (number of units) of the Primary product cannot be changed (will always be 1).

2. Primary product without pricing options in Default pricing configuration - Recommended product with pricing options in Default pricing configuration

Upselling

Up-selling campaign will always start.

3. Primary product with pricing options in Default pricing configuration - Recommended product without pricing options in Default pricing configuration

Upselling

For the Primary product, you can select a specific pricing option (only if it's defined for the Default pricing configuration created for the product).

The up-sell campaign will only start when shoppers add to cart the primary product with the specific pricing options you selected when defining the campaign.

4. Primary product with pricing options in Default pricing configuration - Recommended product with pricing options in Default pricing configuration

Upselling

For the Primary product, you can select a specific pricing option (only if it's defined for the Default pricing configuration created for the product) - campaign will start only when the primary product with specific pricing option is added to cart.

Recommended products will be offered only with the specific pricing options you selected, although shoppers will be able to change it once they add the offering to cart.

How to test whether an upselling campaign works

Once you're done configuring the up-selling campaign, go to Generate links. Select the primary product of the up-selling campaign, and generate a buy link for this offering.

The guidance available in the Place a test order in the 2Checkout platform is valid for all products, regardless of whether they're part of an up-selling campaign or not.

Important: Always place test orders after refreshing the browser session (deleting cookies). Alternatively, use InPrivate Browsing in Internet Explorer 9 and above, Incognito mode in Google Chrome, and Private browsing in Firefox, ensuring that no cookies are set.

Scenario 1: Upselling campaign always start

Up-selling campaign will always start in the following two cases:

  • Primary product without pricing options in Default pricing configuration - Recommended product without pricing options in Default pricing configuration
  • Primary product without pricing options in Default pricing configuration - Recommended product with pricing options in Default pricing configuration

Step 1: Generate the buy link for the Primary product of your up-selling campaign.

Step 2: Instead of hitting the Place test order button, copy the buy link generated and add &DOTEST=1 to the end of the link, per the guidance available here: Place a test order in the 2Checkout platform.

Step 3: Open a new window in your browser using InPrivate Browsing in Internet Explorer 9 and above, Incognito mode in Google Chrome, and Private browsing in Firefox. Paste the link you tweaked by adding the &DOTEST=1 parameter.

Step 4: The upselling campaign will be triggered automatically. Select to replace the Primary product with the Recommended offering and continue through the steps of placing a test order as described here:  Place a test order in the 2Checkout platform.

Scenario 2: Upselling campaign start for specific pricing options

Upselling campaigns will only start for specific pricing options in the following two cases:

  • Primary product with pricing options in Default pricing configuration - Recommended product without pricing options in Default pricing configuration
  • Primary product with pricing options in Default pricing configuration - Recommended product with pricing options in Default pricing configuration
  1. Go to Generate links and select the Primary product of your upselling campaign.
  2. In the Main Settings area, enter the specific pricing option unique code that will trigger the up-selling campaign in the Additional pricing options field. The unique code can be accessed by editing the primary product, selecting the Pricing tab, scrolling down to the Pricing options groups area, and clicking to edit the active pricing options group. Next you will need to edit the specific pricing option designed to trigger the campaign and copy the value inserted under the Unique code field. Once you copied this value, paste it in the Additional pricing options field.
  3. Generate the buy link for the Primary product of your upselling campaign.
  4. Copy the buy link and add &DOTEST=1 to the end of the link, per the guidance available here:  Place a test order in the 2Checkout platform.
  5. Open a new window in your browser using InPrivate Browsing in Internet Explorer 9 and above, Incognito mode in Google Chrome, and Private browsing in Firefox. Paste the link you tweaked by adding the &DOTEST=1 parameter.
  6. The up-selling campaign will be triggered automatically. Select to replace the Primary product with the Recommended offering and continue through the steps of placing a test order as described here:  Place a test order in the 2Checkout platform.

Upselling scenarios priority

If multiple campaigns are configured for the same products, the 2Checkout system triggers the campaigns based on specificity criteria, as follows:

  1. The system primarily triggers the up-selling campaigns that have both specific product quantity and specific pricing options configured.
  2. If the first case is not detected, the system triggers the campaigns that have a specified product quantity configured, regardless of the pricing options.
  3. If the first two cases are not detected, the system triggers the campaigns that have specific pricing options configured, regardless of the product quantity.
  4. Ultimately, the system triggers the campaigns with any pricing options and any product quantity.

To give you a better overview of the scenarios priority, refer to the diagram below.

Upselling campaigns and localization strategies (regional prices)

When configuring up-selling campaigns, you'll need to factor in localized pricing strategies for the primary and recommended products. There are four scenarios you need to consider, related to the type of up-selling campaigns available.

The upselling report

This is an entirely new report introduced in July 2012 to help you monitor the evolution and performance of the up-selling campaigns configured for your account. The Up-selling report centralizes up-selling campaign statistics recorded in the selected time period; however, data is only available starting with July 21st, 2012, when tracking began. The report includes finished orders only, without refunds, for products involved in up-selling campaigns.

FAQ

  1. Are cascading upselling campaigns possible?
    • No. While you can set two upselling campaigns Product A to Product B and Product B to Product C, the system will not recommend products in cascade to shoppers. This means that if a customer adds Product A to cart and then replaces it with Product B, the 2Checkout system will not recommend Product C in this particular scenario even if a valid up-selling campaign is set.
  2. ​What happens when multiple Primary products are added to cart? Are all upselling campaigns started?
    • Only the upselling campaign for the first product added to cart will be started.​
  3. Why can't I change the quantity (number of units) for the Primary product of my up-selling campaign?
    • The quantity (number of units) of the primary product can only be changed when the configuration of at least one of the products in the upselling campaign has a specific pricing option selected. Otherwise, the default value if 1 and the up-selling campaign will always start.
  4. If both an auto-apply promotion and an upselling campaign discount impact a product, which one will work?
    • ​​The upselling discount will take precedence over the auto-apply promotion when shoppers add the recommended product to cart.
  5. Can I use both cross-sell and upsell for the same product?
    • ​​Yes, however, shoppers will only be able to benefit from either the cross-sell or the upselling, not both.​
  6. Can I set multiple upselling campaigns impacting the same product?
    • ​​​​​​​​​No. A product can be used only for a single up-sell campaign.​​​​​​​​
  7. Can multiple upselling campaigns be triggered?
    • ​​​​​​​​​​​​​​​​No. Only a single upselling campaign per browser session.

Copy payment info

Overview

Copy card-on-file data available in the Avangate system from a source subscription to an imported target subscription. Avangate uses the existing payment information to charge customers as a part of the recurring billing (renewal) process.

Use the copyPaymentInfo method.

Requirements

The imported target subscription and the source subscription must belong to the same customer. The Avangate system checks to make sure that the Avangate Customer Reference (internal identifier) coincides for the customer accounts associated to the target and source subscriptions.

Availability

Please contact Avangate directly if you wish to take advantage of this feature.

How does this method work?

  1. Customer A purchases Subscription A using a VISA credit card and you import Subscription B for the same customer with no data or with an AMEX card.
  2. When Avangate renews Subscription A, it charges Customer A using the VISA, while using the AMEX (if the data was provided) for Subscription B charges.
  3. When you copy the payment data from Subscription A to Subscription B, the Avangate system uses the VISA credit card to renew both subscriptions according with their respective recurring billing cycles. Avangate charges customers during the recurring billing process for the imported target subscription using the payment method they used to purchase the source subscription.

Parameters

Parameters

Type/Description

sessionID

Required (string)

 

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

TargetSubscriptionReference

Required (string)
 

The Avangate Subscription Reference of the imported target subscription, to which Avangate copies the payment on file data associated with the source subscription.

SubscriptionReference

Required (string)

 

The Avangate Subscription Reference of the source subscription whose attached payment on file data Avangate copies to the target subscription.

Request

<?php

require ('PATH_TO_AUTH');

var_dump($sessionID);
$TargetSubscription = 'FFAE3C9429';
$SourceSubscription = '9F4154733C';

$jsonRpcRequest = array (
'method' => 'copyPaymentInfo',
'params' => array($sessionID, $TargetSubscription, $SourceSubscription),
'id' => $i++,
'jsonrpc' => '2.0');

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

?>

Response

Parameter Type/Description

Boolean

true or false depending on whether or not the operation succeeded.

Usage management

Overview

The usage-based/on-demand/pay-as-you-go pricing model allows merchants to charge their customers on the consumption or overage of a billable service or resource, usually on top of a recurring flat rate. 

Use the Usage object to manage (add, update, delete, retrieve, and import) usage via the 2Checkout API (JSON-RPC APIv6).

Parameters

Parameters for the Usage object via JSON-RPC APIv6
Parameters Type Required/Optional Description
UsageReference Integer Optional The unique usage identifier. Example: 123459876.
SubscriptionReference String Required Unique code that represents a subscription. Example: 83FE4FEF2.
OptionCode String Required Unique 2Checkout option code. The pay-per-usage price options group for which the usage is uploaded. Example: metered pricing.
UsageStart Datetime Required The datetime when the usage started; can be the same as UsageEnd.  Example: 2018-09-03 17:28:32.
UsageEnd Datetime Required The datetime when the usage ended and was recorded. Example: 2018-09-03 17:28:32.
Units Integer Required Number of units recorded. Example: 10.
Description String Optional It can be used to store a short merchant comment of the usage being uploaded. This can be anything, from the source of usage (mobile, web, etc.), to why changes occurred, etc. Example: Subscription usage for September.

 

 

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