Skip to main content

Retrieve all additional fields

Overview

Use the getAdditionalFields method to extract information about additional fields 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.

Response

Parameters Type/Description

AdditionalFields

Array of objects

Request

<?php

require ('PATH_TO_AUTH');

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


Retrieve SKU code by details

Overview

Use the getSKUCodeByDetails method to retrieve an SKU based on its included 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.

 skuDetailsObject

Object

 

Details below

 

PricingConfigurationCode

Required (string)

 

 

Unique identifier of the pricing configuration.

 

Currency

Optional (string)

 

 

ISO currency code.

 

PurchaseType

Optional (string)

 

 

Purchase type identifier. Possible values:

  • NEW_PRODUCT
  • RENEWAL
  • UPGRADE

 

PriceOptions

Optional (stringArray)

 

 

Array of price options names.

 

Quantity

Optional (int)

 

 

Numeric identifier of product quantity.

Response

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

Request

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

Create a new customer

Overview

Use the createCustomer method to add the details of a customer entity into the Avangate system. By default, customer status is Inactive until you assign a specific subscription to the customer. Following that action, customer status reflects the status of the attached subscription(s).

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.

Customer

Object

Response

AvangateCustomerReference

Int

 

System-generated customer reference.

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);
$newCustomer = new stdClass();
$newCustomer->AvangateCustomerReference = null;
$newCustomer->ExternalCustomerReference = 'ThisIsATestReference123456';
$newCustomer->FirstName = 'NewCustomer';
$newCustomer->LastName = 'NewCustomerLastName';
$newCustomer->Company = null;
$newCustomer->FiscalCode = null;
$newCustomer->Address1 = 'Address';
$newCustomer->Address2 = null;
$newCustomer->City = 'LA';
$newCustomer->Zip = '90210';
$newCustomer->CountryCode = 'us';
$newCustomer->Phone = null;
$newCustomer->Fax = null;
$newCustomer->Email = 'newcustomer@email.com';
$newCustomer->ExistingCards = null;
$newCustomer->Enabled = null;
$newCustomer->Trial = null;
$newCustomer->Language = 'en';

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

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

Retrieve order subscription references

Overview

List the references associated with the subscription generated for an order.

Requirements

Parameters

Parameter Type/Description
sessionID Required (String)
  Session identifier, output of the Login method. An exception is thrown if the values are incorrect.
refNo Required (String)
  The unique identifier of an order from the Avangate system.
pageNo Optional (Int)
 

Break down the subscription information using pagination into groups of 50 items (PartnerSubscription objects) per page.

Example values:

  • 1 - the first 50
  • 2 - the next 50
  • 3 - the next 50

Can be NULL.

Response

Parameter Type/Description

PartnerSubscription

Array of objects

 

Details below

 

SubscriptionReference

String

 

 

The unique reference associated with a subscription generated for a product included in a partner order.

 

HasEndUserInformation

Boolean

 

 

True or false, depending on whether end user information is attached to the subscription.

 

RegistrationStatus

String

 

 

Possible values:

  • Not registered
  • Registered

 

RegistrationEmails

String

 

 

The email used by the end user in the registration process. Can be NULL.

 

FullfilmentStatus

String

 

 

Fulfillment status possible values:

  1. DELIVERED - Order was fulfilled/delivered.
  2. NOT_DELIVERED - Fulfillment is blocked due to various reasons including lack of payment/credit, missing reseller/end user details.
  3. NO_DELIVERY_REQUIRED - No fulfillment confirmation is required.
  4. VENDOR_CONFIRMED_DELIVERY - Fulfillment has been confirmed.
  5. VENDOR_DELIVERY_CONFIRMATION_REQUIRED - You need to confirm fulfillment.

Request

<?php

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

$refNo = 'YOUR_ORDER_REFERENCE';

try {
    $SubscriptionsGenerated= $client->getOrderSubscriptions ($sessionID, $refNo, $pageNo);
} catch (SoapFault $e) {
    Echo "Subscriptions: " . $e->getMessage();
    exit;
}
var_dump ("Subscriptions ", $SubscriptionsGenerated);

Errors

Error Description

NOT_FOUND_PARTNER

A partner must be set first.

EMPTY_ORDER_REFERENCE

Order reference not provided.

INVALID_REFERENCE

Invalid order reference.

 

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

PricingConfiguration

Array of objects

Request

<?php

require ('PATH_TO_AUTH');

$productCode = 'YOUR_PRODUCT_CODE';

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

?>

Retrieve product information by code

Overview

Extract information about a product from the Avangate system using its unique ID and the code of the pricing list to which it is assigned to.

Requirements

Parameters

Parameter Type/Description
sessionID Required (string)
  Session identifier, which is the output of the Login method. An exception will be thrown if the values are incorrect.
productCode Required (string)
  The unique product identifier from your system.
pricingListCode Required (string)
  The unique identifier of the pricing list.

Response

Parameter Type/Description
ProductInfo Complet object
  Complex object containing arrays of SimpleProduct and PriceOptions objects.

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

$productCode = 'YOUR_PRODUCT_CODE';
$pricingListCode = 'YOUR_PRICING_LIST_CODE';

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

Errors

Error Description

INVALID_PARTNER

No partner is set.

INVALID_PRODUCT

Provide a valid product ID.

INVALID_PRICING_LIST_CODE

Provide a valid pricing list code.

PARTNER_PRICING_LISTS_NOT_FOUND

There are no pricing lists with the provided code.

PRODUCT_NOT_FOUND

There is no product with this ID in the given pricing list.

 

Assign to another customer

Overview

Use the setSubscriptionCustomer method. 2Checkout moves subscription under the customer for which you provide the 2Checkout customer reference or the External customer reference during the subscription update process.

json_diagram.png

Requirements

To move a subscription from a source customer to a target customer:

  • Use 2Checkout customer references or External customer references belonging to the target customer. 2Checkout re-assigns the subscription to the target customer. 
  • Customer references must be valid and associated to the target customer entity under which you move the subscription.
  • If you provide both the 2Checkout customer reference and External customer reference they need to belong to the same target customer entity.

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.

avangateCustomerReference

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 AvangateCustomerReference. If you include it, it needs to belong to the same customer as the AvangateCustomerReference.

Response

Parameters Type/Description

Boolean

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

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';
$customerReference = CUSTOMER_REFERENCE;

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

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

Export product data as an XML file

Overview

Export product and pricing data packaged as an XML file. 

Requirements

At least one product needs to have already been configured or imported in the 2Checkout system.

Export limitations

We recommend exporting batches of 20 to 30 products at once for optimal performance.

  • Exporting up to 1000 products is done on the spot.
  • Exporting more than 1000 products lasts longer and is done in the background. 2Checkout can notify you via email when your export file is ready and provides you with the download link.

How does export work?

Use UTF-8 character encoding.

To export existing product data from the 2Checkout platform:

  1. Make your way to Products under Setup.
  2. Run a search for the products you want included in the export file.
  3. Once your search returns the list of desired products, scroll down to the bottom of the page and click Download XML.

How to export all products for an account?

To export existing product data from the 2Checkout platform:

  1. Make your way to Products under Setup;
  2. The Active option is selected under Display by default.
  3. Scroll down to the bottom of the page and click Download XML.

Note: All active products for your account are displayed when accessing the Products area. Not searching for specific offerings will export all active items.

What data is exported?

The XML product export functionality covers data under the following areas (tabs), with some exceptions detailed below:

  1. Information
  2. Pricing
  3. Bundle Options

XML schema

Use UTF-8 character encoding.

Below is the XML schema designed to let you export product data from the 2Checkout system. Export is the root element, and there are three main child elements:

  • AdditionalFields: The export extracts per-product and per-order additional order details from the 2Checkout system. The relationship between the fields and products is mapped under the Product child element.
  • PriceOptionsGroups: The export extracts data on all price options groups defined in the 2Checkout system. The relationship between one or more price options groups and products is mapped under the Product child element.
  • Products: Product information (with some exceptions) that resides under the Information, Pricing and Bundle options area (tabs) of the Control Panel.

 

<Export>
<AdditionalFields>...</AdditionalFields>
<PriceOptionsGroups>...</PriceOptionsGroups>
<Products>...</Products>
</Export>

Update a subscription

Overview

Change specific details about a subscription. Use the updateSubscription method to change specific details about a subscription.

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.

Subscription

Required (Object)

 

You need to include the entire Subscription object keeping its structure unchanged (retrieve it using getSubscription) but you can update only specific parameters enumerated below.

 

EndUser

Object

 

 

End user details.

 

ExpirationDate

String

 

 

Subscription expiration date - If you changed the time zone for the 2Checkout API by editing system settings under Account settings, then 2Checkout calculates the ExpirationDate according to your custom configuration. Note: The default 2Checkout API time zone is GMT+02:00.

You cannot set an expiration date from the past.

 

SubscriptionEnabled

Boolean

 

 

Possible values: TRUE/FALSE

 

RecurringEnabled

Boolean

 

 

Possible values: TRUE/FALSE

 

ExternalCustomerReference

String

 

 

Unique customer alphanumeric (string) identifiers that you control. Use this to 

move a subscription from under a customer to another customer entity. 2Checkout moves subscription under the customer for which you provide the External customer reference during the subscription update process. View example.

 

ProductId

Int

 

 

System-generated unique product ID. Needs to be the ID of an existing product in the 2Checkout system created under your account.

The product ID governs the product to which the subscription is associated with.

Product types must match Regular - Regular or Bundle - Bundle.

IDs must identify products with the renewal system enabled (max billing cycle 36 months).

 

ProductName

String

 

 

The name of the product for identifier used under ProductID.

 

ProductQuantity

Int

 

 

Ordered quantity.

 

PriceOptionCodes

Array

 

 

Array of product options codes. Pricing options codes are case sensitive.

To impact the renewal price, the PriceOptionsCodes need to belong to price options of pricing configurations used for the product with which the subscription is associated.

 

All other parameters of the Subscription object are non-editable.

The 2Checkout system uses the updated subscription information for:

  • Manual and automatic renewals
  • Upgrades
  • Trial conversions

Response

Parameters Type/Description

Boolean

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

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReferenceTest = 'YOUR_SUBSCRIPTION_REFERENCE';

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

$updatedSubscription = callRPC((Object)$jsonRpcRequest, $host, true);
var_dump ($updatedSubscription);
$updatedSubscription->RecurringEnabled = false;
$updatedSubscription-> SubscriptionEnabled = true;
$updatedSubscription->ExpirationDate = '2020-12-12';

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

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

 

Retrieve a promotion

Overview

Use the getPromotion method to extract information on a promotion 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.

PromotionCode

Required (string)

 

System-generated identifier 2Checkout associated with promotion campaigns.

Response

Parameters Type/Description
Promotion Object 

 

Request

<?php

require ('PATH_TO_AUTH');

$promotionCode = 'PROMOTION_CODE'; // code of the promotion that you want to update

try {
    $Discount = $client->getPromotion($sessionID, $promotionCode);
}
catch (SoapFault $e) {
    echo "Discount: " . $e->getMessage();
    exit;
}

var_dump("Discount", $Discount);

 

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