Overview

Use the updatePriceOptionGroup method to update/edit an existing price options group you configured for your account.

• Price options intervals cannot overlap.

Parameters

You cannot update the

• Code of the price options group.

Response

bool(true)

Request

<?php

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


function hmac($key, $data)
{
    $b = 64; // byte length for md5
    if (strlen($key) > $b) {
        $key = pack("H*", md5($key));
    }
    
    $key    = str_pad($key, $b, chr(0x00));
    $ipad   = str_pad('', $b, chr(0x36));
    $opad   = str_pad('', $b, chr(0x5c));
    $k_ipad = $key ^ $ipad;
    $k_opad = $key ^ $opad;
    return md5($k_opad . pack("H*", md5($k_ipad . $data)));
}

$merchantCode = "YOURCODE123"; //your account's merchant code available in the 'System settings' area of the cPanel: https://secure.2checkout.com/cpanel/account_settings.php
$key          = "SECRET_KEY"; //your account's secret key available in the 'System settings' area of the cPanel: https://secure.2checkout.com/cpanel/account_settings.php
$now          = gmdate('Y-m-d H:i:s'); //date_default_timezone_set('UTC')

$string = strlen($merchantCode) . $merchantCode . strlen($now) . $now;
$hash   = hmac($key, $string);

try {
    $sessionID = $client->login($merchantCode, $now, $hash);
}

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

$SearchOptions       = new stdClass();
$SearchOptions->Name = 'New Users from API';

$SearchOptions->Types = array(
    'INTERVAL',
    'RADIO',
    'COMBO'
); //RADIO, CHECKBOX, INTERVAL, COMBO, INTERVAL

$SearchOptions->Limit = 10;
$SearchOptions->Page  = 1;

try {
    $existentPriceOptions = $client->searchPriceOptionGroups($sessionID, $SearchOptions);
}

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

var_dump("existentPriceOptionst", $existentPriceOptions);

$existentPriceOptions[0]->Translations[0]->Name     = 'New Users from API_1';
$existentPriceOptions[0]->Translations[0]->Language = 'EN';
$existentPriceOptions[0]->Required                  = FALSE;

echo "\n";

var_dump($existentPriceOptions);


try {
    $NewPriceOptionGroup = $client->updatePriceOptionGroup($sessionID, $existentPriceOptions[0]);
}

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

var_dump("NewPriceOptionGroup", $NewPriceOptionGroup);


?>

Overview

Use the getPricingConfigurations method to extract information on the pricing configurations you set for a product.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$productCode = 'YOUR_PRODUCT_CODE';

try {
    $ProductPricingConfigurations = $client->getPricingConfigurations($sessionID, $productCode);
}

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

var_dump("Pricing Configurations", $ProductPricingConfigurations);


?>

Overview

Use the updateSubscriptionEndUser method to update the details of a subscription’s end user. This method changes per-subscription end-user data and not customer details.

Parameters

Response

Request

<?php
 
require('PATH_TO_AUTH');

$subscriptionReference = '8F749B63E7';
$EndUser = new stdClass ();
$EndUser->Address1 = 'Address line 1';
$EndUser->Address2 = 'Address line 2';
$EndUser->City = 'LA';
$EndUser->Company = 'Company Name';
$EndUser->CountryCode = "US";
$EndUser->Email = 'customerAPI@avangate.com';
$EndUser->FirstName = 'New Customer 2.0';
$EndUser->Language = 'en';
$EndUser->LastName = 'Avangate';
$EndUser->Phone = '1234567890';
$EndUser->State = 'California';
$EndUser->Zip = '90210';
$EndUser->Fax = null;

try {
    $newEndUser = $client->updateSubscriptionEndUser($sessionID, $subscriptionreference, $EndUser);
}
catch (SoapFault $e) {
    echo "newEndUser: " . $e->getMessage();
    exit;
}
var_dump("newEndUser", $newEndUser);

Overview

Use the setSubscriptionGracePeriod method to set a custom grace period for an Active or Past Due subscription. This method changes per-subscription end user data and not customer details.

Parameters

Response

Request

<?php
 
 
function callRPC($Request, $hostUrl, $Debug = true) {
    $curl = curl_init($hostUrl);
    curl_setopt($curl, CURLOPT_POST, 1);
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
    curl_setopt($curl, CURLOPT_SSLVERSION, 0);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Accept: application/json'));
    $RequestString = json_encode($Request);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $RequestString);
 
 
    if ($Debug) {
        $RequestString;
    }
    $ResponseString = curl_exec($curl);
    if ($Debug) {
        $ResponseString;
    }
 
    if (!empty($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.0/';
 
$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; // counter for api calls
// call login
$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);
 
var_dump($sessionID);
$subscriptionReference = 'C9EB347A47';
$gracePeriod = 14;

$jsonRpcRequest = array (
'method' => 'setSubscriptionGracePeriod',
'params' => array($sessionID, $subscriptionReference, $gracePeriod),
'id' => $i++,
'jsonrpc' => '2.0');

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

Overview

Dunning is the process of methodically communicating with customers to ensure the collection of accounts receivable. Use dunning management to reduce customer churn and recover lost revenue from failed authorizations. 2Checkout notifies customers via email about failed renewals, helping them update their payment information in myAccount.

Availability

Dunning management for hard declines is available as part of the 2Recover add-on. To enable it on your account, contact 2Checkout.

Requirements

Once 2Checkout enables dunning management for your account, you need to activate dunning management for hard declines from the 2Checkout Merchant Control Panel.

How does dunning management for hard declines work?

1. The 2Checkout system attempts to automatically authorize a recurring charge for a subscription according to its renewal deadline.
2. The authorization process fails with a hard decline, a permanent error from the payment processor/gateway indicating that any further authorizations would also be unsuccessful. Reasons include:
   
   • Stolen or lost cards.
   • Invalid credit card data.
3. 2Checkout sends a single dunning management email immediately after each failed automatic authorization attempt made for subscriptions with the auto-renewal system enabled.
4. Shoppers can access myAccount to update the payment information by following the link in the email.
5. As soon as the shoppers update their payment information, 2Checkout automatically attempts to authorize the payment and renew the subscription.

The renewal link works only for subscriptions that are either active or in their grace period. For subscriptions with no grace period settings, shoppers can only update their payment information and retry the payment for a maximum of 3 (three) hours after 2Checkout has made the recurring charge attempt that resulted in a hard decline.

How to activate dunning management

1. Log into your Merchant Control Panel account.
2. Go to the Marketing tools → Lead management and click on the Manage your leads tab, as shown in the image below.
3. Click the Edit button corresponding to Unfinished payment. This will open the Dunning emails section.
4. Scroll down to the Dunning emails section and click Activate.

Overview

Use the getContentsWithPreFill method to get info on all the products added to cart by the shopper in the current session, while pre-filling the customer information based on the subscription reference.

Products added in cart can be either defined in your catalog, or created with dynamic information.    

Parameters

Response

Request

<?php

require('PATH_TO_AUTH');

$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'; // you can also send products with dynamic information
$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]->RenewalInformation = new stdClass();
$Order->Items[0]->RenewalInformation->SubscriptionReference = '63A6FE10AD'; // subscription based on which the customer information is pre-filled

$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'CC';
$Order->PaymentDetails->Currency = 'usd';
$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;

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

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

Overview

Use the getSKUCodeByDetails method to retrieve an SKU based on its included details.

Parameters

Request Example

<?php
require ('PATH_TO_AUTH');

$skuDetailsObject = new \stdClass();
$skuDetailsObject->PricingConfigurationCode = 'YOUR_CODE';
$skuDetailsObject->Currency = 'USD';
$skuDetailsObject->PurchaseType = 'NEW_PRODUCT';
$skuDetailsObject->PriceOptions = ['A'];
$skuDetailsObject->Quantity = 1;

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

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

Response Example

{SKUCode} // eg: SKU-EUR-1-10-N-A

Overview

Place an order with on the fly pricing using catalog products defined in your Control Panel. Set the Items->Price->Type parameter to CUSTOM, while adding the dynamic price to the Items->Price->Amount parameter.

Payment methods

You can place orders with dynamic pricing using the following payment methods:

• Credit cards
• PayPal
• WeChat Pay
• iDEAL
• Purchase Order

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$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->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]->CrossSell = NULL;
$Order->Items[0]->Trial = false;
$Order->Items[0]->AdditionalFields = NULL;
$Order->Items[0]->SubscriptionStartDate = NULL; //If empty or null, subscriptions become active when purchase is made.


$Order->Items[0]->Price = new stdClass();
$Order->Items[0]->Price->Amount = 11; // set the price of the order
$Order->Items[0]->Price->AmountType = 'NET';
$Order->Items[0]->Price->Type = 'CUSTOM'; // must be sent as CUSTOM in order to use dynamic pricing

$Order->BillingDetails = new stdClass();
$Order->BillingDetails->FirstName = 'FirstName';
$Order->BillingDetails->LastName = 'LastName';
$Order->BillingDetails->CountryCode = 'us';
$Order->BillingDetails->State = 'California';
$Order->BillingDetails->City = 'LA';
$Order->BillingDetails->Address1 = 'Address example';
$Order->BillingDetails->Address2 = NULL;
$Order->BillingDetails->Zip = '90210';
$Order->BillingDetails->Email = 'email@2checkout.com';
$Order->BillingDetails->Phone = NULL;
$Order->BillingDetails->Company = NULL;
$Order->DeliveryDetails = NULL;

$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'CC'; // you can also use TEST, PAYPAL, PURCHASEORDER, WE_CHAT_PAY, IDEAL, CHECK. The flow and requirements are different for each payment method.
$Order->PaymentDetails->Currency = 'usd';
$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;

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

echo "<pre>";

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

Overview

Update per-subscription credit and debit card details for your customers to support the automatic billing process for subscriptions and ensure no usage interruptions and their inherent impact. Note: PCI compliance is strongly recommended.

2Checkout enjoys Level 1 PCI DSS Certification, a statement of our continued commitment to ensuring the security of customer data including through the use of encryption, network and traffic monitoring, and strict user access privileges.

Benefits

• Ensure continuous automatic billing for ongoing subscriptions despite issues such as card expiration.
• Enable the purchase of subscriptions using PayPal and Direct Debit and then switching the payment method to credit/debit cards.
• Better control over customer credit/debit card information.
• Simplified customer payment data update process which no longer needs to involve myAccount.

Requirements

Compliance with the PCI Data Security Standard (PCI DSS) when dealing with credit card information is strongly recommended before using this feature.

Subscription pricing user rights

The availability of the Update credit card feature is governed by user rights. To enable access to this functionality for users of your account, go to Account settings, and select Manage user access. Click on the Roles associated with specific accounts, and make sure that the Subscription pricing checkbox is checked.

Availability

Auto-renewable subscriptions: Payment data can be updated only for subscriptions with the auto-renewal system enabled. This is valid for active, trial and expired subscriptions. Imported subscriptions that feature credit/debit card data can also have their cardholder details updated.

Update credit card capabilities are not available for:

• Manually renewable subscriptions
• Lifetime subscriptions
• Disabled subscriptions

Supported credit/debit cards

Supported credit/debit cards must be enabled for your account and must be approved to perform transactions in at least one of the currencies available for your account.

Examples of supported cards: VISA, VISA Electron, MasterCard, Maestro and AMEX (American Express).

Limitations

While you can provide new credit/debit card details to update/replace the initial payment method used, including credit/debit cards, PayPal and Direct Debit, you won't be able to switch auto-renewal transactions from a credit/debit card to PayPal or Direct Debit.

How to update credit card details

1. Go to Orders & customers -> Subscriptions.
2. Use the search functionality available in this area to identify the subscription for which you want the credit card details updated
3. Click View. 
4. On the next screen, click Update credit card.
5. Enter the new payment details associated with the customer's credit/debit card.
6. Click Update.

The 2Checkout system will check the validity of the credit/debit card and will update the customer's payment information accordingly. Pre-authorization is performed for the credit/debit cards you're updating. The pre-authorization involves a temporary hold of a certain sum of money to ensure the validity of the payment method. This is not a charge and your customer won't pay any money for the pre-authorization.

For invalid credit/debit cards, as well as in scenarios involving incorrect details, the system will fail to refresh existing card info.

Following a successful update, the Subscription info area will be updated with the details of the new valid credit/debit card. The next transaction scheduled for the subscription with the updated payment details will be done using the new credit/debit card.

The last four digits of the card number are immediately available when viewing a particular subscription for which the customer is using a credit or debit card.

All successful payment details changes are reflected in the Subscription history area, both the ones made by you or your customers. Shoppers can also update the payment details for the subscriptions they acquired from you through 2Checkout by logging into myAccount.

Overview

Retrieve information about a subscription's history.

Use the API methods displayed below to extend or renew a subscription.