Retrieve all configurations
Overview
Use the getPricingConfigurations method to extract information on the pricing configurations you set for a product.
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. |
ProductCode |
Required (string) |
|
The editable code that you control at product-level, not the unique, system-generated product ID. |
Response
Parameters | Type/Description |
---|---|
Array of objects |
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);
?>
Update price options
Overview
Use the updatePriceOptionGroup method to update/edit an existing price options group you configured for your account.
- Price options intervals cannot overlap.
Parameters
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. |
Required (object) |
|
|
Use this object to update/edit a new price option group for your account. |
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);
?>
Update subscription payment information
Overview
Use the updateSubscriptionPaymentInformation method to update the credit card information related to the payment to be made for a subscription. To be able to do this, you need to generate a payment token using the credit card information via the 2Pay.js library, and then use this token in the request of the method as indicated below.
Request Parameters
Parameter Name | Type | Required/Optional | Description |
---|---|---|---|
sessionID |
String |
Required |
The 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 |
String |
Required |
The reference of the subscription for which you want to retrieve the payment information. |
paymentInformation |
Object |
Required |
The payment information object, details below: |
PaymentDetails |
Object |
Required |
The payment details object, details below: |
Type |
String |
Required |
The payment details type. Restricted to EES_TOKEN_PAYMENT for now. |
PaymentMethod |
Object |
Required |
The payment method object, details below: |
EesToken |
String |
Required |
The 2Pay token obtained by integrating the 2Pay.js library. |
Vendor3DSReturnURL | String | Required | URL address to which customers are redirected after the 3DS details get validated by the bank and the order is successfully authorized. |
Vendor3DSCancelURL | String | Required | URL address to which customers are redirected after the 3DS details get validated by the bank and the order is successfully authorized. |
Request Example
<?php
declare(strict_types=1);
class Configuration
{
public const MERCHANT_CODE = '';
public const MERCHANT_KEY = '';
public const URL = 'http://api.2checkout.com/soap/6.0';
public const ACTION = 'updateSubscriptionPaymentInformation';
public const ADDITIONAL_OPTIONS = null;
public const SUBSCRIPTION_REF = 'YC9XXMGOYO';
//array or JSON
public const PAYLOAD = <<<JSON
{
"PaymentDetails": {
"Type": "EES_TOKEN_PAYMENT",
"PaymentMethod": {
"EesToken": "f6347256-bbbb-45a8-be61-e21fe1725f47",
"Vendor3DSReturnURL": "www.3dsReturnURL.com",
"Vendor3DSCancelURL": "www.3dsCancelURL.com"
}
}
}
JSON;
}
class Client
{
public function call(
string $url = Configuration::URL,
$payload = Configuration::PAYLOAD,
string $action = Configuration::ACTION
): ?object
{
if (is_array($payload)) {
$payload = json_encode($payload);
}
if (!empty($payload)) {
// SoapClient works with objects(StdClass)
$payload = json_decode($payload);
}
$soapClient = $this->getClient($url);
$sessionId = $this->getSession($soapClient);
$args = array_filter([$sessionId, Configuration::SUBSCRIPTION_REF, $payload]);
return $soapClient->$action(...$args);
}
public function getClient(string $url): SoapClient
{
return new SoapClient(
$url . '?wsdl',
[
'location' => $url,
'cache_wsdl' => WSDL_CACHE_NONE,
]
);
}
public function getSession(SoapClient $client)
{
$date = gmdate('Y-m-d H:i:s');
$merchantCode = Configuration::MERCHANT_CODE;
$key = Configuration::MERCHANT_KEY;
$string = strlen($merchantCode) . $merchantCode . strlen($date) . $date;
$hash = hash_hmac('md5', $string, $key);
// $client->__setCookie('XDEBUG_SESSION', 'PHPSTORM');
return $client->login($merchantCode, $date, $hash);
}
}
try {
$client = new Client();
var_dump($client->call());
} catch (Exception $ex) {
var_dump($ex);
}
Response
The method responds with Boolean True when the payment information update was successfully performed.
Otherwise, in case of validation or access rights failures, it returns the usual error response with specific messages indicating the cause of the failure.
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV=http://schemas.xmlsoap.org/soap/envelope/ xmlns:ns1="urn:order" xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:SOAP-ENC=http://schemas.xmlsoap.org/soap/encoding/ SOAP-ENV:encodingStyle=http://schemas.xmlsoap.org/soap/encoding/>
<SOAP-ENV:Body>
<ns1:updateSubscriptionPaymentInformationResponse>
<updateSubscriptionPaymentInformationReturn xsi:type="ns1:PaymentDetailsCard">
<CardType xsi:type="xsd:string">visa</CardType>
<FirstDigits xsi:type="xsd:string">4012</FirstDigits>
<LastDigits xsi:type="xsd:string">9936</LastDigits>
<Authorize3DSUrl xsi:type="xsd:string">https://...</Authorize3DSUrl>
</updateSubscriptionPaymentInformationReturn>
</ns1:updateSubscriptionPaymentInformationResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Search promotions
Overview
Use the searchPromotions method to extract information on promotions you set up for your account.
Parameters
Parameters | Type/Description |
---|---|
sessionID |
Required (string) |
|
Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect. The sessionID expires in 10 minutes. |
Types |
StringArray |
|
Discount type:
|
Channel |
String |
|
Channel:
|
ProductCode |
String |
|
Unique code that you set for each of your products. |
Pagination |
Object. Details below. |
Limit |
Int |
|
Set a limit for the number of results that should be returned. |
Page |
Int |
|
Set the number of pages that should be returned. |
Response
Parameters | Type/Description |
---|---|
Promotion | Array of objects |
Request
<?php
require ('PATH_TO_AUTH');
$searchOptions = new stdClass();
$searchOptions->Types = array ('REGULAR');
$searchOptions->Channel = 'ECOMMERCE';
$searchOptions->ProductCode = 'Product_Code_1';
$searchOptions->Enabled = TRUE;
$searchOptions->Limit = 99;
$searchOptions->Page = 1;
try {
$Discounts = $client->searchPromotions($sessionID, $SearchOptions);
}
catch (SoapFault $e) {
echo "Discounts: " . $e->getMessage();
exit;
}
var_dump("Promotions", $Discounts);
Retrieve a customer
Overview
Use the getCustomerInformation method to retrieve the details of a customer entity from the 2Checkout system.
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. |
2CheckoutCustomerReference |
Required (int) |
System-generated customer reference. Required unless you prefer to use ExternalCustomerReference. |
|
ExternalCustomerReference |
Optional (string) |
|
External customer reference that you control. Optional when you use 2CheckoutCustomerReference. If you include it, it needs to belong to the same customer as the 2CheckoutCustomerReference. |
Response
Object |
Request
<?php
$host = "https://api.2checkout.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 = "YOUR_MERCHANT_CODE";// your account's merchant code available in the 'System settings' area of the cPanel: https://secure.2checkout.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.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;
}
$customerReference = 298084139;
$externalCustomerReference = 'Apitest123456'; //Optional, but if you include it it needs to belong to the same customer as the internal 2Checkout customer reference
try {
$customerInfo = $client->getCustomerInformation($sessionID, $customerReference, $externalCustomerReference);
}
catch (SoapFault $e) {
echo "customerInfo: " . $e->getMessage();
exit;
}
var_dump("customerInfo", $customerInfo);
Signature validation for return URL via InLine checkout
Overview
To start, you need to generate the InLine checkout content using the TwoCoInlineCart client.
At this step, you must add a product to your cart, set the return method, and set a previously generated cart payload signature.
TwoCoInlineCart.cart.setCurrency('USD');
TwoCoInlineCart.products.add({
code : 'TEST_PROD',
quantity: 1,
price : 29
});
TwoCoInlineCart.cart.setReturnMethod({
type: 'redirect',
url : 'https:\/\/yourbackend.com\/'
});
TwoCoInlineCart.cart.setSignature('314cfb1f277ef89f9f3735517...........1c62abee466c9d1774bf1e4655f0');
After triggering TwoCoInlineCart.cart.checkout(); the InLine checkout will initialize in the new iframe.
In case of a valid signature, the cart will boot and the shopper can complete the order. Otherwise, he will see an empty cart page.
In case of a valid signature and successful order placing, the shopper is redirected to the page you have defined in the return parameters. The return URL is appended with some return parameters which are refno, total, total-currency, all of them are signed and their signature should be present in the query parameters.
In the backend, you need to gather all these parameters and validate the parameters' hash you generate with the new signature appended to the return-URL.
To generate the hash and validate the return URL, follow the steps below.
Build the InLine Checkout Signature
To sign an InLine checkout buy-link, you need to follow these steps:
- Sort the parameters that require a signature alphabetically.
- Serialize the parameters and append to them the length of their values.
- Concatenate the resulting values.
- The serialized value is then encrypted with your Buy-Link Secret Word using the HMAC method (algorithm sha256).
- The resulting value is added to the buy-link under the signature parameter.
In order to generate a valid InLine checkout signature, you should include all the parameters from the return URL, except the signature.
Example
When encrypting the values to generate the signature, for the return-url parameter, use an URL with the following structure: https://..... Do not use an encoded URL.
1. Let's consider the following parameters:
- refno = 11606896
- total = 29
- total-currency = USD
The regular return link will have the following structure:
https://www.yourbackend.com/?refno=11606896&total=29&total-currency=USD&signature=08448c91bbb314cfb1f277ef89f9f37355171c62abee466c9d1774bf1e4655f0
2. Sort the parameters alphabetically: refno, total, total-currency.
3. Serialize the values. To serialize a value, you need to append before it the number of letters or digits a value has. For example, the return-type parameter has the 'redirect' value that will be serialized as '8redirect'', where 8 is the number of characters that make up the value.
- refno - 811606896
- total - 229
- total-currency - 3USD
4. Concatenate the values: 118116068962293USD
5. Encrypt using your Secret Word
The serialized value is then encrypted using the HMAC method.
- the algorithm used is sha256
- the key used when encrypting is the merchant secret word (in this example, the secret word is 'vendor-secret-key')
This outputs a 64 character string:
08448c91bbb314cfb1f277ef89f9f37355171c62abee466c9d1774bf1e4655f0
Also, you can use HashValidationTool:
<?php
class HashValidationTool
{
const SHA_256 = 'sha256';
private $params;
private $signature;
private $key;
/**
* HashValidationTool constructor.
*
* @param string $key
*/
public function __construct(string $key)
{
$this->key = $key;
}
/**
* @return string
*/
private function encrypt(): string
{
$serialized = $this->serializeParameters($this->params);
if (strlen($serialized) > 0) {
echo 'Success: serialized params - ' . $serialized . PHP_EOL;
return bin2hex(hash_hmac(self::SHA_256, $serialized, $this->key, true));
} else {
echo 'Error: serialization parameters are empty' . PHP_EOL;
return '';
}
}
/**
* @param string $url
*
* @return bool
*/
public function validate(string $url): bool
{
$this->setUrl($url);
return $this->encrypt() === $this->signature;
}
/**
* @param array $array
*
* @return string
*/
private function serializeParameters(array $array): string
{
ksort($array);
$serializedString = '';
foreach ($array as $value) {
if (is_array($value)) {
$serializedString .= $this->serializeParameters($value);
} else {
$serializedString .= strlen($value) . $value;
}
}
return $serializedString;
}
/**
* @param string $url
*/
private function setUrl(string $url): void
{
$urlParts = parse_url($url);
parse_str($urlParts['query'], $this->params);
$this->signature = $this->params['signature'];
unset($this->params['signature']);
}
}
$hashValidationTool = new HashValidationTool('vendor-secret-key');
if ($hashValidationTool->validate('https://www.yourbackend.com/?merchant=YOUR_VENDOR_CODE¤cy=USD&return-url=https://yourbackend.com/&return-type=redirect&tpl=default&prod=TEST_PROD&price=29&qty=1&refno=11606896&total=29&total-currency=USD&signature=95052ee0c558b53040e97d7d81add2e0f1400ca0936a558910c68ddc8301fc63')) {
echo 'valid';
} else {
echo 'invalid';
}
The successful order placement flow with a valid signature for the InLine checkout is described in the following diagram.
Retrieve specific list of subscriptions
Overview
Extract information on a specific list of subscriptions. Use the getSubscriptions method to retrieve details about a specific list of your account’s subscriptions.
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 (Array of strings) |
Unique, system-generated subscription identifier. |
|
Aggregate |
Required (boolean) |
|
true - search will work across all your aggregated Avangate accounts. false - default value. You limit the search to the account whose details you used for authentication. |
Response
Array of objects |
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;
}
$SubscriptionReferences = array('48F5AC7011', '6A8FDC9CD2', '6A8FDC9CD2', '8F749B63E7');
try {
$ListofSubscriptions = $client->getSubscriptions($sessionID, $SubscriptionReferences);
}
catch (SoapFault $e) {
echo "ListofSubscriptions: " . $e->getMessage();
exit;
}
var_dump("ListofSubscriptions", $ListofSubscriptions);
Order session content object
Overview
Use this object to retrieve session content and to guide shoppers through advanced payment flows, such as those of PayPal, PayPal Express, Wire, Check, etc.
Attributes
Order session contents |
Type/Description |
||||
Errors |
Optional (StringArray) |
||||
|
Payment gateway processing errors. |
||||
Items |
Array of objects |
||||
Details below. | |||||
|
ProductDetails |
Object |
|||
Details below. | |||||
|
|
Name |
Optional (string) |
||
|
|
|
Product name. |
||
|
|
ExtraInfo |
Optional (string) |
||
|
|
|
The text entered in the Additional information field when generating Buy links, or via the INFO[PRODUCT_ID] parameter used in Buy links. |
||
|
|
RenewalStatus |
Optional (boolean) |
||
|
|
|
|
||
|
|
Subscriptions |
Object |
||
Details below. | |||||
|
|
|
SubscriptionReference |
Optional (string) |
|
|
|
|
|
Unique, system-generated subscription identifier. |
|
|
|
|
PurchaseDate |
Optional (string) |
|
|
|
|
|
The date time stamp when shoppers acquired their subscriptions corresponding to the moment when the 2Checkout system marks the purchase as finished. Format (YYYY-MM-DD HH:mm:ss). Default GMT+02:00.
e.g. 2015-08-11 15:18:52 |
|
|
|
|
SubscriptionStartDate |
Optional (string) |
|
|
|
|
|
Example: 2015-09-29 17:57:59 |
|
|
|
|
ExpirationDate |
Optional (string) |
|
|
|
|
|
The date time stamp of upcoming renewal/expiration for subscriptions not taking into account grace period settings.
Format (YYYY-MM-DD HH:mm:ss). Default GMT+02:00.
e.g. 2015-09-11 15:18:52 |
|
|
|
|
Lifetime |
Optional (boolean) |
|
|
|
|
|
|
|
|
|
|
Trial |
Optional (boolean) |
|
|
|
|
|
|
|
|
|
|
Enabled |
Optional (boolean) |
|
|
|
|
|
|
|
|
|
|
RecurringEnabled |
Optional (boolean) |
|
|
|
|
|
|
|
|
PriceOptions |
Optional (Array of strings) |
|||
|
|
Product price options. |
|||
|
Price |
Object |
|||
|
|
This object returns the price per unit at order line level.
In the case of trials, the object returns the costs for the trial to full subscription conversion. |
|||
|
|
UnitNetPrice |
Optional (double) |
||
|
|
|
The value per product unit, excluding sales tax/VAT expressed in the payment currency. |
||
|
|
UnitGrossPrice |
Optional (double) |
||
|
|
|
Total value per product unit, including sales tax/VAT expressed in the payment currency. UnitGrossPrice does not reflect any discounts. |
||
|
|
UnitVAT |
Optional (double) |
||
|
|
|
Sales tax/VAT per product unit expressed in the payment currency. |
||
|
|
UnitDiscount |
Optional (double) |
||
|
|
|
Value of the discount per product unit expressed in the payment currency. |
||
|
|
UnitNetDiscountedPrice |
Optional (double) |
||
|
|
|
The value per product unit, expressed in the payment currency, excluding sales tax/VAT, from which 2Checkout deducts the unit discount. |
||
|
|
UnitGrossDiscountedPrice |
Optional (double) |
||
|
|
|
Total costs shoppers incur per product unit, expressed in the payment currency. This value includes sales tax/VAT, 2Checkout and affiliate commissions, but 2Checkout deducts the value of any discounts. |
||
|
|
UnitAffiliateCommission |
Optional (double) |
||
|
|
|
Value of the affiliate commission per product unit calculated expressed in the payment currency.
2Checkout deducts discounts from the costs incurred by shoppers before calculating affiliate commissions.
2Checkout does not take into account shipping costs when calculating affiliate commissions.
NULL when 2Checkout does not apply an affiliate commission. |
||
|
|
Currency |
Optional (string) |
||
|
|
|
The currency ISO code for the payment - ISO 4217. Example: usd. |
||
|
|
NetPrice |
Optional (double) |
||
|
|
|
The value per order line, excluding sales tax/VAT expressed in the payment currency. |
||
|
|
GrossPrice |
Optional (double) |
||
|
|
|
Total value per order line, including sales tax/VAT expressed in the payment currency. UnitGrossPrice does not reflect any discounts. |
||
|
|
NetDiscountedPrice |
Optional (double) |
||
|
|
|
The NetPrice value per order line, excluding sales tax/VAT, from which 2Checkout deducts discounts. NetDiscountedPrice is expressed in the payment currency. |
||
|
|
GrossDiscountedPrice |
Optional (double) |
||
|
|
|
Total costs shoppers incur per order line, expressed in the payment currency. This value includes sales tax/VAT, 2Checkout and affiliate commissions, but 2Checkout deducts the value of any discounts.
Example:
|
||
|
|
Discount |
Optional (double) |
||
|
|
|
Value of the discounts per order line expressed in the payment currency. |
||
|
|
VAT |
Optional (double) |
||
|
|
|
Value of sales tax/VAT per order line expressed in the payment currency. |
||
|
|
AffiliateCommission |
Optional (double) |
||
|
|
|
Value of the affiliate commission per order line, calculated from the NetDiscountedPrice expressed in the payment currency. Or NULL. 2Checkout does not take into account shipping costs when calculating affiliate commissions. |
||
|
Code |
Optional (string) |
|||
|
|
Unique product identifier your control. Max length 256 characters. |
|||
|
Quantity |
Optional (integer) |
|||
|
|
Number of units |
|||
|
SKU |
Optional (string) |
|||
|
|
SKU identifier. |
|||
|
CrossSell |
Optional (Object) |
|||
Details below. | |||||
|
|
ParentCode |
Optional (string) |
||
|
|
|
The product code of the master product you set to trigger the campaign. |
||
|
|
CampaignCode |
Optional (string) |
||
|
|
|
Unique, system-generated identifier for cross-sell campaigns. |
||
|
Trial |
Optional (Object) |
|||
Details below. | |||||
|
|
Period |
Optional (integer) |
||
|
|
|
The length of the trial subscription lifetime in days. |
||
|
|
GrossPrice |
Optional (double) |
||
|
|
|
Total trial price in the payment currency before 2Checkout deducts any taxes, discounts, etc. |
||
|
|
VAT |
Optional (double) |
||
|
|
|
The total value of taxes for the trial in the payment currency, before 2Checkout deducts any discounts. |
||
|
|
NetPrice |
Optional (double) |
||
|
|
|
Total trial price in the payment currency, not including taxes, before 2Checkout deducts any discounts. |
||
|
AdditionalFields |
Optional (array of objects) |
|||
Details below. | |||||
|
|
Code |
Optional (string) |
||
|
|
|
The alpha-numeric characters, underscores and dashes that are set as the field identifier. |
||
|
|
Text |
Optional (string) |
||
|
|
|
Field text visible to shoppers in the cart. |
||
|
|
Value |
Optional (string) |
||
|
|
|
Selected field value. |
||
|
Promotion |
Optional (object) |
|||
Details below. | |||||
|
|
Name |
Optional (string) |
||
|
|
|
Promotion name. |
||
|
|
Description |
Optional (string) |
||
|
|
|
Promotion description. |
||
|
|
StartDate |
Optional (string) |
||
|
|
|
The date when you set the promotion to start. NULL for promotions that start immediately after you create them. |
||
|
|
EndDate |
Optional (string) |
||
|
|
|
The date when you set the promotion to end. NULL for promotions you want active indefinitely. |
||
|
|
MaximumOrdersNumber |
Optional (integer) |
||
|
|
|
2Checkout only applies the promotion to a maximum number of orders you define.
Can be NULL if you want the promotion to apply to an unlimited number of orders. |
||
|
|
MaximumQuantity |
Optional (integer) |
||
|
|
|
Discount only applies to a maximum number of units purchased through a single order, smaller than the quantity you defined. Shoppers purchase any extra units at full price. Can be NULL if you want the promotion to apply to an unlimited number units. |
||
|
|
InstantDiscount |
Optional (boolean) |
||
|
|
|
The instant discount option auto-applies the discount for ALL selected products, without the need for shoppers to enter a discount coupon. |
||
|
|
Coupon |
Optional (string) |
||
|
|
|
Promotion coupon/voucher. |
||
|
|
DiscountLabel |
Optional (string) |
||
|
|
|
Discounts can be set as a percentage from the product price or as a fixed amount in the chosen currency. |
||
|
|
Enabled |
Optional (string) |
||
|
|
|
true or false, depending on whether a promotion is active or disabled. |
||
|
|
Type |
Optional (string) |
||
|
|
|
|
||
Promotions |
Optional (Array of objects) |
||||
Details below. | |||||
|
Name |
Optional (string) |
|||
|
|
Promotion name. |
|||
|
Description |
Optional (string) |
|||
|
|
Promotion description. |
|||
|
StartDate |
Optional (string) |
|||
|
|
The date when you set the promotion to start. NULL for promotions that start immediately after you create them. |
|||
|
EndDate |
Optional (string) |
|||
|
|
The date when you set the promotion to end. NULL for promotions you want active indefinitely. |
|||
|
MaximumOrdersNumber |
Optional (integer) |
|||
|
|
2Checkout only applies the promotion to a maximum number of orders you define.
Can be NULL if you want the promotion to apply to an unlimited number of orders. |
|||
|
MaximumQuantity |
Optional (integer) |
|||
|
|
Discount only applies to a specific number of units purchased at once, smaller than the maximum quantity you defined. Shoppers purchase any extra units at full price. Can be NULL if you want the promotion to apply to an unlimited number units. |
|||
|
InstantDiscount |
Optional (boolean) |
|||
|
|
The instant discount option auto-applies the discount for ALL selected products, without the need for shoppers to enter a discount coupon. |
|||
|
Coupon |
Optional (string) |
|||
|
|
Promotion coupon/voucher. |
|||
|
DiscountLabel |
Optional (string) |
|||
|
|
Discounts can be set as a percentage from the product price or as a fixed amount in the payment currency. |
|||
|
Enabled |
Optional (string) |
|||
|
|
true or false, depending on whether a promotion is active or disabled. |
|||
|
Type |
Optional (string) |
|||
|
|
|
|||
AdditionalFields |
Optional (array of objects) |
||||
Details below. | |||||
|
Code |
Optional (string) |
|||
|
|
The alpha-numeric characters, underscores and dashes that are set as the field identifier. |
|||
|
Text |
Optional (string) |
|||
|
|
Field text visible to shoppers in the cart. |
|||
|
Value |
Optional (string) |
|||
|
|
Selected field value. |
|||
Currency |
Optional (string) |
||||
|
The currency ISO code for the payment - ISO 4217. Example: usd. |
||||
NetPrice |
Optional (double) |
||||
|
Order value excluding sales tax/VAT expressed in the payment currency. |
||||
GrossPrice |
Optional (double) |
||||
|
Total order value, including sales tax/VAT expressed in the payment currency. GrossPrice does not reflect any discounts. |
||||
NetDiscountedPrice |
Optional (double) |
||||
|
The NetPrice order value excluding sales tax/VAT, from which 2Checkout deducts discounts. NetDiscountedPrice is expressed in the payment currency. |
||||
GrossDiscountedPrice |
Optional (double) |
||||
|
Total costs shoppers incur, expressed in the payment currency. This value includes sales tax/VAT, 2Checkout and affiliate commissions, but 2Checkout deducts the value of any discounts.
For example:
|
||||
Discount |
Optional (double) |
||||
|
Value of the discounts for an order expressed in the payment currency. |
||||
VAT |
Optional (double) |
||||
|
Value of sales tax/VAT expressed in the payment currency. |
||||
AffiliateCommission |
Optional (double) |
||||
|
Value of the affiliate commission for the order calculated from the NetDiscountedPrice expressed in the payment currency. Or NULL. 2Checkout does not take into account shipping costs when calculating affiliate commissions. |
Custom subscription renewal price
Overview
Charge customers custom prices for the renewal of subscriptions, moving away from the recurring pricing configuration at product level. Use the setCustomRenewalPrice method to set custom renewal prices for subscriptions and control the number of recurring billing cycles the price impact subscribers.
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. |
|
Price |
Required (double) |
|
Custom cost subscribers incur. |
Currency |
Required (string) |
|
Number of recurring billing cycles for which Avangate charges customers the custom price rather, ignoring product–level recurring pricing configurations. (Can be null - Default value 1) |
Cycles |
Required (int) |
|
The price you want to charge customers for the upgrade. The currency used by default is the same as in the previous payment customers made. |
ReasonText |
Optional (string) |
|
Save details at the subscription-level about the custom costs. |
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;
}
$subscriptionReference = '30E47F8699';
$Price = 50;
$Currency = 'eur';
$Cycles = 2;
$ReasonText = null;
try {
$CustomPrice = $client->setCustomRenewalPrice($sessionID, $subscriptionReference, $Price, $Currency, $Cycles, $ReasonText);
}
catch (SoapFault $e) {
echo "CustomPrice: " . $e->getMessage();
exit;
}
var_dump("CustomPrice", $CustomPrice);