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/SOAP/02Authentication
require('PATH_TO_setPartner'); // setPartner example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/SOAP/06Reference/Partner/00Set_partner

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

try {
    $NewProforma= $client->createProforma($sessionID, $sales);
} catch (SoapFault $e) {
    echo "NewP: " . $e->getMessage();
    exit;
}
var_dump ("NewP ", $NewProforma);

Errors

Overview

Learn how to tackle the common errors that may arise when issuing refunds via 2Checkout API.

Common error codes 

Overview

Use the setExternalRef method in conjunction with setSubscriptionUpgrade.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$externalReference = 'YOUR_EXTERNAL_REFERENCE';

try {
    $extRef = $client->setExternalRef($sessionID, $externalReference);
}
catch (SoapFault $e) {
    echo "extRef: " . $e->getMessage();
    exit;
}
var_dump("extRef", $extRef);

Overview

After the opportunity is created and saved as a draft, it needs to be sent for approval.

The approval flow needs to be set up as per your organization's needs and procedures. The CPQ provides an "In Review" status for offers ready to be sent and is expecting a "Reviewed" status to proceed with sending the proposal to your customers.

The CPQ solution requires an approval flow  in order to change the  status of the offer and continue the flow.

Approval process configuration

The approval flow needs to be set up before proceeding with the approval of a proposal.

1. Log in to the CPQ application, navigate to the Setup cogwheel and click on it.

2. Enter “Approval Processes” in the Quick Find text box and select Approval Processes.

3. From the Manage Approval Process For pick list, select the needed object to create the approval on (Offer).

4. Click Create New Approval Process pick list and select Use Standard Setup Wizard (Note: Standard Setup gives more configuration options when creating the process).

5. Fill in the new approval process details (Process Name, Unique Name, Description – if any).

6. Click Next.

7. In the “Use this approval process if the following” field, select criteria are met or formula evaluates to true, then fill in the criteria as desired.

8. Click Next. 

9. Set the “Next Automated Approver Determined By” to Manager value (this will route the record to the Manager for review).

10. From the “Record Editability Properties” section, click the Administrators ONLY can edit records during the approval process radio button (or choose what works best for your environment).

11. Click Next.

12. In Step 5, leave the “Approval Assignment Email Template” field blank (for this step: the ability to choose a custom email template to use when notifying approvers that an approval request is assigned to them. Leaving the field blank will automatically assign the default email template for this process, to use).

13. Click Next, then determine the fields that will be displayed on the approval request page (left click on fields in the “Available Fields” section, click Add to move to “Selected Fields” section; use CTRL/SHIFT for multiple selections where needed), leave “Approval Page Fields” and “Security Settings” sections as they are, then click Next.

14. On Step 6, specify the initial submitter by completing the submitter details in the “Initial Submitters” section (this will specify the users allowed to submit the initial request to approve; choose according to your environment requirements). Based on the “Submitter Type” the user has chosen, the “Available Submitters” section will return different results (left click on fields in the “Available Submitters” section, click Add to move to “Allowed Submitters” section; use CTRL/SHIFT for multiple selections where needed).

15. On Step 7, in the “Page Layout Settings” section, the Add the Submit for Approval button and Approval History related list to all Offer page layouts checkbox should be checked.

16. On Step 7, in the “Submission Settings” section, the Allow submitters to recall approval requests should be disabled (If selected, submitters can recall their approval requests. If deselected, only admins can recall requests).

Note: The option is useful for situations where things change on the submitter’s side while waiting for approval (example: an opportunity could be lost after the user submits it for approval).

17. Click Save.

18. On the “What Would You Like To Do Now?” page, select I'll do this later, take me to the approval detail page to review what I've just created.

19. The newly created approval process page will show: in the “APPROVAL STEPS” section click New Approval Step and complete the details: enter a name for the step and click Next and from the “Specify Step Criteria” section, select Enter this step if the following: “formula evaluates to true, else reject record” and insert formula: NOT(ISBLANK(CreatedDate)) and click Save; on Step 3, from the “Select Approver” section, choose Automatically assign using the user field selected earlier (Manager). 

20. Click Save.

21. Move forward with the “FINAL APPROVAL ACTIONS” section, and click New Field Update; fill in the Name in the “Identification” section and select A specific value Reviewed, in the “Specify New Field Value” section, and click Save

22. Move forward with the “FINAL REJECTION ACTIONS” section, and click New Field Update; fill in the Name in the “Identification” section and select A specific value Rejected, in the “Specify New Field Value” section, and click Save

Send the proposal for approval

Perform these steps to send a proposal for approval:

1. In order to send the proposal for approval, you need to click on the Submit for Approval button.

2. The offer will be sent for approval to the Sales Rep Manager who can see the list of items to approve on the home screen of the CPQ app.

3. After the offer is reviewed, its status is changed to Reviewed and then to Sent automatically.

4. The customer will receive an email in order to check the Offer.

5. If the offer is accepted then its status is changed to Completed.

Overview

Retrieve information about the upgrade options for a specific subscription.

Overview

GiroPay is an online banking-based payment method for users in Germany. GiroPay supports online payments via secure online transfers directly between bank accounts. GiroPay accounted for a share of 2% of online payments in Germany in 2019.

Supported currencies

GiroPay is restricted to Germany and supports transactions in EUR.

Workflow

1. Shoppers select GiroPay as a payment option in the checkout interface you provide to them.
2. Create the order object. Use “GIROPAY” as the type of the PaymentDetails object.
3. Use the placeOrder method to send the data to 2Checkout.
4. Use the PaymentMethod object to create a redirect URL for the shoppers. Using the provided URL, make a request using the provided method (usually a GET request) and add the parameters (located in the Params object) as key-value pairs to the URL of the request.
5. 2Checkout returns an Order object as the output of the placeOrder method. 
6. Once you place the order, 2Checkout logs it into the system. At this point in time, the status of the order is PENDING.

Parameters

Request Example 

 <?php

require ('PATH_TO_AUTH');

$Order = new stdClass();
$Order->RefNo = NULL;
$Order->Currency = "EUR" ;
$Order->Country = "DE";
$Order->Language = 'EN';
$Order->CustomerIP = '10.5.22.197';
$Order->ExternalReference = NULL;
$Order->Source = NULL;
$Order->Affiliate = new stdClass();
$Order->Affiliate->AffiliateCode = 'Partner123'
$Order->Affiliate->AffiliateSource = 'MobilePlatform'
$Order->CustomerReference = NULL;
$Order->Items = array();
$Order->Items[0] = new stdClass();
$Order->Items[0]->Code = '67B4EDC822';
$Order->Items[0]->Quantity = 1;
$Order->Items[0]->PriceOptions = NULL;
$Order->Items[0]->SKU = NULL;
$Order->Items[0]->Price = NULL;
$Order->Items[0]->CrossSell = NULL;
$Order->Items[0]->Trial = false;
$Order->Items[0]->AdditionalFields = NULL;
$Order->Items[0]->SubscriptionStartDate = NULL; //If empty or null, subscriptions become active when purchase is made.
$Order->BillingDetails = new stdClass();
$Order->BillingDetails->FirstName = 'John';
$Order->BillingDetails->LastName = 'Doe';
$Order->BillingDetails->CountryCode = "DE";
$Order->BillingDetails->State = 'Espírito Santo';
$Order->BillingDetails->City = 'City';
$Order->BillingDetails->Address1 = '-';
$Order->BillingDetails->Address2 = NULL;
$Order->BillingDetails->Zip = '1111111';
$Order->BillingDetails->Email = 'brazil1@2checkout.com';
$Order->BillingDetails->Phone = '123432323212';
$Order->BillingDetails->Company = 'blank';
$Order->DeliveryDetails = new stdClass();
$Order->DeliveryDetails->FirstName = 'John';
$Order->DeliveryDetails->LastName = 'Doe';
$Order->DeliveryDetails->CountryCode = 'NZ';
$Order->DeliveryDetails->State = 'Espírito Santo';
$Order->DeliveryDetails->City = 'City';
$Order->DeliveryDetails->Address1 = '-';
$Order->DeliveryDetails->Address2 = NULL;
$Order->DeliveryDetails->Zip = '1111111';
$Order->DeliveryDetails->Email = 'brazil1@2checkout.com';
$Order->DeliveryDetails->Phone = '123432323212';
$Order->DeliveryDetails->Company = NULL;
$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'GIROPAY';
$Order->PaymentDetails->Currency = "EUR" ;
$Order->PaymentDetails->HadPayPalToken = false;
$Order->PaymentDetails->CustomerIP = '10.5.22.197';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->PaymentMethod->ReturnURL = 'https://yourreturnurl.com';
$Order->PaymentDetails->PaymentMethod->CancelURL= 'https://yourcancelurl.com ';
$Order->Promotions = NULL;
$Order->AdditionalFields = NULL;
$Order->LocalTime = NULL;
$Order->GiftDetails = NULL;

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

Response Parameters

Response Example

class stdClass#9 (51) {
public $RefNo =>
string(8) "11796010"
public $OrderNo =>
int(0)
public $ExternalReference =>
NULL
public $ShopperRefNo =>
NULL
public $Status =>
string(7) "PENDING"
public $ApproveStatus =>
string(7) "WAITING"
public $VendorApproveStatus =>
string(2) "OK"
public $MerchantCode =>
string(7) "NCR_MCD"
public $Language =>
string(2) "en"
public $OrderDate =>
string(19) "2019-11-21 17:38:55"
public $FinishDate =>
NULL
public $Source =>
string(13) "sourceAPI.net"
public $Affiliate =>
class stdClass#10 (4) {
public $AffiliateCode =>
NULL
public $AffiliateSource =>
NULL
public $AffiliateName =>
NULL
public $AffiliateUrl =>
NULL
}
public $HasShipping =>
bool(false)
public $BillingDetails =>
class stdClass#11 (13) {
public $FiscalCode =>
NULL
public $TaxOffice =>
NULL
public $Phone =>
string(5) "12345"
public $FirstName =>
string(18) "Api First Name Bil"
public $LastName =>
string(17) "Api Last Name Bil"
public $Company =>
NULL
public $Email =>
string(20) "shopper@avangate.com"
public $Address1 =>
string(13) "Acasa Api Bil"
public $Address2 =>
string(14) "Acasa Api Bil2"
public $City =>
string(4) "Acre"
public $Zip =>
string(5) "12345"
public $CountryCode =>
string(2) "de"
public $State =>
string(4) "Acre"
}
public $DeliveryDetails =>
class stdClass#12 (11) {
public $Phone =>
string(5) "12345"
public $FirstName =>
string(18) "Api First Name Bil"
public $LastName =>
string(17) "Api Last Name Bil"
public $Company =>
NULL
public $Email =>
string(20) "shopper@avangate.com"
public $Address1 =>
string(13) "Acasa Api Bil"
public $Address2 =>
string(14) "Acasa Api Bil2"
public $City =>
string(4) "Acre"
public $Zip =>
string(5) "12345"
public $CountryCode =>
string(2) "de"
public $State =>
string(4) "Acre"
}
public $PaymentDetails =>
class stdClass#13 (4) {
public $Type =>
string(5) "OTHER"
public $Currency =>
string(3) "eur"
public $PaymentMethod =>
class stdClass#14 (6) {
public $Amount =>
string(3) "0.1"
public $Currency =>
string(3) "eur"
public $Redirect =>
class stdClass#15 (4) {
public $Url =>
string(37) "https://www.skrill.com/app/payment.pl"
public $Method =>
string(3) "GET"
public $Params =>
class stdClass#16 (1) {
public $sid =>
string(32) "c8cabebe0db1c280864e9ae294d956e2"
}
public $FullHtml =>
string(288) "<!DOCTYPE html><html><body><form action="https://www.skrill.com/app/payment.pl" method="GET" id="postform"><input type="hidden" name="sid" value="c8cabebe0db1c280864e9ae294d956e2" /></form><script type="text/javascript">document.getElementById(
        "postform").submit();</script></body></html>
public $ReturnURL =>
string(25) “https://yourreturnurl.com”
public $CancelURL =>
string(25) “https://yourcancelurl.com”

2Checkout's pricing configuration capabilities enable you to tailor the price details of your products/subscription plans to specific markets or geographic regions. The price, currency, and pricing options set per product can easily adapt to each market, providing a powerful tool to support your localization/globalization strategy.

Example:

A product costs $30 for US-based shoppers and 25 Euro for those in Germany. The 2Checkout system's localization capabilities make it possible for shoppers located in the United States to see the $30 price when adding the product to cart, with the US as the preselected billing country. Similarly, shoppers in Germany will get the 25 Euro localized price, when their country is preselected according to geolocation detection. The flexibility of the 2Checkout system also enables localized prices to be swapped for one another when shoppers manually select the billing country.

Availability

2Checkout Enterprise Edition accounts. 

Requirements

Pricing localization capabilities require the following:

1. Pricing Configurations enabled for your account.
2. Enable geolocation by IP address. 2Checkout uses real-time geo-location to determine shopper locale. Geo-location is enabled by default and should be active to ensure that localized pricing will work for your products.
3. To localize costs you first need to configure a new pricing configuration for a subscription plan/product on top of the Default.

Default pricing configuration

Each product features a Default pricing configuration designed to cover all available billing countries (it includes all markets as long as they aren't covered by any localized pricing strategies). 2Checkout defaults to this pricing configuration when IP geolocation is disabled.

2Checkout recommends you use pricing localization in tandem with IP geolocation. Without geo-location 2Checkout does not pre-select the billing country when shoppers first land in the shopping cart, and they will see the costs configured under the Default pricing configuration. 

Limitations

1. You cannot localize the Default pricing configuration. 
2. All new pricing configurations you add on top of the default are disabled by default until you edit the country details (assign at least one country to a pricing configuration to enable it for the shoppers in that specific market).
3. Marking a new, custom, localized pricing configuration as Default disables the default pricing configuration previously in use (detail reflected by the Not active for eStore status).
4. Transforming a custom, localized pricing configuration into the Default pricing configuration expands its country coverage worldwide, removing all its personalized localization settings.

Setup

1. Click the Add countries link in the eStore billing countries column of a pricing configuration to start adding markets/regions: Europe, the Middle East, and Africa, Asia-Pacific, Latin America, Rest of the World, and North America.
2. Select countries and assign them to the pricing configuration one by one or in bulk. Press and hold the Ctrl key to multi-select items. Once you added the countries for a local pricing configuration.
3. Click Save to save localization details of the pricing configuration and to activate it. When you assign all countries in a geographical region to a pricing configuration, 2Checkout displays the name of that region displayed under the eStore billing countries column. 2Checkout displays a maximum of five assigned standalone markets under the eStore billing countries column, for multi-market localized pricing configurations.

How do localized pricing configurations work?

Localized pricing configurations override the default pricing configuration when 2Checkout detects the shopper country. If the 2Checkout system can't determine the country of a shopper, the shopping cart display prices in accordance with the Default pricing configuration. However, if the shopper selects a country for which you defined a localized pricing configuration, the price details adapt accordingly.

Shoppers from countries not covered by any of their localized pricing configurations also see the price details of the default pricing configuration.

You can associate a specific country ONLY with a single localized pricing configuration at any given time. Re-assigning a country to another localized pricing configuration removes the market automatically from the localized pricing configuration it was part of.

While going through the stages of the purchase process, shoppers will be presented with the price set for the billing country selected in the cart (can be pre-selected, but users can also choose it manually). Per-product pricing details displayed to shoppers change if the billing country is modified to a different market governed by other pricing details. Shoppers will get this warning message in the cart: "The product options have been changed due to availability settings in the selected country."

Non-localized pricing configurations are also active, but not for eStore, as they can be used to supply price lists to your partners.

Localized pricing configuration options

You can create multiple pricing configurations for the same product, be as similar to one another or as different as you prefer. The following parameters can be completely different for multiple pricing configurations applied to the same product.

1. Pricing configuration type (with a base price, without base price, net, gross)
2. Price
3. Default currency
4. Pricing options
5. Renewal discounts
6. Volume discounts

As a result, they can control not only the actual price in accordance to specific geographic regions and countries but also pricing strategies.

Pricing localization and product SKUs

You have the option of configuring stock-keeping units (SKUs) each pricing configuration in the 2Checkout platform, and associate unique SKUs in accordance with the currencies, volume discounts (if any), purchase type and pricing options (if any) settings impacting products when localizing their pricing configurations. 

Upselling and Cross-selling

Localized pricing settings impact their upselling and cross-selling marketing campaigns.

upselling

When configuring upselling campaigns, you'll need to factor in localized pricing strategies for the primary and recommended products. There are four scenarios you need to consider, related to the type of upselling campaigns available.

As a rule of thumb, consider the default pricing configuration of your offerings as the central element of upselling campaigns when pricing options are also involved. In scenarios in which the Primary product of an upselling campaign has pricing options set up for the default pricing configuration, they'll also be available when configuring the upselling recommendation. Pricing options will not be displayed in the Upselling recommendation area when editing a campaign if they're only defined for the localized pricing configurations of the Primary product, but not the default.

Similarly, the pricing options of the Recommended product will only be displayed in the Upselling recommendation area when editing a campaign only if they were enabled for the Default pricing configuration. If not featured under the Default pricing configuration but only for localized pricing configurations, the pricing options will not be available when configuring upselling campaigns.

Cross-selling

Cross-selling campaigns function regardless of the pricing configurations set up for their products. Shoppers located in a country governed by a localized pricing configuration will be able to select the pricing options associated to their locale for the main products and for the cross-selling items as well.

However, if the products are automatically added to cart, they're pricing options will be locked, and shoppers won't have the possibility of editing them (offerings will come with pre-selected pricing options, and the system will disregard the availability of alternatives, which will never be displayed in the cart).

Localized pricing for subscription renewals

When renewing a subscription, the 2Checkout system will correlate the renewal price with that of the initial purchase. Renewal prices can be defined as a part of the default and localized pricing configurations for products with base and without base price.

Essentially, subscriptions initially acquired by shoppers in a specific market governed by a localized pricing configuration, will be renewed in accordance to the same pricing configuration and billing country. Renewal prices will not vary in any way, even if shoppers change the billing country to a market assigned to a different pricing configuration than the one from which they made the initial acquisition.

Renewals made by using the 2Checkout API are impacted by the same limitation, namely, the price will not adapt when the billing country is changed, but will reflect the market in which shoppers were located when they initially purchased the subscription.

Upgrades

When upgrading a product, the 2Checkout system correlates the upgrade price with that of the initial purchase.

2Checkout does not change the localized pricing configuration and billing country when upgrading a subscription, reflecting the initial purchase. Upgrade costs do not vary, even if shoppers change the billing country to a market assigned to a different pricing configuration than the one from which they made the initial acquisition.

Upgrades made by using the 2Checkout API are impacted by the same limitation, namely, the price does adapt when the billing country is changed, but will instead reflect the market in which shoppers were located when they initially purchased the product.

New purchases, renewals and upgrades through API - localized pricing

The 2Checkout API supports localized pricing capabilities.

New purchases

The billing country set by using 2Checkout API causes the price details to be adapted accordingly if you localized the pricing configuration for that specific market.  If there's no match between the localized pricing configuration and the billing country, 2Checkout uses the default pricing configuration used instead.

Upgrades

Upgrades through the 2Checkout API take into account the billing country associated with the initial subscription for the pricing details of the target subscription of the upgrade process. 2Checkout uses the localized pricing configuration of the target subscription plan in accordance with the billing country of the initial subscription.

Note: If the upgrade subscription/product does not feature a pricing configuration localized on a specific market, then the system uses the item's Default pricing configuration.

Renewals

Subscription renewals through the 2Checkout API use the price options from the localized pricing configuration, but you control the price and the billing cycle following the renewal independently of the subscription plan configuration.

Overview

Retrieve the costs of the next subscription renewal.

Attributes

Overview

Renew a subscription in the Avangate system on-demand, controlling the number of days, price and currency of the extension. Use the renewSubscription method renew a 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;
}
$subscriptionReference = '30E47F8699';
$Days = 4;
$Price = 50;
$Currency = 'eur';
try {
    $CustomPrice = $client->renewSubscription($sessionID, $subscriptionReference, $Days, $Price, $Currency);
}
catch (SoapFault $e) {
    echo "CustomPrice: " . $e->getMessage();
    exit;
}
var_dump("CustomPrice", $CustomPrice);

Set up A/B testing campaigns for backup media options to identify the best way to offer backup media to your shoppers.

Requirements & limitations

The Backup Media Options A/B test will only be available if Backup Media Options are active for your account.

Important

When shoppers place the orders, the test is considered successful regardless of the order or payment status.

Setup

1. Go to the A/B Testing page and click Overview.
2. Click the New campaign button in the Backup Media options section. If you already have an unfinished campaign, click Edit.
3. Fill in the details of the new campaign, such as the campaign name, maximum number of tests and the date when the campaign should end.
4. Add the test variations by allocating traffic to each of them and selecting the desired Backup Media options.

1. Click Add variation.
2. Repeat steps 4 and 5 until you have used the entire available traffic.
3. Click Save campaign.
4. Go back to the Overview tab and click the Start Campaign button when you want the campaign to begin.