Skip to main content

Add coupon

Overview

Use the addPromotionCoupon method to add single or multiple coupons to a promotion. Using the addPromotionCoupon for a promotion that is set to apply automatically will change the promotion type to the manual flow, where customers are required to enter the coupon code to receive the 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 add coupons to.

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

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

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

Set SKU codes

Overview

Use the setSku method to create a valid combination of elements (code) for a specific product. 

In case there is an active SKU schema available for that Product Code and Pricing Configuration Code, when setting new SKUs the entire existing schema will be overwritten with the new values. The same validations that are applied to the CSV file import in the Merchant Control Panel are applicable to the API as well.

Product SKUs created via API will also be available in the Merchant Control Panel for manual update (Dashboard → Setup → Products → Edit product → Information → SKU Manager (SKU list Tab).

Request Example

<?php

require ('PATH_TO_AUTH');

$product = new \stdClass();
$product->ProductCode = "6B3CB17DDA_COPY1";

$skuPricingOption1 = new \stdClass();
$skuPricingOption1->Code = "E684EC99B0";

$skuDetail1 = new \stdClass();
$skuDetail1->ProductSKU = "Product_Test_SKU_001022";
$skuDetail1->Currency = "USD";
$skuDetail1->FromQty = 1;
$skuDetail1->ToQty = 3
$skuDetail1->PurchaseType = "NEW_PRODUCT";

$skuGroup = new \stdClass();
$skuGroup->GroupCode = "GRUP_1";

$skuGroupOption = new \stdClass();
$skuGroupOption->Name = "option name 1";
$skuGroupOption->Value = "option_code_1";

$skuGroup->Options = [$skuGroupOption];

$skuDetail1->Groups = [$skuGroup];
$skuDetail1->Options = "eJwBLADT/6G10uOW07exk6mNk7KvrpaSc4l1lbXToqi5sriTcbOXseWu3ZGrlXauuZOojh8cww==";

$skuDetail2 = new \stdClass();
$skuDetail2->ProductSKU = "Product_Test_SKU_001023";
$skuDetail2->Currency = "USD";
$skuDetail2->FromQty = 1;
$skuDetail2->ToQty = 3
$skuDetail2->PurchaseType = "NEW_PRODUCT";

$skuGroup = new \stdClass();
$skuGroup->GroupCode = "GRUP_1";

$skuGroupOption = new \stdClass();
$skuGroupOption->Name = "option name 2";
$skuGroupOption->Value = "option_code_2";

$skuGroup->Options = [$skuGroupOption];

$skuDetail2->Groups = [$skuGroup];
$skuDetail2->Options = "eJwBLADT/6G10uOW07exk6mNk7KvrpaSc4l1lbXToqi5sriTcbOXseWu3ZGrmXauuZOojjccxw==";

$skuPricingOption1->Details = [$skuDetail1, $skuDetail2];

$product->SkuPricingOptions = [$skuPricingOption1];


try {
    $skuOutput = $client->setSku($sessionID, [$product]);
} catch (SoapFault $e) {
    echo "setSku: " . $e->getMessage();
    exit;
}

var_dump("setSku", $skuOutput);



Response Example

class stdClass#201 (2) {
  public $Results =>
  class stdClass#202 (1) {
    public $0 =>
    class stdClass#203 (2) {
      public $ProductCode =>
      string(16) "6B3CB17DDA_COPY1"
      public $PricingConfigurationCode =>
      string(10) "E684EC99B0"
    }
  }
  public $Errors =>
  class stdClass#204 (0) {
  }
}

 

Copy payment info

Overview

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

Use the copyPaymentInfo method.

Requirements

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

Availability

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

How does this method work?

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

Parameters

Parameters

Type/Description

sessionID

Required (string)

 

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

TargetSubscriptionReference

Required (string)

 

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

SubscriptionReference

Required (string)

 

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

Response

Boolean

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

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

Retrieve an order

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

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.

orderReference

Required (string)

 

Order reference number of an older order, which is already approved/paid.

Response

Parameters Type/Description

Order information

Object (orders with catalog products)

Order information Object (orders with dynamic product information)
WSOrder String

 

   Only orders with STATUS = COMPLETE are returned when placing a getOrder API call.

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

 

 

Subscription end user update

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

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)

 

Unique, system-generated subscription identifier.

EndUser

Required (Object)

  Use this object to update end user information.

Response

Parameter Type/Description

Boolean

true or false depending on whether the changes were successful or not.

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

Place a renewal order

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

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.

To place an order with PayPal rather than PayPal Express, use PAYPAL as the type of the PaymentDetails object and send the shopper email and a return URL as part of the PaymentMethod object. See code sample. 

SubscriptionReference

Required (String)

2Checkout generated subscription reference number. E.q. A8C5671BFE.

Response

Edit section 
Parameters Type/Description

Order information

Object

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);
Edit section
 

API Reference

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

Update coupon

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

Parameter Type/Description

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

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

Transition Guide for 2CO Sandbox

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 cPanel.png

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

 

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