Overview

Use the object below to create, update and retrieve customers in 2Checkout.

Input parameters

Overview

Place an order using catalog products defined in your Control Panel, and collect the payment using PayPal.

Currency support

Check with 2Checkout support for a list of currencies available for PayPal. 

Parameters

Workflow

1. Create the order object. Use PAYPAL as the type of the PaymentDetails object and send the shopper email and a return URL as part of the PaymentMethod object. Place the order.
2. Once you place the order, 2Checkout logs it into the system. At this point in time, the status of the order is PENDING. 2Checkout responds with the Order information object.
3. Redirect shoppers to the RedirectURL from the Order information object you receive as response from 2Checkout.
4. Once shoppers log into their PayPal account and complete the transaction, they're redirected to the ReturnURL you set in the order object. 2Checkout also authorizes the order and updates the status to AUTHRECEIVED. 
5. If shoppers log in to their PayPal account and fail to complete the transaction or they cancel it, they're redirected to the CancelURL you set in the order object. 2Checkout updates the status to PENDING.

Response

<?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
{
  "Country": "us",
  "Currency": "USD",
  "CustomerIP": "91.220.121.21",
  "ExternalReference": "SOAP_API_AVANGTE",
  "Language": "en",
  "Source": "testAPI.com",
  "BillingDetails": {
    "Address1": "Test Address",
    "City": "LA",
    "State": "California",
    "CountryCode": "US",
    "Email": "testcustomer@2Checkout.com",
    "FirstName": "Customer",
    "LastName": "2Checkout",
    "Zip": "12345"
  },
  "Items": [
    {
      "Code": "A90B3D8FDE",
      "Quantity": 1
    }
  ],
  "PaymentDetails": {
    "Currency": "USD",
    "CustomerIP": "91.220.121.21",
    "PaymentMethod": {
      "RecurringEnabled": false,
      "ReturnURL": "http://secure.avangate.local/test/index.php",
      "CancelURL": "http://secure.avangate.local/test/create_order.php"
    },
    "Type": "PAYPAL"
  }
}
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 placeOrder method to place an order.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');  // Authentication example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/JSON-RPC/02Authentication
require ('PATH_TO_SET_PARTNER'); // setPartner example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/JSON-RPC/06Reference/Partner/00Set_partner
require ('PATH_TO_ADD_PRODUCT'); // addProduct example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/JSON-RPC/06Reference/08Place_an_order/00Add_product_to_cart

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

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

Overview

Use the enableRecurringBilling method to switch on the automatic renewal system for a subscription that's manually renewable. 

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';

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

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

Overview

Use the getCrossSellTexts method to extract information on all cross-sell campaigns texts.

Parameters

Request

<?php

require ('PATH_TO_AUTH');

$LanguageCode = 'de'; //returns title and description texts you set under https://secure.avangate.com/cpanel/network_cross_selling_settings.php

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

var_dump(" \n Cross-sell campaigns: \n", callRPC($jsonRpcRequest, $host));

?>

Response

Overview

Use the searchPromotions method to extract information on promotions you set up for your account.

Parameters

Response

Promotion object.

Request

<?php

require ('PATH_TO_AUTH');

$searchOptions = new stdClass();
$searchOptions->Types = array ('REGULAR');
$searchOptions->Channel = 'ECOMMERCE';
$searchOptions->ProductCode = 'Product_Code_1';
$searchOptions->Enabled = TRUE;
$searchOptions->Limit = 99;
$searchOptions->Page = 1;

$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'searchPromotions',
'params' => array($sessionID, $searchOptions)
);
var_dump (callRPC((Object)$jsonRpcRequest, $host));
?>

Overview

Use the enableRecurringBilling method to switch on the automatic renewal system for a subscription that's manually renewable. 

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';

try {
    $enabledSubscriptionRecurring = $client->enableRecurringBilling($sessionID, $subscriptionReferenceTest);
}
catch (SoapFault $e) {
    echo "enabledSubscriptionRecurring: " . $e->getMessage();
    exit;
}
var_dump("enabledSubscriptionRecurring", $enabledSubscriptionRecurring);

Overview

Notifications are sent by an HTTP POST request to the message URL that you specified on the INS Notifications tab.

The message parameters are passed as key => value pairs. Your message URLs should route to the script where you will be handling the message. You can listen for messages by simply setting up logic in your application to take action based on the message_type parameter that is passed in each message.

Message types

Currently, there are three types of messages sent using the Instant Notification System (INS).

1. Message Invoice is sent on triggers like order creation or invoice status change.

 {
    "sale_id":"1",
    "sale_date_placed":"1990-01-01 12:00:00",
    "recurring":1,
    "payment_type":"credit card",
    "list_currency":"USD",
    "fraud_status":"pass",
    "order_ref":"1",
    "order_no":"1",
    "vendor_id":"TESTVENDORID",
    "vendor_order_id":"",
    "invoice_id":"100000000000",
    "invoice_status":"approved",
    "invoice_list_amount":"100",
    "invoice_usd_amount":"100",
    "invoice_cust_amount":"100",
    "item_count":1,
    "auth_exp":"2022-01-01",
    "customer_first_name":"John",
    "customer_last_name":"Doe",
    "customer_name":"Jane Doe",
    "customer_email":"john.doe@test.com",
    "customer_phone":"",
    "customer_ip":"1.1.1.1",
    "customer_ip_country":null,
    "cust_currency":"USD",
    "bill_city":"TestCity",
    "bill_country":"NER",
    "bill_postal_code":"",
    "bill_state":"",
    "bill_street_address":"TestStreet",
    "bill_street_address2":"",
    "ship_status":"",
    "ship_tracking_number":"",
    "ship_name":"Doe John",
    "ship_street_address":"TestStreet",
    "ship_street_address2":"",
    "ship_city":"TestCity",
    "ship_state":"",
    "ship_postal_code":"",
    "ship_country":"NER",
    "message_id":1,
    "message_type":"INVOICE_STATUS_CHANGED",
    "message_description":"Invoice status changed",
    "timestamp":"2021-01-01 12:00:00 EEST",
    "key_count":1,
    "item_name_1":"Electronically Delivered Software",
    "item_id_1":"",
    "item_list_amount_1":"100",
    "item_usd_amount_1":"100",
    "item_cust_amount_1":"100",
    "item_type_1":"bill",
    "item_duration_1":"Forever",
    "item_recurrence_1":"1 Month",
    "item_rec_list_amount_1":"100",
    "item_rec_status_1":"live",
    "item_rec_date_next_1":"",
    "item_rec_install_billed_1":"1",
    "hash":"3B2EF87601E548597155C6751FFCCF76"
}

2.   Message Product is sent when a new product is created or an existing product is updated.

{
    "message_id":1,
    "message_type":"CATALOGUE_PRODUCT_CREATED",
    "message_description":"New catalogue product created",
    "timestamp":"2021-01-01 12:00:00 EEST",
    "key_count": 1,
    "avangate_id":"1",
    "enabled":true,
    "fulfillment":"NO_DELIVERY",
    "fulfillment_information":{
        "is_start_after_fulfillment":false,
        "is_electronic_code":false,
        "is_download_link":false,
        "is_backup_media":false,
        "is_download_insurance_service":false,
        "is_instant_delivery_thank_you_page":false,
        "is_display_in_partners_c_panel":false,
        "code_list":null,
        "backup_media":null,
        "product_file":null,
        "additional_information_by_email":null,
        "additional_information_email_translations":{
        },
        "additional_thank_you_page":null,
        "additional_thank_you_page_translations":{
        },
        "return_method":{
            "type":null,
            "url":null
        }
    },
    "generates_subscription":true,
    "gift_option":false,
    "product_group":null,
    "long_description":"",
    "platforms":{
        "0":{
            "id_platform":"1",
            "platform_name":"Linux",
            "category":"Desktop"
        }
    },
    "prices":{
        "name":"TEST's Price Configuration",
        "code":"TESTCODE",
        "default":true,
        "billing_countries":[
        ],
        "use_original_prices":false,
        "pricing_schema":"DYNAMIC",
        "price_type":"NET",
        "default_currency":{
            "id":"1",
            "code":"USD",
            "digitCode":"840",
            "label":"United States Dollar",
            "symbol":"$",
            "symbolPosition":"left",
            "decimalSeparator":".",
            "unitSeparator":",",
            "decimals":"2"
        },
        "prices":{
            "regular":{
                "0":{
                    "amount":100,
                    "currency":"USD",
                    "min_quantity":"1",
                    "max_quantity":"99999",
                    "option_codes":null
                }
            },
            "renewal":{
            }
        },
        "price_options":{
        }
    },
    "product_category":"TESTCATEGORY",
    "product_code":"TESTCODE",
    "product_images":null,
    "product_name":"TESTNAME",
    "product_type":"REGULAR",
    "product_version":"",
    "purchase_multiple_units":true,
    "shipping_class":null,
    "short_description":"",
    "subscription_information":{
        "deprecated_products":[
        ],
        "bundle_renewal_management":"GLOBAL",
        "billing_cycle":-1,
        "billing_cycle_units":"M",
        "is_one_time_fee":true,
        "contract_period":null,
        "usage_billing":7,
        "grace_period":null,
        "renewal_emails":{
            "type":"GLOBAL",
            "settings":{
                "manual_renewal":{
                    "before30_days":false,
                    "before15_days":false,
                    "before7_days":false,
                    "before1_day":false,
                    "on_expiration_date":false,
                    "after5_days":false,
                    "after15_days":false
                },
                "automatic_renewal":{
                    "before30_days":false,
                    "before15_days":false,
                    "before7_days":false,
                    "before1_day":true,
                    "on_expiration_date":true,
                    "after5_days":false,
                    "after15_days":false
                }
            }
        }
    },
    "trial_description":"",
    "trial_url":"",
    "tangible":false,
    "tangible_details":{
        "unit_details":[
        ],
        "fee":[
        ]
    },
    "hash":"435EA2BFAB983240CC27C5FC5D8323B4"
}

3. Message Proposal is sent when a proposal is created or updated. 

{
    "message_id":1,
    "message_type":"PROPOSAL_CREATED",
    "message_description":"Proposal created",
    "timestamp":"2021-01-01 12:00:00 EET",
    "key_count":1,
    "proposal_id":"1",
    "version":"1",
    "created_date":"2021-01-01 12:00:00",
    "updated_date":"2021-01-01 12:00:00",
    "created_by":"TEST",
    "updated_by":"TEST",
    "locked":"",
    "source":"",
    "content":"TEST CONTENT",
    "bill_to":"TEST BILL",
    "name":"TEST NAME",
    "tac":"TEST TAC",
    "type":"TEST TYPE",
    "sent_by":"TEST NAME 2",
    "links":"TEST LINK",
    "status":"PENDING",
    "expiration_date":"2022-01-01 12:00:00",
    "status_comment":"",
    "sell_to":"TEST NAME",
    "hash":"B87C32614A96FCE9C614C0721D19C3B0"
}

Validate response

Each notification message includes a hash computed using the secret word and secret key you set up in your Merchant Control Panel. The hash is returned on each message through the hash key containing the hash algorithm and the hash value, separated by a colon symbol.

Example: "hash":"SHA256:C7CE5C8C4355C3F3162D51530762A31BCFB700030AF3DF072744B5B817F63510"

According to the message, different parameters are required for the hash. The required parameters are concatenated for each type of message and the hash function is applied. The result is converted to uppercase. 

1. For message Invoice, the required parameters are the sale ID, the 2Checkout merchant ID, the invoice ID, and the secret word. 

PHP Example for Message Invoice

<?php

$invoiceDetails = $_POST;

$secretKey = 'EXAMPLE_SECRET_KEY';
$secretWord = 'EXAMPLE_SECRET_WORD';
$TCOVendorId = 123example_vendor_id;  // your 2checkout vendor id should be a number

$saleId = $invoiceDetails['sale_id'];
$invoiceId = $invoiceDetails['invoice_id'];
$hash = explode(':',$invoiceDetails['hash']); // index 0 is algorithm, index 1 is the hash

$parameters = [
    $saleId,
    $TCOVendorId,
    $invoiceId,
    $secretWord
];



$calculatedHash = strtoupper(hash_hmac($hash[0] ,implode($parameters),$secretKey));
if ($calculatedHash === $hash[1]) {
    http_response_code(200);
    echo true;
} else {
    http_response_code(400);
    echo "calculated hash: $calculatedHash \n";
    echo "received hash: $hash[1]";
}

?>

Node.JS (ES6) Example for Message Invoice

const crypto = require('crypto');
const merchantCode = '123example_vendor_id'; 
const secretWord = 'EXAMPLE_SECRET_WORD';
const secretKey = 'EXAMPLE_SECRET_KEY';

let saleId = request.params['sale_id'];
let invoiceId = request.params['invoice_id'];
let insHashArray = request.params['hash'].split(':');
let insAlgo = insHashArray[0];
let insHash = insHashArray[1];

let parameters = [
    saleId,
    merchantCode,
    invoiceId,
    secretWord
];

const hash = crypto.createHmac(insAlgo, secretKey)
               .update(parameters.join(''))
               .digest('hex');

console.log(hash.toUpperCase() === insHash);

Python Example for Message Invoice

import hmac

merchant_code = 'EXAMPLE_MERCHANT_CODE'
secret_word = 'EXAMPLE_SECRET_WORD'
secret_key = 'EXAMPLE_SECRET_KEY'
sale_id = param['sale_id']
invoice_id = param['invoice_id']
ins_hash_array = param['hash'].split(':')
ins_algo = ins_hash_array[0].replace('-', '_').lower();
ins_hash = ins_hash_array[1];

parameters = [
    sale_id,
    merchant_code,
    invoice_id,
    secret_word
]

hash_string = hmac.new(secret_key.encode('utf-8'), ''.join(parameters).encode('utf-8'), ins_algo).hexdigest().upper()

print(ins_hash == hash_string)

2. For message Product, the required parameters are the product code, the 2Checkout merchant ID, and the secret word. 

PHP Example for Message Product

<?php

$invoiceDetails = $_POST;

$secretKey = 'EXAMPLE_SECRET_KEY';
$secretWord = 'EXAMPLE_SECRET_WORD';
$TCOVendorId = 123example_vendor_id;  // your 2checkout vendor id should be a number

$productCode = $invoiceDetails['product_code'];
$hash = explode(':',$invoiceDetails['hash']); // index 0 is algorithm, index 1 is the hash

$parameters = [
    $productCode,
    $TCOVendorId,
    $secretWord
];



$calculatedHash = strtoupper(hash_hmac($hash[0] ,implode($parameters),$secretKey));
if ($calculatedHash === $hash[1]) {
    http_response_code(200);
    echo true;
} else {
    http_response_code(400);
    echo "calculated hash: $calculatedHash \n";
    echo "received hash: $hash[1]";
}

?>

Node.JS (ES6) Example for Message Product

const crypto = require('crypto');
const merchantCode = '123example_vendor_id'; 
const secretWord = 'EXAMPLE_SECRET_WORD';
const secretKey = 'EXAMPLE_SECRET_KEY';

let productCode = request.params[‘product_’code];
let insHashArray = request.params['hash'].split(':');
let insAlgo = insHashArray[0];
let insHash = insHashArray[1];

let parameters = [
    productCode,
    merchantCode,
    secretWord
];

const hash = crypto.createHmac(insAlgo, secretKey)
               .update(parameters.join(''))
               .digest('hex');

console.log(hash.toUpperCase() === insHash);

Python Example for Message Product

import hmac

merchant_code = 'EXAMPLE_MERCHANT_CODE'
secret_word = 'EXAMPLE_SECRET_WORD'
secret_key = 'EXAMPLE_SECRET_KEY'
product_code = param[‘product_code’]
ins_hash_array = param['hash'].split(':')
ins_algo = ins_hash_array[0].replace('-', '_').lower();
ins_hash = ins_hash_array[1];

parameters = [
    product_code,
    merchant_code,
    secret_word
]

hash_string = hmac.new(secret_key.encode('utf-8'), ''.join(parameters).encode('utf-8'), ins_algo).hexdigest().upper()

print(ins_hash == hash_string)

3. For message Proposal, the required parameters are the proposal ID, the 2Checkout merchant ID, and the secret word.

PHP Example for Message Proposal

<?php

$invoiceDetails = $_POST;

$secretKey = '=B6gcTl(4t8@D3yUM!TP';
$secretWord = 'Mv#-Z*nb7U%qYJwc-tsb&f?JEyUP5p5WK4*txCfT@336CuwZrZkdqc&K$zEZqnBP';
$TCOVendorId = 250111206876;

$proposalId = $invoiceDetails['proposal_id'];
$hash = explode(':',$invoiceDetails['hash']); // index 0 is algo, index 1 is hash

$parameters = [
    $proposalId,
    $TCOVendorId,
    $secretWord
];



$calculatedHash = strtoupper(hash_hmac($hash[0] ,implode($parameters),$secretKey));
if ($calculatedHash === $hash[1]) {
    http_response_code(200);
    echo true;
} else {
    http_response_code(400);
    echo "calculated hash: $calculatedHash \n";
    echo "received hash: $hash[1]";
}

?>

Node.JS (ES6) Example for Message Proposal

const crypto = require('crypto');
const secretWord = 'AABBCCDDEEFF';
const 2COVendorId = 1;

let proposalId = request.params['proposal_id'];

let parameters = [
    proposalId,
    2COVendorId,
    secretWord
];

let hash = crypto.createHash('md5').update(parameters.join('')).digest();

console.log(hash.toUpperCase() === request.params['md5_hash']);

Python Example for Message Proposal

from urllib import request
from flask import Flask, jsonify, request, Request
from urllib.parse import urlencode, urldefrag
from werkzeug.datastructures import ImmutableOrderedMultiDict
import hashlib

class MyRequest(Request):
    parameter_storage_class = ImmutableOrderedMultiDict

class MyFlask(Flask):
    request_class = MyRequest

app = MyFlask(__name__)
def calculate_hash_string(payload_tuple_list):
    secretWord = 'AABBCCDDEEFF'
    2COVendorId = 1

    proposalId = payload_tuple_list['proposalId']

    parameters = [
        proposalId,
        2COVendorId,
        secretWord
    ]

    hash_string = hashlib.md5(''.join(parameters).encode('utf-8')).digest().upper()

    return hash_string

@app.route('/ins', methods=['POST'])
def ins():
    ins_payload_received = request.form
    return ins_payload_received['md5_hash'] === calculate_hash_string(ins_payload_received)

if __name__ == '__main__':
app.run()

Read receipt response

Currently, there are no required response values, so a basic response with HTTP 200 status will suffice.

Overview

3D Secure is a system designed to increase security of online transactions using cards by checking customer identities before allowing them to finalize 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 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 is 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 the 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.

Send the following parameters as part of the PaymentMethod object: