Availability

Service Provider Pro (SPP) integration is available only for 2Checkout accounts that handle their own tax and invoice management (2Sell and 2Subscribe accounts). 

2Checkout Settings

To integrate with 2Checkout you’ll need to get your merchant code and secret word from 2Checkout.

• Create a 2Checkout account.
• Log into your 2Checkout account.
• In your dashboard, navigate to Integrations → Webhooks & API
• Your account number is at the top of the API section, under Merchant code
• Your Secret Word is located in the Secret word section:
  • Generate a new INS Secret Word and paste it in the Secret word section on this page
  • Your INS secret word should be the same as the buy-link secret word (found under Dashboard → Integrations → Webhooks & API, scroll down to the Secret Word area, as shown in the image below). Edit your INS secret word and buy-link secret word to match each other, then copy and paste them into your SPP admin.
  • Click on Save settings
• Enter both the seller ID (Merchant code) and your secret word in the SPP module
• On the settings page, navigate to Notification URL. Use this URL to set up notifications in your 2checkout account. (SPP can capture recurring subscription payment, canceled orders, and refunds or chargebacks.)
  • Go to 2checkout Dashboard → Integrations → Webhooks & API section
  • Check the Enable INS and the Enable global URL checkboxes
  • Paste the link from SPP in the field below the “Enable global URL”
  • Click Update to save your settings

About Service Provider Pro (SPP)

SPP is a boutique product-focused company that handles services businesses. Launched in 2014, SPP is helping professionals and agencies sell millions of dollars in services. Find out more about SPP here.

Overview

Product activation means sending the client an email message containing either a binary key (especially for software products) or an activation alphanumeric code for digital products like software and phone cards. The key or the code is used to unlock the subscriptions or get access to website content.

This feature is implemented by storing the keys or codes using two different types of lists:

• Static lists
• Dynamic lists

Static lists

Add a static list

1. Navigate to Fulfillment under Setup.
2. Enter a name and select the list type: Static.
3. Choose the type of codes your customers receive:
   
   • A single activation code that all shoppers share. 
   • Multiple codes that you can enter manually, one per line. You can also tweak the way that 2Checkout handles:
     
     • Duplicates. Your list may or may not contain duplicate codes. 
     • Codes in the context of several units purchased. Send multiple codes according to product quantity or a single code regardless of the number of units purchased. 
     • Notifications when a list is running low on available codes. 
4. Assign the products for which 2Checkout delivers codes from the list. 

Delete a static list

1. Navigate to Fulfillment under Setup.
2. Click Edit on the list you want to delete.
3. Remove all products from the list and save the changes.
4. Go back to the list catalog page and click the Delete button.
5. In the pop-up message, confirm the deletion of the list.

Dynamic lists

Use this option if you host the key generator on your servers.

Workflow

1. 2Checkout queries your code generator.
2. Your code generator creates the codes and provides them to 2Checkout.
3. 2Checkout delivers the codes to your shoppers in fulfillment emails, on the Thank You Page, and in their myAccount. 

Code generator output

For each approved order, 2Checkout queries your server with certain parameters (see parameters table) that you can use to generate codes/binary keys. Depending on the code or key format (alphanumeric or binary) the 2Checkout system expects either a:

• XML file (alphanumeric code or key)
• Or a binary file response (binary code or key)

Limitations

Key generators hosted on websites with self-signed certificates are not allowed.

The Skip TLS validation rule set in System settings applies only for webhook notifications (IPN/LCN/INS) and does not work for key generators.

Add a dynamic list 

To create dynamic lists:

1. Navigate to Fulfillment under Setup.
2. Enter a name and select the list type: Dynamic.
3. Enter the URL corresponding to the location on your server where you host your key generator.
4. Assign the products for which 2Checkout delivers codes from the list. 

Delete a dynamic list

1. Navigate to Fulfillment under Setup.
2. Click Edit on the list you want to delete.
3. Remove all products from the list and save the changes.
4. Go back to the list catalog page and click the Delete button.
5. In the pop-up message, confirm the deletion of the list.

Method and parameters

2Checkout sends the following parameters to your server using HTTP/HTTPS POST using the URL you supplied when configuring the dynamic list.

If you configure additional order fields and 2Checkout collects this type of info during the checkout process, it will be included in the POST request:

If you configure per-product price options 2Checkout also includes them in the POST request. Example: 2Checkout product ID (PID):714585

Generating the output

You can package your response as:

• XML for alphanumerical codes (Basic XML or Advanced XML)
• Binary attachment for binary keys
• Error code sent in the HTTP headers

XML files have certain reserved characters that must be escaped in a certain way when used. The reserved characters and their corresponding escape sequences are: 

• & (ampersand) converted to & 
• < (less than) converted to &lt; 
• > (greater than) converted to &gt; 
• " (double quote) converted to " 
• ' (single quote) converted to ' 

When XML files are created, please replace these characters in the attributes and inside the nodes with the correct escape sequence to have a syntactically correct XML document. These characters are documented in the XML specification: http://www.w3.org/TR/REC-xml/

HTTP Headers

HTTP servers use a large number of response and status codes, usually transparent for the navigator. These codes tell the browser if there was an error or not. The codes are embedded in the HTTP header of the client/server communication. The success status code is 200 while any other code is an error. For example, 400 means "Bad Request" and 403 means "Forbidden". HTTP response header examples:

• HTTP/1.0 400 Bad Request
• HTTP/1.0 200 OK

Content-type

Set the value of the Content-Type field to text/xml" in the header response when you package your response as XML.

Content-Type: text/xml

For all other values, 2Checkout s the content is a binary key.

Basic XML Answer format sample

Use the following template for your XML file :

<?xml version="1.0" encoding="UTF-8"?> 
<Data>
<code>SIMPLE_CODE 1</code>
<code>SIMPLE_CODE 2</code>
...
<code>SIMPLE_CODE N</code>
</Data>

Binary Attachment format

If you deliver a binary file, instead of XML, set the value of Content-Disposition in the header as in the example below. Include the attached file containing the key in the body of the message. Set the filename using the 'Content-Disposition' field.

Content-Disposition: attachment; filename=key.bin

Advanced XML Answer format

If you need to attach additional installation instructions or details to the delivered codes, you can use the XML structure detailed below:

<?xml version="1.0" encoding = "UTF-8" ?>
<data>
<description>General description (for all codes below)</description>
<code>
<description>Description for CODE 1 and/or the binary.key</description>
<key>CODE1</key>
<file name="binary.key" content_type = "text/plain">
UklGRhTsCABBVkkgTElTVCQBAABoZHJsYXZpaDgAAABqBAEAgPQDAAAAAAAQAAEALQAAAAAA
AAACAAAAgD4AAEABAADwAAAAAAAAAAAAAAAAAAAAAAAAAExJU1R0AAAAc3RybHN0cmD4MQAA
</file>
</code>
<code>
<description>Description for CODE 2</description>
<key>CODE 2</key>
</code>
<code>
<description>Description for the the binary_2.key</description>
<file name = "binary_2.key" >
UklGRhTsCABBVkkgTElTVCQBAABoZHJsYXZpaDgAAABqBAEAgPQDAAAAAAAQAAEALQAAAAAA
AAACAAAAgD4AAEABAADwAAAAAAAAAAAAAAAAAAAAAAAAAExJU1R0AAAAc3RybHN0cmD4MQAA
</file>
</code>
</data>

Security 

For security reasons we strongly recommend that you limit access to the key generator URL used to generate access codes or keys and grant access only to the 2Checkout server IP networks. 

HASH field

Use the value of the HASH field to check data integrity. 

Calculate the HASH signature

Example using the following data:

618964531237125074703YES114John3Doe018info@2checkout.com2en11Netherlands2nl10Amstelveen41181

Don't forget to check if the received order reference matches a valid reference order from your system.

Test orders

In the case of test orders, 2Checkout populates the TESTORDER parameter with the value YES. It is highly recommended to reply with testing codes or keys whenever receiving the above-mentioned parameter in the server request, and not codes/keys you would send to actual shoppers.

Code sample

<?php
/* Electronic Delivery */

/* pass to compute HASH. Retrieve your secret key by accessing https://secure.2checkout.com/cpanel/webhooks_api.php */
$secretKey = "AABBCCDDEEFF";

$signature = $_POST['HASH']; // HASH received

function serializeArray($array) {
    $retval = "";
    foreach ($array as $i => $value) {
        if (is_array($value)) {
            $retval .= serializeArray($value);
        }
        else {
            $size = strlen($value);
            $retval .= $size . $value;
        }
    }
    return $retval;
}

unset($_POST['HASH']);

// calculate the hash for the fields received (excluding the hash) to make sure the post is from 2Checkout and wasn't altered on the way
$sha256Hash = hash_hmac('sha256', serializeArray($_POST), $secretKey);
// only for php version > 7.1
$sha3256Hash = '';
if (in_array('sha3-256', hash_algos())) {
    $sha3256Hash = hash_hmac('sha3-256', serializeArray($_POST), $secretKey);
}

// only for php version > 7.1; remove $sha3256Hash from the array otherwise
if (!in_array($signature, array_filter([$sha256Hash, $sha3256Hash]))) {
    http_response_code(400);
    mail("your_address@example.com","BAD ElDel Signature", print_r($_POST, TRUE),"");
    echo 'Invalid signature.'; // 2Checkout logs your answer for debug purposes

    return;
}


// if valid hash continue script

// rudimentary example of business logic
// this example uses only 2Checkout ProductId to decide the output

switch($_POST['PID']) {
    case '123': //for this product your key is a binary file
            
        header('HTTP/1.0 200 OK',false, 200); //inform 2Checkout you received a valid post, you shouldn't have to set this header explicitly
        header('Content-Type: application/octet-stream'); //set the mime type
        header('Content-Disposition: filename=key_123.bin'); //set the file name
        readfile(dirname(__FILE__).'/key_123.zip'); //output the file

        //make sure your script doesn't output anything after this point and/or stop script execution
        exit;

    case '1234': //for this product your key is a text file
            
        header('HTTP/1.0 200 OK',false, 200); //inform 2Checkout you received a valid post, you shouldn't have to set this header explicitly
        header('Content-Type: text/plain'); //set the mime type
        header('Content-Disposition: filename=key_1234.txt'); //set the file name
        readfile(dirname(__FILE__).'/key_1234.log'); //output the file

        //make sure your script doesn't output anything after this point and/or stop script execution
        exit;
            
    case '12345': //for this product your key is a string

        //build a basic xml with the following structure:
        $basic_xml =  '<?xml version="1.0"?>
                            <data>
                                <code>12345 key</code> <!-- your string key here -->
                            </data>';
            
        header('HTTP/1.0 200 OK',false, 200); //inform 2Checkout you received a valid post, you shouldn't have to set this header explicitly
        header('Content-Type: text/xml');
        echo  $basic_xml; //make sure the script doesn't output anything after this point and/or stop script execution
        exit;

    case '123456': //this product is a bundle and contains several string keys
            
        //the xml gets a bit more complicated
        $advanced_xml ='<?xml version="1.0"?>
                            <data>
                              <description>Bundle 123456</description> <!--General description (for all codes below), it will be displayed/sent to enduser-->
                              <code>
                                  <description>key for bundle component 1</description> <!--description for CODE 1, it will be displayed/sent to enduser -->
                                  <key>bundle comp 1 </key> <!-- string key -->
                              </code>
                              <code>
                                  <description>key for bundle component 2</description> <!--description for CODE 2, it will be displayed/sent to enduser -->
                                  <key>bundle comp 2 </key> <!-- string key -->
                              </code>
                            </data>';
            
        header('HTTP/1.0 200 OK',false, 200); //inform 2Checkout you received a valid post, you shouldn't have to set this header explicitly
        header('Content-Type: text/xml');
        echo  $advanced_xml; //make sure the script doesn't output anything after this point and/or stop script execution
        exit;

    case '1234567': //this product is a bundle and one of the products has a string file and a file attached
            
        //the xml contains the new tags: file and extra
        $advanced_xml ='<?xml version="1.0"?>
                            <data>
                              <description>Bundle 123456</description> <!--General description (for all codes below), it will be displayed/sent to enduser-->
                              <code>
                                  <description>key for bundle component 1</description><!-- description for CODE 1, it will be displayed/sent to enduser -->
                                  <key>bundle comp 1 </key><!-- string key -->
                                   <file name="binary.key" content_type = "text/plain"><!-- the file name and content type will be used when offering the file for download to user.
                                   <![CDATA['.base64_encode(file_get_contents(dirname(__FILE__).'/key_p1_1234567.log')).']]>
                                   </file>
                              </code>
                              <code>
                                  <description>key for bundle component 2</description> <!--description for CODE 2, it will be displayed/sent to enduser -->
                                  <key>bundle comp 2 </key> <!-- string key -->
                                  <extra type="INSTALL_HOTLINE" label="Install hotline number">0740216669</extra> <!--the content and label of the extra tags is displayed in cpanel and sent to end-user through the electronic delivery mail-->
                                  <extra type="OPERATING_SYSTEM" label="Works on the following operating systems">Windows XP, Windows 7, Windows 8</extra> <!--the content and label of the extra tags is displayed in cpanel and sent to end-user through the electronic delivery mail-->
                              </code>
                            </data>';
            
        header('HTTP/1.0 200 OK',false, 200); //inform 2Checkout you received a valid post, you shouldn't have to set this header explicitly
        header('Content-Type: text/xml');
        echo  $advanced_xml; //make sure the script doesn't output anything after this point and/or stop script execution
        exit;
}

Overview

Quick payments allow you to provide extra money to your top affiliates either though a one-time payment or via recurrent payments.

Availability

All 2Checkout accounts. 

Generate quick payments reports

You can find the Quick payments tab in the Accounting -> Direct payments menu.

1. Use the Quick payments search section to configure the filters used in generating the report. You can filter the results by target affiliate, website or the payment date.
2. Once you have finished configuring your filters, click Search. The report is displayed below and it contains 10 results/page. You can extend the displayed results number to 20 results/page
3. To export the entire report as a CSV file you can use the Export as CSV button.

The report shows you the payment date, the target affiliate, the amount you paid to your affiliate, 2Checkout's commission and the payment status (Succeeded orFailed).

Overview

Manage the lifecycle of your subscriptions and control different processes such as delaying the start of a subscription, canceling a subscription, searching a subscription from the Subscriptions page in your Merchant Control Panel.

Availability 

The Subscriptions section is available to all 2Checkout accounts. For more details about subscriptions, read here.

Overview

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

Parameters

Overview

Use the convertTrial method to convert a trial to a paid subscription. In the eventuality of a conversion failure, you can use convertTrial again for the same trial subscription only after you let 24 hours pass since the initial attempt. The 2Checkout system attempts to automatically convert trials before they expire to full subscriptions, unless you made an attempt that failed less than 24 hours before the scheduled expiration deadline.

In case the trial conversion fails due to a transaction issue, the 2Checkout system sends unfinished payment follow-up emails to customers, provided that you set up lead management for your account.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH'); 
 
$SubscriptionReference = 'BF44555C6C';

$ExtendSubscriptionFromPaymentDate = true; //false can also be used if you want the subscription start date to be the moment when the trial was set to initially expire.

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

Overview

Use the searchLeads method to retrieve leads created in the 2Checkout system.

Request Parameters

Request Example

<?php

require ('PATH_TO_AUTH');

$LeadSearchInput = new stdClass();

$LeadSearchInput->Type = "New";
$LeadSearchInput->Language = "BG";
$LeadSearchInput->Country = "RO";
$LeadSearchInput->Page = 1;
$LeadSearchInput->Limit = 200;

try {
    $leadData = $client->searchLeads($sessionID, $LeadSearchInput);
} catch (SoapFault $e) {
    echo "searchLeads: " . $e->getMessage();
    exit;
}

var_dump("searchLeads", $leadData);

Response Example

class stdClass#4 (2) {
  public $Items =>
  class stdClass#5 (1) {
    public $0 =>
    class stdClass#6 (14) {
      public $LeadCode =>
      string(10) "60E6C4B574"
      public $GeneratedFrom =>
      string(3) "API"
      public $CartId =>
      string(11) "CartIdValue"
      public $Currency =>
      string(3) "EUR"
      public $Language =>
      string(2) "BG"
      public $ExternalReference =>
      string(18) "REST_API_3CHECKOUT"
      public $MachineId =>
      string(6) "123asd"
      public $LocalTime =>
      string(19) "2019-11-05 16:48:28"
      public $Items =>
      class stdClass#7 (1) {
        public $0 =>
        class stdClass#8 (15) {
          public $Code =>
          string(10) "04C26C50F8"
          public $Quantity =>
          string(1) "2"
          public $SKU =>
          NULL
          public $Name =>
          string(5) "softy"
          public $Description =>
          NULL
          public $IsDynamic =>
          bool(false)
          public $Tangible =>
          bool(false)
          public $PurchaseType =>
          string(7) "PRODUCT"
          public $PriceOptions =>
          NULL
          }
          public $RecurringOptions =>
          class stdClass#9 (5) {
            public $CycleLength =>
            NULL
            public $CycleUnit =>
            NULL
            public $CycleAmount =>
            NULL
            public $ContractLength =>
            NULL
            public $ContractUnit =>
            NULL
          }
          public $RenewalInformation =>
          class stdClass#10 (1) {
            public $SubscriptionReference =>
            NULL
          }
          public $MarketingCampaigns =>
          class stdClass#11 (3) {
            public $Type =>
            string(2) "23"
            public $ParentCode =>
            string(1) "m"
            public $CampaignCode =>
            string(2) "23"
          }
          public $Price =>
          class stdClass#12 (2) {
            public $Amount =>
            string(2) "20"
            public $Type =>
            string(6) "CUSTOM"
          }
          public $AdditionalFields =>
          NULL
          public $SubscriptionStartDate =>
          string(19) "2019-11-05 16:48:28"
        }
      }
      public $BillingDetails =>
      class stdClass#13 (12) {
        public $FirstName =>
        string(8) "Customer"
        public $LastName =>
        string(9) "2Checkout"
        public $Phone =>
        NULL
        public $Company =>
        NULL
        public $FiscalCode =>
        string(8) "32423423"
        public $Email =>
        string(22) "customer@2checkout.com"
        public $Address1 =>
        string(12) "Test Address"
        public $Address2 =>
        NULL
        public $City =>
        string(2) "LA"
        public $Zip =>
        string(5) "12345"
        public $CountryCode =>
        string(2) "RO"
        public $State =>
        string(2) "CA"
      }
      public $DeliveryDetails =>
      class stdClass#14 (12) {
        public $FirstName =>
        string(8) "Customer"
        public $LastName =>
        string(9) "2Checkout"
        public $Phone =>
        NULL
        public $Company =>
        NULL
        public $FiscalCode =>
        string(8) "32423423"
        public $Email =>
        string(22) "customer@2checkout.com"
        public $Address1 =>
        string(12) "Test Address"
        public $Address2 =>
        NULL
        public $City =>
        string(2) "LA"
        public $Zip =>
        string(5) "12345"
        public $CountryCode =>
        string(2) "RO"
        public $State =>
        string(2) "CA"
      }
      public $DeliveryInformation =>
      class stdClass#15 (1) {
        public $ShippingMethod =>
        class stdClass#16 (1) {
          public $Code =>
          string(5) "sdfsd"
        }
      }
      public $PaymentDetails =>
      class stdClass#17 (4) {
        public $Type =>
        string(2) "CC"
        public $Currency =>
        string(3) "EUR"
        public $PaymentMethod =>
        class stdClass#18 (2) {
          public $RecurringEnabled =>
          bool(false)
          public $CardPayment =>
          class stdClass#19 (1) {
            public $InstallmentsNumber =>
            string(2) "23"
          }
        }
        public $CustomerIP =>
        string(7) "1.2.3.4"
      }
      public $Promotions =>
      array(1) {
        [0] =>
        string(0) ""
      }
    }
  }
  public $Pagination =>
  class stdClass#20 (3) {
    public $Page =>
    int(1)
    public $Limit =>
    int(200)
    public $Count =>
    int(1)
  }
}

Overview

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

Retrieve a customer

Customer object

Overview

With Trustly, you can accept payments, issue payouts, and access valuable user insight data. Easy activation and multi-currency functionality give you the power to expand your business across borders with access to customers in Europe, Australia, Canada, and the US.

Availability

Trustly is available for shoppers in the following countries:

• Austria
• Croatia
• Cyprus
• Czech Republic
• Denmark
• Estonia
• Finland
• Germany
• Latvia
• Lithuania
• Malta
• Netherlands
• Norway
• Spain
• Sweden
• United Kingdom

Requirements

Make sure the billing country code is set to AT, CY, CZ, DE, DK, EE, ES, FI, GB, HR, LT, LV, MT, NL, SE.

Supported currencies

• CZK
• DKK
• EUR
• GBP
• NOK
• SEK

Workflow

1. Shoppers select Trustly as a payment option in the interface you provide to them.
2. Create the order object. Use TRUSTLY as the type of the PaymentDetails object, and include ReturnURL.
3. Use the placeOrder method to send the data to 2Checkout.
4. Once you place the order, 2Checkout logs it into the system. At this point in time, the status of the order is PENDING.
5. 2Checkout returns an order object as the output of the placeOrder method. 
6. 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.avangate.com/6.0/scripts...bc7fd72d008428
7. After being redirected to Trustly, shoppers need to complete the steps of Trustly payment flow.
8. After customers enter their payment data to Trustly, Trustly notifies 2Checkout if the payment is approved, and the status of the order becomes COMPLETE.
9. Shoppers are redirected to the RedirectURL from the order information object. In case the payment fails, shoppers are redirected to the CancelURL. 

Overview

Refund a sale made in 2Checkout via the issueRefund API method. Depending on your business needs, you can refund only one sale item, the entire order amount, or a partial amount from the total order.

Requirements

The payment for the refundable order needs to be collected.

You cannot issue a refund for an amount higher than the total order amount.

Parameters