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;

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

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

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#10 (5) {
            public $CycleLength =>
            NULL
            public $CycleUnit =>
            NULL
            public $CycleAmount =>
            NULL
            public $ContractLength =>
            NULL
            public $ContractUnit =>
            NULL
          }
          public $RenewalInformation =>
          class stdClass#11 (1) {
            public $SubscriptionReference =>
            NULL
          }
          public $MarketingCampaigns =>
          class stdClass#12 (3) {
            public $Type =>
            string(2) "23"
            public $ParentCode =>
            string(1) "m"
            public $CampaignCode =>
            string(2) "23"
          }
          public $Price =>
          class stdClass#13 (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#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 $DeliveryDetails =>
      class stdClass#15 (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#16 (1) {
        public $ShippingMethod =>
        class stdClass#17 (1) {
          public $Code =>
          string(5) "sdfsd"
        }
      }
      public $PaymentDetails =>
      class stdClass#18 (4) {
        public $Type =>
        string(2) "CC"
        public $Currency =>
        string(3) "EUR"
        public $PaymentMethod =>
        class stdClass#19 (2) {
          public $RecurringEnabled =>
          bool(false)
          public $CardPayment =>
          class stdClass#20 (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#21 (3) {
    public $Page =>
    int(1)
    public $Limit =>
    int(200)
    public $Count =>
    int(1)
  }
}

Overview

User privileges define the access level of your Merchant Control Panel users to specific 2Checkout features and modules.

A collection of privileges is called a user role. You can define your own user roles based on specific access levels that you want to grant to your users. You can assign multiple roles to a user.

You need to have two factor authentication enabled in order to add or edit information in the Settings area of your Merchant Control Panel.

Add/Edit users

Follow the steps below to add/edit new users:

1. Log in to the 2Checkout Merchant Control Panel using your master account.
2. Navigate to the Settings cogwheel in the top right corner.
3. Click on User Management.

4. On the User Management page, click on Add user.

5. On the Add user page, fill in the new user account details: Username, Email, First name, Last name, Password, Password lifetime, User status, User role.

6. To edit a user, click on the Edit icon on the Users page.

7. Click Save.

User management options

• You can use the strong password generator that complies with the above requirements to make sure you're using a secure password.
• The user is required to change the password after the first login. This option is enabled by default.
• The reset password option allows you to disable the old password and the user will receive an e-mail for setting a new password.
• You can set passwords to expire in a number of days of your choosing. By default, passwords expire in 90 days.
• Passwords never expire invalidates the password expiration setting. Disabled by default.

Add/Edit user roles

Follow the steps below to add or edit user roles:

1. Log in to the 2Checkout Merchant Control Panel using your master account.
2. Navigate to the Settings cogwheel in the top right corner.
3. Click on User Management.
4. On the User Management page, click on the Roles tab.
5. On the Roles page, click on Add role.

6. On the Add role page, fill in the role info (Role name, Role description), and then select the privileges you want to assign to that specific role.

7. To edit a role, click on the Roles tab and click on the Edit icon next to the role you want to change (see image at Step 5 above).

8. On the Edit role page, edit/change the role info (Role name, Role description) and then check or uncheck the privileges you want to assign to the role.

9. Click the green Save button at the bottom of the page to save/update the changes.

Assign user roles

Follow the steps below to assign roles to the existing users.

1. Log in to the 2Checkout Merchant Control Panel using your master account.
2. Navigate to the Settings cogwheel in the top right corner.
3. Click on User Management.
4. On the User Management page, click on the Users tab.
5. Identify the user account that you want to assign a role to and click Edit.

6. On the Edit User page, you can update the User info and also assign/check a role to the user or change the role already assigned to that particular user. 

7. Click Save to update changes.

Privileges

Setup

Marketing Tools

Orders & Reports

Account Settings

Partner Management

Third-Party Apps

​This guide provides an overview of the financial compliance regulations that apply to merchants in the United States. It contains details about the 1099-K, W8 and W9 forms that merchants with a legal entity in the US or selling in the US are required to fill in for submission to the IRS.

Overview

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

Search shipping method

Shipping method object

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.

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

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

Overview

License Change Notification (LCN) works as a message service generating automatic subscription notifications for your 2Checkout account. Use the notifications to process subscription data into your own management systems by synchronizing it with 2Checkout account events. 2Checkout generates notifications for subscription update and expiration events (including past-due notifications).

How can I use LCN?

Use LCN to automate back-end functions for your services, including but not limited to:

• Creating end-user accounts
• Providing access to acquired services
• Manage subscriptions
• Fulfilling purchases
• Engaging subscribers
• Converting trials to paid subscriptions
• Cutting access to a delinquent account

Webhook asynchronicity

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

How does LCN work?

1. Create one or multiple LCN listener pages on your website. 2Checkout sends LCNs to publicly accessible servers.
2. Configure the LCN 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 LCN listener. 
4. 2Checkout sends subscription notifications to the endpoints you defined when subscribers change specific subscription details, using secure (HTTPS) POST.
5. 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.
6. Your custom LCN listener scripts consume the notifications and process the info received.
7. Configure your LCN listener to output a read receipt confirmation on the listener page after receiving a valid LCN message. This article includes guidance on how to generate the confirmation.
8. In the absence of a confirmation from one of your LCN listeners, 2Checkout continues to send notifications to that endpoint, according to the failure retry process, until you provide a valid response.
9. The 2Checkout system regularly checks the status of subscriptions to identify expired items and modifications. 2Checkout then sends notifications for expirations as well as for updates that occurred in the last 24 hours prior to the moment when it performs the check. 2Checkout does not re-send notifications for the same event unless the status of the subscription changes or it identifies additional modifications.

Set up the default LCN URL

1. Log into your 2Checkout account.
2. Navigate to Dashboard → Integrations → Webhooks and API.
3. Click on the LCN Settings tab.
4. Click on the Edit button to edit an existing URL corresponding to your default LCN listener or click on the Add LCN URL button to add a URL corresponding to your default LCN listener in the LCN URL field.
5. Save your settings by clicking on the Update button at the bottom of the page.
6. 2Checkout checks the validity of the URLs in terms of access to ensure that notifications reach your LCN listener without any issues.

Set up multiple LCN URLs

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

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

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

Debug LCN

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

Alternatively, search for specific subscriptions in the Subscriptions area. On the subscription details page, you have the option to resend notifications. You can also see how many LCN notifications have been sent so far for a subscription. Opt to reissue the LCN for debugging and 2Checkout re-generates and re-sends the LCN, but also displays a copy of the content sent in the control panel.

Secure your LCN script 

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

Overview

Multi-product promotions allow you to offer percentage-based discounts to your shoppers, based on the number of unique products added to the shopping cart. They apply automatically as long as the order includes the products assigned to the promotion.

How to configure a multi-product promotion

1. Enter a promotion title and description. Promotion names are visible to your shoppers if the order meets the promotion criteria.
   • 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.
2. Define the time interval when you want the promotion to be active. To start a promotion as soon as you activate it, leave the start date empty. If you don't set an 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 set to unlimited.
3. You can restrict promotions to a specific number of orders, or set them to run indefinitely
4. Define a minimum order value threshold. Choose whether to apply the promotion to any order or only to orders exceeding a certain value (including taxes). To set a threshold, choose Custom, define the threshold and select the default currency. Orders using currencies without a threshold are automatically converted to the default threshold currency, using exchange rates applicable at the moment of purchase. 
5. Select whether or not to activate the promotion as soon as you save it.
6. Configure the discount depending on the number of unique products added to the shopping cart. Click Add rule, enter a number of unique products to be detected in the cart and set the corresponding discount. You can add multiple scenarios for different numbers of unique products. If you define multiple promotions or scenarios, 2Checkout automatically applies the one with the highest discount, provided that the order meets the promotion criteria.
7. Assign products to the promotion. Multi-products promotions only apply to products in the shopping cart that are not subject to another regular promotion or cross-selling discount at the time of purchase!
8. Save the promotion when you're done configuring it.

Overview

Under the Payment Services Directive 2 (PSD2) initiative, in order to prevent ever-evolving fraud methods, Payment Service Providers (PSPs), such as 2Checkout, must apply extra security steps to implement Strong Customer Authentication (SCA) and further protect the confidentiality of consumers’ data.

For more details about 3D Secure support in API, check the Payment Services Directive 2 (PSD2) article. 

You can also read the resources below to have a better understanding of what is PSD2 and what it entails:

• What is the 2nd Payment Service Directive (PSD2)?

• What is PSD2 and What Does Strong Customer Authentication (SCA) Mean for You?

• The Impact of PSD2 and SCA: Ordering Flows and Exemptions

Impact

All merchants using the Growth, Standard, 2Sell, 2Subscribe, 2Monetize and Enterprise packages are not affected.

If your integration is using https://2checkout.com/checkout/api/1/ endpoint to trigger payments, then you need to follow the transition process below.

3D Secure (3DS) support added to our Payment API

For card-based payments, this resulted in the implementation of 3D Secure version 2 (3DS2 aka EMV 3DS). 3D Secure has been employed to secure online card transactions since 2001, but now a new version has been developed to meet the PSD2 SCA requirements. Basically, to be able to accept payments from the world’s largest card networks (Visa, Mastercard, Amex,etc.), any merchant will need to have implemented 3D Secure version 2 for their online store. Initially, this will apply mainly to EU-based merchants and their clients. Outside the EU, the current implementation pace of EMV 3DS is considered slow and less dominant.

The new flow for 3DS transactions in the Payment API is asynchronous and requires that you redirect the buyer to an authentication URL that will be returned in the authorization response, and wait for the buyer and sale parameters to be returned to a callback URL on your server.

What happens if I do not update my integration

If no change is done to your API integration, the Payment API will continue to work as normal, but you will start to notice a higher rate of declines as the processors will not be able to continue the transaction if the shopper’s card requires 3DS authentication.

Set up Callback URL

To enable 3DS support in your integration, you need to set up an endpoint on your server where the 2Checkout system will return the shopper and order parameters when the order is completed. The return will be a GET request and will include all standard 2Checkout Return Process parameters: total, order_number, invoice_id, merchant_order_id, and key parameter, which will contain the MD5 hash to validate the passback. 

MD5 Hash Validation

The MD5 hash is calculated as: UPPERCASE(MD5_ENCRYPTED(INS secret word + seller id + order_number + total)).

The INS secret word can be found in your Merchant Control Panel, under Integrations → Webhooks and APIs → Secret word section. The seller id is your numerical merchant code/seller ID. The order_number is the order number for the sale returned on the passback. The total is the numerical value for the total amount of the sale. Each of our community-supported libraries provides a binding to validate the hash.

Pass Callback URL in the authorization request

To let the 2Checkout system know that you are ready to handle the new 3DS flow, a new parameter needs to be added - returnUrl - in the root of the JSON payload on your authorization (create sale) API call. The returnUrl value needs to be the absolute path of your callback URL.

Authorization Request Sample

{
    "sellerId": "your-seller-id",
    "privateKey": "your-private-key",
    "merchantOrderId": "example-custom-id-123",
    "token": "client-side-token",
    "currency": "USD",
    "total": "1.11",
    "billingAddr": {
        "name": "Testing Tester",
        "addrLine1": "123 Test St",
        "city": "Columbus",
        "state": "Ohio",
        "zipCode": "43123",
        "country": "USA",
        "email": "example@2co.com",
        "phoneNumber": "5555555555"
        },
    "returnUrl": "https://www.your-site.com/return.php"
}

If the card needs 3D Secure authentication for the payment, then the API will return an HTTP status '400'. In the body of the response, under the exception object, the errorCode value will be ‘700’ and the errorMsg value will contain the URL where the customer needs to be redirected for the authentication of the payment.

API Response Sample

{
    "validationErrors": null,
    "exception": {
        "errorMsg": "https://api.2checkout.com/5.0/scripts
/credit_card/authorize?avng8apitoken=77fdf3f03b265840",
        "httpStatus": "400",
        "exception": false,
        "errorCode": "700"
    },
    "response": null
}

Once the shopper completes the 3DS authentication process, they will be redirected to your callback URL along with the order parameters. If the 3DS authentication fails, they will be returned to the 2Checkout cart so that they can verify their payment method and re-attempt the payment.