Overview

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

Use the copyPaymentInfo method.

Requirements

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

Availability

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

How does this method work?

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

Parameters

Response

Request

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

function hmac($key, $data)
{
    $b = 64; // byte length for md5
    if (strlen($key) > $b) {
        $key = pack("H*", md5($key));
    }
    
    $key    = str_pad($key, $b, chr(0x00));
    $ipad   = str_pad('', $b, chr(0x36));
    $opad   = str_pad('', $b, chr(0x5c));
    $k_ipad = $key ^ $ipad;
    $k_opad = $key ^ $opad;
    return md5($k_opad . pack("H*", md5($k_ipad . $data)));
}
$merchantCode = "YOUR_MERCHANT_CODE";// your account's merchant code available in the 'System settings' area of the cPanel: https://secure.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
$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;
}
$TargetSubscription = '559338F092';
$SourceSubscription = '9F4154733C';
try {
    $payInfo = $client->copyPaymentInfo($sessionID, $TargetSubscription, $SourceSubscription);
}
catch (SoapFault $e) {
    echo "payInfo: " . $e->getMessage();
    exit;
}
var_dump("payInfo", $payInfo);

Overview

Use the getOrder method to retrieve details on a specific order placed with dynamic product information, or catalog products, using the unique, system-generated reference.

Parameters

Response

Request 

<?php

require ('PATH_TO_AUTH');

$orderReference = 'YOUR_ORDER_REFERENCE';

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

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

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
 
 
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/4.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 = '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;

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

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

Overview

Renew a subscription and collect recurring revenue using the 2Checkout Subscription Reference. You can renew subscriptions for both catalog and dynamic products. 

Requirements

To place a renewal order, you need to provide a valid subscription reference number.

Payment methods

You can place renewal orders using the following payment methods:

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

Use the PaymentDetails object to change the payment method used in the ordering process.

Parameters

Response

 

Request

<?php

require ('PATH_TO_AUTH');

$Order = new stdClass();
$Order->Currency = 'USD';
$Order->Language = "EN";
$Order->Country = 'US';
$Order->CustomerIP = '91.220.121.21';
$Order->Source = "sourceAPI.net";
$Order->LocalTime = date('Y-m-d H:i:s');
$Order->Items = array();

/**/
$Order->Items[0]->RenewalInformation = new stdClass();
$Order->Items[0]->RenewalInformation->SubscriptionReference = 'A8C5671BFE'; //subscription used in the renewal process
$Order->Items[0]->Price = new stdClass();
$Order->Items[0]->Price->Type = 'CUSTOM';
$Order->Items[0]->Price->Amount = '10';
$Order->Items[0]->PriceOptions = array('uniqscale1=4');//

$Order->MachineId = "MachineID";

$Order->BillingDetails = new stdClass();
$Order->BillingDetails->Address1 = 'Bil1ing address';
$Order->BillingDetails->Address2 = 'Billing address 2';
$Order->BillingDetails->City = 'Billing City';
$Order->BillingDetails->State = 'Billing State';
$Order->BillingDetails->CountryCode = 'US';
$Order->BillingDetails->Phone = 1231232123;
$Order->BillingDetails->Email = 'customer_details@test.com';
$Order->BillingDetails->FirstName = 'First';
$Order->BillingDetails->LastName = 'Customer';
$Order->BillingDetails->Company = 'Billing Company';
$Order->BillingDetails->Zip = '55104';

$Order->DeliveryDetails = new stdClass();
$Order->DeliveryDetails->Address1 = 'Bil1ing address';
$Order->DeliveryDetails->Address2 = 'Billing address 2';
$Order->DeliveryDetails->City = 'Billing City';
$Order->DeliveryDetails->State = 'Billing State';
$Order->DeliveryDetails->CountryCode = 'US';
$Order->DeliveryDetails->Phone = '12345';
$Order->DeliveryDetails->Email = 'customer_details@test.com';
$Order->DeliveryDetails->FirstName = 'First';
$Order->DeliveryDetails->LastName = 'Customer';
$Order->DeliveryDetails->Zip = "55104";

$Order->PaymentDetails = new stdClass();
$Order->PaymentDetails->Type = "CC";
$Order->PaymentDetails->Currency = $currency;

$Order->PaymentDetails->PaymentMethod = new stdClass();
/**/
$Order->PaymentDetails->PaymentMethod->CardNumber = "4111111111111111";
$Order->PaymentDetails->PaymentMethod->CardType = "VISA";
$Order->PaymentDetails->PaymentMethod->ExpirationYear = "2019";
$Order->PaymentDetails->PaymentMethod->ExpirationMonth = "12";
$Order->PaymentDetails->PaymentMethod->CCID = "123";
$Order->PaymentDetails->PaymentMethod->HolderName = "John Doe";
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = TRUE;
$Order->PaymentDetails->PaymentMethod->HolderNameTime = 1;
$Order->PaymentDetails->PaymentMethod->CardNumberTime = 1;
/**/

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

var_dump("newOrder", $Order);

This is a summary of the objects/classes and methods available.

Overview

Use the updatePromotionCoupon method to add single or multiple coupons to a promotion.

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

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

// Promotion code corresponding to the promotion you want to add coupons to
$promotionCode = '';

// 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'];

try {
    $updatedPromotion = $client->addPromotionCoupon ($sessionID, $promotionCode, $promotionCoupon);
}

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

var_dump("UpdatedPromotion", $updatedPromotion);

Overview

In 2Checkout's legacy checkout system, we have always supported the demo parameter to test the checkout process without actually creating an order. In 2014, we introduced our sandbox environment to provide merchants with a way to completely test the order lifecycle through their API and INS integration.

Over the past couple of years, we have been working to integrate the legacy platform with our new platform's test ordering system so that our merchants can fully test their integration without the need for a separate sandbox account. Since there is no longer a need for it, we are decommissioning the legacy sandbox environment and ask that all remaining sandbox users transition their testing to our test ordering system.

If you are not using 2Checkout's legacy sandbox platform there is no need to read further. We are not making any changes to our production environment.

Demo/Test Ordering System

To place a test order with 2Checkout's legacy checkout system using your production account, you just need to pass the demo parameter with a value of `Y` as we have always supported.

Example

https://www.2checkout.com/checkout/purchase?sid=your-seller-id&mode=2CO&li_0_name=test&li_0_price=1.00&demo=Y
Form:
<form action='https://www.2checkout.com/checkout/purchase' method='post'>
<input type='hidden' name='sid' value='your-seller-id' />
<input type='hidden' name='mode' value='2CO' />
<input type='hidden' name='li_0_name' value='test' />
<input type='hidden' name='li_0_price' value='1.00' />
<input type='hidden' name='demo' value='Y' />
<input name='submit' type='submit' value='Checkout' />
</form>

Example

You can then use the data detailed in this article to test each use case.

To place a test order with 2Checkout's legacy Payment API, just add the demo property to the root of your JSON payload with a value of TRUE.

https://www.2checkout.com/checkout/api/1/your-seller-id/rs/authService

{
    "sellerId": "your-seller-id",
    "privateKey": "your-private-key",
    "merchantOrderId": "123",
    "token": "customer-client-side-token",
    "currency": "USD",
    "total": "0.01",
    "billingAddr": {
        "name": "John Doe",
        "addrLine1": "123 Test St",
        "city": "Columbus",
        "state": "Ohio",
        "zipCode": "43123",
        "country": "USA",
        "email": "example@2co.com",
        "phoneNumber": "5555555555"
    },
    "demo": true
}

Some legacy accounts may have demo mode disabled. If you are having any problems placing demo orders, contact 2Checkout for assistance.

Test Order Management

To locate your Test orders, log in to your Merchant Control Panel and navigate to Orders & Customers → Order Search, and use the 'Test orders' filter, as shown in this image.

Test orders can be refunded or re-billed (recurring sales) and will send all necessary INS messages just like production orders. More information on the 2Checkout test ordering system can be found in our Knowledge Center.
 

Recommended resources

Overview

Use this object to add/create and update/edit pricing configurations for your account. You can assign one or multiple price option groups to pricing configurations.

You identify a pricing configuration using its unique identifier: Code.

Parameters

Overview

Create Special price promotions and define the final order price your customers will pay considering any pricing options or volume discounts configured on the product. Use Special promotions to have full control over the discounted price displayed to your customers.

Benefits

• Increase average order value through better incentives
• Improve customer satisfaction by offering the products at the right price
• Extended control over the prices displayed throughout the entire buying experience

Availability

Special price promotions are enabled by default on all 2Checkout accounts.

Limitations

Special price promotions are available through the ConvertPlus ordering flow. API support for creating Special price promotions is not available at this moment.

Once a product is added to a Special price promotion, you cannot update its price, or its volume discounts setup. To update the pricing configuration of a product that is part of an active campaign, remove the product from the promotion and then update its price.

Special price promotions are not available in the Affiliates Network.

How it works

Special price promotions allow you to control the final price paid by the customers, taking into account product pricing configurations/options or volume discounts that may be applied to the order.

Gross / Net product price

If 2Checkout handles the management of taxes on your behalf, then you are able to create products with gross price type (the product price includes the tax/VAT to be collected from the customers). When adding products with gross price type in a Special price promotion, you are able to control the final order price paid by customers including taxes. 

Example: Product 2Checkout Monthly Subscription costs $19.99 (including taxes). Let's say a 19% VAT is applied based on customer location. If no promotion is applied, the cart price is:

Now let's use a Special price promotion to define a final order price of $14.99 for product 2Checkout Monthly Subscription. The Special price promotion takes into account the 19% VAT applied to the order and the total order price displayed is $14.99 (including taxes):

Pricing options / Volume discounts

When creating a Special price promotion, you are able to define the final price your customers will pay for each pricing configuration configured. A price matrix is available for defining the order price based on the volume discounts/pricing options set on the product.

The values from the fields left blank are auto-converted by 2Checkout based on exchanged rates from the European Central Bank, from the previous day.

Adding a Special price promotion

To create a Special price promotion, follow the below steps:

1. Go to Marketing Tools > Promotions.
2. Click on the Special price promotions tab.
3. Click Add Special price promotion.
4. Give the promotion a suggestive title and description. Shoppers can see the promotion title during purchase.
5. Select when you want the promotion to run. You can limit promotions to a specific time interval or let them run indefinitely. To start a promotion as soon as you mark it Active, leave the start date empty. If you don't set the end date, the promotion will stop when the maximum number of orders has been reached or will continue to run if the maximum number of orders is unlimited.
6. Choose the coupon/voucher type:
   
   • Single - one voucher to impact multiple orders;
   • Multiple - individual and unique, pre-order vouchers.
7. Choose whether to restrict the promotion to a number of orders, or apply it for all orders. This option is only available for single coupons.
8. Choose whether or not to limit the promotion based on the product quantity. Any product quantity above this limit will be sold at full price.
9. Set the default currency of the promotion. 
10. Fill in the promotion coupon/voucher code. The maximum length of a coupon code is 255 alphanumeric characters.
    
    • Single: enter the coupon values manually
    • Multiple: either add the values manually one coupon per line or use the coupon generator available in the Control Panel to generate 5, 10, 20, 30, 50 or 100 vouchers at a time and either append them to an existing list or replace existing items. The generator creates random vouchers that resemble this: D8C10E32. 2Checkout recommends limiting the number of coupon codes to a maximum of 25000.
11. Choose whether or not to apply discounts automatically. Only available for single coupons. This option applies discounts to all selected products in all orders, without the need for shoppers to enter the coupon manually.
12. Apply promotion to recurring charges. You can apply it to none, to one recurring charge, to all or to a specific number of recurring charges after which the renewal price is recalculated.
13. Select the products to be included in the promotion.
14. Select the pricing configurations for which the promotion should apply.
15. Add the special promotional prices that should be displayed to end-users, when the promotion is active in cart. Filling in the price for the default currency is mandatory. Use the price matrix to define the price for each pricing option/volume discounts threshold active on the product. Set the amount for all currencies, or leave them empty and let 2Checkout convert the amounts automatically.