updates RSS feed

Enter campaign

Overview

Use the enterCampaign method to mark the auto renewal cancellation intent.

Parameters

Parameters   Type/Description
sessionID Required (string)
  Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect. The sessionID expires in 10 minutes.
SubscriptionReference Required (string)
  Unique, system-generated subscription identifier.
CampaignCode Required (string)
  The code of the campaign you want to confirm.
EnterCampaignStep Object
  Step Required (string)
    Can have one of the following values: TEXT, REASON, DISPLAY, PAUSE.
  Success Required (Integer)
   

Indicates whether the user continued through the cancellation flow or chose to keep the subscription at this step.

  • 0 – The user continued the cancellation process after this step (e.g., clicked "Next", did not exit).
  • 1 – The user interrupted the flow and chose to keep the subscription active (e.g., closed the wizard, clicked "Keep my subscription").

Note: A value of 1 signifies that the cancellation process has ended early, and no further steps will follow.
  Reason String, nullable
    Designed for the REASON step.
It’s the reason why the user wants to stop the auto renewal for the subscription.
It should be one of the churn reasons managed by the merchant in the 2Checkout platform.
  Comment String, nullable
    Designed for the REASON step.
It’s an additional field for the user to explain the reason better.

Response

Parameters Type/Description
Boolean true or false depending on whether the changes were successful or not.

Request

<?php
 
require('PATH_TO_AUTH');
 
$subscriptionReference = 'F27CFE06ED';
$campaignCode = 'UGPPKKJY5L1LHBFPHKQ3';
$enterCampaignStep = new stdClass();
$enterCampaignStep->Step = “REASON”;
$enterCampaignStep->Success = 0;
$enterCampaignStep->Reason = “CHURN_REASON_NOT_SATISFIED”;
$enterCampaignStep->Comment = “Not statisfied because …”;
 
try {
    $result = $client->enterCampaign($sessionID, $subscriptionReference, $campaignCode, $enterCampaignStep);
}
catch (SoapFault $e) {
    echo "result: " . $e->getMessage();
    exit;
}
var_dump("result", $result);

Accept campaign discount

Overview

Use the acceptChurnCampaignDiscount method to confirm the campaign you want for the churn campaign process.

Parameters

Parameters Type/Description
sessionID Required (string)
  Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect. The sessionID expires in 10 minutes.
SubscriptionReference Required (string)
  Unique, system-generated subscription identifier.
CampaignCode Required (string)
  The code of the campaign you want to confirm.

Response

Parameters Type/Description
Boolean true or false depending on whether the changes were successful or not.

Request

<?php
 
require('PATH_TO_AUTH');
 
$subscriptionReference = 'F27CFE06ED';
$campaignCode = 'UGPPKKJY5L1LHBFPHKQ3';
 
try {
    $result = $client->acceptChurnCampaignDiscount($sessionID, $subscriptionReference, $campaignCode);
}
catch (SoapFault $e) {
    echo "result: " . $e->getMessage();
    exit;
}
var_dump("result", $result);

Retrieve eligible campaigns

Overview

Use the getEligibleChurnCampaigns method to retrieve all the eligible campaigns for a specific subscription with data in a specific language.

Parameters

Parameters Type/Description
sessionID Required (string)
  Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect. The sessionID expires in 10 minutes.
SubscriptionReference Required (string)
  Unique, system-generated subscription identifier.
Language Required (string)
  The language abbreviation in which messages are translated.

Response

Parameters Type/Description
SubscriptionChurnPreventionCampaigns Object

Request

<?php
 
require('PATH_TO_AUTH');
 
$subscriptionReference = 'F27CFE06ED';
$language = 'en';
 
try {
    $campaigns = $client->getEligibleChurnCampaigns($sessionID, $subscriptionReference, $language);
}
catch (SoapFault $e) {
    echo "campaigns: " . $e->getMessage();
    exit;
}
var_dump("campaigns", $campaigns);

Use Stored Credit

Overview

The Stored Credit payment method allows merchants to process payments without requiring payment details from the shopper. Instead, the shopper's credit balance is pre-stored and managed within your system (NOT stored by 2Checkout). When using this payment method via API, it is the merchant's responsibility to validate that the shopper has sufficient credits to complete the transaction. This method allows you to accept payments using pre-purchased credits systems such as proprietary gift vouchers.

Availability

This payment method is exclusive to the API and is not available on any of 2Checkout's hosted shopping carts.

Supported currencies

Stored Credit is at the moment available only in USD. Contact 2Checkout to ask about availability in other currencies.

Workflow

  1. Distribute the credits to your customers using your desired process, outside of the 2Checkout platform.
  2. Validate that the customer who intends to initiate the order has enough credits available.

  3. Create the order object. Use STORED_CREDIT as the type in PaymentDetails object.

     
    It is not recommended that you use the PaymentMethod object for Stored Credit, the only parameter supported is RecurringEnabled = false which is also the default value, true is not supported and will return an error.
  4. Place the order.

Request parameters

Parameters Type/Description
sessionID

Required (string)

Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect. The sessionID expires in 10 minutes.
Order

Required (object)

Object designed to collect all data necessary for an order, including billing, product/subscription plan and payment details. See code sample for more details.

Request example

<?php
declare(strict_types=1);
class Configuration
{
    public const MERCHANT_CODE = 'MERCHANT';
    public const MERCHANT_KEY = 'SECRET_KEY';
    public const URL = 'https://api.2checkout.com/soap/6.0';
    public const ACTION = 'placeOrder';
    public const PAYLOAD =  <<<JSON
{
    "Currency": "USD",
    "Language": "EN",
    "Country": "us",
    "CustomerIP": "91.220.121.21",
    "Source": "sourceAPI.net",
    "LocalTime": "2022-01-13 09:41:59",
    "CustomerReference": 421820775,
    "Items": [
        {
            "Code": "TA-TuneUp-M-RENEW"
        }
    ],
    "BillingDetails": {
        "Address1": "Test Address",
        "City": "LA",
        "State": "California",
        "CountryCode": "US",
        "Email": "testcustomer@2Checkout.com",
        "FirstName": "Customer",
        "LastName": "2Checkout",
        "Zip": "12345"
      },
    "PaymentDetails": {
        "Type": "STORED_CREDIT",
        "Currency": "USD",
        "CustomerIP": "91.220.121.21"
    }
}
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;
        $algo = 'sha256';
        $hash = hash_hmac($algo, $string, $key);
        $client->__setCookie('XDEBUG_SESSION', 'PHPSTORM');
        return $client->login($merchantCode, $date, $hash, $algo);
    }
}
try {
    $client = new Client();
    var_dump($client->call());
} catch (Exception $ex) {
    var_dump($ex);
}

Response parameters

Parameter Type/Description
Order information Object
Object containing order information.

Use Stored Credit

Overview

The Stored Credit payment method allows merchants to process payments without requiring payment details from the shopper. Instead, the shopper's credit balance is pre-stored and managed within your system (NOT stored by 2Checkout). When using this payment method via API, it is the merchant's responsibility to validate that the shopper has sufficient credits to complete the transaction. This method allows you to accept payments using pre-purchased credits systems such as proprietary gift vouchers.

Availability

This payment method is exclusive to the API and is not available on any of 2Checkout's hosted shopping carts.

Supported currencies

Stored Credit is at the moment available only in USD. Contact 2Checkout to ask about availability in other currencies.

Workflow

  1. Distribute the credits to your customers using your desired process, outside of the 2Checkout platform.
  2. Validate that the customer who intends to initiate the order has enough credits available.

  3. Create the order object. Use STORED_CREDIT as the type in PaymentDetails object.

     
    It is not recommended that you use the PaymentMethod object for Stored Credit, the only parameter supported is RecurringEnabled = false which is also the default value, true is not supported and will return an error.
  4. Place the order.

Request parameters

Parameters Type/Description
sessionID

Required (string)

Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect. The sessionID expires in 10 minutes.
Order

Required (object)

Object designed to collect all data necessary for an order, including billing, products/subscription plan and payment details. See code sample for more details.

Request example

<?php
declare(strict_types=1);
class Configuration
{
    public const MERCHANT_CODE = 'MERCHANT';
    public const MERCHANT_KEY = 'SECRET_KEY';
    public const URL = 'https://api.2checkout.com/rpc/6.0';
    public const ACTION = 'placeOrder';
    //array or JSON
    public const PAYLOAD = <<<JSON
{
    "Currency": "USD",
    "Language": "EN",
    "Country": "us",
    "CustomerIP": "91.220.121.21",
    "Source": "sourceAPI.net",
    "LocalTime": "2022-01-13 09:41:59",
    "CustomerReference": 421820775,
    "Items": [
        {
            "Code": "TA-TuneUp-M-RENEW"
        }
    ],
    "BillingDetails": {
        "Address1": "Test Address",
        "City": "LA",
        "State": "California",
        "CountryCode": "US",
        "Email": "testcustomer@2Checkout.com",
        "FirstName": "Customer",
        "LastName": "2Checkout",
        "Zip": "12345"
      },
    "PaymentDetails": {
        "Type": "STORED_CREDIT",
        "Currency": "USD",
        "CustomerIP": "91.220.121.21"
    }
}
JSON;
}
class Client
{
    private const LOGIN_METHOD = 'login';
    private $calls = 1;
    private $sessionId;
    private function generateAuth(): array
    {
        $merchantCode = Configuration::MERCHANT_CODE;
        $key = Configuration::MERCHANT_KEY;
        $date = gmdate('Y-m-d H:i:s');
        $string = strlen($merchantCode) . $merchantCode . strlen($date) . $date;
        $algo = 'sha256';
        $hash = hash_hmac($algo, $string, $key);
        return compact('merchantCode', 'date', 'hash', 'algo');
    }
    public function login(string $url)
    {
        $payload = $this->generateAuth();
        $response = $this->call($url, array_values($payload), self::LOGIN_METHOD);
        $this->sessionId = $response['result'];
    }
    public function call(
        string $url = Configuration::URL,
        $payload = Configuration::PAYLOAD,
        string $action = Configuration::ACTION
    ): ?array {
        if (empty($this->sessionId) && $action !== self::LOGIN_METHOD) {
            $this->login($url);
        }
        if (is_string($payload)) {
            $payload = json_decode($payload, true);
        }
        if (!empty($this->sessionId)) {
            $payload = [$this->sessionId, $payload];
        }
        $payload = array_filter($payload);
        $request = json_encode([
            'jsonrpc' => '2.0',
            'method'  => $action,
            'params'  => $payload,
            'id'      => $this->calls++,
        ]);
        $curl = curl_init($url);
        curl_setopt($curl, CURLOPT_POST, 1);
        curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
        curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
        curl_setopt($curl, CURLOPT_SSLVERSION, 0);
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt(
            $curl,
            CURLOPT_HTTPHEADER,
            ['Content-Type: application/json', 'Accept: application/json', 'Cookie: XDEBUG_SESSION=PHPSTORM']
        );
        curl_setopt($curl, CURLOPT_POSTFIELDS, $request);
        $response = curl_exec($curl);
        if (empty($response)) {
            die('Server unavailable');
        }
        echo $response . '</br>';
        return json_decode($response, true);;
    }
}
$client = new Client();
$result = $client->call();
var_dump($result);

Response parameters

Parameter Type/Description
Order information

Object

Object containing order information.

Use eChecks

Overview

eChecks (electronic checks) are a secure, efficient, and cost-effective digital payment method that allows merchants to process payments directly from a customer's bank account. Using the Automated Clearing House (ACH) network, eChecks streamline transactions by replacing traditional paper checks with electronic processing. 

This method is ideal for recurring payments, large transactions, or industries where ACH payments are commonly used.

Supported currencies

eChecks support only USD transactions.

Workflow

  1. Collect the following information from your customers:
    • Account holder name
    • Bank Routing number
    • Account number
    • Account type
      • Use value "S" for SAVINGS accounts and "C" for CHECKING accounts in API
  2. Create the order object. Use DIRECT_DEBIT_ACH as the type in the PaymentDetails object and pass the collected information through the PaymentMethod object.
  3. Place the order.

Request parameters

Parameters Type/Description
sessionID Required (string)
Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect. The sessionID expires in 10 minutes.
Order Required (Object)
Object designed to collect all data necessary for an order, including billing, product/subscription plan and payment details. See code sample for more details.

Request example

<?php
declare(strict_types=1);
class Configuration
{
    public const MERCHANT_CODE = 'MERCHANT';
    public const MERCHANT_KEY = 'SECRET_KEY';
    public const URL = 'https://api.2checkout.com/soap/6.0';
    public const ACTION = 'placeOrder';

    public const PAYLOAD =  <<<JSON
{
    "Currency": "USD",
    "Language": "EN",
    "Country": "us",
    "CustomerIP": "91.220.121.21",
    "Source": "sourceAPI.net",
    "LocalTime": "2022-01-13 09:41:59",
    "CustomerReference": 421820775,
    "Items": [
        {
            "Code": "TA-TuneUp-M-RENEW"
        }
    ],
    "BillingDetails": {
        "Address1": "Test Address",
        "City": "LA",
        "State": "California",
        "CountryCode": "US",
        "Email": "testcustomer@2Checkout.com",
        "FirstName": "Customer",
        "LastName": "2Checkout",
        "Zip": "12345"
      },
    "PaymentDetails": {
        "Type": "DIRECT_DEBIT_ACH",
        "Currency": "USD",
        "CustomerIP": "91.220.121.21",
        "PaymentMethod": {
            "AccountHolderName": "John Doe",
            "BankRoutingNumber": "222371863",
            "AccountNumber": "999999999",
            "AccountType": "S",
            "RecurringEnabled": true
        }
    }
}
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;
        $algo = 'sha256';
        $hash = hash_hmac($algo, $string, $key);
        $client->__setCookie('XDEBUG_SESSION', 'PHPSTORM');
        return $client->login($merchantCode, $date, $hash, $algo);
    }
}
try {
    $client = new Client();
    var_dump($client->call());
} catch (Exception $ex) {
    var_dump($ex);
}

Response Parameters

Parameter Type/Description
Order information Object
Object containing order information.

Use eChecks

Overview

eChecks (electronic checks) are a secure, efficient, and cost-effective digital payment method that allows merchants to process payments directly from a customer's bank account. Using the Automated Clearing House (ACH) network, eChecks streamline transactions by replacing traditional paper checks with electronic processing. 

This method is ideal for recurring payments, large transactions, or industries where ACH payments are commonly used.

Supported currencies

eChecks support only USD transactions.

Workflow

  1. Collect the following information from your customers:
    • Account holder name
    • Bank Routing number
    • Account number
    • Account type
      • Use value "S" for SAVINGS accounts and "C" for CHECKING accounts in API
  2. Create the order object. Use DIRECT_DEBIT_ACH as the type in the PaymentDetails object and pass the collected information through the PaymentMethod object.
  3. Place the order.

Request parameters

Parameters Type/Description
sessionID Required (string)
Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect. The sessionID expires in 10 minutes.
Order Required (Object)
Object designed to collect all data necessary for an order, including billing, product/subscription plan and payment details. See code sample for more details.

Request example

<?php
declare(strict_types=1);
class Configuration
{
    public const MERCHANT_CODE = 'MERCHANT';
    public const MERCHANT_KEY = 'SECRET_KEY';
    public const URL = 'https://api.2checkout.com/rpc/6.0';
    public const ACTION = 'placeOrder';
    //array or JSON
    public const PAYLOAD = <<<JSON
{
    "Currency": "USD",
    "Language": "EN",
    "Country": "us",
    "CustomerIP": "91.220.121.21",
    "Source": "sourceAPI.net",
    "LocalTime": "2022-01-13 09:41:59",
    "CustomerReference": 421820775,
    "Items": [
        {
            "Code": "TA-TuneUp-M-RENEW"
        }
    ],
    "BillingDetails": {
        "Address1": "Test Address",
        "City": "LA",
        "State": "California",
        "CountryCode": "US",
        "Email": "testcustomer@2Checkout.com",
        "FirstName": "Customer",
        "LastName": "2Checkout",
        "Zip": "12345"
      },
    "PaymentDetails": {
        "Type": "DIRECT_DEBIT_ACH",
        "Currency": "USD",
        "CustomerIP": "91.220.121.21",
        "PaymentMethod": {
            "AccountHolderName": "John Doe",
            "BankRoutingNumber": "222371863",
            "AccountNumber": "999999999",
            "AccountType": "C",
            "RecurringEnabled": true
        }
    }
}
JSON;
}
class Client
{
    private const LOGIN_METHOD = 'login';
    private $calls = 1;
    private $sessionId;
    private function generateAuth(): array
    {
        $merchantCode = Configuration::MERCHANT_CODE;
        $key = Configuration::MERCHANT_KEY;
        $date = gmdate('Y-m-d H:i:s');
        $string = strlen($merchantCode) . $merchantCode . strlen($date) . $date;
        $algo = 'sha256';
        $hash = hash_hmac($algo, $string, $key);
        return compact('merchantCode', 'date', 'hash', 'algo');
    }
    public function login(string $url)
    {
        $payload = $this->generateAuth();
        $response = $this->call($url, array_values($payload), self::LOGIN_METHOD);
        $this->sessionId = $response['result'];
    }
    public function call(
        string $url = Configuration::URL,
        $payload = Configuration::PAYLOAD,
        string $action = Configuration::ACTION
    ): ?array {
        if (empty($this->sessionId) && $action !== self::LOGIN_METHOD) {
            $this->login($url);
        }
        if (is_string($payload)) {
            $payload = json_decode($payload, true);
        }
        if (!empty($this->sessionId)) {
            $payload = [$this->sessionId, $payload];
        }
        $payload = array_filter($payload);
        $request = json_encode([
            'jsonrpc' => '2.0',
            'method'  => $action,
            'params'  => $payload,
            'id'      => $this->calls++,
        ]);
        $curl = curl_init($url);
        curl_setopt($curl, CURLOPT_POST, 1);
        curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
        curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
        curl_setopt($curl, CURLOPT_SSLVERSION, 0);
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt(
            $curl,
            CURLOPT_HTTPHEADER,
            ['Content-Type: application/json', 'Accept: application/json', 'Cookie: XDEBUG_SESSION=PHPSTORM']
        );
        curl_setopt($curl, CURLOPT_POSTFIELDS, $request);
        $response = curl_exec($curl);
        if (empty($response)) {
            die('Server unavailable');
        }
        echo $response . '</br>';
        return json_decode($response, true);;
    }
}
$client = new Client();
$result = $client->call();
var_dump($result);

Response Parameters

Parameter Type/Description
Order information Object
Object containing order information.

Need help?

Do you have a question? If you didn’t find the answer you are looking for in our documentation, you can contact our Support teams for more information. If you have a technical issue or question, please contact us. We are happy to help.

Get in touch

Not yet a Verifone customer?

We’ll help you choose the right payment solution for your business, wherever you want to sell, in-person or online. Our team of experts will happily discuss your needs.

Contact sales Get Started
Verifone logo