Skip to main content

Update promotion coupon

Overview

Use the updatePromotionCoupon method via SOAP API 4.0 to add single or multiple coupons to a promotion.

Updating a promotion with multiple coupons causes any existing single coupon to be removed.

Parameters

Parameter Type/Description

sessionID

Required (string)

 

Output of the Login method.

promotionCode

Required (string)

 

The code corresponding to the promotion that you want to update.

promotionCoupon

Required (object)

 

type

Required (string)

 

 

Coupon type. Available values:

  • SINGLE, use in conjunction with Code
  • MULTIPLE, use in conjunction with Codes

 

Code/Codes

Required (string / array of strings)

 

 

Coupon code (for SINGLE) or array of coupon codes (for MULTIPLE).

Response

Parameter Type/Description
promotionCoupon Object

Request

<?php 

class Client
{
    protected static $merchantCode;
    protected static $loginDate;
    protected static $hash;
    protected static $baseUrl;
    protected static $callCount = 0;
    protected static $sessionId = '';

    protected static $client;

    public static function setCredentials($code, $key)
    {
        static::$merchantCode = $code;
        static::$loginDate = gmdate('Y-m-d H:i:s');
        static::$hash = hash_hmac('md5', strlen($code) . $code . strlen(static::$loginDate) . static::$loginDate, $key);
        static::$sessionId = static::login();
    }

    public static function setBaseUrl($url)
    {
        static::$baseUrl = $url;
    }

    public static function login()
    {
        $client = static::getClient();
        return $client->login(static::$merchantCode, static::$loginDate, static::$hash);
    }

    public static function __callStatic($name, $arguments = array())
    {
        $client = static::getClient();

        array_unshift($arguments, static::$sessionId);
        $response = call_user_func_array(array($client, $name), $arguments);

        return $response;
    }

    protected static function getClient()
    {
        $opts = array(
            'http'=> ['user_agent' => 'PHPSoapClient'],
            'ssl' => [
                'verify_peer' => false,
                'verify_peer_name' => false,
            ],
        );

        if (null === static::$client) {
            static::$client = new \SoapClient(static::$baseUrl . '?wsdl', [
                'location' => static::$baseUrl,
                'cache_wsdl' => WSDL_CACHE_NONE,
                'stream_context' => stream_context_create($opts),
            ]);
        }

        return static::$client;
    }
}

Client::setBaseUrl('https://api.2checkout.com/soap/3.1/');
Client::setCredentials('YOUR_MERCHANT_CODE', 'YOUR_SECRET_KEY');
Client::login();

$promotionCode = 'YOUR_PROMOTION_CODE'; // code of the promotion that you want to update

// // Define single coupon object
// $promotionCoupon = new stdClass;
// $promotionCoupon->Type = 'SINGLE';
// $promotionCoupon->Code = 'YOUR_CODE_HERE';

// Define multiple coupon object
// $promotionCoupon = new stdClass;
// $promotionCoupon->Type = 'MULTIPLE';
// $promotionCoupon->Codes = ['YOUR_CODE_1', 'YOUR_CODE_2'];

$response = Client::updatePromotionCoupon ($promotionCode,$promotionCoupon); // Update existing coupons
var_dump($response);

 

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

 

 

 

 

  • true - customers opted for subscriptions to renew automatically when they expire.
  • false - customers did not choose to renew the subscription automatically.

                    

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.

Orders with installments

Overview

2Checkout supports local Brazilian Visa, MasterCard and AMEX credit/debit cards limited to national purchases in the local currency BRL (Brazilian Real)

Requirements

  1. Installments are available only for:
    • Brazilian customers
    • Local Visa, MasterCard or AMEX cards
    • Non-recurring transactions
  2. Minimum installment threshold is 5 BRL. The maximum number of installments is 6.
  3. Mandatory information for payments also includes a shopper phone number and  Fiscal Code (CPF/CNPJ).

Do local BR cards with/without installments require an addendum to my contract?

Yes. Please contact 2Checkout for activation.

How does it work?

  1. Create the Order object.
  2. Validate the number of installments available based on total order value. 
  3. Place the order specifying the number of installments. 

Funds collection for installment payments

2Checkout pays you in full, regardless of the number of installments (this is covered directly by the banks). 

 

 

Dynamic 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

Parameters Type/Description

Errors

                        Optional (StringArray)

 

                        Payment gateway processing errors.

Items

Array of objects

   

Details below. 

 

ProductDetails

Object

   

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

     

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)

       
  • true – For subscriptions with active recurring options
  • false – For subscriptions without recurring options.
    Tangible   Optional (boolean)
       
  • true – For products with physical delivery.
  • false – For products that don't require physical delivery.
    IsDynamic   Optional (boolean)
       
  • true – For products created with dynamic information.
  • false – For catalog products.
    ShortDescription   Optional (string)
        Short product description
    DeliveryInformation   Optional (object)
        Details below.
      Delivery Optional (string)
        Delivery information.
      DownloadFile Optional (object)
        Information related to the download file.
      DeliveryDescription Optional (string)
        Delivery description.
      CodesDescription Optional (string)
        Description of the codes delivered.
      Codes Optional (array)
        Array with the codes delivered.

                   

PriceOptions

Optional (array of objects)

   

Array of price option groups.

   

Code

Optional (strings)

     

Pricing option code. 

   

Required

Optional (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

Optional (array of objects)

     

Array of pricing options.

      Name Optional (string)
        Pricing option name.
      Value Optional (string)
        Pricing option code.
      Surcharge Optional (string)
        Surcharge of the pricing option. The value is not added to the product amount, but it will be stated in the cart as part of the total product price.
 

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 (in the payment currency), excluding sales tax/VAT, from which Avangate deducts discounts.

   

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.

 

Quantity

Optional (integer)

   

Number of units

 

SKU

Optional (string)

   

SKU identifier.

  PurchaseType Optional (string)
   

Purchase type for orders placed with dynamic information. Possible values:

  • PRODUCT
  • TAX
  • COUPON
  • SHIPPING
  ExternalReference Optional (string)
    External order reference.
  SubscriptionStartDate Optional (string)
    Set subscription starting date. 
 

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.

BillingDetails

Optional (Object)

   

Details below. 

 

FirstName

Optional (string)

   

Shopper name.

 

LastName

Optional (string)

   

Shopper surname.

 

CountryCode

Optional (string)

   

Shopper country. ISO 3166 two-letter code.

 

State

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

   

The state in the shopper's country. 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.

 

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.

 

FiscalCode

Optional (string) – Required for Brazil

   

• For companies, it needs to be the VAT ID. Avangate 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).

• Can be null for end users.

DeliveryDetails

Optional (Object)

Optional. When missing, Avangate uses the same details as for the BillingDetails object.

   

Details below. 

 

FirstName

Optional (string)

   

Shopper name from the delivery details.

 

LastName

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

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.

Single Sign On by customer reference

Overview

Use the getSingleSignOnByCustomer method to create Single Sign On links into Avangate myAccount based on customer references (IDs). Use either the Avangate Customer Reference or the External Customer Reference to identify specific customers.

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.

idCustomer

Required (string)

 

Unique customer identifiers. Can be either the ExternalCustomerReference you control or the system-generated AvangateCustomerReference.

customerType

Required (string)

 

Possible values:

  • ExternalCustomerReference
  • AvangateCustomerReference

page

Optional (string)

 

The specific myAccount page where you redirect the customer.

Possible values:

my_subscription - redirect shoppers to the subscription's page of myAccount based on the SubscriptionReference you provide.

my_products - redirects shoppers to the myAccount page designed to list all products purchased from Avangate.

https://store.YourCustomDomain.com/m...t/my_products/?

user_data - redirects shoppers to the Personal Information page in myAccount

https://store.YourCustomDomain.com/m...unt/user_data/?

order_lookup - redirects shoppers to the Order Lookup area of myAccount:

https://store.YourCustomDomain.com/m.../order_lookup/

faq - redirects shoppers to the Support page of myAccount

https://secure. YourCustomDomain.com/support/

payment_methods – redirect shoppers to the Payment Methods area of myAccount:

https://store.YourCustomDomain.com/m...yment_methods/

Do not include PAGE in the URL to redirect shoppers to myAccount homepage

https://store.YourCustomDomain.com/myaccount/?

 

request

Optional (string)

 

Needed for 'my_subscription'

Request[]=code=123D40F123 redirects customers to the page for the subscription with the 123D40F123 SubscriptionReference value.

 

validityTime

Optional (int)

 

The time, in seconds, before the single sign-on URL expires. By default, the URL expires after 10 seconds. (optional)

validationIp

Optional (string)

 

The IP address of the shopper, necessary for security purposes. Can be an empty string or a valid IP, or null.

Response

Parameters Type/Description

Single sign-on URL

String

 

The string generated is the complete single sign-on URL pointing to Avangate myAccount, containing the unique URL. Shoppers using it log into their Avangate myAccount automatically.

Request

<?php

require ('PATH_TO_AUTH');

$idCustomer = '352365983';
$customerType = 'AvangateCustomerReference';
$page = 'my_license';
$request = null;
$validityTime = 50;
$validationIp = null;

$jsonRpcRequest = array (
'method' => 'getSingleSignOnByCustomer',
'params' => array($sessionID, $idCustomer, $customerType, $page, $request, $validityTime, $validationIp),
'id' => $i++,
'jsonrpc' => '2.0');

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

One click (1-click) purchase

Overview 

2Checkout supports 1-click purchases for returning customers who paid for their previous orders with:

  • Credit/Debit cards
  • PayPal

How does this work? 

  1. Identify returning customers. 
  2. Access data on the previous purchases of returning customers.
  3. Validate previous order references for 1-click purchase scenarios using the isValidOrderReference method (explained below).
  4. Place a new order using a valid previous order reference as the payment method. 
  5. 2Checkout charges returning customers using their payment-on-file information, either a card or their PayPal account. 

Requirements 

  • Use only references of previous orders  with one of the following statuses AUTHRECEIVED or COMPLETE.
  • The email address of the BillingDetails object is mandatory and it needs to match the email address used as a part of the billing details of the initial order whose reference you're now using to place a new order. 2Checkout checks whether the email addresses are identical, and throws an error if they're not, blocking the order placement process. Note: You need to provide only the email address of the shopper, and can ignore the rest of the required customer billing information. If you enter any billing details in addition to the email address, you'll have to provide all information required in the BillingDetails object.

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.

Order

Required (Object)

 

Object designed to collect all data necessary for an order, including billing, product/subscription plan and payment details.

Response 

Parameters Type/Description

Order information

Object

  Object containing order information.

Validate previous order reference

<?php

require('PATH_TO_AUTH');

$orderReference = '670174996';

try {
    $validOrderRef = $client->isValidOrderReference($sessionID, $orderReference);
}
catch (SoapFault $e) {
    echo "validOrderRef: " . $e->getMessage();
    exit;
}
var_dump("validOrderRef", $validOrderRef);

try {
    $existentOrder = $client->getOrder($sessionID, $orderReference);
}
catch (SoapFault $e) {
    echo "existentOrder: " . $e->getMessage();
    exit;
}

Place an order using previous order reference 

<?php

require('PATH_TO_AUTH');

$oldOrderExistent = callRPC((Object)$jsonRpcRequest, $host, true);
$Order = new stdClass();
$Order->RefNo = NULL;
$Order->Currency = 'usd';
$Order->Country = 'US';
$Order->Language = 'en';
$Order->CustomerIP = '91.220.121.21';
$Order->ExternalReference = NULL;
$Order->Source = NULL;
$Order->AffiliateId = NULL;
$Order->CustomerReference = NULL;

$Order->Items = array();
$Order->Items[0] = new stdClass();
$Order->Items[0]->Code = 'my_subscription_1';
$Order->Items[0]->Quantity = 1;
$Order->Items[0]->PriceOptions = NULL;
$Order->Items[0]->SKU = NULL;
$Order->Items[0]->Price = NULL;
$Order->Items[0]->CrossSell = NULL;
$Order->Items[0]->Trial = false;
$Order->Items[0]->AdditionalFields = NULL;
$Order->Items[0]->Promotion = NULL;

$Order->BillingDetails = new stdClass();
$Order->BillingDetails->Email = $oldOrderExistent->BillingDetails->Email;;
$Order->DeliveryDetails = NULL;
$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'PREVIOUS_ORDER';
$Order->PaymentDetails->Currency = 'usd';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->CustomerIP = '10.10.10.10';
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = true;
$Order->PaymentDetails->PaymentMethod->RefNo = $orderReference;

$Order->AdditionalFields = NULL;
$Order->LocalTime = NULL;
$Order->GiftDetails = NULL;

try {
    $newOrderPaidWithPreviousRef = $client->placeOrder($sessionID, $Order);
}
catch (SoapFault $e) {
    echo "newOrderPaidWithPreviousRef: " . $e->getMessage();
    exit;
}
var_dump("newOrderPaidWithPreviousRef", $newOrderPaidWithPreviousRef);
?>

Retrieve a price option group

Overview

Use the getPriceOptionGroup method to extract information about a specific price option group that you configured.

Parameters

Parameters Type/Description

ProductGroup

Object

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.

groupCode

Required (string)

 

The code that the 2Checkout system generated or that you set for the product pricing options group.

Request

Parameters Type/Description

PriceOptionGroup

Array of objects

Request

<?php

require ('PATH_TO_AUTH');

$groupCode = 'USERS';

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

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

 

Single Sign On (SSO)

Overview

Redirect and login shoppers automatically from your user portal into their 2Checkout myAccount based on subscription or customer information.

Requirements

You need a custom domain to use Single Sign On. Contact 2Checkout directly for guidance on how to set up a custom domain.

 

 

Export product data as an XML file

Overview

Export product and pricing data packaged as an XML file. 

Requirements

At least one product needs to have already been configured or imported in the 2Checkout system.

Export limitations

We recommend exporting batches of 20 to 30 products at once for optimal performance.

  • Exporting up to 1000 products is done on the spot.
  • Exporting more than 1000 products lasts longer and is done in the background. 2Checkout can notify you via email when your export file is ready and provides you with the download link.

How does export work?

Use UTF-8 character encoding.

To export existing product data from the 2Checkout platform:

  1. Make your way to Products under Setup.
  2. Run a search for the products you want included in the export file.
  3. Once your search returns the list of desired products, scroll down to the bottom of the page and click Download XML.

How to export all products for an account?

To export existing product data from the 2Checkout platform:

  1. Make your way to Products under Setup;
  2. The Active option is selected under Display by default.
  3. Scroll down to the bottom of the page and click Download XML.

Note: All active products for your account are displayed when accessing the Products area. Not searching for specific offerings will export all active items.

What data is exported?

The XML product export functionality covers data under the following areas (tabs), with some exceptions detailed below:

  1. Information
  2. Pricing
  3. Bundle Options

XML schema

Use UTF-8 character encoding.

Below is the XML schema designed to let you export product data from the 2Checkout system. Export is the root element, and there are three main child elements:

  • AdditionalFields: The export extracts per-product and per-order additional order details from the 2Checkout system. The relationship between the fields and products is mapped under the Product child element.
  • PriceOptionsGroups: The export extracts data on all price options groups defined in the 2Checkout system. The relationship between one or more price options groups and products is mapped under the Product child element.
  • Products: Product information (with some exceptions) that resides under the Information, Pricing and Bundle options area (tabs) of the Control Panel.

 

<Export>
<AdditionalFields>...</AdditionalFields>
<PriceOptionsGroups>...</PriceOptionsGroups>
<Products>...</Products>
</Export>

Retrieve a promotion

Overview

Use the getPromotion method to extract information on a promotion you set up for your account.

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.

PromotionCode

Required (string)

 

System-generated identifier 2Checkout associated with promotion campaigns.

Response

Parameters Type/Description
Promotion Object 

 

Request

<?php

require ('PATH_TO_AUTH');

$promotionCode = 'PROMOTION_CODE'; // code of the promotion that you want to update

try {
    $Discount = $client->getPromotion($sessionID, $promotionCode);
}
catch (SoapFault $e) {
    echo "Discount: " . $e->getMessage();
    exit;
}

var_dump("Discount", $Discount);

 

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.

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.

Verifone logo