Overview

Retrieve information about the upgrade options for a specific subscription.

Overview

Use the addPromotion method via JSON-RPC API 4.0 to create a new 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);

$promotionObject = new stdClass;
$promotionObject->Name = 'YOUR_PROMOTION_TITLE';
$promotionObject->Description = 'YOUR_PROMOTION_DESCRIPTION';
$promotionObject->StartDate = date('Y-m-d', strtotime('1 month ago'));
$promotionObject->EndDate = date('Y-m-d', strtotime('+1 month'));
$promotionObject->Type = 'REGULAR';
$promotionObject->Enabled = 1;
$promotionObject->MaximumOrdersNumber = 0;
$promotionObject->MaximumQuantity = 0;
$promotionObject->InstantDiscount = false;
$promotionObject->ChannelType = 'ECOMMERCE';
$promotionObject->ApplyRecurring = 'NONE';
$promotionObject->RecurringChargesNumber = 3;
$promotionObject->PublishToAffiliatesNetwork = 0;
$promotionObject->InstantDiscount = 0;

$couponObject = new stdClass;
$couponObject->Type = 'SINGLE';
$couponObject->Code = 'single_code';
$promotionObject->Coupon = $couponObject;

$discountObj = new stdClass;
$discountObj->Type = 'PERCENT';
$discountObj->Value = 30;
$promotionObject->Discount = $discountObj;
$promotionObject->Products = [$productsObj1, $productsObj2, $productsObj3];
$promotionObject->Translations = [$translation1, $translation2];

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

$result = callRPC((object)$jsonRpcRequest, $host);
var_dump($result);

Overview

Use the placeOrder method to create an order using products defined in your Control Panel and collect the payment using credit card based payment methods.

Parameters

Requirements

For credit card orders placed using API 5.0, you need to pass through additional parameters that support the 3D Secure flow. 3D Secure works by redirecting customers to pages provided by their banks, where they need to enter additional security tokens or password to trigger the completion of the charge. By using 3D Secure, you get additional protection from liability for fraudulent card payments, with customers having to go through an extra layer of authentication. Send the following parameters in the placeOrder call:

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->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 = 'my_subscription_1';
$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 = 'First';
$Order->BillingDetails->LastName = 'Last';
$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 = 'email@address.com';
$Order->BillingDetails->Phone = NULL;
$Order->BillingDetails->Company = NULL;
$Order->DeliveryDetails = NULL;

$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'CC';
$Order->PaymentDetails->Currency = 'usd';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->CustomerIP = '10.10.10.10';
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = true;
$Order->PaymentDetails->PaymentMethod->CardNumber = "4111111111111111";
$Order->PaymentDetails->PaymentMethod->CardType = 'visa';
$Order->PaymentDetails->PaymentMethod->ExpirationYear = '2019';
$Order->PaymentDetails->PaymentMethod->ExpirationMonth = '12';
$Order->PaymentDetails->PaymentMethod->CCID = '123';
$Order->PaymentDetails->PaymentMethod->HolderName = 'John';
$Order->PaymentDetails->PaymentMethod->CardNumberTime = 83.21; // can be null - high value in seconds is a red flag for fraud attempts.
$Order->PaymentDetails->PaymentMethod->HolderNameTime = 13.35; // can be null - high value in seconds is a red flag for fraud attempts.
$Order->PaymentDetails->PaymentMethod->Vendor3DSReturnURL = "http://www.success.ro";
$Order->PaymentDetails->PaymentMethod->Vendor3DSCancelURL = "http://www.error.ro"; 

$Order->Promotions = NULL;
$Order->AdditionalFields = NULL;
$Order->LocalTime = NULL;
$Order->GiftDetails = NULL;

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

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

Overview

Retrieve information about the upgrade options for a specific subscription.

Overview

With the roll-out of Strong Customer Authentication regulation in Europe, the use of 3D Secure Authentication becomes mandatory for all payments made with Credit Cards. In order to integrate the 2Checkout API, 3DS 2.0 support needs to be implemented for both direct API orders made with credit card details as well as with 2pay tokens.

More information on the 3DS and PSD2 information can be found on our blog.

Availability

Available for all 2Checkout accounts.

3DS Secure Flow

Additional parameters are required in order to support the 3D Secure flow and this works by redirecting customers to pages provided by their banks, where they need to enter additional security tokens or passwords to trigger the completion of the charge. By using 3D Secure, you get additional protection from liability for fraudulent card payments, with shoppers having to go through an extra layer of authentication.

These are the required steps for the 3DS flow:

1. The shopper fills in the payment details and places an order.

2. The merchant processes the order.

The merchant receives the shopper's data from the checkout page and triggers an order to 2Checkout with their information, including credit card data: cardholder name, credit card number, expiration date, and CVV are the mandatory fields.

Additionally, the merchant needs 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.

3. 2Checkout processes the order from the merchant. The 2Checkout API will respond to the placeOrder API call with the order information or an error message.

4. The merchant processes the 2Checkout response.

Since 3DS is not always mandatory, how do we know when we are not on the 3DS flow?

If the order in the response is in Status AUTHRECEIVED or COMPLETE and PaymentDetails node looks like this, then the order does not require 3DS authorization.

{
  "Type": "CC",
  "Currency": "usd",
  "PaymentMethod": {
    "FirstDigits": "4111",
    "LastDigits": "1111",
    "CardType": "visa",
    "RecurringEnabled": false,
    "Vendor3DSReturnURL": null,
    "Vendor3DSCancelURL": null,
    "InstallmentsNumber": null
  },
  "CustomerIP": "10.11.12.1"
}

For 2pay tokens, the request is similar, as the credit card details are replaced by the encrypted token.

After this response, the shopper is redirected to the Finish page.

If the order in the response is in Status PENDING and the PaymentDetails node contains the Authorize3DS node, it'll look like this:

{
  "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"

5. The merchant redirects the shopper to the 3DS page.

The actual authorization is not done yet, but it will be completed after redirecting the shopper to the Authorize3DS URL where they enter the 3DS code. 

Example of URL (composed from Authorize3DS['href'] and Authorize3DS['Params']):

http://api.sandbox63.avangate.local/6.0/scripts/credit_card/authorize?avng8apitoken=50dcb997be8b70bd

6. The shopper authenticates the payment.

The shopper reaches the bank's 3D Secure page, where they must complete the authentication flow by use of a one-time password (OTP) sent to their mobile phones by the issuing bank, or by use of a personal PIN.

7. The issuing bank processes the authentication request.

Based on the status of the authentication flow, the shopper is redirected back to the merchant's site, to the URL for either the success (Vendor3DSReturnURL) or the failed flow (Vendor3DSCancelURL). 

8. The merchant handles the 3DS flow result.

The shopper is redirected to the appropriate page, where the merchant needs to handle that specific case.

Integration test cases

Using the test credit cards available here, follow the next steps:

1. Build a request in order to place a new order, with all the relevant information. Make sure that when the order is sent in the API, the response contains an order object (order was placed successfully).
2. Handle the 3DS flows, both when 3DS is mandatory (and the shopper needs to be redirected to authorize the transaction), as well as where this is not needed (order is created with status AUTHRECEIVED or COMPLETE).
3. If you have any additional webhook integrations, make sure that the webhooks are correctly configured and that the notifications are received and processed successfully. 

Overview

Retrieve the current cart session content, and learn insights about your customers' actions in cart.

You can obtain the VAT or sales TAX based on current cart items, prefill the customer information based on the subscription reference, or get the price applied in the cart by using the API method from below.

Overview

Some of the Inline Checkout parameters require a signature to prevent any interference in the ordering process. Optional parameters also require a signature if they are included in the Inline Checkout. You can read here which parameters require a signature.

Demo Sample

In order to attach the signature of signed parameters to the TwoCoInlineCart library, use the setSignature() method.

TwoCoInlineCart.setup.setMerchant('MERCHANT_CODE');
...
TwoCoInlineCart.cart.setSignature('<signature>');
...
TwoCoInlineCart.cart.checkout();

Overview

Starting with 2Checkout API 5.0, search methods are including the option of pagination. Pagination has been developed for decreasing the request loading time while allowing you to better handle the returning responses.

How does it work?

Pagination works on all the search methods existing on 2Checkout API 5.0. The default pagination behavior is to display page 1 with 10 results. The maximum number of items displayed on a single page is 200.

Parameters

To use pagination, include the Pagination object inside the search method call, using the parameters below:

Response

The response of search methods that are including pagination will contain a new object, with the following parameters:

Sample request

The below PHP sample includes a search method for subscriptions.

<?php

require('PATH_TO_AUTH');

$SubscriptionSearch = new stdClass();
$SubscriptionSearch->CustomerEmail  = 'email@avangate.com';
$SubscriptionSearch->DeliveredCode = null;
$SubscriptionSearch->AvangateCustomerReference = null;
$SubscriptionSearch->ExternalCustomerReference = null;
$SubscriptionSearch->Aggregate = false;
$SubscriptionSearch->SubscriptionEnabled = null; //true false null
$SubscriptionSearch->RecurringEnabled = null; // true - autorenewal, false - manual renewal, null = both(default)
$SubscriptionSearch->ProductCodes = null; //array('Product_Code1', 'Product_Code2');
$SubscriptionSearch->CountryCodes = null;//array ('au')
$SubscriptionSearch->PurchasedAfter = null;
$SubscriptionSearch->PurchasedBefore = null;
$SubscriptionSearch->ExpireAfter = null;
$SubscriptionSearch->ExpireBefore = null;
$SubscriptionSearch->LifetimeSubscription = null;
$SubscriptionSearch->Type = 'regular'; //'trial', 'regular', 'regularfromtrial'
$SubscriptionSearch->TestSubscription = null; // true, false, null = both(default)
$SubscriptionSearch->Pagination = new stdClass();
$SubscriptionSearch->Pagination->Page = 1; // set the number of pages for the response
$SubscriptionSearch->Pagination->Limit = 200; // set the limit for the values from the response

try {
    $accountSubscriptions = $client->searchSubscriptions($sessionID, $SubscriptionSearch);
}
catch (SoapFault $e) {
    echo "accountSubscriptions: " . $e->getMessage();
    exit;
}
var_dump("accountSubscriptions", $accountSubscriptions);

Overview

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

Retrieve shipping price

Shipping price object

Overview

Use the addPromotionSources method to define new sources for an existing promotion.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

// Promotion code corresponding to the promotion you want to add sources to
$promotionCode = '';

// Sources array with the source values 
$sources = ['source1', 'source2'];

try {
    $updatedPromotion = $client->addPromotionSources($promotionCode,$sources);
}

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

var_dump("UpdatedPromotion", $updatedPromotion);