Skip to main content

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.

 

 

Create promotion

Overview

Use the addPromotion method via JSON-RPC API 4.0 to create a new promotion.

Parameters

Parameters

Type/Description

sessionID

Required (String)

 

Output of the Login method.

Promotion

Object

 

Name

Optional(String)

 

 

Promotion name

 

Description

Optional(String)

 

 

Promotion description

 

StartDate

Optional(String)

 

 

Starting date. The date when you set the promotion to start. Is NULL for promotions that start immediately after they're created.

Format: Y-m-d

 

EndDate

Optional(String)

 

 

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

Format: Y-m-d

 

MaximumOrdersNumber

Optional(Int)

 

 

Avangate stops offering the discount when the promotion reaches the maximum number of orders. Can be NULL if you want the promotion to apply to an unlimited number of orders.

 

MaximumQuantity

Optional(Int)

 

 

Discount only applies to a specific number of products, smaller than the maximum quantity you defined. Can be NULL if you want the promotion to apply to an unlimited number of units. Any extra quantity added to the cart will be sold at full price.

 

InstantDiscount

Optional(Boolean)

 

 

Selecting the instant discount option will auto-apply the discount for ALL the selected products for all shoppers, without the need to enter the discount coupon.

Coupon

Optional(Object)

 

Type

Optional(String)

 

 

  • SINGLE = one coupon code shared by all shoppers
  • MULTIPLE = array of unique coupon codes, each designed for individual use

 

Code/Codes

Optional(String/Array)

 

 

Varies according to type. Send:

  • Code = 'single_code'; when Type = 'SINGLE';
  • Codes = ['code1', 'code2']; when Type = 'MULTIPLE';

Enabled

Optional(Boolean)

 

TRUE

FALSE

ChannelType

Optional(String)

 

Possible values:

  • ECOMMERCE
  • CHANNEL_MANAGER
  • ALL

Type

Optional(String)

 

REGULAR

Discount

Optional(Object)

 

Type

Optional(String)

 

 

Discount type:

  • PERCENT, use in combination with Value
  • FIXED, use in combination with Values and DefaultCurrency

 

Value / Values

Optional (Int / Array of objects)

 

 

  • Value = Int, determines the discount percentage from 0 to 100
  • Values = Array of Value objects

 

 

Value

Optional(Object)

 

 

 

Currency

Optional (String)

 

 

 

 

ISO currency code

 

 

 

Amount

Optional (Int)

 

 

 

 

Discount amount in corresponding currency.

 

DefaultCurrency

Optional(String)

 

 

ISO code

Products

Optional(Object)

 

Code

Optional(Int)

 

 

Unique product code that you control.

 

PricingConfigurationCode

Optional(String)

 

 

Unique system generated pricing configuration code.

 

PricingOptionCodes

Array of strings

 

 

Array of pricing option codes controlled by you.

PriceThreshold

Object

 

Limits discount use only when total order value (taxes included) exceeds the threshold you configure.

 

Amount

Decimal

 

 

The minimum threshold you defined for the default currency.

 

Currency

String

 

 

Currency code available for the default currency of custom threshold settings.

Translations

Optional(Array of objects)

 

PromotionTranslation

Optional(Object)

 

 

Name

Optional(String)

 

 

 

Localized name corresponding to translated language.

Name: Le product

Language: FR

 

 

Language

Optional(String)

 

 

 

 

Sources

StringArray

 

Array of strings defining the sale source through the SRC parameter.

PublishToAffiliatesNetwork

Optional(Int)

 

 

ApplyRecurring

Optional(String)

 

  • NONE
  • ALL
  • CUSTOM

RecurringChargesNumber

Optional(Int)

 

Offer discounts for a number of recurring billing charges beyond the initial purchase.

Response

Parameters Type/Description
Promotion 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;
    }
}


$promotionObject = new stdClass;
$promotionObject->Name = 'YOUR_PROMOTION_TITLE';
$promotionObject->Description = 'YOUR_PROMOTION_DESCRIPTION';
$promotionObject->StartDate = date('Y-m-d', strtotime('1 month ago'));
$promotionObject->EndDate = date('Y-m-d', strtotime('+1 month'));
$promotionObject->Type = 'REGULAR';
$promotionObject->Enabled = 1;
$promotionObject->MaximumOrdersNumber = 0;
$promotionObject->MaximumQuantity = 0;
$promotionObject->InstantDiscount = false;
$promotionObject->ChannelType = 'ECOMMERCE';
$promotionObject->ApplyRecurring = 'NONE';
$promotionObject->RecurringChargesNumber = 3;
$promotionObject->PublishToAffiliatesNetwork = 0;
$promotionObject->AutoApply = 0;

$couponObject = new stdClass;
$couponObject->Type = 'SINGLE';
$couponObject->Code = 'single_code';
$promotionObject->Coupon = $couponObject;

$discountObj = new stdClass;
$discountObj->Type = 'PERCENT';
$discountObj->Value = 80;
$promotionObject->Discount = $discountObj;
$promotionObject->Products = [$productsObj1, $productsObj2, $productsObj3];
$promotionObject->Translations = [$translation1, $translation2];

Client::setBaseUrl('https://api.2checkout.com/soap/3.1/');
Client::setCredentials('YOUR_MERCHANT_CODE', 'YOUR_SECRET_KEY');
Client::login();
$response = Client::addPromotion($promotionObject);
var_dump($response);

 

Set up subscription plans

Overview

Set up subscription plans and offer shoppers:

  • Free and paid trials
  • Evergreen (one time fee) products/subscriptions
  • Renewing subscriptions
  • Subscriptions with metered billing

Availability

All 2Checkout accounts. 

Requirements

Make sure to have the mandatory product info on hand. 

Set up a subscription plan

  1. Navigate to Products, create a new item, and go through the initial stages of product setup. You'll be able to configure a billing cycle and recurring costs immediately, and you can fine-tune the setting with the advanced options for subscription pricing and renewal. 
  2. Configure recurring and manual charges, local pricing and currencies, pricing options, and renewal discounts,  under the Pricing tab. 
  3. Set up billing cycles, contracts, and renewal notifications under the Renewal tab.

Renewal/Recurring pricing

Set up different renewal prices for subscriptions and configure recurring charges.

Products with a base price

Access guidance on configuring custom recurring charges

A number of options are available, including matching the costs of renewals to those of the initial purchases and configuring a renewal base price independent of the price first paid by subscribers. You can define individual prices for each currency and option, not necessarily based on a formula. For subscriptions sold initially based on a base price, when setting a renewal base price, 2Checkout applies all active pricing options to the new base price.

Products without base price

Access guidance on configuring custom recurring charges

Matching the costs of renewals to those of the initial purchases is an option that's also available for products without a base price. In addition, you get the possibility to also set renewal prices manually, according to the overall pricing strategy associated with the subscription.

Promotions for subscriptions

Discount the costs of subscriptions both on the initial purchase and for every subsequent charge be it recurring or not. 

Renewal discounts

Navigate to Subscriptions under Setup, and select the Renewal Discounts tab.

  1. Enter a promotion title (will be visible to shoppers during the purchase process) and a description.
  2. Discount code: enter the coupon value.
  3. Set the discount either as a percentage or a fixed amount.
  4. Edit the settings of the product for which you're discounting subscription charges and assign the promotion to the plan under the Pricing Tab. Provided that you have defined at least one promotion, you can apply a discount to both manual and automatic renewals (recurring charges).
  • For products with a base price (dynamic), discounts can be applied in the Renewal Price area of the pricing configuration page.
  • For products without a base price (flat), discounts can be added by navigating to the Prices area on the pricing configuration page and then selecting the Renewal tab.

Promotions for recurring orders

Use Apply to recurring charges to easily extend the benefits of promotions for subscriptions you offer customers well beyond the first transaction, by applying them not only to the initial purchase but also to as many subsequent charges as you wish. 

Billing cycle 

Control individual billing cycle settings right from the Renewal area of the Control Panel when editing a product.

The billing cycle defines the time interval between the initial billing date and the renewal charge. Options available: 

  • Renewal interval in days - supported values from 7 to 1095 days. The minimum subscription lifecycle is 7 days. Please contact 2Checkout directly if this feature is not available for your account.
  • Monthly from one (1) month to three (3) years (36 months).
  • One time fee to set up the duration for the subscription as non-renewing (lifetime).

Changing the billing cycle for a subscription plan comes into effect only after existing, active subscriptions renew. 

Subscription billing cycle workflow

Following the initial acquisitions, at the end of the billing cycle, the 2Checkout system can:

  • Convert all trials for which shoppers supplied payment information such as the credit card unless they opted out during the trial period. 
  • Automatically renew the subscription generated for the purchased product if shoppers enabled recurring billing. 
  • Send manual renewal links to the shoppers who opted out of recurring billing. 

Manage subscriptions for bundled products

Subscription management for bundle products comes with two different options:

  • Create subscription settings for bundle product
  • Use the subscription settings of each product in the bundle

It's up to you to decide whether to generate a global subscription for all the products in a bundle, overwriting per-product specific renewal configurations, or whether to define individual renewal settings for each standalone product part of the bundle.

Renewal notification emails

The 2Checkout system notifies your shoppers when their subscription is close to expiration via email. You can opt to:

  • Send emails according to the global renewal notification settings
  • Create individual renewal notification settings for this product

Both options enable you to control the number of notification messages sent to customers, as well as when they should receive them. Whether their subscription is set to manual payment or automatic renewal, shoppers can get email notifications:

  • 30 days before the subscription expiration date
  • 15 days before the subscription expiration date
  • 7 days before the subscription expiration date
  • 1 day before the subscription expiration date (only available if your account supports setting renewal intervals in days. Contact 2Checkout directly if you'd like to take advantage of this feature.)
  • on the expiration date
  • 5 days after the subscription expiration date
  • 15 days after the subscription expiration date

Renewal with a new product version

Ensure smooth upgrades from deprecated versions of a product to the latest release. 2Checkout offers shoppers the option to replace their old version of a subscription with the latest one, provided that you configure Renewal with a new product version settings. Essentially, this enables customers to upgrade older versions of offerings they purchased from you as a part of the renewal process.

  1. When setting up the subscription, check the box which specifies that the product is a newer version of other items.
  2. Next, access the list with existing products, and select the deprecated items you want to be replaced by the subscription you're creating, during the renewal process.
  3. Choose to replace as many old versions of the deprecated product with the new one as you want.

Global renewal settings

Select the Renewal Settings tab under Setup->Renewal and set the global renewal options to apply to all the products for which 2Checkout generates subscriptions.

When customers buy a subscription, they will be able to activate auto-renewals and, thus, agree to automated future charges for that subscription. To do that, they need to provide express consent and opt-in for automatic renewal, during the purchase process. When selecting the Enable auto-renewal option during the purchase process, shoppers enroll in the automatic renewal system, enabling 2Checkout to set in place a recurring charge schedule for their subscription based on the billing cycle setup.

Shoppers have the option to cancel automatic renewals by accessing their 2Checkout myAccount.

If shoppers decide not to enroll in the automatic renewal system, 2Checkout sends out email notifications when subscriptions are about to expire. These email notifications inform shoppers that they need to purchase subscription renewals.

The 2Checkout system allows you to control the intervals of time when expiration notifications will be sent out to customers, both per-product, and via the Global Renewal Settings. Any changes of the Global Renewal Setting will impact all offerings that have the Renewal status enabled, but will be overridden by per-product subscription settings:

Grace period 

Enable shoppers to purchase renewals even after subscriptions expire, while their old subscriptions are still in the grace period. Subscriptions that are not renewed ahead of the expiration deadline that enter the grace period feature the Past due status.

Grace period options available include:

  • 0 days
  • 5 days
  • 15 days
  • 30 days
  • 60 days
  • Unlimited

When the unlimited option is selected, customers can renew their subscription regardless of the amount of time that passes after the expiration mark.

  • Subscription validity after renewal starts on - you can choose to have the new subscription start on the same day when the previous subscription expires, or on the renewal day.
  • Send renewal emails - to all subscription renewals or only to renewals of 6 months (or more). This setting suppresses all emails sent when renewing subscriptions with billing cycles shorter than 6 months, except for the emails sent 7 days before the subscription expiration date.

Email template manager - renewal notifications

Personalization of notification content emailed to subscribers comes to complement the customization capabilities of renewal settings in the 2Checkout system. By controlling the messages shoppers receive you maximize chances of successful renewals.

Navigate to Email template manager under Marketing tools, and expand the Renewal area on the custom HTML email templates page. You can add custom text to auto and manual payment notification emails, and preview all messages, including Trial automatic purchase notifications.

Two email formats are available, HTML and Text. When selecting the first, you'll also be able to choose an HTML template, either by opting for the default one or by adding custom designs.

Place an order with installments

Overview

Use the placeOrder method to create an order and collect the payment.

Supported payment methods 

Credit/Debit cards: Visa and MasterCard local Brazilian cards.

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.

Requirements

  1. Payment methods: Visa, MasterCard or AMEX
  2. Country: Brazil
  3. Currency BRL
  4. Specified number of installments under the PaymentMethod object. (Minimum installment threshold is 5 BRL.)
    • Phone number
    • Fiscal code (CPF/CNPJ)
  5. Mandatory billing information must include:
  6. Transaction: non-recurring
  7. Installments are available only for:
    • Brazilian customers
    • Local Visa, MasterCard and AMEX cards
    • Non-recurring transactions
<?php

require ('PATH_TO_AUTH');

$Order = new stdClass();
$Order->RefNo = NULL;
$Order->Currency = 'brl';
$Order->Country = 'BR';
$Order->Language = 'en';
$Order->CustomerIP = '91.220.121.21';
$Order->ExternalReference = NULL;
$Order->Source = NULL;
$Order->Affiliate = new stdClass();
$Order->Affiliate->AffiliateCode = 'Partner123'
$Order->Affiliate->AffiliateSource = 'MobilePlatform'
$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->FirstName = 'FirstName';
$Order->BillingDetails->LastName = 'LastName';
$Order->BillingDetails->CountryCode = 'BR';
$Order->BillingDetails->State = 'DF';
$Order->BillingDetails->City = 'LA';
$Order->BillingDetails->Address1 = 'Address example';
$Order->BillingDetails->Address2 = NULL;
$Order->BillingDetails->Zip = '70403-900';
$Order->BillingDetails->Email = 'customer@email.com';
$Order->BillingDetails->Phone = "556133127400";
$Order->BillingDetails->FiscalCode = "056.027.963-98";
$Order->BillingDetails->Company = NULL;

$Order->DeliveryDetails = NULL;

$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'CC';
$Order->PaymentDetails->Currency = 'brl';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->CustomerIP = '10.10.10.10';
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = true;
$Order->PaymentDetails->PaymentMethod->CardNumber = "4111111111111111";
$Order->PaymentDetails->PaymentMethod->CardType = 'visa';
$Order->PaymentDetails->PaymentMethod->ExpirationYear = '2019';
$Order->PaymentDetails->PaymentMethod->ExpirationMonth = '12';
$Order->PaymentDetails->PaymentMethod->HolderName = 'John';
$Order->PaymentDetails->PaymentMethod->CCID = '123';

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


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

$Order = new stdClass();
$Order->RefNo = NULL;
$Order->Currency = 'brl';
$Order->Country = 'BR';
$Order->Language = 'en';
$Order->CustomerIP = '91.220.121.21';
$Order->ExternalReference = NULL;
$Order->Source = NULL;
$Order->Affiliate = new stdClass();
$Order->Affiliate->AffiliateCode = 'Partner123'
$Order->Affiliate->AffiliateSource = 'MobilePlatform'
$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->FirstName = 'FirstName';
$Order->BillingDetails->LastName = 'LastName';
$Order->BillingDetails->CountryCode = 'BR';
$Order->BillingDetails->State = 'DF';
$Order->BillingDetails->City = 'LA';
$Order->BillingDetails->Address1 = 'Address example';
$Order->BillingDetails->Address2 = NULL;
$Order->BillingDetails->Zip = '70403-900';
$Order->BillingDetails->Email = 'customer@email.com';
$Order->BillingDetails->Phone = "556133127400";
$Order->BillingDetails->FiscalCode = "056.027.963-98";
$Order->BillingDetails->Company = NULL;
$Order->DeliveryDetails = NULL;
$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'CC';
$Order->PaymentDetails->Currency = 'brl';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->CustomerIP = '10.10.10.10';
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = true;
$Order->PaymentDetails->PaymentMethod->CardNumber = "4111111111111111";
$Order->PaymentDetails->PaymentMethod->InstallmentsNumber = 2;
$Order->PaymentDetails->PaymentMethod->CardType = 'visa';
$Order->PaymentDetails->PaymentMethod->ExpirationYear = '2019';
$Order->PaymentDetails->PaymentMethod->ExpirationMonth = '12';
$Order->PaymentDetails->PaymentMethod->HolderName = 'John';
$Order->PaymentDetails->PaymentMethod->CCID = '123';

$Order->AdditionalFields = NULL;
$Order->LocalTime = NULL;
$Order->GiftDetails = NULL;
try {
    $newOrder = $client->placeOrder($sessionID, $Order);
}
catch (SoapFault $e) {
    echo "newOrder: " . $e->getMessage();
    exit;
}
var_dump("newOrder", $newOrder);

Generate a trial link

Overview

You can attract new customers or increase your conversion rates by offering a free or extra charge trial for one of your products. Once the trial period expires, customers are automatically charged with the full value of the product, unless they choose to cancel.

Availability

Available to all 2Checkout accounts.

Generate a trial link

  1. Access the trial link generation options in the Checkout Links area, under Dashboard → Setup → Generate Links. Alternatively, you can navigate to this page through the View Edit product section of the Merchant Control Panel, select the product you want to generate the trial subscription for, go to the Information tab, and click on Get trial links.
  2. Click the Trial link radio button.

set free trial_1.png

3. Select the product for which you're creating the trial. 

set free trial_2.png

4. Choose the duration of the trial. Minimum 7 days. Default: 30 days. 

5. Configure the trial price. 0 by default, but you have the option of charging shoppers for the trials. To further modify pricing, you can use Additional pricing options. Input pricing options codes separated by commas. 2Checkout uses pricing options to calculate the costs of the automatic trial conversion.

set free trial_3.png

6. Scroll down to the bottom of the page and generate the link.

set free trial_4.png

7. Place the URL on call-to-actions on your store that offer access to trials.

CUSTOMIZE THE TRIAL 

  1. Trial period - Minimum 7 days. 
  2. Trial price - 2Checkout uses the custom prices and ignores the per-product pricing configuration. 
  3. Additional pricing options - Input pricing options codes separated by a comma. 2Checkout calculates the costs of the trial conversion based on the pricing options.
  4. Advanced options - In the advanced options screen, you can specify the default language and billing currency for the checkout process.
    • Default language - AUTO preselected. Choose a specific language for the ordering interface.
    • Billing currency - AUTO preselected. Choose a specific currency for the ordering process. 
  5. Additional options
    • Scroll down to the Additional options area, to choose the Order template displayed to your shoppers.
    • Enter a specific link source for the sales, and have the separate link identifier (SRC) to track every sale point generator (e.g. homepage, product page, etc.)
    • Provided that you defined a coupon code for the product you're generating the trial subscription for, insert it in the coupon code field. The appropriate discount is deducted from the full product price (and displayed in the shopping cart and/or checkout page).
    • Select a different hashing algorithm from the one preselected from Hashing algorithm subsection

SimpleProduct Object Structure

Parameters

Parameter Type/Descriptio
ProductId Int
  Unique Avangate Product ID.
ProductCode String
  Unique Product Code.
ProductName String
  Product Name
ProductType String
  Possible values: REGULAR or BUNDLE
ProductVersion String
  Product version. Can be NULL.
ProductImage String
  URLs to the product image uploaded into the Avangate platform. Can be NULL.
Price Double
  Product price calculated using the configuration of pricing options from the pricing list.
Currency String
  The ISO code of the currency set for the partner - ISO 4217.
PriceType String
  Possible values NET or GROSS.

 

Create fix discount

Overview

Use setPromotionDiscount via JSON-RPC API 4.0 to set a fixed promotion discount.

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 set the discount for.

promotionDiscount

Required(Object)

 

Type

Required (String)

 

 

Discount type:

  • PERCENT, use in combination with Value
  • FIXED, use in combination with Values and DefaultCurrency

 

Value / Values

Required (Int / Array of objects)

 

 

  • Value = Int, determines the discount percentage from 0 to 100
  • Values = Array of Value objects

 

 

Value

Required (Object)

 

 

 

Currency

Required (String)

 

 

 

 

Discount currency ISO code (ISO 4217).

 

 

 

Amount

Required (Int)

 

 

 

 

Discount amount in corresponding currency.

 

DefaultCurrency

Required (String)

 

 

Default discount currency ISO code (ISO 4217).

Response

Parameter Type/Description
promotionDiscount Object

Request

<?php

function callRPC($Request, $host, $Debug = true) {
    $curl = curl_init($host);
    curl_setopt($curl, CURLOPT_POST, 1);
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($curl, CURLOPT_VERBOSE, true);
    curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
    curl_setopt($curl, CURLOPT_SSLVERSION, 0);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Accept: application/json'));
    $RequestString = json_encode($Request);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $RequestString);
    if ($Debug) {
        $RequestString;
    }
    $ResponseString = curl_exec($curl);
    if ($Debug) {
        $ResponseString;
    }
    if (!empty($ResponseString)) {
        var_dump($ResponseString);
        $Response = json_decode($ResponseString);
        if (isset($Response->result)) {
            return $Response->result;
        }
        if (!is_null($Response->error)) {
            var_dump($Request->method, $Response->error);
        }
    } else {
        return null;
    }
}

$host = 'https://api.avangate.com/rpc/3.1/';

$merchantCode = "YOUR_MERCHANT_CODE"; // your account's merchant code available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$key = "YOUR_SECRET_KEY"; // your account's secret key available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php

$string = strlen($merchantCode) . $merchantCode . strlen(gmdate('Y-m-d H:i:s')) . gmdate('Y-m-d H:i:s');
$hash = hash_hmac('md5', $string, $key);

$i = 1;

$jsonRpcRequest = new stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method = 'login';
$jsonRpcRequest->params = array($merchantCode, gmdate('Y-m-d H:i:s'), $hash);
$jsonRpcRequest->id = $i++;

$sessionID = callRPC($jsonRpcRequest, $host);

// Promotion code assigned to the promotion you want to update
$promotionCode = '';

$promotionDiscount = new stdClass;
$promotionDiscount->Type = 'FIXED';
$promotionDiscount->DefaultCurrency = 'USD';

// Define the first discount object for a specific currency
$discount1 = new stdClass;
$discount1->Currency = 'USD';
$discount1->Amount = 22;

// Define the second discount object for a specific currency
$discount2 = new stdClass;
$discount2->Currency = 'EUR';
$discount2->Amount = 50;

$promotionDiscount->Values = [$discount1, $discount2];

$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'setPromotionDiscount',
'params' => array($sessionID, $promotionCode, $promotionDiscount)
);
var_dump (callRPC((Object)$jsonRpcRequest, $host));

Recurring billing charges

Overview

2Checkout calculates recurring charges for your subscription plans based on your pricing setups. You have the option to change recurring charges and modify the costs incurred by subscribers when renewing their subscriptions. 

Availability

All 2Checkout accounts. 

Requirements 

Create at least a product/subscription plan before defining pricing. 

Type 

  • Net: without taxes - 2Checkout applies extra taxes to the default price, such as Tax/VAT for US/EU orders during the ordering process. 
  • Gross: with taxes included - 2Checkout takes the taxes out of the costs paid by shoppers, without modifying the price during the ordering process. 

Currency 

When defining product prices you can:

  1. Configure the price only for the default currency - 2Checkout converts amounts in the cart based on the currency selected by/for shoppers. Currency rates are available here: https://secure.2checkout.com/content/...p?CURRENCY=USD

    This is an XML schema with the corresponding values for the other currencies compared to the one supplied in the CURRENCY query parameter.

  2. Specify prices in all currencies available for your account - 2Checkout serves shoppers the prices for all the currencies you set up without converting the amounts.

Setup

Navigate to the Pricing tab of a product/subscription plan and edit the desired pricing configuration. 

  • For products with dynamic pricing (with base price), look for the Renewal Price area.
  • For products with static pricing (without base price), look for the Renewal tab in the Prices area.

Options

There are three options to control recurring charges: 

Set renewal prices to equal the initial purchase prices (eStore only)

Use this setting when you want subscribers to continue paying the same amount for recurring charges that they paid initially when they first acquired your product. 

Create new renewal base prices

Set up prices in the default currency or for all the currencies available for your account. 2Checkout calculates recurring charges based on the renewal-based price modified by the costs defined for any extra options you configure with the exception of volume discounts.

Modify the renewal costs with discounts

Set up a renewal discount and assign it to impact manual or auto-recurring charges. 

Change recurring costs at the subscription level

Access this option by editing subscriptions. 

  1. Click the link on the price information for the Current billing amount in the Subscription info area. 
  2. Click edit.
  3. Enter a new billing amount. 
  4. Set it to impact:
  • All future billing cycles
  • Only a specific number of upcoming billing cycles

Custom recurring charges at the subscription level cause the 2Checkout system to completely ignore any sort of changes you make to product charges, including ro recurring/renewal costs. 

Retrieve subscription payment information

Overview

Use the getSubscriptionPaymentInformation method to retrieve information related to the payment made for a 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.
subscriptionReference Required (String)
  The reference of the subscription you want to retrieve payment information for.

Response

Parameters Type/Description

Type

String

 

Payment method type.

Currency

String

 

ISO code of the order currency.

PaymentMethod

Object

 

FirstDigits

String

 

 

First 4 digits of the card used on the order.

 

LastDigits

String

 

 

Last 4 digits of the card used on the order.

 

CardType

String

 

 

Type of card used on the order.

  ExpirationMonth String
    Card expiration month.
  ExpirationYear String
    Card expiration year.
  CardUpdated Boolean
    The card updated by our internal account updater.
  Authorize3DSUrl String
    URL address to which customers are redirected after the 3DS details get validated by the bank and the order is successfully authorized.

Response sample

{
    "Type": "CC",
    "Currency": "USD",
    "PaymentMethod": {
        "FirstDigits": "4111",
        "LastDigits": "1111",
        "ExpirationMonth": null,
        "ExpirationYear": null,
        "CardUpdated": false,
        "Authorize3DSUrl": null,
        "CardType": "Visa"
    }
}

 

Request

<?php
require ('PATH_TO_AUTH');

$subscriptionReference = "Subscription_Code";

try {
    $paymentInformation = $client->getSubscriptionPaymentInformation($sessionID, $subscriptionReference);
} catch (SoapFault $e) {
    echo  $e->getMessage();
}
var_dump($paymentInformation);

Retrieve subscription payment information

Overview

Use the getSubscriptionPaymentInformation method to retrieve information related to the payment made for a 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.
subscriptionReference Required (String)
  The reference of the subscription you want to retrieve payment information for.

Response

Parameters Type/Description

Type

String

 

Payment method type.

Currency

String

 

ISO code of the order currency.

PaymentMethod

Object

 

FirstDigits

String

 

 

First 4 digits of the card used on the order.

 

LastDigits

String

 

 

Last 4 digits of the card used on the order.

 

CardType

String

 

 

Type of card used on the order.

  ExpirationMonth String
    Card expiration month.
  ExpirationYear String
    Card expiration year.
  CardUpdated Boolean
    The card updated by our internal account updater.
  Authorize3DSUrl String
    URL address to which customers are redirected after the 3DS details get validated by the bank and the order is successfully authorized.

Response sample

{
    "Type": "CC",
    "Currency": "USD",
    "PaymentMethod": {
        "FirstDigits": "4111",
        "LastDigits": "1111",
        "ExpirationMonth": null,
        "ExpirationYear": null,
        "CardUpdated": false,
        "Authorize3DSUrl": null,
        "CardType": "Visa"
    }
}

 

Request

<?php
require ('PATH_TO_AUTH');

$subscriptionReference = "Subscription_Code";

$jsonRpcRequest = new stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method = 'getSubscriptionPaymentInformation';
$jsonRpcRequest->params = array($sessionID, $subscriptionReference);
$jsonRpcRequest->id = $i++;

$paymentInformation = callRPC($jsonRpcRequest, $host);
var_dump($paymentInformation);

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