Overview

Use this object to create new orders and collect payments from shoppers using catalog products defined in your Merchant Control Panel.

For orders that require physical delivery, if no shipping methods are provided, 2Checkout will add to the cart your account's default shipping configuration.

You can find a list of common errors that may arise when using the placeOrder call via API 6.0 here.

Supported payment methods/flows

• Credit/Debit cards: Visa, Visa Electron, MasterCard, Maestro, Amex, Discover, Dankort, Carte Bleue, JCB. 2Checkout supports local Brazilian cards.
• PayPal and PayPal Express
• Purchase Order
• Wire
• Check
• WeChat Pay
• iDEAL
• Alipay
• Trustly
• TEST orders
• Free orders (no payment information required)
• Previous order references - In addition to the payment methods enumerated above, 2Checkout also supports 1-click purchase flows in which you use valid previous order references belonging to returning customers to pay for new orders with their previously used cards and PayPal accounts.
• 2Pay.js
• Order with installments
• Apple Pay
• Boleto/Pix 
• Google Pay
• eChecks
• Stored Credit

Requirements

For credit card orders placed using API 6.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 passwords 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:

Parameters

Request example (with Credit Card)

<?php

declare(strict_types=1);

class Configuration
{
    public const MERCHANT_CODE = '';
    public const MERCHANT_KEY = '';
    public const URL = 'http://api.2checkout.com/soap/6.0';
    public const ACTION = 'placeOrder';
    public const ADDITIONAL_OPTIONS = null;
    //array or JSON
    public const PAYLOAD = <<<JSON
{
    "Currency": "USD",
    "Country": "US",
    "CustomerIP": "91.220.121.21",
    "Source": "testAPI.com",
    "WSOrder": "http://www.myurlfortest.com",
    "ExternalReference": null,
    "BillingDetails": {
        "Address1": "Test Address",
        "City": "London",
        "CountryCode": "US",
        "Email": "customer@2Checkout.com",
        "FirstName": "Customer",
        "LastName": "2Checkout",
        "Phone": "556133127400",
        "State": "DF",
        "Zip": "70403-900"
    },
    "PaymentDetails": {
        "Type": "CC",
        "Currency": "USD",
        "CustomerIP": "91.220.121.21",
        "PaymentMethod": {
            "CCID": "123",
            "CardNumber": "4111111111111111",
            "CardNumberTime": "12",
            "CardType": "Visa",
            "ExpirationMonth": "12",
            "ExpirationYear": "2023",
            "HolderName": "John Doe",
            "HolderNameTime": "12",
            "RecurringEnabled": true,
            "Vendor3DSReturnURL": "www.test.com",
            "Vendor3DSCancelURL": "www.test.com"
        }
    },
    "Items": [
        {
            "Code": "testprod",
            "Quantity": "1"
        }
    ]
}
JSON;
}

class Client
{
    public function call(
        string $url = Configuration::URL,
               $payload = Configuration::PAYLOAD,
        string $action = Configuration::ACTION
    ): ?object
    {
        if (is_array($payload)) {
            $payload = json_encode($payload);
        }
        if (!empty($payload)) {
            // SoapClient works with objects(StdClass)
            $payload = json_decode($payload);
        }

        $soapClient = $this->getClient($url);
        $sessionId = $this->getSession($soapClient);

        $args = array_filter([$sessionId, $payload]);

        return $soapClient->$action(...$args);
    }

    public function getClient(string $url): SoapClient
    {
        return new SoapClient(
            $url . '?wsdl',
            [
                'location' => $url,
                'cache_wsdl' => WSDL_CACHE_NONE,
            ]
        );
    }

    public function getSession(SoapClient $client)
    {
        $date = gmdate('Y-m-d H:i:s');
        $merchantCode = Configuration::MERCHANT_CODE;
        $key = Configuration::MERCHANT_KEY;
        $string = strlen($merchantCode) . $merchantCode . strlen($date) . $date;
        $hash = hash_hmac('md5', $string, $key);
        // $client->__setCookie('XDEBUG_SESSION', 'PHPSTORM');
        return $client->login($merchantCode, $date, $hash);
    }
}

try {
    $client = new Client();
    var_dump($client->call());
} catch (Exception $ex) {
    var_dump($ex);
}

Overview

Use the addPromotion method to create a new promotion.

Parameters 

Response

Request

<?php

require ('PATH_TO_AUTH');

$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 updatePromotion method to alter the details of an existing promotion.

Parameters

Response

Request

<?php
require ('PATH_TO_AUTH'); 

// Retrieve promotion details

$promotionCode = 'PROMOTION_CODE'; // code of the promotion that you want to update

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

// Keep the promotion you want to update in $existingPromotion
$existingPromotion = callRPC((Object)$jsonRpcRequest, $host);
// Set the fields to update 
$existingPromotion->Description = 'Updated description';

// Update the promotion
$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'updatePromotion',
'params' => array($sessionID, $existingPromotion)
);
var_dump (callRPC((Object)$jsonRpcRequest, $host));

Overview

Use the createProposal method via SOAP API 6.0 to add/create a new quote.

Request Parameters

Request sample

<?php

require ('PATH_TO_AUTH');

$proposal = new stdClass();
$proposal->Type = "acquisition";
$proposal->BillTo = new stdClass();
$proposal->BillTo->Company = "Billing company";
$proposal->Content = new stdClass();
$proposal->Content->Language = "EN";
$proposal->Content->Currency = "USD";
$proposal->Content->LineItems =  array();
$lineItem = new stdClass();
$lineItem->ProductName = "My Product Name";
$lineItem->ProductCode = "5DCB30C6B0";
$lineItem->Quantity = 1;
$lineItem->Price = 54.2;
$lineItem->DiscountedPrice = 50;
$lineItem->PriceType = "net";
$lineItem->ContractPeriod = 0;
$proposal->Content->LineItems[0] = $lineItem;
$proposal->tac = new stdClass();
$proposal->tac->content = "Lorem ipsum.";
$proposal->SellTo = new stdClass();
$proposal->SellTo->Company = "End user company";

try {
    $results = $soapClient->createProposal($sessionID, $proposal);
    echo "New proposal created: </br>", 
    var_dump($results);
}
catch (SoapFault $e) {
    echo "Could not create proposal: " . $e->getMessage();
    exit;
}

Request sample with prorationDate

<?php

        require ('PATH_TO_AUTH');

        $proposal = new stdClass();
        $proposal->Type = "amendment";
        $proposal->BillTo = new stdClass();
        $proposal->BillTo->Company = "Billing company";
        $proposal->Content = new stdClass();
        $proposal->Content->Language = "EN";
        $proposal->Content->Currency = "USD";
        $proposal->Content->Tersm = 10;
        $proposal->Content->LineItems =  array();
        $lineItem = new stdClass();
        $lineItem->ProductName = "My Product Name";
        $lineItem->ProductCode = "5DCB30C6B0";
        $lineItem->Quantity = 1;
        $lineItem->Price = 54.2;
        $lineItem->DiscountedPrice = 50;
        $lineItem->PriceType = "net";
        $lineItem->ProrationDate = "2020-11-14T15:28:56+00:00";
        $lineItem->ContractPeriod = 0;
        $lineItem->subscriptionReference ="1234567890";
        $proposal->Content->LineItems[0] = $lineItem;
        $proposal->tac = new stdClass();
        $proposal->tac->content = "Lorem ipsum.";
        $proposal->SellTo = new stdClass();
        $proposal->SellTo->Company = "End user company";

        try {
            $results = $soapClient->createProposal($sessionID, $proposal);
            echo "New proposal created: </br>",
            var_dump($results);
        }
        catch (SoapFault $e) {
            echo "Could not create proposal: " . $e->getMessage();
            exit;
        }

Request sample with vatCode

    <?php

        require ('PATH_TO_AUTH');

        $proposal = new stdClass();
        $proposal->Type = "acquisition";
        $proposal->BillTo = new stdClass();
        $proposal->BillTo->Company = "Billing company";
        $proposal->Content = new stdClass();
        $proposal->Content->Language = "EN";
        $proposal->Content->Currency = "USD";
        $proposal->Content->LineItems =  array();
        $lineItem = new stdClass();
        $lineItem->ProductName = "My Product Name";
        $lineItem->ProductCode = "5DCB30C6B0";
        $lineItem->Quantity = 1;
        $lineItem->Price = 54.2;
        $lineItem->DiscountedPrice = 50;
        $lineItem->PriceType = "net";
        $lineItem->ContractPeriod = 0;
        $proposal->Content->LineItems[0] = $lineItem;
        $proposal->tac = new stdClass();
        $proposal->tac->content = "Lorem ipsum.";
        $proposal->SellTo = new stdClass();
        $proposal->SellTo->Company = "End user company";
        $proposal->SellTo->VatCode = "854234564";

        try {
            $results = $soapClient->createProposal($sessionID, $proposal);
            echo "New proposal created: </br>", 
            var_dump($results);
        }
        catch (SoapFault $e) {
            echo "Could not create proposal: " . $e->getMessage();
            exit;
        }

Request sample with TaxExemptionId

<?php

        require ('PATH_TO_AUTH');

        $proposal = new stdClass();
        $proposal->Type = "acquisition";
        $proposal->BillTo = new stdClass();
        $proposal->BillTo->Company = "Billing company";
        $proposal->Content = new stdClass();
        $proposal->Content->Language = "EN";
        $proposal->Content->Currency = "USD";
        $proposal->Content->LineItems =  array();
        $lineItem = new stdClass();
        $lineItem->ProductName = "My Product Name";
        $lineItem->ProductCode = "5DCB30C6B0";
        $lineItem->Quantity = 1;
        $lineItem->Price = 54.2;
        $lineItem->DiscountedPrice = 50;
        $lineItem->PriceType = "net";
        $lineItem->ContractPeriod = 0;
        $proposal->Content->LineItems[0] = $lineItem;
        $proposal->tac = new stdClass();
        $proposal->tac->content = "Lorem ipsum.";
        $proposal->SellTo = new stdClass();
        $proposal->SellTo->Company = "End user company";
        $proposal->SellTo->TaxExemptionId = "854234564";

        try {
            $results = $soapClient->createProposal($sessionID, $proposal);
            echo "New proposal created: </br>", 
            var_dump($results);
        }
        catch (SoapFault $e) {
            echo "Could not create proposal: " . $e->getMessage();
            exit;
        }    

Response

The createProposal call via SOAP API returns a Proposal object.

Overview

Two-factor authentication is a method of computer access control that grants users access to their account after validating two criteria:

• Knowledge - represented by a security aspect the user has knowledge of, such as the username and password.
• Possession - represented by an item that only exists in the possession of that specific user, such as a smartphone, tablet, phone number, or email address.

Through two-factor authentication, users can access the 2Checkout Merchant Control Panel using their username, password, and a security token provided either by the Google Authenticator app or sent via email (associated with their Merchant Control Panel account).

For security reasons, master account users can enable two-factor authentication for their own accounts only via Google Authenticator.

2Checkout allows you to manage user access to specific features by creating and assigning user roles. This extra layer of security enables you to restrict access to the Merchant Control Panel to specific users, based on unique tokens.

Availability

All 2Checkout accounts.

Requirements

• Two-factor authentication through Google Authenticator requires a compatible mobile device running Android 2.3.3 or newer, or iOS 7.0 or newer.
• Two-factor authentication via email requires the user to have access to his or her email account.

Google Authenticator for Android

You can download the Google Authenticator app for Android here or by accessing Google Play Store from your Android device.

Google Authenticator for iOS

You can download the Google Authenticator app for iOS here or by accessing the App Store from your iOS device.

Two-factor authentication types

2Checkout supports two types of two-factor authentication:

• Two-factor authentication powered by Google Authenticator. Authentication codes are delivered through the Google Authenticator app for Android and iOS.
• Two-factor authentication via email. Particular cases where users do not have access to their smartphones, such as environments that adhere to a "clean desk" policy, require authentication codes to be sent via email. In these situations, two-factor enrollment is done by the master account. Users enrolled by the master account cannot disable two-factor authentication on their own.

Two-factor authentication via Google Authenticator

Enable two-factor authentication

Follow the steps below to enable two-factor authentication for your account.

1. Log in to the 2Checkout Merchant Control Panel.
2. Navigate to the Settings cogwheel in the upper right corner.
3. Click on My details.

4. Go to the Two-factor authentication tab.

5. Scan the QR code using your smart device or enter the Authentication secret in the Google Authenticator app. The app will provide an authentication code.

6. Enter the authentication code in the dedicated field in the 2Checkout Merchant Control Panel.

7. Click Activate.

From this point on, every login attempt will require an authentication code provided by Google Authenticator.

Disable two-factor authentication

Follow the steps below to disable two-factor authentication.

1. Login to the 2Checkout Control Panel.
2. Navigate to the Settings cogwheel in the upper right corner.
3. Click on My details.
4. Go to the Two-factor authentication tab.
5. Click Deactivate.

Two-factor authentication via email

Particular cases where users do not have access to their smartphones, such as environments that adhere to a "clean desk" policy, require authentication codes to be sent via email. In these situations, two-factor enrollment is done by the master account. Users enrolled by the master account cannot disable two-factor authentication on their own.

Follow the steps below to enable two-factor authentication via email.

1. Login to the 2Checkout Merchant Control Panel with a master account.
2. Navigate to the Settings cogwheel in the upper right corner.
3. Click on User management.
4. Identify the user you wish to enable two-factor authentication for and click Edit.
5. Check the Two-factor authentication by email option.
6. Click Save.

Once you enable two-factor authentication for a user, 2Checkout notifies them about the change and sends an authentication code to their email address each time a login attempt is detected.

Request

<?php 

class Client
{
    protected static $merchantCode;
    protected static $loginDate;
    protected static $hash;
    protected static $baseUrl;
    protected static $callCount = 0;
    protected static $sessionId = '';

    protected static $client;

    public static function setCredentials($code, $key)
    {
        static::$merchantCode = $code;
        static::$loginDate = gmdate('Y-m-d H:i:s');
        static::$hash = hash_hmac('md5', strlen($code) . $code . strlen(static::$loginDate) . static::$loginDate, $key);
        static::$sessionId = static::login();
    }

    public static function setBaseUrl($url)
    {
        static::$baseUrl = $url;
    }

    public static function login()
    {
        $client = static::getClient();
        return $client->login(static::$merchantCode, static::$loginDate, static::$hash);
    }

    public static function __callStatic($name, $arguments = array())
    {
        $client = static::getClient();

        array_unshift($arguments, static::$sessionId);
        $response = call_user_func_array(array($client, $name), $arguments);

        return $response;
    }

    protected static function getClient()
    {
        $opts = array(
            'http'=> ['user_agent' => 'PHPSoapClient'],
            'ssl' => [
                'verify_peer' => false,
                'verify_peer_name' => false,
            ],
        );

        if (null === static::$client) {
            static::$client = new \SoapClient(static::$baseUrl . '?wsdl', [
                'location' => static::$baseUrl,
                'cache_wsdl' => WSDL_CACHE_NONE,
                'stream_context' => stream_context_create($opts),
            ]);
        }

        return static::$client;
    }
}

Client::setBaseUrl('https://api.avangate.com/soap/3.1/');
Client::setCredentials('YOUR_MERCHANT_CODE', 'YOUR_SECRET_KEY');
Client::login();

$promotionCode = 'YOUR_PROMOTION_CODE'; // code of the promotion that you want to update

// // Define single coupon object
// $promotionCoupon = new stdClass;
// $promotionCoupon->Type = 'SINGLE';
// $promotionCoupon->Code = 'YOUR_CODE_HERE';

// Define multiple coupon object
// $promotionCoupon = new stdClass;
// $promotionCoupon->Type = 'MULTIPLE';
// $promotionCoupon->Codes = ['YOUR_CODE_1', 'YOUR_CODE_2'];

$response = Client::addPromotionCoupon ($promotionCode,$promotionCoupon); // Add coupons to the existing promotion
var_dump($response);

Overview

Use the enableSubscription method to enable a subscription.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';

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

Overview

Use the enableSubscription method to enable a subscription.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';

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

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

Overview

Change specific details about a subscription. Use the updateSubscription method to change specific details about a subscription.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReferenceTest = 'YOUR_SUBSCRIPTION_REFERENCE';

try{
    $retrievedSubscription = $client->getSubscription($sessionID, $subscriptionReferenceTest);
}

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

var_dump ($updatedSubscription);


$retrievedSubscription->RecurringEnabled = false;
$retrievedSubscription->SubscriptionEnabled = false;
$retrievedSubscription->ExpirationDate = '2026-12-12';

$churnReasons = ['CHURN_REASON_OTHER'];
$churnReasonOther = 'I refuse to continue the subscription';

try {
    $updatedSubscription = $client->updateSubscription($sessionID, $retrievedSubscription);
}
catch (SoapFault $e) {
    echo "updatedSubscription: " . $e->getMessage();
    exit;
}
var_dump("updatedSubscription", $updatedSubscription);

?>

Overview

Learn how to tackle the common errors that may arise when using the placeOrder call via 2Checkout API.

Error codes for Order Object

Item: Product

 Item: Trial

Item: Cross-sell

Item: Price_options

Item: Price

Item: Refund

Item: Mark_Shipped

Item: Shipping_Price

Item: Billing_Details

Item: Delivery

Item: Payment_Method

Item: Payment_Details

Item: Currency

Item: Language

Item: Affiliate

Item: ExtraInformation

Item: Source

Item: Gift_details

Item: Coupon

Item: Promotion

Item: Additional_Field

Item: Order_Product_Additional_Fields

Item: SubscriptionCustomSettings

Other