Overview

Use the searchPriceOptionGroups to extract information on the price option groups you configured.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$SearchOptions = new \stdClass();
//$searchObject->Name = 'optionGroupA';
$SearchOptions->Types = ["RADIO"];
$SearchOptions->Pagination = new stdClass();
$SearchOptions->Pagination->Page = 1;
$SearchOptions->Pagination->Limit = 200;

$jsonRpcRequest = new stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method = 'searchPriceOptionGroups';
$jsonRpcRequest->params = array($sessionID, $SearchOptions);
$jsonRpcRequest->id = $i++;

$searchProducts = callRPC($jsonRpcRequest, $host);

?>

Overview

Get information about all the pricing lists available to a specific partner and which can be used for a new purchase.

Requirements

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

try {
    $PartnerPricingLists= $client->getPartnerPricingLists ($sessionID);
} catch (SoapFault $e) {
    echo "PricingLists: " . $e->getMessage();
    exit;
}
var_dump ("PricingLists", $PartnerPricingLists);

Errors

Overview

In 2007, against the backdrop of a continuously growing eCommerce market, the European Commission (EC) and the European Banking Authority (EBA) concluded that it was time consumers were offered a wider choice of secure payment services. Thus, the two regulatory bodies encouraged the rise of non-bank financial institutions that could provide the digital market with faster payment options, but at the same time increasing consumer protection and transaction transparency. This is how the first Payment Services Directive (PSD) came into being.

In 2015, in an eCommerce market dominated by increasing mobile usage and internet payments, the EC decided to review and adjust the PSD to the current digital context, adding necessary improvements to ensure customer security. As a result, PSD2 came into effect on January 13th, 2018 bringing clear changes and significant enhancements to the payment industry regulations.

Payment Services Directive 2 (PSD2)

What is PSD2 bringing new?

With an initial start on January 13th, 2018, the Payment Services Directive 2 (PSD2) has taken effect in the entire European Union in the local legislation. Although not all areas are in effect yet, PSD2’s biggest relevant changes for the European online sellers are related to:

• Security of payments done by European Union shoppers through mandatory Strong Consumer Authentication component (SCA)

• Access to an account (XS2A) for account information and payment initiation services –allowing bank customers to give access to third-party providers to retrieve data and initiate payments directly from banks accounts

• Recurring transactions treatment

PSD2 Requirements

The PSD2 requirements are based on three pillars:

• Pillar 1 addresses transparency in terms of pricing, extended customer rights, and stricter reporting standards for banks. It applies to transactions where at least one party (one Leg out) is in the European Economic Area (EEA).
• Pillar 2 concerns security, including requirements for strong customer authentication (SCA). This impacts all parties involved in the eCommerce flow.
• Pillar 3 sets out the technological requirements by which banks must allow Payment Institutes to use their infrastructure to access account data and initiate payments on behalf of customers. 

Compliance with PSD2 is to be implemented in two stages: Pillar 1 (transparency) became effective on January 13th, 2018, while Pillars 2 and 3 must come into force on September 14th, 2019.

Strong Customer Authentication (SCA)

To prevent ever-evolving fraud methods, starting September 14th, 2019, Payment Service Providers (PSPs), such as 2Checkout, must apply extra security steps to implement SCA and further protect the confidentiality of consumers’ data.

SCA increases the smoothness and the security of the transaction, therefore increasing the trust level of the merchant and the consumer bank who will be more willing to authorize and to complete the consumer's purchase because they trust the security of the transaction.

The implementation of SCA will be based on a 3-layer authentication method, out of which at least two layers will be mandatory for customers:

• knowledge (something the customer knows, like a password or PIN),
• possession (something the customer has, such as a smartphone, application, token) and
• inherence (something the customer is – fingerprint or face recognition).

For card-based payments, this resulted in the implementation of 3D Secure version 2 (3DS2 or EMV 3DS). 3D Secure has been employed to secure online card transactions since 2001, but now a new version has been developed to meet the PSD2 SCA requirements. Basically, to be able to accept payments from the world’s largest card networks (Visa, Mastercard, Amex,etc.), any merchant will need to have implemented 3D Secure version 2 for their online store. The initial start will be mainly EU-based merchants and their clients. Outside the EU, the current implementation pace of the 3D Secure 2 is considered slow and less dominant.

3D Secure 2 is an evolutionary step from its predecessor and allows the card issuer (bank) to use a wider range of data-points from the transaction to run a risk-based analysis. For low-risk transactions and low-value (< 30 EUR), the card issuer will not send an authentication request to the cardholder, although authenticating the transaction. However, for all other customer-initiated transactions, the cardholder will be required to authenticate with an SMS/APP or other biometric means.

3D Secure 2 will be mobile-friendly unlike its previous version, so it will display a responsive design easily adjustable to any mobile device and will also bring improvements in terms of UX.

SCA applies also to alternative payment methods, but it’s important to note that many e-wallets, or other mobile payment services, already have SCA implemented, as these services already use multiple-step authentication.

What is the 3D Secure version 2 flow?

Unlike 3D Secure version 1, 3D Secure version 2 makes it easier for banks to offer innovative authentication experiences through their mobile banking applications. Instead of entering a password or just receiving a text message on their mobile phone, the cardholder can authenticate a payment through the banking application by simply using their fingerprint or even facial recognition.

The second improvement in user experience is that 3D Secure 2 is designed to embed the challenge flow directly within the web and mobile checkout flows, without requiring full page redirects.

3D Secure version 2 is the technical solution to comply with the SCA regulations. 2Checkout will support two types of flows:

• Frictionless flow – if the issuing bank considers the transaction to be secure, shoppers don't have to authenticate themselves, hence no friction in the payment process,
• Challenge flow – if the issuing bank requires more proof to authenticate a transaction, it can request additional information from the customer like a password that the cardholder will need to provide via an SMS or a generated token from a mobile device and fill it into the issuer webpage, just as it happens now with the current version of the 3D Secure. 

Transactions that require Strong Consumer Authentication (SCA)

SCA will be required for all customer-initiated online transactions (CIT) within Europe, which means most payment options (contactless payments included) and bank transfers are performed with SCA. In the case of online payments, SCA will apply to transactions where both the business and the cardholder’s banks are located within the European Economic Area (EEA).

The 3D Secure version 2 protocol itself will allow payment providers like 2Checkout to request exemptions from SCA and skip authentication for low-risk payments. Payments that require SCA will need to go through the ‘challenge’ flow, whereas transactions that can be exempted from SCA can be sent through the ‘frictionless’ flow.

An online seller cannot apply for these exemptions themselves, but a payment provider can apply on their behalf.

SCA Exemptions

The SCA exemptions mentioned below refer only to online transactions (eCommerce), but it’s good to remember that there are other offline transactions that are impacted by SCA which, however, will not be mentioned here. Merchant-initiated transactions (MIT), such as recurring billing will not require SCA, with some exceptions. Read the list below to find out the SCA exemptions that apply to online commerce transactions:

Impact for merchants

• Increased security for transactions, limiting the fraud cases and also decrease of chargebacks
• Customer experience will be affected as the SCA will introduce new steps in the checkout and might affect conversion rates, therefore merchants need to have communication and choose the best flows for their shopper to avoid disruption as much as possible. Online sellers, 2Checkout as well, will attempt to use SCA as little as possible, but it won’t be possible to avoid it completely. The exemption has to be sought from and granted by the shopper’s issuing bank, who remains the ultimate arbiter on this.
• UX for mobile checkout experience will be improved, as 3D Secure version 2 is focused on mobile and tablet, which was an issue with the current version, thus it will increase conversion rates from mobile visitors
• Competitive prices as a result of market openness and the fact that banks will share their data to be used by third parties

Impact for shoppers

• Safer and more secure payments, limiting the fraud cases
• Lengthier checkout flow due to the two mandatory authentication layers for customers
• Lower prices for payments/banking and non-banking services due to increased market competitiveness on longer-term

How we help our merchants

2Checkout payment solutions are constantly optimized and updated to follow the latest bank and card network regulations and will apply relevant exemptions for low-risk payments to only trigger authentication when required. We have designed our SCA-ready payment solutions to let you take advantage of exemptions when possible and help protect your conversion.

We are upgrading our checkout pages and our payment APIs that support strong customer authentication, in a way that is designed to keep changes for merchants at a minimum and minimize the impact of SCA on your checkout conversion.

Recommendations for online merchants

• Multiple models flexibility and having intelligent payment routing with a multitude of processors with SCA support helps merchants worry less about the conversions/authorization rates impact as we can test user experience impact by routing the transactions to different flows treating exceptions of SCA and/or combination of authentication factors implementations
• Having access to alternative payment methods that were already built-in with SCA traits will give additional choice to buyers without disrupting their flow – i.e. iDeal, Bancontact, SEPA Payments, mobile wallets
• Having analytics, customization and advanced ordering engine/eCommerce will empower merchants to understand and reduce friction with proper communication or different flows (i.e. retry pages, change of payment method, abandons recovery, dunning, etc). We see this as an upgrade of technologies in the financial ecosystem and immediate impact on Card, not Present transactions is a growth of omnichannel with focus on mobile but also increased subscriptions volumes given the transparency of the renewal process (if different pricing or recurring interval subscriber is informed and asked to authenticate).

Related links

Overview

Use the convertTrial method to convert a trial to a paid subscription. In the eventuality of a conversion failure, you can use convertTrial again for the same trial subscription only after you let 24 hours pass since the initial attempt. The 2Checkout system attempts to automatically convert trials before they expire to full subscriptions unless you made an attempt that failed less than 24 hours before the scheduled expiration deadline.

In case the trial conversion fails due to a transaction issue, the 2Checkout system sends unfinished payment follow-up emails to customers, provided that you set up lead management for your account.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH'); 
 
$SubscriptionReference = 'BF44555C6C';

$ExtendSubscriptionFromPaymentDate = true; //false can also be used if you want the subscription start date to be the moment when the trial was set to initially expire.

try {
    $convertedTrial = $client->convertTrial($sessionID, $SubscriptionReference, $ExtendSubscriptionFromPaymentDate);
}
catch (SoapFault $e) {
    echo "convertedTrial: " . $e->getMessage();
    exit;
}
var_dump("convertedTrial", $convertedTrial);

Watch this tutorial to see how you can pause a subscription from your Merchant Control Panel.

Overview

Use the convertTrial method to convert a trial to a paid subscription. In the eventuality of a conversion failure, you can use convertTrial again for the same trial subscription only after you let 24 hours pass since the initial attempt. The 2Checkout system attempts to automatically convert trials before they expire to full subscriptions, unless you made an attempt that failed less than 24 hours before the scheduled expiration deadline.

In case the trial conversion fails due to a transaction issue, the 2Checkout system sends unfinished payment follow-up emails to customers, provided that you set up lead management for your account.

Parameters

Response

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;
}
$SubscriptionReference = '30E47F8699';
$ExtendSubscriptionFromPaymentDate = true; //false can also be used if you want the subscription start date to be the moment when the trial was set to initially expire.
try {
    $convertedTrial = $client->convertTrial($sessionID, $SubscriptionReference, $ExtendSubscriptionFromPaymentDate);
}
catch (SoapFault $e) {
    echo "convertedTrial: " . $e->getMessage();
    exit;
}
var_dump("convertedTrial", $convertedTrial);

Overview

Use the issueRefund method to issue a partial refund for an order processed by 2Checkout.

Requirements 

The payment for the refundable order needs to be collected.

You cannot issue a refund for an amount higher than the total order amount.

Request

<?php

$host = 'https://api.avangate.com';
$merchantCode = "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 = "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'); //GMT date format)
$algo = "sha256";
$string = strlen($merchantCode) . $merchantCode . strlen($now) . $now;
$hash = hash_hmac($algo, $string, $key);

try {
    $client = new SoapClient($host . "/soap/6.0/?wsdl", [
        'location'       => $host . "/soap/6.0/",
        "stream_context" => stream_context_create([
            'ssl' => [
                'verify_peer'      => false,
                'verify_peer_name' => false
            ]
        ])
    ]);
    $sessionID = $client->login($merchantCode, $now, $hash, $algo);
    echo("Token: {$sessionID}" . PHP_EOL);

    $orderReference = "73152871";
    $items = [];
    $item = new stdClass();
    $item->Quantity = 1;
    $item->LineItemReference = "a439c84a4b1e8ad1d7bf38407f5ea7473433ce7b";
    $item->Amount = 29.99;

    $items[] = $item;
    $comment = "This is a comment";
    $reason = "Fraud";

    $refundedOrder = $client->issueRefund($sessionID, $orderReference, null, $items, $comment, $reason);
    var_dump($refundOrder);
} catch (SoapFault $e) {
    echo "Authentication: " . $e->getMessage() . PHP_EOL;
    exit;
} 

Response

Watch this tutorial to see how to set free trials for your customers in your Merchant Control Panel.

Overview

Use deletePromotionProducts to remove products from an existing promotion.

Parameters

Response

Request

<?php

function callRPC($Request, $host, $Debug = true) {
    $curl = curl_init($host);
    curl_setopt($curl, CURLOPT_POST, 1);
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($curl, CURLOPT_VERBOSE, true);
    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)) {
        var_dump($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.1/';

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

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

$promotionCode = '';

// 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 = [''];

$productPromotion = [$newProduct1, $newProduct2];

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