Overview

Under the Payment Services Directive 2 (PSD2) initiative, in order to prevent ever-evolving fraud methods, Payment Service Providers (PSPs), such as 2Checkout, must apply extra security steps to implement Strong Customer Authentication (SCA) and further protect the confidentiality of consumers’ data. 

For more details about 3D Secure support in API, check the Payment Services Directive 2 (PSD2) article.  

You can also read the resources below to have a better understanding of what is PSD2 and what it entails: 

• What is the 2nd Payment Service Directive (PSD2)? 
• What is PSD2 and What Does Strong Customer Authentication (SCA) Mean for You? 
• The Impact of PSD2 and SCA: Ordering Flows and Exemptions 

Impact 

All merchants using the 2Checkout Public API versions 3.0, 3.1, and 4.0, on all protocols, are affected by this change.  

In order to avoid your orders being declined due to the lack of 3DS, we recommend you migrate to API version 6.  

How to migrate 

Migrating your placeOrder call to API 6.0 is as simple as updating the endpoint: 

• REST: https://api.2checkout.com/rest/ 
• SOAP: https://api.2checkout.com/soap/6.0/ 
• JSON-RPC: https://api.2checkout.com/rpc/6.0/ 

Once you’ve migrated to API 6.0, you need to provide two mandatory parameters in the paymentMethod object:  

• Vendor3DSReturnURL - the URL address to which customers are redirected after the 3DS details get validated by the bank and the order is successfully authorized. 
• Vendor3DSCancelURL - the URL address to which customers are redirected if the 3DS details were not validated or the order could not be authorized. 

Once the order has been submitted, you will find a new property in the API response - Authorize3DS. 

Based on the parameters provided in Authorize3DS, you need to build and redirect the shopper to a page where they will finalize the 3DS flow.

{ 
  "Type": "CC", 
  "Currency": "usd", 
  "PaymentMethod": { 
    "Authorize3DS": { 
      "Href": "http://api.sandbox63.avangate.local/6.0/scripts/credit_card/authorize", 
      "Method": "GET", 
      "Params": { 
        "avng8apitoken": "50dcb997be8b70bd" 
      } 

    }, 

    "Vendor3DSReturnURL": "http://shopping.cart.local/checkout/external/return/cc", 
    "Vendor3DSCancelURL": "http://shopping.cart.local/checkout/external/cancel/cc", 
    "FirstDigits": "4111", 
    "LastDigits": "1111", 
    "CardType": "Visa", 
    "RecurringEnabled": false 

  }, 
  "CustomerIP": "10.11.12.1" 

The shopper needs to be redirected to: http://api.sandbox63.avangate.local/6.0/scripts/credit_card/authorize?avng8apitoken=50dcb997be8b70bd 

Once the order is approved by the shopper, 2Checkout will update the order status and trigger the webhook notifications.  

You can read more information on the 3DS flow here. 

Overview

Use the getSubscriptionAdditionalInformation method to retrieve all the additional information fields belonging to a subscription.

Parameters

Response

Request

<?php

require('PATH_TO_AUTH');

$subscriptionReference = '351D8F557E';

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

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

Overview

Place an order with catalog products without requiring any payment information from your customers (free orders).

Requirements

The final order price has to be 0. Either use products with 0 price, or add a promotion for 100% of the total order price. It's mandatory to set RecurringEnabled to false.

Parameters

Response 

Request

<?php

require ('PATH_TO_AUTH');

$Order = new stdClass();
$Order->RefNo = NULL;
$Order->Currency = 'usd';
$Order->Country = 'US';
$Order->Language = 'en';
$Order->CustomerIP = '91.220.121.21';
$Order->ExternalReference = NULL;
$Order->Source = NULL;
$Order->AffiliateId = NULL;
$Order->CustomerReference = NULL;
$Order->Items = array();
$Order->Items[0] = new stdClass();
$Order->Items[0]->Code = 'my_subscription_1'; // product needs to have 0 price
$Order->Items[0]->Quantity = 1;

$Order->BillingDetails = new stdClass();
$Order->BillingDetails->FirstName = 'John';
$Order->BillingDetails->LastName = 'Doe';
$Order->BillingDetails->CountryCode = 'us';
$Order->BillingDetails->State = 'California';
$Order->BillingDetails->City = 'LA';
$Order->BillingDetails->Address1 = 'Address example';
$Order->BillingDetails->Address2 = NULL;
$Order->BillingDetails->Zip = '90210';
$Order->BillingDetails->Email = 'john.doe@2checkout.com';
$Order->BillingDetails->Phone = NULL;
$Order->BillingDetails->Company = NULL;

$Order->DeliveryDetails = NULL;

$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'FREE';
$Order->PaymentDetails->Currency = 'usd';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = false;

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

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

var_dump($order);

Overview

Use the getSubscriptionAdditionalInformationField method to retrieve information related to an additional information field belonging to a subscription.

Parameters

Response

Request

<?php

require('PATH_TO_AUTH');

$subscriptionReference = '351D8F557E';
$fieldName = 'subscription';


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

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

Overview

Use the deleteSubscriptionAdditionalInformationField method to delete the additional information field from a subscription.

Parameters

Response

Request

<?php

require('PATH_TO_AUTH');

$subscriptionReference = '351D8F557E';
$fieldName = 'subscription';
$fieldValue = 'test';

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

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

Overview

Use the updateSubscriptionAdditionalInformationField method to update the additional information field from to a subscription.

Requirements 

The maximum field length is 100 characters.

Parameters

Response

Request

<?php

require('PATH_TO_AUTH');

$subscriptionReference = '351D8F557E';
$fieldName = 'subscription';
$fieldValue = 'test2';

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

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

Overview

Include payment (credit/debit card) information that Avangate uses for recurring billing to renew imported subscriptions. Importing subscriptions with payment data is available only to eligible Avangate accounts. Contact Avangate directly for additional details.

Use the addSubscription method to import a subscription into the Avangate system.

Parameters

Response

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);
$Product = new stdClass ();
$Product->ProductCode = 'my_subscription_1';
$Product->ProductId = 4639321;
$Product->ProductName = 'Avangate Subscription Imported';
$Product->ProductVersion = 1.0;
$Product->ProductQuantity = 3;
$Product->PriceOptionCodes = array();
$EndUser = new stdClass ();
$EndUser->Address1 = 'Address line 1';
$EndUser->Address2 = 'Address line 2';
$EndUser->City = 'LA';
$EndUser->Company = 'Company Name';
$EndUser->CountryCode = "US";
$EndUser->Email = 'customerAPI@avangate.com';
$EndUser->FirstName = 'Customer';
$EndUser->Language = 'en';
$EndUser->LastName = 'Avangate';
$EndUser->Phone = '1234567890';
$EndUser->State = 'California';
$EndUser->Fax = NULL;
$EndUser->Zip = '90210';
$Subscription = new stdClass();
$Subscription->ExternalSubscriptionReference = '12345678912ImportedSubscription';
$Subscription->SubscriptionCode= NULL;
$Subscription->StartDate = '2013-01-01';
$Subscription->ExpirationDate = '2017-12-30';
$Subscription->Product = $Product;
$Subscription->EndUser = $EndUser;
$Subscription->ExternalCustomerReference = '12354678ExtCustRef';

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

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

Overview

Use the getSubscriptionAdditionalInformation method to retrieve all the additional information fields belonging to a subscription.

Parameters

Response

Request

<?php

require('PATH_TO_AUTH');

$subscriptionReference = 'F27CFE06ED';

try {
    $subscriptionInfo = $client->getSubscriptionAdditionalInformation($sessionID, $subscriptionReference);
}
catch (SoapFault $e) {
    echo "subscriptionInfo: " . $e->getMessage();
    exit;
}
var_dump("subscriptionInfo", $subscriptionInfo);

Overview

Use the getSubscriptionAdditionalInformation method to retrieve all the additional information fields belonging to a subscription.

Parameters

Response

Request

<?php

require('PATH_TO_AUTH');

$subscriptionReference = 'F27CFE06ED';

try {
    $subscriptionInfo = $client->getSubscriptionAdditionalInformation($sessionID, $subscriptionReference);
}
catch (SoapFault $e) {
    echo "subscriptionInfo: " . $e->getMessage();
    exit;
}
var_dump("subscriptionInfo", $subscriptionInfo);

Overview

Use the getSubscriptionAdditionalInformationField method to retrieve information related to an additional information field belonging to a subscription.

Parameters

Response

Request

<?php

require('PATH_TO_AUTH');

$subscriptionReference = 'F27CFE06ED';
$fieldName = 'subscription';

try {
    $subscriptionInfo = $client->getSubscriptionAdditionalInformationField($sessionID, $subscriptionReference, $fieldName);
}
catch (SoapFault $e) {
    echo "subscriptionInfo: " . $e->getMessage();
    exit;
}
var_dump("subscriptionInfo", $subscriptionInfo);