Overview

Retrieve information about a subscription.

Parameters

Overview

Use webhooks to be notified automatically and in real-time about events in your 2Checkout account.

Availability

IPN notifications are available to all 2Checkout account types.

What is IPN?

Instant Payment Notification (IPN) works as a message service generating automatic order/transaction notifications for your 2Checkout account. Use the notifications to process order data into your own management systems by synchronizing it with 2Checkout account events.

Webhook asynchronicity

2Checkout’s webhooks (IPN and LCN) operate asynchronously.

How can I use IPN?

Use IPN to automate back-end functions, including but not limited to:

• Creating end-user accounts
• Providing access to acquired services
• Fulfilling purchases
• Tracking orders and customers
• Engaging customers

How does IPN work?

1. Create one or multiple IPN listener pages on your website. 2Checkout sends IPNs to publicly accessible servers.
2. Configure the IPN settings of your 2Checkout account to point to the URLs of your default/preferred listener pages. Our system performs a GET request against the URL you fill in and expects an HTTP 200 code as a response. Make sure that your URL can be queried via a GET request from our webserver  IPs.
3. Set up multiple URLs if you require more listener pages, such as in testing scenarios in which you don’t want to use your default IPN listener. 
4. 2Checkout sends order notifications to the endpoints you defined when shoppers acquire products/services from your online store. 2Checkout packages the payment information and sends it using secure (HTTPS) POST, according to your IPN settings.
5. 2Checkout sends the IPN parameters according to your setup from IPN Settings. To include additional information in the notifications, enable new parameters in the IPN settings page. Learn more about IPN parameters here.
6. 2Checkout uses an HMAC_SHA signature to validate the HTTPS POST. Calculate the signature using data sent and your 2Checkout account’s secret key, following the instructions included in this article.
7. Your custom IPN listener scripts consume the notifications and process the info received.
8. Configure your IPN listeners to output a read receipt confirmation on the listener page after receiving a valid IPN message. Guidance on how to generate the confirmation can be found here.
9. In the absence of a confirmation from one of your IPN listeners, 2Checkout continues to send notifications to that endpoint, according to the failure retry process, until you provide a valid response.
10. In the eventuality that 2Checkout fails to send IPNs or doesn’t receive a confirmation from your IPN listener, it displays an error in your Control Panel, on the Dashboard.

Set up the default IPN URL

1. Log into your 2Checkout account.
2. Navigate to Dashboard → Integrations → Webhooks and API.
3. Click on the IPN Settings tab.

4. Click on the Edit button to edit an existing URL corresponding to your default IPN listener or click on the Add URL button to add a URL corresponding to your default IPN listener in the IPN URL field.

      All merchants are strongly advised to migrate to SHA2/SHA3. We will stop supporting the MD5 algorithm in our platform on the 15th of August, 2024. For more details check the Migration guide documentation.
5. Check the Allow concurrent requests (faster notifications) option. If checked, 2Checkout sends multiple notifications concurrently to your IPN URL. Note: This may cause concurrency problems, but will greatly improve the notification time.
6. Save your settings.
7. 2Checkout checks the validity of the URLs in terms of access to ensure that notifications reach your IPN listener without any issues.

Set up multiple IPN URLs

You can set up multiple endpoints for your IPN notifications, for scenarios in which you have multiple Internal Systems that require to receive this information. You can set up eight (8) URLs for your notifications.

Navigate to IPN settings under Integrations → Webhooks and API, in your Merchant Control Panel Dashboard. Select the IPN Settings tab and click on the Add IPN URL button to create an additional URL configuration for your notifications.

To find out more about the NOTIFICATION_URL functionality, read more here.

Debug IPN

To view or debug IPN notifications during the integration phase, place TEST orders.

Alternatively, search for specific orders in the "Orders & Reports" area. When you access the order details page you get the option to resend notifications. You can also see how many IPN notifications have been sent so far for an order. Opt to reissue the IPN for debugging and 2Checkout re-generates and re-sends the IPN, but also displays a copy of the content sent in the control panel.

Secure your IPN script

For security reasons, 2Checkout recommends that you restrict access to the IPN script.

Overview

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

                                           Retrieve product group                                                  Retrieve product groups

Product group object

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

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

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

Overview

Retrieve information about the upgrade options for a specific subscription.

Overview

Use the updateLead method to update an existing lead and change all current values with new data.

Request Parameters

Request Example

<?php

require ('PATH_TO_AUTH');

$Lead = new stdClass();

$Lead->CartId = "CartIdValue";
$Lead->Currency = "EUR";
$Lead->Language = "BG";
$Lead->ExternalReference = "REST_API_3CHECKOUT";
$Lead->Source = "testAPI.com";
$Lead->CustomerReference = "asdf1";
$Lead->MachineId = "123asd";

$Lead->Items = [];

$Item = new stdClass();
$Item->Code = "04C26C50F8";
$Item->Quantity = 2;
$Item->IsDynamic = false;
$Item->Tangible = true;
$Item->PurchaseType = "PRODUCT";
$Item->PriceOptions = [];

$priceOption = new stdClass();
$priceOption->Name = "group name 1";
$priceOption->Required = false;
$option = new stdClass();
$option->Name = 'add25';
$option->Value = 'add25';
$option->Surcharge = 100;
$priceOption->Options[] = $option;

$Item->PriceOptions[] = $priceOption;

$recurringOptions = new stdClass();
$recurringOptions->CycleLength = 6;
$recurringOptions->CycleUnit = 'MONTH';
$recurringOptions->CycleAmount = 100;
$recurringOptions->ContractLength = 2;
$recurringOptions->ContractUnit = 'YEAR';
$Item->RecurringOptions = $recurringOptions;

$marketingCampaigns = new stdClass();
$marketingCampaigns->Type = 23;
$marketingCampaigns->ParentCode = "m";
$marketingCampaigns->CampaignCode = 23;
$Item->MarketingCampaigns = $marketingCampaigns;

$Item->Price = new stdClass();
$Item->Price->Amount = 20;
$Item->Price->Type = "CUSTOM";

$additionalFields = [];

$additionalField = new stdClass();
$additionalField->Code = "TestFieldOne";
$additionalField->Text = "test text";
$additionalField->Value = "test value";
$additionalFields[] = $additionalField;
$Item->AdditionalFields = $additionalFields;

$Item->SubscriptionStartDate = date("Y-m-d H:i:s");

$Lead->Items[] = $Item;

$billingDetails = new stdClass();
$billingDetails->FirstName = "Customer";
$billingDetails->LastName = "2Checkout";
$billingDetails->Phone = null;
$billingDetails->Company = null;
$billingDetails->FiscalCode = "32423423";
$billingDetails->Email = "customer@2checkout.com";
$billingDetails->Address1 = "Test Address";
$billingDetails->Address2 = null;
$billingDetails->City = "LA";
$billingDetails->Zip = "12345";
$billingDetails->CountryCode = "RO";
$billingDetails->State = "CA";

$Lead->BillingDetails = $billingDetails;
$Lead->DeliveryDetails = clone($billingDetails);

$Lead->DeliveryInformation = new stdClass();
$Lead->DeliveryInformation->ShippingMethod = new stdClass();
$Lead->DeliveryInformation->ShippingMethod->Code = "sdfsd";

$Lead->PaymentDetails = new stdClass();
$Lead->PaymentDetails->Type = "CC";
$Lead->PaymentDetails->Currency = "EUR";
$Lead->PaymentDetails->PaymentMethod = new stdClass();
$Lead->PaymentDetails->PaymentMethod->RecurringEnabled = false;
$Lead->PaymentDetails->PaymentMethod->CardPayment = new stdClass();
$Lead->PaymentDetails->PaymentMethod->CardPayment->InstallmentsNumber = 23;
$Lead->PaymentDetails->CustomerIP = "1.2.3.4";

$Lead->LocalTime = date("Y-m-d H:i:s");

$jsonRpcRequest = array (
    'method' => 'updateLead',
    'params' => array($sessionID, $Lead, '60E6C4B574'),
    'id' => $i++,
    'jsonrpc' => '2.0'
);

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

Response Example

class stdClass#18 (4) {
  public $LeadCode =>
  string(10) "60E6C4B574"
  public $CreatedAt =>
  string(19) "2019-11-05T16:39:36"
  public $UpdatedAt =>
  string(19) "2019-11-05T16:48:31"
  public $Errors =>
  array(0) {
  }
}

Overview

Retrieve information about a subscription's history. Subscriptions can be retrieved starting with 5 minutes after their orders are generated in the 2Checkout system.

Use the API methods displayed below to extend or renew a subscription.

Overview

Use the addProduct method to create subscription plans/products for your 2Checkout account. 

Request Parameters

Request Example

<?php

declare(strict_types=1);

class Configuration
{
    public const MERCHANT_CODE = '';
    public const MERCHANT_KEY = '';
    public const URL = 'http://api.2checkout.com/soap/6.0';
    public const ACTION = 'addProduct';
    public const ADDITIONAL_OPTIONS = null;
    //array or JSON
    public const PAYLOAD = <<<JSON
{
  "AvangateId": null,
  "Enabled": true,
  "GeneratesSubscription": true,
  "GiftOption": false,
  "LongDescription": "Some long description",
  "ProductCode": "API_Imported_Product_1",
  "ProductGroupCode": "9652CDA441",
  "TaxCategory": "5db74b57-98a5-4fc1-b559-aee8eba3f046",
  "Tangible": 0,
  "Fulfillment": "",
  "Platforms": [
    {
      "Category": "Mobile",
      "IdPlatform": "23",
      "PlatformName": "Android"
    },
    {
      "Category": "Mobile",
      "IdPlatform": "20",
      "PlatformName": "iPhone"
    },
    {
      "Category": "Desktop",
      "IdPlatform": "32",
      "PlatformName": "Windows 10"
    }
  ],
  "Prices": [],
  "PricingConfigurations": [
    {
      "BillingCountries": [],
      "Code": "54DCBC3DC8",
      "Default": true,
      "DefaultCurrency": "USD",
      "Name": "2Checkout Subscription's Price Configuration Marius",
      "PriceOptions": [
        {
          "Code": "SUPPORT",
          "Required": true
        },
        {
          "Code": "USERS",
          "Required": true
        },
        {
          "Code": "BACKUP",
          "Required": false
        }
      ],
      "PriceType": "NET",
      "Prices": {
        "Regular": [
          {
            "Amount": 99,
            "Currency": "USD",
            "MaxQuantity": "99999",
            "MinQuantity": "1",
            "OptionCodes": []
          },
          {
            "Amount": 0,
            "Currency": "EUR",
            "MaxQuantity": "99999",
            "MinQuantity": "1",
            "OptionCodes": []
          }
        ],
        "Renewal": []
      },
      "PricingSchema": "DYNAMIC"
    }
  ],
  "ProductCategory": "Audio & Video",
  "ProductImages": [
    {
      "Default": true,
      "URL": "https://store.avancart.com/images/merchant/ef0b9a69f90b1ab0228784ccc7d52136/products/box-2.jpg"
    }
  ],
  "ProductName": "Product Name 01",
  "ProductType": "REGULAR",
  "ProductVersion": "1.0",
  "PurchaseMultipleUnits": true,

  "ShortDescription": "some short description",
  "SubscriptionInformation": {
    "BillingCycle": "1",
    "BillingCycleUnits": "M",
    "BundleRenewalManagement": "GLOBAL",
    "ContractPeriod": {
      "Action": "RESTART",
      "EmailsDuringContract": true,
      "IsUnlimited": true,
      "Period": -1,
      "PeriodUnits": "D"
    },
    "DeprecatedProducts": [],
    "GracePeriod": {
      "IsUnlimited": false,
      "Period": "7",
      "PeriodUnits": "D",
      "Type": "CUSTOM"
    },
    "IsOneTimeFee": false,
    "RenewalEmails": {
      "Settings": {
        "AutomaticRenewal": {
          "After15Days": false,
          "After5Days": false,
          "Before15Days": false,
          "Before1Day": false,
          "Before30Days": false,
          "Before7Days": true,
          "OnExpirationDate": true
        },
        "ManualRenewal": {
          "After15Days": false,
          "After5Days": false,
          "Before15Days": false,
          "Before1Day": false,
          "Before30Days": false,
          "Before7Days": true,
          "OnExpirationDate": true
        }
      },
      "Type": "CUSTOM"
    },
    "UsageBilling": 0
  },
  "SystemRequirements": "",
  "Translations": [
    {
      "Description": "some description",
      "Language": "ZH",
      "LongDescription": "some long description",
      "Name": "some name",
      "SystemRequirements": "",
      "TrialUrl": "url",
      "TrialDescription": "TrialDescription"
    }
  ],
  "TrialDescription": "",
  "TrialUrl": ""
}
JSON;
}

class Client
{
    public function call(
        string $url = Configuration::URL,
        $payload = Configuration::PAYLOAD,
        string $action = Configuration::ACTION
    ): ?object
    {
        if (is_array($payload)) {
            $payload = json_encode($payload);
        }
        if (!empty($payload)) {
            // SoapClient works with objects(StdClass)
            $payload = json_decode($payload);
        }
        $soapClient = $this->getClient($url);
        $sessionId = $this->getSession($soapClient);
        $args = array_filter([$sessionId, $payload]);
        return $soapClient->$action(...$args);
    }

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

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

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

Response 

bool(true)

Overview

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

Retrieve next renewal price

Next renewal price object