Overview

Use Order search data portability capabilities to generate and export a chargeback dispute report.

Create a custom template for the chargeback report in order search

Before generating a chargeback report you need to create its corresponding order search export template. Follow these steps:

1. Go to Orders & customers -> Order search.
2. Run a search. Optional: you can filter results, but this is not necessary.
3. Click Export.
4. Click Edit templates in the pop-up.
5. Click Add new template on the Export Templates settings page.
6. Enter a unique name for this order search export template. For example: Custom Chargebacks Report.
7. Select the information that will be included in this report. For example:
   
   • Under Order:
     
     • Reference no
     • Order date
     • Chargeback status
     • Chargeback reason
   • Under Product:
     
     • Product ID
     • Product
   • Under Price:
     
     • Currency
     • General total
   • Under Customer and End User information:
     
     • Client
   • This enables you to choose the column headers of the order search report which can be exported as a .CSV (comma separated values) or an .XLS (Excel) file, or the XML elements when the export is a XML file.
8. Once you selected the type of details to be included into the report, click the arrow button between the Additional Column headers and the Template Column headers fields.
9. The desired details will be added to the Template Column headers. Click Save to add the new template to the list of existing items.

Note: You can include additional info in the report, based on your account's specific setup.

For complete guidance on order search export templates please read: Custom order search export templates - XML , CSV, XLS.

Export a custom chargeback report using order search

1. Navigate to Order search under Orders & customers.
2. Under order status, select Finished. Chargebacks can only be opened for finished orders.
3. Select the desired order search interval.
4. Run a search.
5. Click the Export button.
6. In the pop-up, select the desired download format, for example CSV.
7. Open the menu under Export Templates and select the custom chargeback export template you created. Click Export.
8. Save the exported chargebacks report locally on your machine, and open it with your preferred CSV editor (you can use Office Excel for example).

The report will include all orders returned to the search you performed, but you can filter content based on the Chargeback reason and Chargeback status column headers.

Introduction

Use the Avangate API to create, update and extract product catalog and pricing information for your account, place orders and manage subscriptions.

Workflow

1. Use the following URLs:

https://api.avangate.com/soap/4.0/

Full service description is available at: https://api.avangate.com/soap/4.0/?wsdl

1. Authenticate using the login method and create a session (connection).
2. Throughout the lifetime of the session (max 10 minutes) you can invoke all Avangate API methods. To invoke methods you need to send a request to Avangate.
3. The Avangate system provides responses for all requests.

Code samples

The code samples included in this document work with PHP version 5.6.  

Overview

Apply promotions to recurring charges, overwriting the renewal price configured for each product included in the promotion.

Availability

You can configure all regular promotions to apply to either all recurring charges or a limited number.

Adding a recurring promotion

1. Go to Marketing tools -> Promotions -> Regular promotions.
2. Click Add regular promotion.
3. Give the promotion a suggestive title and description. Shoppers can see the promotion title during purchase.
   
   • Add localized promotion names for any of the supported languages. The 2Checkout shopping cart automatically displays localized promotion names based on the selected shopping cart language.
4. Select when you want the promotion to run. You can limit promotions to a specific time interval or let them run indefinitely. To start a promotion as soon as you mark it Active, leave the start date empty. If you don't set the end date, the promotion will stop when the maximum number of orders has been reached or will continue to run if the maximum number of orders is unlimited.
5. Choose the coupon/voucher type:
   
   • Single - one voucher to impact multiple orders;
   • Multiple - individual and unique, per-order vouchers.
6. Choose whether to restrict the promotion to a number of orders, or apply it for all orders. This option is only available for single coupons.
7. Fill in the promotion coupon/voucher code. The maximum length of a coupon code is 255 alphanumeric characters.
   
   • Single: enter the coupon values manually
   • Multiple: either add the values manually one coupon per line, or use the coupon generator available in the Merchant Control Panel to generate 5, 10, 20, 30, 50, or 100 vouchers at a time and either append them to an existing list or replace existing items. The generator creates random vouchers that resemble this: D8C10E32. 2Checkout recommends limiting the number of coupon codes to a maximum of 25000.
8. Choose whether or not to apply discounts automatically. Only available for single coupons. This option applies discounts to all selected products in all orders, without the need for shoppers to enter the coupon manually.
9. Configure the recurring settings. You can apply it to none, to one recurring charge, to all or to a specific number of recurring charges after which the renewal price is recalculated.
10. Choose whether or not to publish the promotion to the 2Checkout Affiliate Network.
11. Activate the promotion.
12. Select the products to be included in the promotion.
13. Click Save.

Renewal discounts

As an alternative to recurring promotions, you can configure renewal discounts. In this case, the coupon is applied automatically per product during renewal. 

1. Go to Setup -> Renewal -> Renewal discounts.
2. Click Add renewal discount.
3. Enter a promotion title (visible to shoppers during purchase) and description.
   
   • Add localized promotion names for any of the supported languages. The 2Checkout shopping cart automatically displays localized promotion names based on the selected shopping cart language.
4. Enter the discount coupon code in the discount code field.
5. Set the discount to either percentage-based or fixed.
6. Select the number of renewal charges to apply the discount to. You can apply it to:
   
   • one renewal charge 
   • each renewal charge
     
     • Formally named The first renewal charge only. 
     • Discounted price will be calculated on each renewal.
   • all renewal charges
     
     • Discounted price is only calculated once and used for all future renewals (usage costs are not impacted).
   • each number of renewal charges (defined by you)
     
     • Formally named A limited number of charges. 
     • Discounted price is calculated every x renewal charges.
7. Save the promotion.

By choosing to apply the discount to all renewal charges, 2Checkout will set the discounted price as the subscription custom price.

Overview

Use the getInvoices method to extract shopper invoices from the Avangate system based on unique order references. The method returns the binary code for invoices in the PDF file format, Base64 encoded (Base64 is used to represent binary data in the ASCII string format).

getInvoices works for COMPLETE orders for which an invoice was already issued. For refunded orders, getInvoices provides two shopper invoices, one for the original order and the second for the refund, reflecting the repayment made.

In the case of cross-selling orders which contain products from different merchants, getInvoice enables you to re-send only the invoices for your own offerings.

Parameters

Request

<?php

require ('PATH_TO_AUTH');

$reference = 'ORDER_REFERENCE';

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

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

Response

Overview

2Checkout provides a HASH signature enabling you to check the source and validity of placed orders in scenarios requiring customers to go through extra steps after successfully finishing the ordering process to access the purchased product/service.

An example is requiring some additional information from your customers after they place the order to let them access their subscription.

1. The customer places the order and views the Thank you page.
2. The customer is redirect to your website via a link containing all parameters necessary for you to validate the order.
3. You need to check the data sent by the 2Checkout system.

Usage

2Checkout offers the following elements that you can use for validation:

1. The securityHashSource string. securityHashSource is a serialized value of the order reference number, order status, list of products IDs, list of quantities for each product and order date.

   Example: securityHashSource components:

   • order reference number (643276 - 6 characters); 

   • the order status (AUTHRECEIVED - 12 chars);

   • two products (with IDs 123456 - 6 chars, and 234567 - 6 chars);

   • quantities for each product ( 2 x 123456 and 3 x 234567);

   • order date (2012-11-02 20:32:12 - 19 characters); 
     
     The esulting securityHashSource is: 664327612AUTHRECEIVED61212345662345671213192012-11-02 20:32:12 - logically divided as following (6)643276(12)AUTHRECEIVED(6)12123456(6)234567(1)2(1)3(19)2012-11-02 20:32:12.

     Explanation: (no. of chars) ref. no. value (no. of chars) order status (no. of chars for each product id) product id (no. of chars for each quantity) quantity value (no. of chars) order date value. Note: datetime stamps sent use the timezone of the 2Checkout servers.

2. The securityHash string is created using hmac for the securityHashSource and your 2Checkout secret code. For PHP: hash_hmac('md5', $hashSource, $SECRETKEY).
3. Order date is also offered to help with hash integrity, ensuring that it cannot be used twice. Order date can also be parsed from the securityHashSource (standard string of 19 chars).

Overview

Use the getInvoices method to extract shopper invoices from the 2Checkout system based on unique order references. The method returns the binary code for invoices in the PDF file format, Base64 encoded (Base64 is used to represent binary data in the ASCII string format).

getInvoices works for COMPLETE orders for which an invoice was already issued. For refunded orders, getInvoices provides two shopper invoices, one for the original order and the second for the refund, reflecting the repayment made.

In the case of cross-selling orders which contain products from different merchants, getInvoice enables you to re-send only the invoices for your own offerings.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$reference = 'ORDER_REFERENCE';

try {
    $invoices = $client->getInvoices($sessionID, $reference);
}
catch (SoapFault $e) {
    echo "invoices: " . $e->getMessage();
    exit;
}
var_dump("invoices", $invoices);

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:

Overview

Use the API methods displayed below to create orders for physical products.

Search the shipping methods defined in your Control Panel, and extract information on how the shipping price is calculated.

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