Overview

Reimbursing customers by issuing Total or Partial refunds for their orders is available via API. 

Issuing refunds can be done on the REST protocol via a POST request to /orders/{RefNo}/refund/ and on SOAP and JSON-RPC protocols via the issueRefund method.

Availability

Refunding an order via API is available for all accounts.

Requirements

• Order must be in status COMPLETE
• Order must not be older than 3 months
• The refunded amount must not be higher than the total amount of the order

Request Object

RefundItem Object

Request example

REST

{
  "amount": 23,
  "items": [
    {
      "LineItemReference": "my_product_1",
      "Quantity": 1
    }
  ],
  "comment": "requested by shopper",
  "reason": "CUSTOM_REASON"
}

SOAP and JSON-RPC Example

For the SOAP and JSON-RPC protocols, the issueRefund method needs to be called with the components of the requests in the parameter list. 

More information about issuing refunds can be found here (for JSON-RPC) and here (for SOAP).

The JSON-RPC object that needs to be sent would look like

{
   "jsonrpc":"2.0",
   "method":"issueRefund",
   "params":[
      "om7sb5uob2p2g9r321iif2v3hd7p5gkn", //session id
      "11370513",                         //orderRef
      "25.39",                           //amount 
      {
         "Quantity":1,                   //quantity of product refunded
         "Amount":25.39                  //amount of product refunded
      },
      "This is a comment",               //comment
      "Duplicate purchase"               //reason
   ],
   "id":2
}

 For SOAP requests, the following parameters need to be added to the SOAP request:

$refundedOrder = $client->issueRefund($sessionID, $orderReference, $amount, $items, $comment, $reason);

Response

The API will return a Boolean when issuing refunds. A true response means that the refund was registered successfully.

Error handling

A full list of errors returned by the issueRefund API method can be found here.

Overview

Retrieve information on the evolution of a subscription in the Avangate system, including details of the initial acquisition and the subsequent renewals and upgrades. Use the getSubscriptionHistory method to retrieve details about a subscription. 

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';

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

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

Overview

Use deletePromotionProducts to remove products from an existing promotion.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

// Define the first product to remove from the promotion
$newProduct1 = new stdClass;
$newProduct1->Code = '';
$newProduct1->PricingConfigurationCode = '';
$newProduct1->PricingOptionCodes = ['',''];

// Define another product to remove from the promotion
$newProduct2 = new stdClass;
$newProduct2->Code = '';
$newProduct2->PricingOptionCodes = [''];

$promotionProducts = [$newProduct1, $newProduct2];

try {
    $updatedPromotion = $client->deletePromotionProducts ($promotionCode, $promotionProducts);
}

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

var_dump("UpdatedPromotion", $updatedPromotion);

Overview

Use this method to attach a comment when placing a partner order.

Requirements

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');  // Authentication example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/JSON-RPC/02Authentication
require ('PATH_TO_SET_PARTNER'); // setPartner example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/JSON-RPC/06Reference/Partner/00Set_partner
require ('PATH_TO_ADD_PRODUCT'); // addProduct example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/JSON-RPC/06Reference/08Place_an_order/00Add_product_to_cart

$comment = 'YOUR_COMMENT';

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

require ('PATH_TO_PLACE_ORDER');

Errors

Overview

Use the updateCustomerInformation method to update the details of a customer entity from the 2Checkout system.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$customerReference = CUSTOMER_REFERENCE;
$externalCustomerReference = 'EXT_CUSTOMER_REFERENCE'; //Optional, but if you include it it needs to belong to the same customer as the internal 2Checkout customer reference

try {
    $existingCustomer = $client->getCustomerInformation($sessionID, $customerReference, $externalCustomerReference);
}

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

$existingCustomer->Email = 'newemailaddress@email.com';
$UpdateEndUserSubscriptions = false; // Optional, but if true the changes made on customer info are pushed to all subscriptions from this customer.

try {
    $updatedCustomerInfo = $client->updateCustomerInformation($sessionID, $existingCustomer, $UpdateEndUserSubscriptions);
}
catch (SoapFault $e) {
    echo "updatedCustomerInfo: " . $e->getMessage();
    exit;
}
var_dump("updatedCustomerInfo", $updatedCustomerInfo);

?>

Overview

Use the getProductCrossSellCampaigns method to extract information on all cross-sell campaigns triggered by the same primary product.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$ProductCode = 'subscr1';

try {
    $ProductCrossSellCampaigns = $client->getProductCrossSellCampaigns($sessionID, $ProductCode);
}

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

var_dump("ProductCrossSellCampaigns", $ProductCrossSellCampaigns);

Overview

This object is returned directly or within a successful response from the following API requests:

Retrieve a price option group                  Retrieve assigned price option groups                         Retrieve price option groups

Pricing option group

Overview

Use the updateCustomerInformation method to update the details of a customer entity from the 2Checkout system.

Parameters

Response

Request

<?php
$host   = "https://api.2checkout.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.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;
}
$customerInfo->Email = 'newemailaddressupdated@email.com';
$UpdateEndUserSubscriptions = false; // // Optional, but if true the changes made on customer info are pushed to all subscriptions from this customer.
try {
    $updatedCustomerInfo = $client->updateCustomerInformation($sessionID, $customerInfo, $UpdateEndUserSubscriptions);
}
catch (SoapFault $e) {
    echo "updatedCustomerInfo: " . $e->getMessage();
    exit;
}
var_dump("updatedCustomerInfo", $updatedCustomerInfo);

Overview

Use this method to retrieve a list of resellers defined and stored for one of your partners.

Requirements

This method requires you to set a specific partner using setPartner.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');  // Authentication example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/JSON-RPC/02Authentication
require ('PATH_TO_SET_PARTNER'); // setPartner example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/JSON-RPC/06Reference/Partner/00Set_partner

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

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

Errors

Overview

Generate a partner invoice for one or more orders, based on their unique reference numbers.

Requirements

You can include only confirmed/approved orders in partner invoices. To include multiple orders in the same partner invoice they must share the same currency.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');  // Authentication example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/JSON-RPC/02Authentication
require ('PATH_TO_SET_PARTNER'); // setPartner example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/JSON-RPC/06Reference/Partner/00Set_partner

$sales = array(
'ORDER_REFERENCE_1',
'ORDER_REFERENCE_2'
);

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

Errors