Overview

Use the AddSpecialPricePromotion method via SOAP API 6.0 to create a promotion with a special price.

Request parameters 

Request sample

<?php

require('PATH_TO_AUTH');

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

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

$productsObj1 = new stdClass;
$productsObj1->Code = 'test';
$promotionObject->Products = [$productsObj1];


$priceMatrixDefinition1 = new stdClass;
$priceMatrixDefinition1->ProductCode = "test";
$priceMatrixDefinition1->PricingConfigurationCode = "738C6A2049";
$priceMatrixDefinition1->OptionHash = "708e43960c4edc42f14cf388bcb24bde";

$option1 = new stdClass;
$option1->GroupName = "Units";
$option1->OptionText = "1 - maximum";

$price1 = new stdClass;
$price1->Value = 10;
$price1->Currency = "USD";
$price2 = new stdClass;
$price2->Value = 15;
$price2->Currency = "EUR";

$priceMatrixDefinition1->Options = [$option1];
$priceMatrixDefinition1->Prices = [$price1, $price2];

$promotionObject->PriceMatrix = [$priceMatrixDefinition1];


try {
    $newPromotion = $client->addPromotion($sessionID, $promotionObject);
} catch (SoapFault $e) {
    echo "NewPromotion: " . $e->getMessage();
    exit;
}

var_dump("Promotion", $newPromotion);

Response

{
   "@encodingStyle": "http://schemas.xmlsoap.org/soap/encoding/",
   "Body": {
      "addPromotionResponse": {
         "addPromotionReturn": {
            "@type": "ns2:Promotion",
            "Code": {
               "@type": "xsd:string",
               "#text": "6GR7JU369E"
            },
            "Name": {
               "@type": "xsd:string",
               "#text": "Promo percentage REST"
            },
            "Description": {
               "@type": "xsd:string",
               "#text": "Promo description1"
            },
            "StartDate": {
               "@type": "xsd:string",
               "#text": "2019-11-30"
            },
            "EndDate": {
               "@type": "xsd:string",
               "#text": "2100-12-31"
            },
            "MaximumOrdersNumber": {
               "@type": "xsd:int",
               "#text": "-1"
            },
            "MaximumQuantity": {
               "@type": "xsd:int",
               "#text": "1"
            },
            "InstantDiscount": {
               "@type": "xsd:boolean",
               "#text": "false"
            },
            "Coupon": {
               "@type": "ns2:PromotionCouponSingleOrMultiple",
               "Type": {
                  "@type": "xsd:string",
                  "#text": "MULTIPLE"
               },
               "Codes": {
                  "@arrayType": "xsd:string[2]",
                  "@type": "ns2:StringArray",
                  "item": [
                     {
                        "@type": "xsd:string",
                        "#text": "code1"
                     },
                     {
                        "@type": "xsd:string",
                        "#text": "code2"
                     }
                  ]
               }
            },
            "Enabled": {
               "@type": "xsd:boolean",
               "#text": "true"
            },
            "ChannelType": {
               "@nil": "true"
            },
            "Type": {
               "@type": "xsd:string",
               "#text": "SPECIAL_PRICE"
            },
            "Discount": {
               "@nil": "true"
            },
            "Products": {
               "@arrayType": "ns2:PromotionProduct[1]",
               "@type": "ns2:PromotionProductsArray",
               "item": {
                  "@type": "ns2:PromotionProduct",
                  "Code": {
                     "@type": "xsd:string",
                     "#text": "test"
                  },
                  "PricingOptionCodes": {
                     "@nil": "true"
                  },
                  "PricingConfigurationCode": {
                     "@nil": "true"
                  }
               }
            },
            "PriceThreshold": {
               "@nil": "true"
            },
            "Translations": {
               "@arrayType": "ns2:PromotionTranslation[1]",
               "@type": "ns2:PromotionTranslationsArray",
               "item": {
                  "@type": "ns2:PromotionTranslation",
                  "Name": {
                     "@type": "xsd:string",
                     "#text": "Promo percentage REST"
                  },
                  "Language": {
                     "@type": "xsd:string",
                     "#text": "EN"
                  }
               }
            },
            "Sources": {
               "@arrayType": "xsd:string[0]",
               "@type": "ns2:SourcesArray"
            },
            "PublishToAffiliatesNetwork": {
               "@nil": "true"
            },
            "ApplyRecurring": {
               "@type": "xsd:string",
               "#text": "NONE"
            },
            "RecurringChargesNumber": {
               "@type": "xsd:int",
               "#text": "0"
            },
            "DefaultCurrency": {
               "@type": "xsd:string",
               "#text": "EUR"
            },
            "PriceMatrix": {
               "@arrayType": "ns2:PromotionPriceMatrix[1]",
               "@type": "ns2:PromotionPriceMatrixArray",
               "item": {
                  "@type": "ns2:PromotionPriceMatrix",
                  "ProductCode": {
                     "@type": "xsd:string",
                     "#text": "test"
                  },
                  "PricingConfigurationCode": {
                     "@type": "xsd:string",
                     "#text": "738C6A2049"
                  },
                  "OptionHash": {
                     "@type": "xsd:string",
                     "#text": "708e43960c4edc42f14cf388bcb24bde"
                  },
                  "Options": {
                     "@arrayType": "ns2:PromotionPriceMatrixOptions[1]",
                     "@type": "ns2:PromotionPriceMatrixOptionsArray",
                     "item": {
                        "@type": "ns2:PromotionPriceMatrixOptions",
                        "GroupName": {
                           "@type": "xsd:string",
                           "#text": "Units"
                        },
                        "OptionText": {
                           "@type": "xsd:string",
                           "#text": "1 - maximum"
                        }
                     }
                  },
                  "Prices": {
                     "@arrayType": "ns2:PromotionPriceMatrixPrices[12]",
                     "@type": "ns2:PromotionPriceMatrixPricesArray",
                     "item": [
                        {
                           "@type": "ns2:PromotionPriceMatrixPrices",
                           "Value": {
                              "@type": "xsd:double",
                              "#text": "31.156"
                           },
                           "Currency": {
                              "@type": "xsd:string",
                              "#text": "CAD"
                           }
                        },
                        {
                           "@type": "ns2:PromotionPriceMatrixPrices",
                           "Value": {
                              "@type": "xsd:double",
                              "#text": "20"
                           },
                           "Currency": {
                              "@type": "xsd:string",
                              "#text": "EUR"
                           }
                        },
                        {
                           "@type": "ns2:PromotionPriceMatrixPrices",
                           "Value": {
                              "@type": "xsd:double",
                              "#text": "40"
                           },
                           "Currency": {
                              "@type": "xsd:string",
                              "#text": "USD"
                           }
                        },
                        {
                           "@type": "ns2:PromotionPriceMatrixPrices",
                           "Value": {
                              "@type": "xsd:double",
                              "#text": "1587.5251590698"
                           },
                           "Currency": {
                              "@type": "xsd:string",
                              "#text": "ARS"
                           }
                        },
                        {
                           "@type": "ns2:PromotionPriceMatrixPrices",
                           "Value": {
                              "@type": "xsd:double",
                              "#text": "18541.12858627"
                           },
                           "Currency": {
                              "@type": "xsd:string",
                              "#text": "CLP"
                           }
                        },
                        {
                           "@type": "ns2:PromotionPriceMatrixPrices",
                           "Value": {
                              "@type": "xsd:double",
                              "#text": "18.1324"
                           },
                           "Currency": {
                              "@type": "xsd:string",
                              "#text": "GBP"
                           }
                        },
                        {
                           "@type": "ns2:PromotionPriceMatrixPrices",
                           "Value": {
                              "@type": "xsd:double",
                              "#text": "2447.2"
                           },
                           "Currency": {
                              "@type": "xsd:string",
                              "#text": "JPY"
                           }
                        },
                        {
                           "@type": "ns2:PromotionPriceMatrixPrices",
                           "Value": {
                              "@type": "xsd:double",
                              "#text": "499.518"
                           },
                           "Currency": {
                              "@type": "xsd:string",
                              "#text": "MXN"
                           }
                        },
                        {
                           "@type": "ns2:PromotionPriceMatrixPrices",
                           "Value": {
                              "@type": "xsd:double",
                              "#text": "97.536"
                           },
                           "Currency": {
                              "@type": "xsd:string",
                              "#text": "RON"
                           }
                        },
                        {
                           "@type": "ns2:PromotionPriceMatrixPrices",
                           "Value": {
                              "@type": "xsd:double",
                              "#text": "1846.05"
                           },
                           "Currency": {
                              "@type": "xsd:string",
                              "#text": "RUB"
                           }
                        },
                        {
                           "@type": "ns2:PromotionPriceMatrixPrices",
                           "Value": {
                              "@type": "xsd:double",
                              "#text": "601.82854437393"
                           },
                           "Currency": {
                              "@type": "xsd:string",
                              "#text": "UAH"
                           }
                        },
                        {
                           "@type": "ns2:PromotionPriceMatrixPrices",
                           "Value": {
                              "@type": "xsd:double",
                              "#text": "384.374"
                           },
                           "Currency": {
                              "@type": "xsd:string",
                              "#text": "ZAR"
                           }
                        }
                     ]
                  }
               }
            }
         }
      }
   }
} 

Overview

Use Instant Refund/Reverse Notifications (IRN) to automate the process of requesting: 

• Transaction reversals
• Full refunds
• Partial refunds

The IRNs let you send refund and reversal requests directly from your own management interface/platform into the 2Checkout system. 

Once 2Checkout approves the REVERSE/REFUND procedure, we send you an email and an IPN notification containing the status corresponding to the canceled transaction, REVERSE or REFUND respectively. We display the total canceled amount as a negative value.

Reversal

A reversal involves 2Checkout unblocking the shopper's balance corresponding to the transaction that we authorized for future capture immediately after payment confirmation, following approval from the financial department. Reversals happen before 2Checkout captures the authorized amount and also precedes order fulfillment/delivery. 2Checkout does not charge transaction processing commissions for orders that we reverse. Such orders feature the REVERSED status in the 2Checkout Control Panel as well as in all notifications regarding the reversal.

REFUND

2Checkout can only refund completed transactions associated with finalized orders (fulfilled/delivered). 

Method and URL

POST: https://secure.2checkout.com/order/irn.php

Authentication

You're required to validate each request with a HASH (HMAC_SHA256 signature). To build the HMAC_SHA256 source string, prepend each required value with its own length in bytes.

• Use 0 for null or empty values without prepending their length. However, when the value is 0 (zero), you do need to prepend its length (1).
• Note that for UTF-8 characters the length in bytes can be longer than the string length.

IRN HASH example

For the purposes of this example, we assume that the values of the secret key are 123456789!@#$%^&*. Your secret key is available in the Account Settings area of your account. 

Parameters to be included in the HASH signature

$params = array(
'MERCHANT' => 'MERCCODE',
'ORDER_REF' => 12345678,
'ORDER_AMOUNT' => 39.99,
'ORDER_CURRENCY' => 'USD',
'IRN_DATE' => '2012-12-12 12:12:12',
'PRODUCTS_IDS' => array(35386, 35387),
'PRODUCTS_QTY' => array(1, 2),
'REGENERATE_CODES' => array('1234-5678-9012-3456'),
'LICENSE_HANDLING' => array('CANCEL')
);

Serialized string for hash 

8MERCCODE812345678539.993USD192012-12-12 12:12:125353865353871112191234-5678-9012-34566CANCEL

Hash: e24fe2f3a2fadcd375be2fc9410d48fe

Parameters

Include parameters in the request in the exact order featured below. 

Response

2Checkout validates your request by showing a response in the page that receives the information, under the following format:

<EPAYMENT>ORDER_REF|RESPONSE_CODE|RESPONSE_MSG|IRN_DATE|ORDER_HASH </EPAYMENT>

The parameters in the validation signature 2Checkout sends:

If the 2Checkout response is set to be sent to a specific URL (the REF_URL parameter contains a valid URL), the reply will be sent as follows:

REF_URL = http://www.mysite.com/callback.php

http://www.mysite.com/callback.php?ORDER_REF=value&RESPONSE_CODE=value&RESPONSE_MSG=value&IRN_DATE=value&ORDER_HASH=value

Secret key: 123456789!@#$%^&*

<EPAYMENT>12345678|1|OK|2012-12-12 12:12:12</EPAYMENT>

Serialized string for hash: 812345678112OK192012-12-12 12:12:12

Hash: e8324511d50f0f78a0a20aca28295290

IRN response codes and messages

*In some cases “Response message” does not have a “Response code”.

Batch refunds/reversals

Batch processing is not supported. You need to send standalone requests for every reverse or total/partial refund.

PHP code samples

Total refund

<?php

function SerializeArray($myarray, $strip_slashes = true, $elementsToProcess = null)
{
    $retvalue = "";
    if ($elementsToProcess !== null && is_array($elementsToProcess)) {
        $_myarray = $myarray;
        $myarray = array();

        foreach ($elementsToProcess as $key) {
            if (!isset($_myarray[$key])) {
                continue;
            }
            $myarray[$key] = $_myarray[$key];
        }
    }
    foreach ($myarray as $val) {
        if (is_array($val)) {
            $retvalue .= SerializeArray($val, $strip_slashes);
        } else {
            $size = ($strip_slashes) ? strlen(StripSlashes($val)) : strlen($val);
            $retvalue .= ($strip_slashes) ? $size . StripSlashes($val) : $size . $val;
        }
    }

    return $retvalue;
}

$key = "SECRET_KEY";

$algo = "sha256"; // or sha3-256

$irn = array(
    'MERCHANT'       => 'MERCHANT',
    'ORDER_REF'      => 12345678,
    'ORDER_AMOUNT'   => 11.00,
    'ORDER_CURRENCY' => 'USD',
    'IRN_DATE'       => date('Y-m-d H:i:s'),
    'SIGNATURE_ALG'  => $algo,
    'REFUND_REASON'  => 'Other' // send one of the 2Checkout predefined reasons, or your customized reason
);

$process = array(
    'MERCHANT',
    'ORDER_REF',
    'ORDER_AMOUNT',
    'ORDER_CURRENCY',
    'IRN_DATE',
    'PRODUCTS_IDS',
    'PRODUCTS_QTY',
    'REGENERATE_CODES',
    'LICENSE_HANDLING',
    'AMOUNT'
);
$string = SerializeArray($irn, true, $process);

$hash = hash_hmac($algo, $string, $key);

$irn['ORDER_HASH'] = $hash;

$dataels = array();

$data = http_build_query($irn); $curl = curl_init("https://secure.2checkout.com/order/irn.php");
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 1);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 2);
curl_setopt($curl, CURLOPT_SSLVERSION, 0);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($curl, CURLOPT_PROXY, '');
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
$responseString = curl_exec($curl);

var_dump($responseString); 

Multiple partial refunds

<?php

function SerializeArray($myarray, $strip_slashes = true, $elementsToProcess = null)
{
    $retvalue = "";
    if ($elementsToProcess !== null && is_array($elementsToProcess)) {
        $_myarray = $myarray;
        $myarray = array();

        foreach ($elementsToProcess as $key) {
            if (!isset($_myarray[$key])) {
                continue;
            }
            $myarray[$key] = $_myarray[$key];
        }
    }
    foreach ($myarray as $val) {
        if (is_array($val)) {
            $retvalue .= SerializeArray($val, $strip_slashes);
        } else {
            $size = ($strip_slashes) ? strlen(StripSlashes($val)) : strlen($val);
            $retvalue .= ($strip_slashes) ? $size . StripSlashes($val) : $size . $val;
        }
    }

    return $retvalue;
}

$key = "SECRET_KEY";

$algo = "sha256"; // or sha3-256

$irn = array(
    'MERCHANT'       => 'MERCHANT',
    'ORDER_REF'      => 12345678,
    'ORDER_AMOUNT'   => 11.00,
    'ORDER_CURRENCY' => 'USD',
    'IRN_DATE'       => date('Y-m-d H:i:s'),
    'PRODUCTS_IDS'   => array(1119321, 2225673),
    'PRODUCTS_QTY'   => array(1, 1),
    'SIGNATURE_ALG'  => $algo,
    'AMOUNT'         => array('1.00', '5.00')
);

$process = array(
    'MERCHANT',
    'ORDER_REF',
    'ORDER_AMOUNT',
    'ORDER_CURRENCY',
    'IRN_DATE',
    'PRODUCTS_IDS',
    'PRODUCTS_QTY',
    'REGENERATE_CODES',
    'LICENSE_HANDLING',
    'AMOUNT'
);
$string = SerializeArray($irn, true, $process);

$hash = hash_hmac($algo, $string, $key);

$irn['ORDER_HASH'] = $hash;

$dataels = array();

$data = http_build_query($irn);  

$curl = curl_init("https://secure.2checkout.com/order/irn.php"); curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 1);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 2);
curl_setopt($curl, CURLOPT_SSLVERSION, 0);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($curl, CURLOPT_PROXY, '');
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
$responseString = curl_exec($curl);

var_dump($responseString); 

Overview

2Checkout complies with regulatory obligations worldwide and is committed to providing a secure platform for all our customers. This is why we are asking you to confirm your identify and provide proof of ownership of your company.

Account identity verification is a process referred to as "Know Your Customer" (KYC). We have simplified the process of supplying all valid, relevant documents, which should take you only a few minutes, and we appreciate your cooperation when it comes to verifying your information and reducing risk.

Requirements

Provide scanned copies of valid, relevant documents (i.e., do not include expired documents).

Workflow

For new accounts

1. Sign-up for a 2Checkout account.

2. Navigate to the Know your customer area and upload scanned copies of relevant documents from the checklist in this article. This will accelerate the review process and you can start selling and accepting transactions from customers worldwide.

3. Newly created 2Checkout accounts undergo a review.

4. Work with the 2Checkout underwriting team to help validate your information.

For existing accounts

1. Log in to your Merchant Control Panel account.

2. Navigate to Settings in the upper right corner of your Dashboard, as shown below.

3. In the Account Settings window, scroll down to the Account Information section and click on the Business Details link, as the image below shows.

4. In the Know your customer documents window, scroll down to the Upload documents field and select the type/types of documents you want to upload. 

5. After adding your scanned copies of documents, click on the Upload button.

As regulatory and compliance obligations change over time, 2Checkout can request additional valid, relevant documents to verify your identity and proof of ownership of your company.

KYC Documents Checklist

The document checklist is different for individuals and for businesses/companies.

Individuals

• Valid government-issued ID such as a passport or national identity card
• Valid address proof, such as electricity bill, telephone bill (no older than two months from the date when you upload the scanned copies)
• Any other valid, relevant documents that can prove your identity (in addition to the government-issued ID)

Companies/Business Entities

• Company ownership documents (such as Articles of Incorporation or Organization, showing beneficial ownership)
• Tax identification documents
  
  • Europe - TIN or other relevant documentation
  • US - SSN / TIN / PTIN or other relevant documentation
• Valid government-issued ID such as a passport or national identity card. Include DOB, for anybody with 10% or more ownership in the company
• Any other valid, relevant documents that can prove your identity and offer proof of ownership for your company.

Overview

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

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$LanguageCode = 'de'; //returns title and description texts you set under https://secure.2checkout.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));

Subscription details

After logging in to your Merchant Control Panel account, navigate to Orders & Customers → Subscriptions, and use the Subscription search filters to see subscriptions of a certain type and/or from a specific time period.

Click the View button in the Subscription details column to see more details.

Main subscription details page area

At the top of the page you can see some general details of the subscription:

• Subscription status;
  • Subscription details: An upgraded label will be applicable only to the upgraded subscriptions with disable option
• 2Checkout Subscription Reference;
• Customer (the shopper who made the purchase);
• Product name

Subscription info

This area centralizes details on:

• Start date;
• Expiration date;
• Billing cycle value;
• Automatic billing status;
• Payment Method and the four last digits of the credit/debit card used for payments;
• Next billing date;
• Current billing amount.

Statistics

This area shows an overview of the subscription value expressed in your account's default settlement currency.

The statistics offer a quick overview of the evolution of a subscription, helping you to keep track of renewals, upgrades, and notifications.

Manual renewal and upgrade

Access manual renewal and upgrade links for subscriptions. 

Subscription history

This area centralizes information on orders (including unfinished renewals), notifications and changes impacting a specific subscription. You can see if one of your customers chose to opt-out from renewal e-mails using the unsubscribe link from the reminder e-mails, or from his 2Checkout account. The actions of subscribing to renewal e-mails are also captured in the subscription history.

Expiration notification

For expired subscriptions, you can send a renewal reminder to your customers directly from the Subscription page. Click the Send expiration email and choose whether the expired card instructions should also be included in the email notification.

End-user 

This area shows details of the subscription's end user. The data is identical to the delivery details the customer entered when placing the initial order and can be identical to the billing information.

Subscription renewal billing following the initial purchase will be done using the end-user details, and not the original billing information supplied by the customer when the product was first purchased.

You can edit this data by clicking the Edit button.

Overview

In order to pass the identity of the merchant to the 2Checkout Signature Generation API endpoint, you need to generate a valid JSON Web Token (JWT). This is an Internet standard for creating JSON-based access tokens that assert some number of claims.

The https://jwt.io/ website allows you to decode, verify, and generate JSON Web Tokens.

Recommended resources

JWTs are credentials, which can grant access to resources. Be careful where you paste them!

Generate a merchant JWT

To generate a merchant JWT, follow the steps below:

1. Before generating a JWT, you need to copy the Buy-link Secret Word from your Merchant Control Panel. Log in to your Control Panel and navigate to Integrations → Webhooks & API → Secret word section.

2. Copy the string from the Buy-link Secret Word field to the clipboard.

3. Navigate to the https://jwt.io website and start generating the JWT token.

• In the Debugger section, you need to input data into the sections highlighted in this image.

• The data in the HEADER section identifies which algorithm and token type are used to generate the signature. For your JWT token, use HMAC-SHA-512 (HS512) and token type JWT:

  • alg: HS512 (string, required) - encryption algorithm;

  • typ: JWT (string, required) - token type;

{
 "alg" : "HS512",
 "typ" : "JWT"
}

• The PAYLOAD section contains a set of claims. The JWT specification defines seven Registered Claim Names which are the standard fields commonly included in tokens. For your JWT, use the following claims:

  • sub: MERCH_CODE (string, required) - subject, the merchant code whom the token refers;

  • iat: 1580915730 (string, required) - issued at, must be current timestamp since the UNIX epoch;

  • exp: 1580915730 (string, optional) - expiration time, must be in UNIX timestamp format from future.

If the expiration time (exp) is not provided, the JWT token expiration time will be calculated from iat + 30 minutes.

All the other fields/claims will be ignored.

 {
  "sub": "MERCH_CODE",
  "iat": 1580912768,
  "exp": 1580916205
}

• In the VERIFY SIGNATURE section, you calculate the signature. This is calculated by encoding the header and payload using Base64url encoding and concatenating the two values with a period separator. Then run the resulting string through the cryptographic algorithm specified in the header, which in this case is HMAC-SHA512.
• For your JWT token, replace the <Buy link secret word> from the example below with your Buy-link Secret Word from step 1.

HMACSHA512(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  <Buy link secret word>
)

•  You will get the JWT token:

eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJz...z0ZY6L6T1GvlOHiptgOQ

4. Use this JWT token in the future to pass your identity as a merchant to the 2Checkout Signature Generation API endpoint. 

Overview

Use the addProductGroup method to create product groups for your account:

• Send null for product group Code. 2Checkout ignores any values you send for Code and generates identifiers itself. 
• Use unique product group names. 
• 2Checkout throws an exception if you send a blank product group.
• If you send only the name of the product group 2Checkout creates the new product group entity. 

Parameters

Response

bool(true)

Request

<?php

require ('PATH_TO_AUTH');

$ProductGroup = new stdClass();
$ProductGroup->Name = 'New Product Group from API';
$ProductGroup->Code = null;//Send null for the Code. 2Checkout generates unique product group code identifiers.
$ProductGroup->TemplateName = 'Default Template';//'001 - Two Column Billing'; //the name of the cart template you want to associate with the product group
$ProductGroup->Description = 'This is a generic description';

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

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

?>

Overview

Use the createProposal method via JSON-RPC 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";

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

try {
    $result = callRPC($jsonRpcRequest, $host);
    echo "Proposal: </br>", 
    var_dump($result);
}
catch (SoapFault $e) {
    echo "Could not fetch 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->Terms = 30;
        $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;
        $lineItem->ProrationDate = "2020-11-14T15:28:56+00:00";
        $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";

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

        try {
            $result = callRPC($jsonRpcRequest, $host);
            echo "Proposal: </br>",
            var_dump($result);
        } catch (SoapFault $e) {
            echo "Could not fetch 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";

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

        try {
            $result = callRPC($jsonRpcRequest, $host);
            echo "Proposal: </br>", 
            var_dump($result);
        }
        catch (SoapFault $e) {
            echo "Could not fetch 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";

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

        try {
            $result = callRPC($jsonRpcRequest, $host);
            echo "Proposal: </br>", 
            var_dump($result);
        }
        catch (SoapFault $e) {
            echo "Could not fetch proposal: " . $e->getMessage();
            exit;
        }

Response

The createProposal API call returns Proposal object.

Overview

Use this object to retrieve information about the cross-sell campaigns you configured for your account. 

Parameters

Overview

Minimize your customers' effort by collecting their order/billing information and passing it to InLine Checkout. Simplify the checkout experience and enable your customers to place orders only by confirming their payment information.

Related links

Advanced InLine Checkout experience

InLine Checkout offers you advanced control over the ordering process, for minimizing the customer's effort during the purchase. You can send the billing and delivery information directly to the cart if they are collected on your website by a shopping cart application. InLine Checkout enables you to:

• Place test orders
• Set coupons codes in cart
• Set the cart language
• Set the cart currency
• Set a redirect URL after a finalized purchase

We recently improved the perceived loading time for the InLine checkout ordering engine by pre-loading the cart iframe. Faster loading time for the InLine cart means an enhanced shopping experience and helps you to increase conversion rates with no other effort on your side. See more details below in the Cart methods table.

Send information to InLine Checkout

After you integrate the InLine Checkout JavaScript code in your website application, you get access to the library that allows you to add products, control billing and shipping details, and start the checkout process. Follow the instructions below to control the information displayed by InLine Checkout.

Handling products

Products are handled by the products' service. This service allows you to retrieve the list of added products, add products to cart, remove individual products, or remove all the products from the cart.

Use the methods and product attributes listed below to add/remove products from the cart.

Product attributes

Product methods

HANDLING billing details

Billing details are handled by the billing service. Each billing information is controlled by a setter method.

Use the attributes and methods listed below to control the billing information displayed in the cart. Customers are able to fill in their billing information in the overlay provided by InLine Checkout. In case your shopping cart application collects customer's billing information, use the attributes and methods listed below to pass that information over to the cart.

Billing details attributes

Billing details methods

Handle shipping details 

Shipping details are handled by the shipping service. Each shipping information is controlled by a setter method.

Use the attributes and methods listed below to control the shipping information displayed in the cart. In case you use a shopping cart application that collects the shipping information, use the attributes and methods listed below to pass that information over to the cart.

Shipping details attributes

Shipping details methods

HANDLE the Checkout process 

Control the cart behavior by using the cart service. Use the checkout method to start the InLine Checkout experience.

Cart attributes

Cart methods

Retrieve cart attributes from InLine Checkout by using get methods: getTest, getLanguage, getCurrency, getSource, getCoupons, getSuccessURL, getCustomerReference, getExternalCustomerReference, getCartLockedFlag.

*When inserting the JavaScript code snippet from your Control Panel into your e-commerce website, you will get access to the library that allows you to add products, control billing and shipping details, and start the checkout process, without having to call the register() method.

Subscribe to shopping cart events

To subscribe to shopping cart events you need to call the events service 'subscribe' method with the event name as the first argument and a callback function as the second argument.

Below you can find a list of events that are supported by the shopping cart and you can subscribe to:

1. 'cart:opened' - triggers when the shopping cart is opened.
2. 'cart:closed' - triggers when the shopping cart is closed.
3. 'payment:finalized' - triggers when the payment has finalized.
4. 'fulfillment:finalized' - triggers when the fulfillment is completed.

TwoCoInLineCart.events.subscribe('cart:opened', function () {
    console.log('cart:opened triggered');
});

Sample request for catalog products

TwoCoInlineCart.setup.setMerchant('merchantCode'); // your Merchant code
TwoCoInlineCart.register();

TwoCoInlineCart.billing.setCountry('US'); // customer billing country
TwoCoInlineCart.billing.setName('John Doe'); // customer billing Name
TwoCoInlineCart.billing.setEmail('john.doe@email.com'); // customer email address
TwoCoInlineCart.billing.setCompanyName('<company name>')
TwoCoInlineCart.billing.setFiscalCode('<fiscal code>')
TwoCoInlineCart.billing.setTaxOffice('<tax office>')
TwoCoInlineCart.cart.setReset(true); // erase previous cart sessions

TwoCoInlineCart.shipping.setName('Jane Doe'); // customer Delivery name
TwoCoInlineCart.shipping.setEmail('jane.doe@email.com'); // customer Delivery email

TwoCoInlineCart.products.add({
    code: 'the-2co-product-code',
    quantity: 3
    options: [{
       name: 'color',
       value: 'red'
   }]
});

TwoCoInlineCart.products.addMany([
    {
        type: 'PRODUCT', 
        name: 'product 1', 
        price: 10, 
        tangible: true, 
        quantity: 1, 
    },
    {
        type: 'PRODUCT', 
        name: 'product 2', 
        price: 30, 
        tangible: true, 
        quantity: 1, 
    }                
]);

TwoCoInlineCart.cart.addCoupon('50%OFF'); // discount code
TwoCoInlineCart.cart.setCurrency('GBP'); // order currency
TwoCoInlineCart.cart.setLanguage('fr'); // language code
TwoCoInlineCart.cart.setOrderExternalRef('1231231'); // order external reference
TwoCoInlineCart.cart.setExternalCustomerReference('ID123extern'); // external customer reference 
TwoCoInlineCart.cart.checkout(); // start checkout process

Sample request for dynamic products

TwoCoInlineCart.setup.setMerchant('merchantCode'); // your merchant code
TwoCoInlineCart.setup.setMode('DYNAMIC'); // product type
TwoCoInlineCart.register();

TwoCoInlineCart.cart.setCurrency('USD'); // order currency

TwoCoInlineCart.products.add({
name        : 'A test dynamic product',
recurrence:{
    unit: 'WEEK',
    length: 2
},
duration: {
    unit: 'YEAR',
    length: 1
},
renewalPrice: 100.99
});
TwoCoInlineCart.cart.checkout(); //start checkout process