Skip to main content

Place order with custom subscription settings

Overview

Use the placeOrder method to create an order using custom subscription settings via JSON-RPC API 6.0.

Request parameters

Parameters Type Required/Optional Description
sessionID String Required 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 Object Required

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

Response

Parameters Type Description
Order information Object Object that includes all data necessary for an order, including billing, product/subscription plan, and payment details.

Request sample

<?php
$Order = new \stdClass();
$Order->Currency = 'usd';
$Order->Country = 'US';
$Order->Language = 'en';
$Order->CustomerIP = '91.220.121.21';
$Order->ExternalReference = NULL;
$Order->Source = NULL;
$Order->Affiliate = new stdClass();
$Order->Affiliate->AffiliateCode = 'Partner123'
$Order->Affiliate->AffiliateSource = 'MobilePlatform'
$Order->CustomerReference = NULL;

// Don't forget about B2B flag
$Order->ExtraInformation = new \stdClass();
$Order->ExtraInformation->B2B = true;


$Order->Items = array();
$Order->Items[0] = new \stdClass();
$Order->Items[0]->Code = 'my_subscription_1';
$Order->Items[0]->Quantity = 1;
$Order->Items[0]->PriceOptions = NULL;
$Order->Items[0]->SKU = NULL;
$Order->Items[0]->Price = NULL;
$Order->Items[0]->CrossSell = NULL;
$Order->Items[0]->Trial = false;
$Order->Items[0]->AdditionalFields = NULL;
$Order->Items[0]->SubscriptionStartDate = NULL; //If empty or null, subscriptions become active when purchase is made.

// Subscription custom settings
$Order->Items[0]->SubscriptionCustomSettings = new \stdClass();
$Order->Items[0]->SubscriptionCustomSettings->ContractLength = "123";
$Order->Items[0]->SubscriptionCustomSettings->CycleAmountType = "NET";
$Order->Items[0]->SubscriptionCustomSettings->CycleUnit = "DAY";
$Order->Items[0]->SubscriptionCustomSettings->CycleAmount = "123";
$Order->Items[0]->SubscriptionCustomSettings->CycleLength = "123";
$Order->Items[0]->SubscriptionCustomSettings->MerchantDealAutoRenewal = true;
$Order->Items[0]->SubscriptionCustomSettings->ClientDealAutoRenewal = true;


$Order->BillingDetails = new \stdClass();
$Order->BillingDetails->FirstName = 'First';
$Order->BillingDetails->LastName = 'Last';
$Order->BillingDetails->CountryCode = 'us';
$Order->BillingDetails->State = 'California';
$Order->BillingDetails->City = 'LA';
$Order->BillingDetails->Address1 = 'Address example';
$Order->BillingDetails->Address2 = NULL;
$Order->BillingDetails->Zip = '90210';
$Order->BillingDetails->Email = 'email@address.com';
$Order->BillingDetails->Phone = NULL;
$Order->BillingDetails->Company = NULL;
$Order->DeliveryDetails = NULL;

$Order->PaymentDetails = new \stdClass ();
$Order->PaymentDetails->Type = 'CC';
$Order->PaymentDetails->Currency = 'usd';
$Order->PaymentDetails->PaymentMethod = new \stdClass ();
$Order->PaymentDetails->CustomerIP = '10.10.10.10';
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = true;
$Order->PaymentDetails->PaymentMethod->CardNumber = "4111111111111111";
$Order->PaymentDetails->PaymentMethod->CardType = 'visa';
$Order->PaymentDetails->PaymentMethod->ExpirationYear = '2019';
$Order->PaymentDetails->PaymentMethod->ExpirationMonth = '12';
$Order->PaymentDetails->PaymentMethod->CCID = '123';
$Order->PaymentDetails->PaymentMethod->HolderName = 'John';
$Order->PaymentDetails->PaymentMethod->CardNumberTime = 83.21; // can be null - high value in seconds is a red flag for fraud attempts.
$Order->PaymentDetails->PaymentMethod->HolderNameTime = 13.35; // can be null - high value in seconds is a red flag for fraud attempts.
$Order->PaymentDetails->PaymentMethod->Vendor3DSReturnURL = "http://www.success.ro";
$Order->PaymentDetails->PaymentMethod->Vendor3DSCancelURL = "http://www.error.ro";

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

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

Add additional fields

Overview

Use the addAdditionalField method to create new additional fields for your account.

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.

AdditionalField

Object

 

Additional field object.

Response

bool(true)

Request

<?php

require ('PATH_TO_AUTH');

$AdditionalField                             = new stdClass();
$AdditionalField->Label                      = 'Do you agree with the new newsletter policy 2015?';
$AdditionalField->Type                       = 'LISTBOX';
$AdditionalField->Code                       = 'NewsletterPolicy1234576';
$AdditionalField->ApplyTo                    = 'ORDER';
$AdditionalField->Values                     = array();
$AdditionalField->Values[0]                  = 'YES';
$AdditionalField->Values[1]                  = 'NO';
$AdditionalField->ValidationRule             = null;
$AdditionalField->Translations               = array();
$AdditionalField->Translations[0]            = new stdClass();
$AdditionalField->Translations[0]->Label     = "Êtes-vous d'accord avec la politique de la newsletter?";
$AdditionalField->Translations[0]->Values    = array();
$AdditionalField->Translations[0]->Values[0] = 'Oui';
$AdditionalField->Translations[0]->Values[1] = 'Non';
$AdditionalField->Translations[0]->Language  = 'fr';
$AdditionalField->Translations[1]            = new stdClass();
$AdditionalField->Translations[1]->Label     = 'Haben Sie mit dem Newsletter Politik zu?';
$AdditionalField->Translations[1]->Values    = array();
$AdditionalField->Translations[1]->Values[0] = 'Ja';
$AdditionalField->Translations[1]->Values[1] = 'Nein';
$AdditionalField->Translations[1]->Language  = 'de';

$jsonRpcRequest = array(
    'jsonrpc' => '2.0',
    'id' => $i++,
    'method' => 'addAdditionalField',
    'params' => array(
        $sessionID,
        $AdditionalField
    )
);
var_dump(callRPC((Object) $jsonRpcRequest, $host));

?>

 

Retrieve a product’s campaigns

Overview

Use the getProductCrossSellCampaigns method to extract information on all cross-sells campaigns triggered by the same primary product.

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.

ProductCode

Required (string)

 

The code of the primary product triggering cross-sell campaign that you can define for each of your offerings.

Response

Parameters Type/Description

CrossSellCampaign

Object

Request

<?php

require ('PATH_TO_AUTH');

$ProductCode = 'subscr1';

try {
    $ProductCrossSellCampaigns = $client->getProductCrossSellCampaigns($sessionID, $ProductCode);
}

catch (SoapFault $e) {
    echo "ProductCrossSellCampaigns: " . $e->getMessage();
    exit;
}

var_dump("ProductCrossSellCampaigns", $ProductCrossSellCampaigns);

 

Enable recurring billing

Overview

Use the enableRecurringBilling method to switch on the automatic renewal system for a subscription that's manually renewable. 

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.

Response

Parameters Type/Description

Boolean

true or false depending on whether the changes were successful or not.

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';

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

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

Assign a subscription to another customer

Overview

Use the setSubscriptionCustomer method. 2Checkout moves subscription under the customer for which you provide the 2Checkout customer reference or the External customer reference during the subscription update process.

json_diagram.png

Requirements

To move a subscription from a source customer to a target customer:

  • Use 2Checkout customer references or External customer references belonging to the target customer. 2Checkout re-assigns the subscription to the target customer. 
  • Customer references must be valid and associated to the target customer entity under which you move the subscription.
  • If you provide both the 2Checkout customer reference and External customer reference they need to belong to the same target customer entity.

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.

2CheckoutCustomerReference

Required (int)

 

System-generated customer reference. Required unless you prefer to use ExternalCustomerReference.

ExternalCustomerReference

Optional (string)

 

External customer reference that you control. Optional when you use 2CheckoutCustomerReference. If you include it, it needs to belong to the same customer as the 2CheckoutCustomerReference.

Response

Boolean

true or false depending on whether the changes were successful or not.

Request


<?php
$host   = "https://api.2checkout.com";
$client = new SoapClient($host . "/soap/3.0/?wsdl", array(
    'location' => $host . "/soap/3.0/",
    "stream_context" => stream_context_create(array(
        'ssl' => array(
            'verify_peer' => false,
            'verify_peer_name' => false
        )
    ))
));

function hmac($key, $data)
{
    $b = 64; // byte length for md5
    if (strlen($key) > $b) {
        $key = pack("H*", md5($key));
    }
    
    $key    = str_pad($key, $b, chr(0x00));
    $ipad   = str_pad('', $b, chr(0x36));
    $opad   = str_pad('', $b, chr(0x5c));
    $k_ipad = $key ^ $ipad;
    $k_opad = $key ^ $opad;
    return md5($k_opad . pack("H*", md5($k_ipad . $data)));
}
$merchantCode = "YOUR_MERCHANT_CODE";// your account's merchant code available in the 'System settings' area of the cPanel: https://secure.2checkout.com/cpanel/account_settings.php
$key = "YOUR_SECRET_KEY";// your account's secret key available in the 'System settings' area of the cPanel: https://secure.2checkout.com/cpanel/account_settings.php
$now          = gmdate('Y-m-d H:i:s'); //date_default_timezone_set('UTC')
$string = strlen($merchantCode) . $merchantCode . strlen($now) . $now;
$hash   = hmac($key, $string);
try {
    $sessionID = $client->login($merchantCode, $now, $hash);
}
catch (SoapFault $e) {
    echo "Authentication: " . $e->getMessage();
    exit;
}
$subscriptionReference = '30E47F8699';
$customerReference = 220531648;
try {
    $newCustomerInfo = $client->setSubscriptionCustomer($sessionID, $subscriptionReference, $customerReference);
}
catch (SoapFault $e) {
    echo "newCustomerInfo: " . $e->getMessage();
    exit;
}
var_dump("newCustomerInfo", $newCustomerInfo);

 

Error handling for issueRefund

Overview

Learn how to tackle the common errors that may arise when issuing refunds via 2Checkout API.

Common error codes 

Error code Description

ORDER_REF missing or format incorrect 

The order reference number was not provided, or has an invalid format. Check the order reference provided.

ORDER_AMOUNT missing or format incorrect 

Refundable amount was not provided, or it has an invalid format. Check the order amount provided.

Order already canceled 

Order is already canceled.

Invalid ORDER_REF 

The order reference number is not correct. Check the order reference provided.

Invalid ORDER_AMOUNT 

The refundable amount is invalid. Check the order amount provided.

PRODUCTS_CODES missing or format incorrect 

Products codes were not provided, or have an invalid format. Check the product codes provided.

PRODUCTS_QTY missing or format incorrect 

Product quantity was not provided, or has an invalid format. Check the product quantity provided.

Invalid PRODUCTS_QTY 

The product quantity is not correct. Check the product quantity provided.

You have already placed a Total refund for this order. 

Order has been already refunded in total. Check again the current refund status of the order.

You already have a pending refund request. 

The order already has a pending refund request. Before issuing a new refund, the current request needs to be settled.

The maximum refundable amount for this order has been exceeded. 

The refundable amount cannot exceed the order amount. Check the refundable amount.

You cannot place a refund request due to the order's current status. 

The order needs to be in FINISHED status, before being refunded. Check the current order status.

You cannot place a refund request due to the order's payment details. 

The current customer payment details do not allow refund requests. Contact 2Checkout for additional details.

The allowed period to request a new refund for this order has expired. 

You are not able to issue a refund for this order at this moment. Contact 2Checkout for additional details.

Multiple refunds are not supported by this order's payment type. 

The payment method on this order does not allow multiple refunds.

Refunding not supported for this Cross Vendor Sale order. 

The order type does not allow refunds. Contact 2Checkout for additional details.

Order total is negative. 

The order total is negative. Send only positive order amounts.

You cannot place a refund request due to the order's approval status. 

The order cannot be refunded due to its approval status. Contact 2Checkout for additional details.

Multiple refunds are not supported by this order's terminal. 

The order cannot be refunded to due to its payment method terminal. Contact 2Checkout for additional details.

Partial reverse is not supported. 

Partial refunds are not supported on this payment method. Contact 2Checkout for additional details.

Invalid product type. Refunds are available only for the following product types: REGULAR / BUNDLE / MEDIA / DOWNLOAD_INSURANCE, but not for DISCOUNT / SHIPPING. 

The product item cannot be refunded. Contact 2Checkout for additional details.

You cannot request a refund because a chargeback dispute was open for the order. 

You cannot issue a refund for orders that have a chargeback dispute open. 

Invalid REFUND_REASON

The refund reasons provided is not valid. In case you have custom refund reasons created, send one of their names as values. 

Place an order with installments

Overview 

Use the placeOrder method to create an order and collect the payment.

Supported payment methods 

Credit/Debit cards: Visa and MasterCard local Brazilian cards.

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.

Requirements

  1. Payment methods: Visa, MasterCard or AMEX
  2. Country: Brazil
  3. Currency BRL
  4. The specified number of installments under the PaymentMethod object. (Minimum installment threshold is 5 BRL.)
    • Phone number
    • Fiscal code (CPF/CNPJ)
  5. Mandatory billing information must include:

  6. Transaction: non-recurring
  7. Installments are available only for:
    • Brazilian customers
    • Local Visa, MasterCard and AMEX cards
    • Non-recurring transactions

<?php

require ('PATH_TO_AUTH');

$Order = new stdClass();
$Order->RefNo = NULL;
$Order->Currency = 'brl';
$Order->Country = 'BR';
$Order->Language = 'en';
$Order->CustomerIP = '91.220.121.21';
$Order->ExternalReference = NULL;
$Order->Source = NULL;
$Order->AffiliateId = NULL;
$Order->CustomerReference = NULL;
$Order->Items = array();
$Order->Items[0] = new stdClass();
$Order->Items[0]->Code = 'my_subscription_1';
$Order->Items[0]->Quantity = 1;
$Order->Items[0]->PriceOptions = NULL;
$Order->Items[0]->SKU = NULL;
$Order->Items[0]->Price = NULL;
$Order->Items[0]->CrossSell = NULL;
$Order->Items[0]->Trial = false;
$Order->Items[0]->AdditionalFields = NULL;
$Order->Items[0]->Promotion = NULL;

$Order->BillingDetails = new stdClass();
$Order->BillingDetails->FirstName = 'FirstName';
$Order->BillingDetails->LastName = 'LastName';
$Order->BillingDetails->CountryCode = 'BR';
$Order->BillingDetails->State = 'DF';
$Order->BillingDetails->City = 'LA';
$Order->BillingDetails->Address1 = 'Address example';
$Order->BillingDetails->Address2 = NULL;
$Order->BillingDetails->Zip = '70403-900';
$Order->BillingDetails->Email = 'customer@email.com';
$Order->BillingDetails->Phone = "556133127400";
$Order->BillingDetails->FiscalCode = "056.027.963-98";
$Order->BillingDetails->Company = NULL;

$Order->DeliveryDetails = NULL;

$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'CC';
$Order->PaymentDetails->Currency = 'brl';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->CustomerIP = '10.10.10.10';
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = true;
$Order->PaymentDetails->PaymentMethod->CardNumber = "4111111111111111";
$Order->PaymentDetails->PaymentMethod->CardType = 'visa';
$Order->PaymentDetails->PaymentMethod->ExpirationYear = '2019';
$Order->PaymentDetails->PaymentMethod->ExpirationMonth = '12';
$Order->PaymentDetails->PaymentMethod->HolderName = 'John';
$Order->PaymentDetails->PaymentMethod->CCID = '123';

$Order->Promotions = NULL;
$Order->AdditionalFields = NULL;
$Order->LocalTime = NULL;
$Order->GiftDetails = NULL;


try {
    $OrderInstallments = $client->getInstallments($sessionID, $Order);
}
catch (SoapFault $e) {
    echo "Order_Installments: " . $e->getMessage();
    exit;
}
var_dump("Order_Installments", $OrderInstallments);

$Order = new stdClass();
$Order->RefNo = NULL;
$Order->Currency = 'brl';
$Order->Country = 'BR';
$Order->Language = 'en';
$Order->CustomerIP = '91.220.121.21';
$Order->ExternalReference = NULL;
$Order->Source = NULL;
$Order->AffiliateId = NULL;
$Order->CustomerReference = NULL;
$Order->Items = array();
$Order->Items[0] = new stdClass();
$Order->Items[0]->Code = 'my_subscription_1';
$Order->Items[0]->Quantity = 1;
$Order->Items[0]->PriceOptions = NULL;
$Order->Items[0]->SKU = NULL;
$Order->Items[0]->Price = NULL;
$Order->Items[0]->CrossSell = NULL;
$Order->Items[0]->Trial = false;
$Order->Items[0]->AdditionalFields = NULL;
$Order->Items[0]->Promotion = NULL;
$Order->BillingDetails = new stdClass();
$Order->BillingDetails->FirstName = 'FirstName';
$Order->BillingDetails->LastName = 'LastName';
$Order->BillingDetails->CountryCode = 'BR';
$Order->BillingDetails->State = 'DF';
$Order->BillingDetails->City = 'LA';
$Order->BillingDetails->Address1 = 'Address example';
$Order->BillingDetails->Address2 = NULL;
$Order->BillingDetails->Zip = '70403-900';
$Order->BillingDetails->Email = 'customer@email.com';
$Order->BillingDetails->Phone = "556133127400";
$Order->BillingDetails->FiscalCode = "056.027.963-98";
$Order->BillingDetails->Company = NULL;
$Order->DeliveryDetails = NULL;
$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'CC';
$Order->PaymentDetails->Currency = 'brl';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->CustomerIP = '10.10.10.10';
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = true;
$Order->PaymentDetails->PaymentMethod->CardNumber = "4111111111111111";
$Order->PaymentDetails->PaymentMethod->InstallmentsNumber = 2;
$Order->PaymentDetails->PaymentMethod->CardType = 'visa';
$Order->PaymentDetails->PaymentMethod->ExpirationYear = '2019';
$Order->PaymentDetails->PaymentMethod->ExpirationMonth = '12';
$Order->PaymentDetails->PaymentMethod->HolderName = 'John';
$Order->PaymentDetails->PaymentMethod->CCID = '123';

$Order->AdditionalFields = NULL;
$Order->LocalTime = NULL;
$Order->GiftDetails = NULL;
try {
    $newOrder = $client->placeOrder($sessionID, $Order);
}
catch (SoapFault $e) {
    echo "newOrder: " . $e->getMessage();
    exit;
}
var_dump("newOrder", $newOrder);

 

Retrieve all additional fields

Overview

Use the getAdditionalFields method to extract information about additional fields you set up for your account.

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.

Response

Parameters Type/Description

AdditionalFields

Array of objects

Request

<?php

require ('PATH_TO_AUTH');

try {
    $AdditionalFields = $client->getAdditionalFields($sessionID);
}

catch (SoapFault $e) {
    echo "AdditionalFields: " . $e->getMessage();
    exit;
}

var_dump("AdditionalFields", $AdditionalFields);

 

Partial refund

Overview

Use the issueRefund method to issue a partial refund for an order processed by 2Checkout.

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.

We recommend you create a new order with placeOrder to have one that can be refunded.

The order’s status must be ’COMPLETE’ and it should have a TotalPrice > 0.

The OrderDate cannot be older than a year from the current date.

To obtain the LineItemReference, use the getOrder method: https://knowledgecenter.2checkout.com/API-Integration/JSON-RPC_API_6.0/Reference/14Retrieve-an-order

Request example

require ('PATH_TO_AUTH'); // authentication call

$orderReference = "11686290";

$items = [];
$item = new stdClass();
$item->Quantity = 1;
$item->LineItemReference = "f1ca85810f935115ef8dacd6aae4b1759f4f03c1";
$item->Amount = 0.1;

$items[] = $item;

$amount = '20';
$comment = "This is a comment";
$reason = "No reason";

$jsonRpcRequest          = new stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method  = 'issueRefund';
$jsonRpcRequest->params  = array($sessionID, $orderReference, $amount, $items, $comment, $reason);
$jsonRpcRequest->id      = $i++;

$partialRefund = callRPC($jsonRpcRequest, $host);
var_dump ($partialRefund);

Response

Response Type/Description
Boolean

TRUE is the refund was processed successfully

FALSE otherwise

Retrieve subscription payment information

Overview

Use the getSubscriptionPaymentInformation method to retrieve information related to the payment made for a subscription.

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)
  The reference of the subscription you want to retrieve payment information for.

Response

Parameters Type/Description

Type

String

 

Payment method type.

Currency

String

 

ISO code of the order currency.

PaymentMethod

Object

 

FirstDigits

String

 

 

First 4 digits of the card used on the order.

 

LastDigits

String

 

 

Last 4 digits of the card used on the order.

 

CardType

String

 

 

Type of card used on the order.

Request

<?php
require ('PATH_TO_AUTH');

$subscriptionReference = "Subscription_Code";

try {
    $paymentInformation = $client->getSubscriptionPaymentInformation($sessionID, $subscriptionReference);
} catch (SoapFault $e) {
    echo  $e->getMessage();
}
var_dump($paymentInformation);

 

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.

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.

Verifone logo