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

Overview

Place an order with catalog products defined in your Merchant Control Panel and collect the payment using iDEAL.

Requirements

Shoppers in the Netherlands can purchase using iDEAL. The billing country and the order country code have to be NL.

Supported currencies

• EUR

Accepted on other payment flows

One-click (1-click) purchase for iDeal is available in API 6.0.

Workflow

1. Use the getIdealIssuerBanks method for retrieving information on the 2Checkout list of banks that support iDEAL payments. More details about this method here.
2. Shoppers select iDEAL as a payment option in the interface you provide them and select their bank from the list.
3. Create the order object. Use IDEAL as the type of the PaymentDetails object, and include ReturnURL and CancelURL. The BankCode parameter should be added based on the bank selected by the customer, from the array obtained after calling method getIdealIssuerBanks.
4. Use the placeOrder method to send the data to 2Checkout.
5. Once you place the order, 2Checkout logs it into the system. At this point in time, the status of the order is PENDING.
6. 2Checkout returns an Order object as the output of the placeOrder method. 
7. Use the PaymentMethod object to create a redirect URL for the shoppers, concatenating the values of the Href and avng8apitoken parameters. Here's an example of the redirect URL:
   

   https://api.2checkout.com/4.0/scripts/ideal/authorize/?avng8apitoken=f56373d92ed6b153
   

8. Customers are directed to the iDEAL payment page, where they have to confirm their payment details before finishing the ordering process.
9. Shoppers are redirected to the RedirectURL from the Order information object. In case the payment fails, shoppers are redirected to the CancelURL. 

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$Order = new stdClass();
$Order->RefNo = NULL;
$Order->Currency = 'EUR';
$Order->Country = 'NL';
$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 = 'Test Cosmin API';
$Order->BillingDetails->LastName = 'Cosmin API';
$Order->BillingDetails->CountryCode = 'NL';
$Order->BillingDetails->State = 'California';
$Order->BillingDetails->City = 'LA';
$Order->BillingDetails->Address1 = 'Address example';
$Order->BillingDetails->Address2 = NULL;
$Order->BillingDetails->Zip = '90210';
$Order->BillingDetails->Email = 'cosmin.deftu@2checkout.com';
$Order->BillingDetails->Phone = NULL;
$Order->BillingDetails->Company = NULL;
$Order->DeliveryDetails = NULL;

$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'IDEAL';
$Order->PaymentDetails->Currency = 'EUR';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->CustomerIP = '91.220.121.21';
$Order->PaymentDetails->PaymentMethod->ReturnURL = 'http://yourreturnurl.com';
$Order->PaymentDetails->PaymentMethod->CancelURL= 'http://yourcancelurl.com';
$Order->PaymentDetails->PaymentMethod->BankCode='RABONL2U+RAB'; // value retrieved based on the bank selected by the customer, from the array obtained after calling method getIdealIssuerBanks.


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

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

$idealredirect = $output->PaymentDetails->PaymentMethod->Authorize->Href."/?avng8apitoken=".$output->PaymentDetails->PaymentMethod->Authorize->Params->avng8apitoken;

header('Location:' . $idealredirect);

Overview

3D Secure is a system designed to increase the security of online transactions using cards by checking customer identities before allowing them to finalize the purchase. 3D Secure works by redirecting your 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 your customers having to go through an extra layer of authentication.

Introducing Dynamic 3D Secure via API

Starting with 2Checkout API 5.0, your orders placed via API are processed automatically through the Dynamic 3D Secure flow. Dynamic 3D Secure is a mechanism that allows us to evaluate a transaction in real-time based on a range of rule parameters that are able to determine if 3D Secure should be enabled or not.

Based on specific filters set in our backend system, 3D Secure will be enabled or not on a transaction basis in real-time. The list of filters includes:

• Credit card issuing country
• Billing country 
• IP country 
• Order amount

If one of these filters is not matching with the thresholds set in the 2Checkout system, 3D Secure will be enabled. Otherwise, the transaction is considered to be safe and can go through without 3D Secure.

Availability

Placing orders via API with the 3D Secure flow is available starting with version 5 of 2Checkout's API.

Benefits

Place orders via API starting with version 5, and let Dynamic 3D Secure mechanism bring you the following advantages:

• Increased authorization rates – we measured and observed that in specific countries the use of 3D Secure could have an overwhelmingly positive impact (United Kingdom, Russia) while in other countries it has a negative impact (United States, China).
• Mitigated fraud risks – 3D Secure significantly decreased the fraud rate for your incoming orders.
• Less chargeback – the use of 3D Secure can reduce the number of chargebacks in some cases (e.g. reasons like fraud/not recognized) as customers are not allowed to open a chargeback with their bank.

How it works

For credit card orders placed starting with 2Checkout API 5.0, you need to pass through additional parameters that support the Dynamic 3D Secure flow.

1. Once the order has been placed with the customer’s billing details, in order to confirm the payment, the shopper needs to be redirected to a 3D Secure confirmation page. 
2. The URL where the customer needs to be redirected is provided in the API response, in the PaymentMethod object, under the Authorize3DS object. 
3. Here, the redirect URL needs to be created by taking the Href attribute (the URL of the authorization page) and adding the parameters provided in the Params object. 
4. The key-value pairs are the parameters that need to be attached to the URL, where the key is the parameter name and the value is its value. 

For example, for the below parameters:

{
"PaymentMethod": {
    "Authorize3DS": {
    "Href": "https://api.avangate.com/5.0/scripts/credit_card/authorize",
    "Method": "GET",
    "Params": {
        "avng8apitoken": "1234567890abcdef",
            }
        }
    }
}    
    

The URL should be constructed as follows: https://api.avangate.com/5.0/scripts...34567890abcdef.

5. Once the shopper confirms the payment, they will be redirected to the URL provided by you in the Vendor3DSReturnURL. If the payment fails due to 3DS (order could not be validated), then the customer will be returned to the URL provided in Vendor3DSCancelURL.

Send the following parameters as part of the PaymentMethod object: