Skip to main content

Add promotion coupon

Request

<?php 

class Client
{
    protected static $merchantCode;
    protected static $loginDate;
    protected static $hash;
    protected static $baseUrl;
    protected static $callCount = 0;
    protected static $sessionId = '';

    protected static $client;

    public static function setCredentials($code, $key)
    {
        static::$merchantCode = $code;
        static::$loginDate = gmdate('Y-m-d H:i:s');
        static::$hash = hash_hmac('md5', strlen($code) . $code . strlen(static::$loginDate) . static::$loginDate, $key);
        static::$sessionId = static::login();
    }

    public static function setBaseUrl($url)
    {
        static::$baseUrl = $url;
    }

    public static function login()
    {
        $client = static::getClient();
        return $client->login(static::$merchantCode, static::$loginDate, static::$hash);
    }

    public static function __callStatic($name, $arguments = array())
    {
        $client = static::getClient();

        array_unshift($arguments, static::$sessionId);
        $response = call_user_func_array(array($client, $name), $arguments);

        return $response;
    }

    protected static function getClient()
    {
        $opts = array(
            'http'=> ['user_agent' => 'PHPSoapClient'],
            'ssl' => [
                'verify_peer' => false,
                'verify_peer_name' => false,
            ],
        );

        if (null === static::$client) {
            static::$client = new \SoapClient(static::$baseUrl . '?wsdl', [
                'location' => static::$baseUrl,
                'cache_wsdl' => WSDL_CACHE_NONE,
                'stream_context' => stream_context_create($opts),
            ]);
        }

        return static::$client;
    }
}

Client::setBaseUrl('https://api.avangate.com/soap/3.1/');
Client::setCredentials('YOUR_MERCHANT_CODE', 'YOUR_SECRET_KEY');
Client::login();

$promotionCode = 'YOUR_PROMOTION_CODE'; // code of the promotion that you want to update

// // Define single coupon object
// $promotionCoupon = new stdClass;
// $promotionCoupon->Type = 'SINGLE';
// $promotionCoupon->Code = 'YOUR_CODE_HERE';

// Define multiple coupon object
// $promotionCoupon = new stdClass;
// $promotionCoupon->Type = 'MULTIPLE';
// $promotionCoupon->Codes = ['YOUR_CODE_1', 'YOUR_CODE_2'];

$response = Client::addPromotionCoupon ($promotionCode,$promotionCoupon); // Add coupons to the existing promotion
var_dump($response);

Enable a subscription

Overview

Use the enableSubscription method to enable 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)

 

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

try {
    $enabledSubscription = $client->enableSubscription($sessionID, $SubscriptionReference);
}
catch (SoapFault $e) {
    echo "enabledSubscription: " . $e->getMessage();
    exit;
}
var_dump("enabledSubscription", $enabledSubscription);

Enable a subscription

Overview

Use the enableSubscription method to enable a subscription.

Parameters

Parameters Type/Description

sessionID

Required (string)

 

Session identifier, the output of the Login method. Include sessionID into all your requests. Avangate 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' => 'enableSubscription',
'params' => array($sessionID, $subscriptionReference),
'id' => $i++,
'jsonrpc' => '2.0');

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

Update a subscription

Overview

Change specific details about a subscription. Use the updateSubscription method to change specific details about 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.
Subscription Required (Object)
  You need to include the entire Subscription object keeping its structure unchanged (retrieve it using getSubscription) but you can update only specific parameters enumerated below.
  EndUser Object
    End user details.
  ExpirationDate String
   

Subscription expiration date - If you changed the time zone for the 2Checkout API by editing system settings under Account settings, then 2Checkout calculates the ExpirationDate according to your custom configuration. Note: The default 2Checkout API time zone is GMT+02:00.

You cannot set an expiration date from the past.

  ActivationDate String
   

Subscription activation date - If you changed the time zone for the 2Checkout API by editing system settings under Account settings, then 2Checkout calculates the ActivationDate according to your custom configuration. Note: The default 2Checkout API time zone is GMT+02:00.

This field is optional. If provided, it cannot be set lower than the subscription start date (creation/purchase date) and it can be changed only while the subscription is in pending activation status.

  SubscriptionEnabled Boolean
    Possible values: TRUE/FALSE
  RecurringEnabled Boolean
    Possible values: TRUE/FALSE
  ExternalCustomerReference String
   

Unique customer alphanumeric (string) identifiers that you control. Use this to 

move a subscription from under a customer to another customer entity. 2Checkout moves subscription under the customer for which you provide the External customer reference during the subscription update process. View example.

  ProductId Int
   

System-generated unique product ID. Needs to be the ID of an existing product in the 2Checkout system created under your account.

The product ID governs the product to which the subscription is associated with.

Product types must match Regular - Regular or Bundle - Bundle.

IDs must identify products with the renewal system enabled (max billing cycle 36 months).

  ProductName String
    The name of the product for identifier used under ProductID.
  ProductQuantity Int
    Ordered quantity.
  PriceOptionCodes Array
   

Array of product options codes. Pricing options codes are case sensitive.

To impact the renewal price, the PriceOptionsCodes need to belong to price options of pricing configurations used for the product with which the subscription is associated.

ChurnReasons Array
 

This payload can be sent only when the Subscription object (from above) will have RecurringEnabled set as TRUE. Possible values for this field are:
CHURN_REASON_NOT_SATISFIED_PRODUCT

CHURN_REASON_ENABLED_BY_MISTAKE

CHURN_REASON_PREFER_MANUAL

CHURN_REASON_ALREADY_RENEWED

CHURN_REASON_DONT_NEED

CHURN_REASON_WANT_PAUSE

CHURN_REASON_COVID

CHURN_REASON_HIGH_PRICE

CHURN_REASON_NOT_SATISFIED_SUPPORT

CHURN_REASON_EXTRAORDINARY

CHURN_REASON_OTHER

ChurnReasonOther String
  This field should have a value only if the ChurnReasons has the CHURN_REASON_EXTRAORDINARY or CHURN_REASON_OTHER values

 

All other parameters of the Subscription object are non-editable.

The 2Checkout system uses the updated subscription information for:

  • Manual and automatic renewals
  • Upgrades
  • Trial conversions

Response

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

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReferenceTest = 'YOUR_SUBSCRIPTION_REFERENCE';

try{
    $retrievedSubscription = $client->getSubscription($sessionID, $subscriptionReferenceTest);
}

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

var_dump ($updatedSubscription);


$retrievedSubscription->RecurringEnabled = false;
$retrievedSubscription->SubscriptionEnabled = false;
$retrievedSubscription->ExpirationDate = '2026-12-12';

$churnReasons = ['CHURN_REASON_OTHER'];
$churnReasonOther = 'I refuse to continue the subscription';

try {
    $updatedSubscription = $client->updateSubscription($sessionID, $retrievedSubscription);
}
catch (SoapFault $e) {
    echo "updatedSubscription: " . $e->getMessage();
    exit;
}
var_dump("updatedSubscription", $updatedSubscription);

?>

 

Error handling for API 6.0

Overview

Learn how to tackle the common errors that may arise when using the placeOrder call via 2Checkout API.

Error codes for Order Object

Item: Product

Error code Description
ORDER_PRODUCTS_EMPTY No products have been provided.
ORDER_PRODUCT_RENEWAL_SUBSCRIPTION_REFERENCE_EMPTY Subscription reference cannot be empty.
ORDER_PRODUCT_RENEWAL_SUBSCRIPTION_REFERENCE_INVALID Subscription reference is invalid.
ORDER_PRODUCT_RENEWAL_SUBSCRIPTION_REFERENCE_NOT_FOUND Subscription reference is invalid.
ORDER_PRODUCT_RENEWAL_PERIOD_INVALID The renewal period is invalid.
ORDER_PRODUCTS_RENEWAL_NOT_ALLOWED Renewal is not allowed with multiple products.
ORDER_PRODUCT_CODE_INVALID Invalid product code.
PRODUCT_ERROR Invalid product id.
ORDER_PRODUCT_CODE_INVALID Requested product [%s] was not found.
ORDER_PRODUCT_PRICE_STRUCTURE_INVALID The price structure is not valid.
ORDER_PRODUCT_PRICE_AMOUNT_INVALID The price amount is not valid.
ORDER_PRODUCT_PRICE_TYPE_INVALID The price type is not valid
ORDER_PRODUCT_PRICE_TYPE_BASE_INVALID The price amount does not need to be set on the base price flow.
ORDER_PRODUCT_PRICE_TYPE_DEFAULT_INVALID The price amount does not need to be set on the default price flow.
ORDER_PRODUCT_PRICE_TYPE_CUSTOM_INVALID The price amount is mandatory to be set on the custom price flow.
ORDER_PRODUCT_INVALID Internal product validation error.
ORDER_PRODUCT_NAME_INVALID Name is mandatory when you set IsDynamic to TRUE.
ORDER_ITEMS_INVALID Invalid items. You cannot mix dynamic and catalog products.
ORDER_PRODUCT_IS_DYNAMIC_INVALID Invalid IsDynamic value. Use: TRUE or FALSE.
ORDER_PRODUCT_PURCHASE_TYPE_INVALID Invalid product purchase type. Accepted values: PRODUCT, SHIPPING, COUPON and TAX.
ORDER_PRODUCT_TANGIBLE_INVALID Invalid Tangible value. Use: TRUE or FALSE.
ORDER_ITEMS_QUANTITY_INVALID Item quantity must be between 1 and 99999.

 Item: Trial

Error code Description
INVALID_PRODUCT Invalid product ID.
PRODUCT_ALREADY_IN_CART Product already in cart.
INVALID_TRIAL_PERIOD The trial period needs to be greater than 0 days.
INVALID_TRIAL_PRODUCT Invalid trial product.

Item: Cross-sell

Error code Description
INVALID_CROSS_SELL_PRODUCT Invalid cross-sell product ID/Invalid cross-sell parent product code/Invalid cross-sell parent product ID/Invalid cross-sell products for a specified campaign.
PRODUCT_ALREADY_IN_CART Product already in cart.
PRODUCT_NOT_IN_CART The cross-sell master product is not already in the cart.
INVALID_CROSS_SELL_CAMPAIGN Invalid cross-sell campaign.
ORDER_ITEMS_CROSS_SELL_PARENT_DISABLED Parent product form cross-sell campaign is disabled.
ORDER_ITEMS_CROSS_SELL_CHILD_DISABLED Child product form cross-sell campaign is disabled.
ITEM_CROSS_SELL_INVALID CrossSell field is invalid.
ITEM_CROSS_SELL_PARENT_CODE_INVALID CrossSell parent code is invalid.
ITEM_CROSS_SELL_CAMPAIGN_CODE_INVALID CrossSell campaign code is invalid.
ITEM_CROSS_SELL_AUTOADDED_INVALID CrossSell 'AutoAdded' field is invalid.

Item: Price_options

Error code Description
INVALID_OPTIONS Your pricing has error: %s.
ORDER_ITEMS_PRICE_OPTIONS_NAME_EMPTY Item price options name is empty.
ORDER_ITEMS_PRICE_OPTIONS_OPTION_NAME_EMPTY Item price options option name is empty.
ORDER_ITEMS_PRICE_OPTIONS_OPTION_VALUE_EMPTY Item price options option value is empty.
ORDER_ITEMS_PRICE_OPTIONS_NAME_INVALID Invalid item price options name.
ORDER_ITEMS_PRICE_OPTIONS_INVALID Invalid item price options.
ORDER_ITEMS_PRICE_OPTIONS_OPTION_NAME_INVALID Invalid item price options option name.
ORDER_ITEMS_PRICE_OPTIONS_OPTION_VALUE_INVALID Invalid item price options option value.
ORDER_ITEMS_PRICE_OPTIONS_OPTION_SURCHARGE_INVALID Invalid item price options option surcharge.

Item: Price

Error code Description
PRICE_ERROR The price needs to be a decimal value.
PRODUCT_ERROR You need to add the product to the order before setting the price./Invalid product id.
CURRENCY_ERROR No currency is set for the current session.
ORDER_ITEMS_RECURRING_OPTIONS_CYCLE_UNIT_INVALID Invalid item recurring option cycle unit. Accepted values: DAY, WEEK, MONTH, YEAR.
ORDER_ITEMS_RECURRING_OPTIONS_CYCLE_LENGTH_INVALID Invalid item recurring option cycle length. Use integers.
ORDER_ITEMS_RECURRING_OPTIONS_CONTRACT_UNIT_INVALID Invalid item recurring option contract unit. Accepted values: DAY, WEEK, MONTH, YEAR, FOREVER.
ORDER_ITEMS_RECURRING_OPTIONS_CONTRACT_LENGTH_INVALID Invalid item recurring option contract length. Use integers.
ORDER_ITEMS_RECURRING_OPTIONS_CYCLE_AMOUNT_INVALID Item recurring option cycle amount must be zero or a positive value (INT or FLOAT).
ORDER_PRODUCT_PRICE_AMOUNT_TYPE_INVALID The price amount type is not valid.

Item: Refund

Error code Description
ORDER_REFUND_ORDER_REF_MISSING ORDER_REF missing or format incorrect.
ORDER_REFUND_ORDER_AMOUNT_MISSING ORDER_AMOUNT missing or format incorrect.
ERROR_CANCELLING_ORDER Error canceling order.
ORDER_ALREADY_CANCELED Order already canceled.
UNKNOWN_ERROR Unknown error.
ORDER_REFUND_INVALID_ORDER_REF Invalid ORDER_REF.
ORDER_REFUND_INVALID_ORDER_AMOUNT Invalid ORDER_AMOUNT.
ORDER_REFUND_LINE_ITEM_REFERENCE_MISSING ORDER_REFUND_LINE_ITEM_REFERENCE missing or format incorrect.
ORDER_REFUND_PRODUCTS_QTY_MISSING PRODUCTS_QTY missing or format incorrect.
ORDER_REFUND_INVALID_PRODUCTS_QTY Invalid PRODUCTS_QTY.
ORDER_REFUND_AMOUNT_MISSING AMOUNT missing or format incorrect.
ORDER_REFUND_AMOUNT_INVALID Invalid AMOUNT.
ORDER_REFUND_ALREADY_PLACED_TOTAL_REFUND You have already placed a Total refund for this order.
ORDER_REFUND_ALREADY_PLACED You have already placed a refund for this order.
ORDER_REFUND_ALREADY_HAVE_PENDING_REFUND_REQUEST You already have a pending refund request.
ORDER_REFUND_AMOUNT_EXCEEDED_MAXIMUM_REFUNDABLE_AMOUNT The maximum refundable amount for this order has been exceeded.
ORDER_REFUND_FAILED_DUE_TO_ORDER_CURRENT_STATUS You cannot place a refund request due to the order's current status.
ORDER_REFUND_FAILED_DUE_TO_PAYMENT_DETAILS You cannot place a refund request due to the order's payment details.
ORDER_REFUND_FAILED_DUE_TO_PERIOD_TO_REQUEST_REFUND_HAS_EXPIRED The allowed period to request a new refund for this order has expired.
ORDER_REFUND_MULTIPLE_NOT_SUPPORTED_BY_PAYMENT_TYPE Multiple refunds are not supported by this order's payment type.
ORDER_REFUND_NOT_SUPPORTED_FOR_CROSS_VENDOR_SALE Refunding not supported for this Cross Vendor Sale order.
ORDER_REFUND_TOTAL_NEGATIVE Order total is negative.
ORDER_REFUND_AMOUNT_NEGATIVE Order amount is negative.
ORDER_REFUND_ITEM_AMOUNT_NEGATIVE Order item amount is negative.
ORDER_REFUND_FAILED_DUE_TO_ORDER_APPROVAL_STATUS You cannot place a refund request due to the order's approval status.
ORDER_REFUND_MULTIPLE_REFUNDS_NOT_SUPPORTED Multiple refunds are not supported by this order's terminal.
ORDER_REFUND_PARTIAL_REVERSE_NOT_SUPPORTED Partial reverse is not supported.
ORDER_REFUND_INVALID_PRODUCT_TYPE Invalid product type. Refunds are available only for the following product types: REGULAR / BUNDLE / MEDIA / DOWNLOAD_INSURANCE / SHIPPING, but not for DISCOUNT.
ORDER_REFUND_FAILED_DUE_TO_OPEN_CHARGEBACK_DISPUTE You cannot request a refund because a chargeback dispute was open for the order.
ORDER_REFUND_INVALID_REASON Invalid REFUND_REASON.
ORDER_REFUND_LINE_ITEM_REFERENCES_NOT_FOUND ORDER_REFUND_LINE_ITEM_REFERENCES is incorrect or not part of Order.
ORDER_REFUND_FEATURE_MISSING You are not allowed to request refund.

Item: Mark_Shipped

Error code Description
ORDER_MARK_SHIPPED_ALREADY_MARKED_SHIPPED Sale already marked shipped.
ORDER_MARK_SHIPPED_NOT_SHIPPABLE Item not shippable.
ORDER_MARK_SHIPPED_STATUS_INVALID Order Status is not Payment Authorized.
ORDER_MARK_SHIPPED_AUTH_EXPIRED Payment authorization has expired. Reauthorize payment before marking shipped.
ORDER_MARK_SHIPPED_TOO_SOON Please wait 24 hours before trying to reauthorize again.
ORDER_MARK_SHIPPED_REAUTH_FAILED Failed to reauthorize payment.
ORDER_MARK_SHIPPED_INTERNAL_ERROR_REAUTH Failed to mark shipped but reauthorization succeeded.
ORDER_MARK_SHIPPED_INTERNAL_ERROR Failed to mark shipped.

Item: Shipping_Price

Error code Description
COUPON_CODES_INVALID The coupon codes format is invalid.
BILLING_DETAILS_COUNTRY_INVALID The billing country code is invalid.
DELIVERY_DETAILS_COUNTRY_INVALID The delivery country code is invalid.
PARAMETERS_INVALID The country code [%s] does not have a currency that is in your account's transactional currencies.
ITEMS_INVALID The shipping price can only be calculated for physical products.

Item: Billing_Details

Error code Description
ORDER_BILLING_DETAILS_COUNTRY_DYNAMIC_NOT_ALLOWED Functionality not available for your account.
ORDER_BILLING_DETAILS_EMPTY Billing details can not be used for delivery as they are empty.
ORDER_BILLING_EMAIL_EMPTY Email cannot be empty.
ORDER_BILLING_EMAIL_EMAIL_INVALID Email is not valid.
ORDER_BILLING_FIRST_NAME_EMPTY The First Name cannot be empty.
ORDER_BILLING_LAST_NAME_EMPTY The Last Name cannot be empty.
ORDER_BILLING_ADDRESS1_EMPTY The Address 1 cannot be empty.
ORDER_BILLING_CITY_EMPTY The City cannot be empty.
ORDER_BILLING_ZIP_EMPTY The Zip cannot be empty.
ORDER_BILLING_STATE_EMPTY The State cannot be empty.
ORDER_BILLING_DETAILS_COUNTRY_EMPTY The Country cannot be empty.
ORDER_BILLING_DETAILS_COUNTRY_INVALID The Country is not supported by the vendor.
ORDER_BILLING_DETAILS_STATE_EMPTY The State cannot be empty.
ORDER_BILLING_DETAILS_STATE_INVALID The State is not valid.
ORDER_BILLING_DETAILS_PHONE_EMPTY The Phone cannot be empty.
ORDER_BILLING_DETAILS_CPF_CNPJ_EMPTY The CPF/CPNJ cannot be empty.
ORDER_BILLING_DETAILS_CPF_CNPJ_INVALID The CPF/CNPJ is invalid.
ORDER_BILLING_DETAILS_COMPANY_EMPTY The Company cannot be empty.
ORDER_BILLING_DETAILS_GSTIN_EMPTY The GSTIN number cannot be empty.
ORDER_BILLING_DETAILS_GSTIN_INVALID The GSTIN number is invalid.
ORDER_BILLING_DETAILS_FISCAL_CODE_EMPTY The Fiscal Code cannot be empty.
ORDER_BILLING_DETAILS_TAX_OFFICE_EMPTY The Tax office cannot be empty.
ORDER_BILLING_DETAILS_TAX_OFFICE_INVALID The Tax office is not valid.
ORDER_BILLING_DETAILS_FISCAL_CODE_INVALID The Fiscal Code is not valid.
ORDER_BILLING_DETAILS_INVALID No billing details have been provided.
ORDER_BILLING_DETAILS_EMAIL_EMPTY The billing email cannot be empty.
ORDER_BILLING_DETAILS_PHONE_INVALID The Phone is invalid (10/11 digits expected).
ORDER_BILLING_DETAILS_TAX_OFFICE_INVALID TaxOffice length exceeds 50 characters.

Item: Delivery

Error code Description
ORDER_DELIVERY_EMAIL_EMPTY The Email cannot be empty.
ORDER_DELIVERY_EMAIL_EMAIL_INVALID The Email is not valid.
ORDER_DELIVERY_FIRST_NAME_EMPTY The First Name cannot be empty.
ORDER_DELIVERY_LAST_NAME_EMPTY The Last Name cannot be empty.
ORDER_DELIVERY_ADDRESS1_EMPTY The Address 1 cannot be empty.
ORDER_DELIVERY_CITY_EMPTY The City cannot be empty.
ORDER_DELIVERY_ZIP_EMPTY The Zip cannot be empty.
ORDER_DELIVERY_STATE_EMPTY The State cannot be empty.
ORDER_DELIVERY_DETAILS_COUNTRY_INVALID The country code is not valid for the current vendor.

Item: Payment_Method

Error code Description

ORDER_PAYMENT_METHOD_EMPTY

No payment method has been provided.
ORDER_PAYMENT_METHOD_INVALID The payment method is not supported by your account.
ORDER_PAYMENT_METHOD_PREVIOUS_ORDER_REFNO_EMPTY The previous order reference number cannot be empty.
ORDER_PAYMENT_METHOD_RETRY_INVALID This payment method is not supported for retrying this order.
ORDER_PAYMENT_METHOD_RESTRICTED The payment method is restricted for product.
ORDER_PAYMENT_METHOD_COUNTRY_INVALID The payment method is not available in the selected country.
ORDER_PAYMENT_METHOD_CURRENCY_INVALID The payment currency is not supported for selected payment method.
ORDER_PAYMENT_METHOD_NOT_ALLOWED Card processing is restricted. Your integration does not meet the requirements for handling sensitive card data.
ORDER_PAYMENT_METHOD_PREVIOUS_ORDER_EMAIL_INVALID The billing email is different from the one of the reference order.
ORDER_PAYMENT_METHOD_CC_VENDOR_3DS_RETURN_URL_EMPTY The PaymentDetails.PaymentMethod.Vendor3DSReturnURL can not be empty.
ORDER_PAYMENT_METHOD_CC_VENDOR_3DS_RETURN_URL_INVALID The PaymentDetails.PaymentMethod.Vendor3DSReturnURL is not valid.
ORDER_PAYMENT_METHOD_CC_VENDOR_3DS_CANCEL_URL_EMPTY The PaymentDetails.PaymentMethod.Vendor3DSCancelURL can not be empty.
ORDER_PAYMENT_METHOD_CC_VENDOR_3DS_CANCEL_URL_INVALID The PaymentDetails.PaymentMethod.Vendor3DSCancelURL is not valid.
ORDER_PAYMENT_METHOD_PAYPAL_EXPRESS_PROCESS_ERROR An error occurred while trying to place the order.
ORDER_PAYMENT_METHOD_PAYPAL_EXPRESS_INTERNAL_ERROR An error from Paypal Express gateway.
ORDER_PAYMENT_METHOD_DIRECT_DEBIT_PROCESS_ERROR An error occurred while trying to place the order.
ORDER_PAYMENT_METHOD_DIRECT_DEBIT_INTERNAL_ERROR Generic error.
ORDER_PAYMENT_METHOD_IDEAL_PROCESS_ERROR An error occurred while trying to place the order.
ORDER_PAYMENT_METHOD_IDEAL_INTERNAL_ERROR Generic error.
ORDER_PAYMENT_METHOD_WE_CHAT_PAY_PROCESS_ERROR An error occurred while trying to place the order.
ORDER_PAYMENT_METHOD_WE_CHAT_PAY_INTERNAL_ERROR Generic error.
ORDER_PAYMENT_METHOD_DIRECT_DEBIT_SWIFT_EMPTY The swift code cannot be empty.
ORDER_PAYMENT_METHOD_DIRECT_DEBIT_IBAN_EMPTY The IBAN cannot be empty or exceed 28 characters./The FirstName cannot be empty or exceed 30 characters./The LastName cannot be empty or exceed 30 characters.
ORDER_PAYMENT_METHOD_IDEAL_BANK_CODE_EMPTY The bank code cannot be empty.
ORDER_PAYMENT_METHOD_INVALID The payment method [%s] is not supported.
ORDER_PAYMENT_METHOD_ORDER_REFERENCE_INVALID Order reference number is required for [%s] payment method./Order reference number is invalid for subscription reference [%s].
PAYMENT_ERROR You cannot place a trial order using [%s] payment method.
PAYMENT_ERROR You cannot place a trial order without a payment method.
ORDER_PAYMENT_METHOD_CARD_MONTH_INVALID The expiration month is invalid.
ORDER_PAYMENT_METHOD_CARD_YEAR_INVALID The expiration year is invalid.
ORDER_PAYMENT_METHOD_CARD_DATE_INVALID The card has expired.
ORDER_PAYMENT_METHOD_CARD_PROCESS_ERROR Couldn't complete the payment validation process: Error processing the credit card transaction. Please contact the issuer bank for more details, or enter another card.
ORDER_PAYMENT_METHOD_CARD_PROCESS_ERROR Couldn't complete the payment validation process: Error processing the credit card transaction. Insufficient funds. Please charge your card account or enter another card.
ORDER_PAYMENT_METHOD_CARD_PROCESS_ERROR Couldn't complete the payment validation process: Access denied in payment gateway! The transaction cannot be finalized at this time. Please try to finalize the transaction in a few minutes.
ORDER_PAYMENT_METHOD_CARD_PROCESS_ERROR Couldn't complete the payment validation process: Error processing the credit card transaction. Please enter another card or try to finalize the transaction in a few minutes.
ORDER_PAYMENT_METHOD_CARD_PROCESS_ERROR 'Couldn't complete the payment validation process: <div align="left">Error processing the credit card transaction. Your credit card was not charged.<br><br>Possible cause: <li>your card is not active for online transactions<li>you have entered invalid or incomplete credit card details<li>a temporary error occurred while processing the payment<br><br><font color="000000">Recommendations:<br>Please enter another card or try to finalize the transaction in a few minutes. If you still get an error, please contact the issuer bank for more details by calling the number on the back of your card.</font></div>
ORDER_PAYMENT_METHOD_CARD_PROCESS_ERROR Couldn't complete the payment validation process: Error processing the credit card transaction. Expired card. Please contact the issuer bank for more details, or enter another card.
ORDER_PAYMENT_METHOD_CARD_PROCESS_ERROR Couldn't complete the payment validation process: Error processing the credit card transaction. No such card. The transaction can be finalized only after entering a valid credit card.
ORDER_PAYMENT_METHOD_CARD_PROCESS_ERROR Couldn't complete the payment validation process: Error processing the credit card transaction. You have entered an invalid CVV2 or CVC2.
ORDER_CURRENCY_CODE_EMPTY The currency code cannot be empty.
ORDER_CURRENCY_INVALID The currency [%s] is not supported by the vendor.
PAYMENT_DECRYPTION_FAILED Invalid key identifier.
TEST_ORDER_NOT_ALLOWED Test orders are not available for your account.
ORDER_PAYMENT_METHOD_CCID_INVALID Invalid CVV2/CVC2 code.
ORDER_PAYMENT_METHOD_CARD_HOLDER_INVALID Invalid name.
ORDER_PAYMENT_METHOD_CARD_NUMBER_INVALID Your card type [%s] does not match the card number [%s].
ORDER_PAYMENT_METHOD_CARD_CURRENCY_INVALID The provided currency [%s] is not supported with this card type. Supported currencies: [%s].
ORDER_REF_MISMATCH The reference number does not belong to a valid order.
ORDER_FRAUD_ERROR The reference number identifies an order that is not yet cleared by fraud.
ORDER_STATUS_ERROR The reference number identifies an order with an incorrect status.
PAYMENT_ERROR The referenced order has an unsupported payment method.
ORDER_PAYMENT_METHOD_CARD_INVALID  Forbidden. You've reached the maximum allowed number of orders with the same credit card.
ORDER_PAYMENT_METHOD_CARD_INVALID Invalid card number entered.
ORDER_PAYMENT_METHOD_CARD_INVALID Visa usually has 16 or 13 digits, but you entered 14.
ORDER_PAYMENT_METHOD_CARD_INVALID Unknown error!
ORDER_PAYMENT_METHOD_CARD_INVALID We don't accept %s cards for online processing.
ORDER_PAYMENT_METHOD_CARD_INVALID Card number is missing %s digit(s).
ORDER_PAYMENT_METHOD_CARD_INVALID The month isn't a string.
ORDER_PAYMENT_METHOD_CARD_INVALID Month has invalid format.
ORDER_PAYMENT_METHOD_CARD_INVALID Invalid expiration date entered or the card has expired.
PAYMENT_ERROR AutoApprove feature is not available for your account.
PAYMENT_ERROR Net payment terms has to be a number of days between [%d] and [%d].
ORDER_PAYMENT_METHOD_DIRECT_DEBIT_IBANSWIFT_INCORRECT Invalid IBAN: [%s] or SWIFT CODE: [%s].
ORDER_PAYMENT_METHOD_DIRECT_DEBIT_IBAN_INVALID Invalid IBAN: [%s].
ORDER_PAYMENT_METHOD_DIRECT_DEBIT_SWIFT_INVALID Invalid SWIFT code: [%s].
ORDER_PAYMENT_METHOD_PAYPAL_RETURN_URL_EMPTY The return URL can not be empty.
ORDER_PAYMENT_METHOD_IDEAL_RETURN_URL_EMPTY The return URL can not be empty.
ORDER_PAYMENT_METHOD_WE_CHAT_PAY_RETURN_URL_EMPTY The return URL can not be empty.
ORDER_PAYMENT_METHOD_EXTERNAL_RETURN_URL_EMPTY The return URL can not be empty.
ORDER_PAYMENT_METHOD_PAYPAL_RETURN_URL_INVALID The return URL is not valid.
ORDER_PAYMENT_METHOD_IDEAL_RETURN_URL_INVALID The return URL is not valid.
ORDER_PAYMENT_METHOD_WE_CHAT_RETURN_URL_INVALID The return URL is not valid.
ORDER_PAYMENT_METHOD_EXTERNAL_RETURN_URL_INVALID The return URL is not valid.
ORDER_PAYMENT_METHOD_IDEAL_BANK_CODE_INVALID Invalid bank code [%s].
INVALID_PAYMENT_METHOD This payment method is not available for your account.
INVALID_CC_TOKEN Invalid token.
INVALID_EES_TOKEN The token is not valid. In order to proceed with the place order a valid token is required.
ORDER_PAYMENT_METHOD_APPLE_PAY_TOKEN_INVALID Invalid payment data: Invalid token.
ORDER_PAYMENT_METHOD_INVALID The payment method [%s] is not supported.
PAYMENT_ERROR Company name is mandatory for Purchase Order.

Item: Payment_Details

Error code Description
ORDER_PAYMENT_DETAILS_INVALID No payment details have been provided/Free orders without payment details are not enabled for your account.

Item: Currency

Error code Description
ORDER_CURRENCY_CODE_EMPTY The currency code cannot be empty.
ORDER_CURRENCY_INVALID The currency [%s] is not supported by the vendor.

Item: Language

Error code Description
ORDER_LANGUAGE_EMPTY Language code cannot be empty.
ORDER_LANGUAGE_INVALID Language [%s] is not supported by current vendor settings.

Item: Affiliate

Error code Description
AFFILIATE_CODE_EMPTY The AffiliateCode parameter cannot be empty.
AFFILIATE_CODE_INVALID The AffiliateCode parameter is invalid.

Item: ExtraInformation

Error code Description
INVALID_RETRY_FAILED_PAYMENT_LINK The retry payment link is not a valid URL.
INVALID_RETRY_FAILED_PAYMENT_LINK The retry payment link has no parameter with placeholder [%s].

Item: Source

Error code Description
INVALID_SOURCE The provided source is empty.

Item: Gift_details

Error code Description
INVALID_GIFT_DETAILS Gift details require that FirstName, LastName, and Email be non-empty.
INVALID_GIFT_EMAIL The gift email [%s] is not valid.
PRODUCT_ERROR Cannot mark the order as a gift until there are products added to the cart.
PRODUCT_ERROR Cannot mark the order as a gift because there are products that are not available as gifts.

Item: Coupon

Error code Description
ORDER_COUPON_CODE_EMPTY The coupon code is empty.
ORDER_COUPON_CODE_INVALID The provided coupon [%s] is invalid.

Item: Promotion

Error code Description
ORDER_PRODUCT_PROMOTION_CODE_INVALID The provided promotion code [%s] is invalid.

Item: Additional_Field

Error code Description
ORDER_ADDITIONAL_FIELD_REQUIRED The order additional information field [%s] was not set, and it's marked as mandatory.

Item: Order_Product_Additional_Fields

Error code Description
ORDER_PRODUCT_ADDITIONAL_FIELD_REQUIRED Add the required product additional information fields [%s] for products [%s].
ORDER_PRODUCT_ADDITIONAL_FIELD_REQUIRED The product additional information field [%s] was not set for product [%s], and it\'s marked as mandatory

Item: SubscriptionCustomSettings

Error code Description
ORDER_ITEMS_SUBSCRIPTION_CUSTOM_SETTINGS_CYCLE_UNIT_INVALID Invalid item subscription custom settings cycle unit. Accepted values: DAY, MONTH.
ORDER_ITEMS_SUBSCRIPTION_CUSTOM_SETTINGS_CYCLE_LENGTH_INVALID Invalid item subscription custom settings cycle length. Use positive integers, or -1 when contract length is NULL.
ORDER_ITEMS_SUBSCRIPTION_CUSTOM_SETTINGS_CONTRACT_LENGTH_INVALID Invalid item subscription custom settings contract length. Use positive integers or NULL.
ORDER_ITEMS_SUBSCRIPTION_CUSTOM_SETTINGS_CONTRACT_LENGTH_FORBIDDEN Forbidden item subscription custom settings contract length. Use a value that is a multiple of the cycle length value.
ORDER_ITEMS_SUBSCRIPTION_CUSTOM_SETTINGS_CYCLE_AMOUNT_INVALID Item subscription custom settings cycle amount must be a positive value (INT or FLOAT).
ORDER_ITEMS_SUBSCRIPTION_CUSTOM_SETTINGS_CYCLE_AMOUNT_TYPE_INVALID Invalid item subscription custom settings cycle amount type. Accepted values: NET, GROSS.
ORDER_ITEMS_SUBSCRIPTION_CUSTOM_SETTINGS_CLIENT_DEAL_AUTO_RENEWAL_INVALID Invalid item subscription custom settings client deal auto-renewal.
ORDER_ITEMS_SUBSCRIPTION_CUSTOM_SETTINGS_MERCHANT_DEAL_AUTO_RENEWAL_INVALID Invalid item subscription custom settings merchant deal auto-renewal.

Other

Error code Description

ORDER_PHYSICAL_FEATURE_MISSING

You are not allowed to place orders with physical products.
ORDER_ERROR Couldn't process the order/Order reference is invalid.
GIFT_ORDER_NOT_ALLOWED Cannot place the order because order is marked as gift and product is not available as a gift.
TEST_ORDER_NOT_ALLOWED Test orders are not available for your account.
ORDER_CURRENCY_MISMATCH Order currency values must match.
ORDER_TOTAL_NEGATIVE Order total must be zero or a positive value.
ORDER_TEST_MODE_REQUIRED Test mode is required on test subscriptions.
BANNED_SHOPPER_IP The shopper is banned.
AUTHENTICATION_ERROR Authentication needed for this resource.

 

Promotions

Overview

Use the Promotion object via JSON-RPC API 4.0 to retrieve information on discounts/promotions you set up for your account.

Parameters

Parameters Type/Description

Promotion

Object

  Detailed below.

CouponCodes

Array of strings

 

Array of coupon/voucher codes when Coupon / Voucher type is Multiple. Otherwise, empty array.

ChannelType

String

 

Possible values:

  • ECOMMERCE
  • CHANNEL_MANAGER
  • ALL

CouponType

String

 

Possible values:

  • SINGLE
  • MULTIPLE

DiscountType

String

 

Possible values:

  • FIXED
  • PERCENT

Type

String

 

REGULAR

Discount

Int

 

The value of the discount. Example, for a $30 USD discount Avangate returns the value 30 and for a 25% price cut, Avangate returns 25.

Products

Array

 

Array of product codes for the products impacted by the promotion.

Name

String

 

Promotion name.

Description

String

 

Promotion description.

StartDate

String

 

Starting date. The date when you set the promotion to start. Is NULL for promotions that start immediately after they're created.

EndDate

String

 

Ending date. The date when you set the promotion to end. Is NULL for promotions that you want active indefinitely.

MaximumOrdersNumber

Int

 

When the maximum number of orders is reached the promotion stops. Can be NULL if you want the promotion to apply to an unlimited number of orders.

MaximumQuantity

Int

 

Discount only applies to a specific number of product, smaller than the maximum quantity you defined. Can be NULL if you want the promotion to apply to an unlimited number units. Any extra quantity added to the cart will be sold at full price.

InstantDiscount

Boolean

 

Selecting the instant discount option will auto-apply the discount for ALL the selected products for all shoppers, without the need to enter the discount coupon.

Coupon

String

 

The promotion/voucher for which you are extracting the information.

DiscountLabel

String

 

Discounts can be set as a percentage from the product price or as a fixed amount in the chosen currency.

Enabled

Boolean

 

Can be TRUE if promotion is enabled, or FALSE if otherwise.

Currency

String

 

Currency code available for the default currency of FIXED promotions. Missing for PERCENT promotions.

Code

String

 

Unique, system-generated identifier Avangate associates with promotion campaigns.

PriceThreshold

Object

 

Limits discount use only when total order value (taxes included) exceeds the threshold you configure.

 

Amount

 Decimal

 

 

The minimum threshold you defined for the default currency.

 

Currency

String

 

 

Currency code available for the default currency of custom threshold settings

 

 

 

 

Order with dynamic products

Overview

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

Place orders with dynamic product information

Retrieve an order

Dynamic order object

Parameters Type/Description

RefNo

String

 

2Checkout generates unique reference numbers for all orders (purchases). You can use this parameter to retry authorizations for orders with failed transactions by changing the payment method.

 

NULL when you place new orders.

ChargebackResolution String
 

Chargeback status information. Possible values:

· OPEN (chargeback is in progress)

· WON (chargeback won by you)

· LOST (chargeback won by the customer)

· ACCEPTED (you agreed to repay the value of the order to the customer)

· NONE (no chargeback initiated for the order)

To manage chargeback notifications navigate to Control Panel Dashboard →Integrations → Webhooks and API, and click on the IPN settings tab.

In the General IPN Settings section, under Triggers, make sure to check the boxes next to the following options:

· chargeback open (2Checkout sends an IPN when shoppers open a chargeback dispute).

· chargeback closed - (2Checkout sends an IPN when the parties involved resolve a chargeback dispute).

Also, check the checkbox next to the CHARGEBACK_RESOLUTION parameter featured in the Response tags area.

ChargebackReasonCode String
 

Identifier for the chargeback dispute reason from the 2Checkout system. Empty for orders with no chargeback dispute initiated.

Possible values:

  • MERCHANDISE_NOT_RECEIVED - Order not fulfilled/not delivered
  • NOT_AS_DESCRIBED - Product(s) not as described/unfunctional
  • DUPLICATE_TRANSACTION - Duplicate order
  • FRAUD / NOT_RECOGNIZED - Fraud/Order not recognized
  • CREDIT_NOT_PROCESSED - Agreed refund not processed
  • NOT_RECOGNIZED - New/renewal order not recognized
  • AUTHORIZATION_PROBLEM - Authorization problem
  • INFO_REQUEST - Information request
  • UNKNOWN - Unknown

OrderNo

String

 

The consecutive order number 2Checkout associates with orders and displays in the Order search area of your account.

ExternalReference

String

 

Set external reference identifiers for orders. Enables you to replicate the functionality of the REF parameter included Integero Buy Links. Maximum 100 characters. If there is a need for longer references, you can apply an md5 hash for any string value, resulting in a 32 characters string. You can verify the hash after the order notification, on the client side.

ShopperRefNo

String

 

External shopper identifier.

Status

String

 

The status of the order:

  • AUTHRECEIVED – 2Checkout blocks the amount corresponding to the transaction, but the process of collecting funds is incomplete.
  • PENDING - 2Checkout has yet to block the amount corresponding to the transaction or shoppers used an offline payment method like wire transfer.
  • COMPLETE – The shopper completed the transaction for the purchase and 2Checkout or you fulfilled the order (when required).
  • CANCELED – 2Checkout cancels orders for which shoppers fail to transfer funds in due time.
  • REVERSED – 2Checkout reverses order transactions that never reach the Complete/Finished stage. Shoppers never complete transactions for such purchases.
  • REFUND – 2Checkout refunds orders only after they reach the Complete/Finished stage and returns the funds collected to shoppers.

ApproveStatus

String

 

The status of the order resulted from the evaluation by the 2Checkout anti-fraud system or by a member of the anti-fraud department. This status varies for new purchases and for orders requiring customers to make manual payments.

Possible values:

  • WAITING: The 2Checkout anti-fraud system or a member of the anti-fraud department has yet to approve the order.
  • OK: The 2Checkout anti-fraud system or a member of the anti-fraud department approved the order.
  • INVALIDDATA: Shopper-supplied data is invalid – 2Checkout did not approve the order.
  • FRAUD: The order is fraudulent.

VendorApproveStatus

String

 

Shows if you approved or not a partner order. Possible values:

  • OK
  • WAITING
  • REJECTED

Language

String

 

ISO 639-1 two-letter code. Language used for the purchase process. Example: “en.”

OrderDate

String

 

Y-m-d H:i:s (2014-05-22 00:12:12) The datetime stamp (in the API time zone defined in cPanel) when customers place their orders.

FinishDate

String

 

Y-m-d H:i:s (2014-05-22 00:12:12) The datetime stamp (in the API time zone defined in cPanel) when the order reach the Complete status.

 

NULL for order that did not reach the Complete/Finished stage.

Source

String

 

The link source for the sales. Enables you to replicate the functionality of the SRC (separate link identifier) parameter when included Integero Buy Links. Use the SRC parameter to track sale sources.

Maximum length 255 characters. Cannot be null.

AffiliateSource

String

 

The link source for affiliate referred sales. Similar to the functionality of the SRC (separate link identifier) parameter included Integero Buy Links, but controlled by the AFFSRC parameter. Affiliates use the AFFSRC parameter to track sale sources for their referrals. Maximum length 255 characters.

AffiliateId

Integer

 

Identifier belonging to affiliates who refer orders.

AffiliateName

String

 

Affiliate name.

AffiliateUrl

String

 

Affiliate website URL from the Affiliate Details.

RecurringEnabled

Boolean

 

true or false, depending on whether the shoppers checked the subscription auto-renewal checkbox or not, during the purchase process.

HasShipping

Boolean

 

true or false, depending on whether the order requires shipping.

DeliveryInformation

Object

Details below

                                  ShippingMethod

Object

Details below

                                                            Code

String

                                                Unique system-identified for your shipping method.
                                                           TrackingURL String
  Tracking URL provided to customers who purchase physical goods.
                                                           TrackingNumber String
  Tracking Number provided to customers for tracking the delivery of their physical products.
                                                           Comment String
  Additional information provided to customers who purchsae physical goods.

BillingDetails

Object

   

Details below. 

 

FirstName

String

   

Shopper name.

 

LastName

String

   

Shopper surname.

 

CountryCode

String

   

Shopper country. ISO 3166 two-letter code.

 

State

String – Required for US, Brazil, India and Romania

   

The state in the shopper's country. Mandatory when you set the Billing Country to US, Brazil, India and Romania. Use case insensitive utf8 strings for the full name, or just the two letter code.

 

City

String

   

Shopper city.

 

Address1

String

   

Shopper address.

 

Address2

String

   

Shopper address.

 

Zip

String

   

ZIP/ Postal code.

 

Email

String

   

Shopper email address.

 

Phone

String

   

Shopper phone number. Mandatory when you set Brazil as the Billing Country. Can be NULL.

 

Company

String

   

Company name. Can be null for end users. When present, you also need to provide the FiscalCode.

 

FiscalCode

String – Required for Brazil

   

• For companies, it needs to be the VAT ID. 2Checkout will validate the value provided and throw an error if the VAT ID is invalid/incorrect when calling setPaymentDetails. When present, you also need to provide the Company name.

• Mandatory when the Billing Country is set to Brazil. For Brazilian customers it represents the Fiscal Code (CPF/CNPJ).

• Mandatory when the Billing Country is set to India and purchase is made by a Company.

• Can be null for end users.

DeliveryDetails

Object

Optional. When missing, 2Checkout uses the same details as for the BillingDetails object.

   

Details below. 

 

FirstName

String

   

Shopper name from the delivery details.

 

LastName

String

   

Shopper surname from the delivery details.

 

CountryCode

String

   

Shopper country. ISO 3166 two-letter code from the delivery details.

 

State

String – Required for US, Brazil and Romania

   

The state in the shopper's country from the delivery details. Mandatory when you set the Billing Country to US, Brazil and Romania. Use case insensitive utf8 strings for the full name, or just the two letter code.

 

City

String

   

Shopper city from the delivery details.

 

Address1

String

   

Shopper address from the delivery details.

 

Address2

String

   

Shopper address from the delivery details.

 

Zip

String

   

ZIP/ Postal code from the delivery details.

 

Email

String

   

Shopper email address from the delivery details.

 

Phone

String

   

Shopper phone number from the delivery details. Mandatory when you set Brazil as the Billing Country. Can be NULL.

 

Company

String

   

Company name from the delivery details. Can be null for end users. When present, you also need to provide the FiscalCode.

PaymentDetails

Object

 

Adapt this object to the desired payment method.

 

Type

String

   

The payment method:

  • CC (credit/debit card - including local Brazilian cards).
  • PAYPAL
  • PAYPAL_EXPRESS
  • CCNOPCI (credit/debit card for non-PCI certified merchants).
  • TEST (for test orders).
  • PREVIOUS_ORDER (place new orders using the reference of a previous order).
  • EXISTING_PAYMENT_DATA  (use a card one of your customers already used to purchase from your account).
  • WIRE – the placeOrder response includes Wire payment details.
  • CHECK – the placeOrder response includes Check payment details.
  • PURCHASEORDER - use for orders with POs.
  • FREE – for 0 value orders for which you’re not requiring customers to provide payment details.
  • GOOGLE PAY
 

Currency

String

   

The currency ISO code for the payment - ISO 4217. Example: “usd.”

 

PaymentMethod

Object

   

Object structure and parameters differ according to payment method selected and API method (placing orders (POST) vs. retrieving order data (GET)). For payments with credit cards, PalPay Express, previous order reference and purchase order use the objects below.

 

For payments with check and wire, send only the ‘CHECH’ and ‘WIRE’ strings.

 

null for 0 value orders for which you’re not requiring customers to enter payment details.

                           RecurringEnabled Boolean
    true or false, depending on whether the order has active recurring options
   

PaymentDetailsCard

Object

       

Details below. 

     

CardType

String

       

visa, visaelectron, mastercard, maestro, amex, discover, dankort, cartebleue, jcb, hipercard, elo

     

FirstDigits

String

       

First four digits of the credit card.

     

LastDigits

String

       

Last four digits of the credit card.

      Vendor3DSReturnURL String
        URL to which customers are redirected after a successful 3DS process.
      Vendor3DSCancelURL String
        URL to which customers are redirected after a failed 3DS process.
      InstallmentsNumber String
        Number of installments needed for covering the order total.
 

CheckPaymentDetails

Object

     

Details below. 

   

Beneficiary

String

     

The beneficiary of the payment.

Can be NULL.

   

CheckPostalAddress

String

     

The address of the beneficiary.

Can be NULL.

   

Amount

Float

     

The total costs incurred by the customer for an order.

Can be NULL.

   

Currency

String

     

The currency ISO code of the order/payment - ISO 4217.

Can be NULL.

 

PayPalExpress

Object

       

Details below. 

     

Email

String

       

Email address customers use for their PayPal account.

     

ReturnURL

String

       

The PayPal Express Checkout redirect URL returned by calling the getPayPalExpressCheckoutRedirectURL method. The return URL is the page on your website to which PayPal redirects your buyer's browser after the buyer logs Integero PayPal and approves the payment. Typically, this is a secure page (https://...) on your site.

     

CancelURL

String

       

The cancel URL is the page on your website to which PayPal redirects your buyer's browser if the buyer does not approve the payment. Typically, this is the secure page (https://...) on your site from which you redirected the buyer to PayPal.

 

WirePaymentDetails

Object

     

Details below. 

   

Amount

Float

     

The total costs customers incur.

Can be NULL.

   

Currency

String

     

The currency ISO code of the order - ISO 4217.

Can be NULL.

   

PaymentReference

String

     

Transaction identifier.

Can be NULL.

   

RoutingNumber

String

     

Identification number assigned to financial institutions.

Can be NULL.

   

BankAccounts

Optional (Array of objects)

       

Details below. 

     

Beneficiary

String

       

The beneficiary of the payment.

Can be NULL.

     

BankName

String

       

The name of the beneficiary's bank.

Can be NULL.

     

BankCountry

String

       

The country of the beneficiary's bank.

Can be NULL.

     

BankCity

String

       

The city of the beneficiary's bank.

Can be NULL.

     

BankAddress

String

       

The address of the beneficiary's bank.

Can be NULL.

     

BankAccount

String

       

The number for the account in which customers transfer the funds.

Can be NULL.

     

BankAccountIban

String

       

The IBAN of the beneficiary's bank.

Can be NULL.

     

BankAccountSwiftCode

String

       

The Swift Code of the beneficiary's bank.

Can be NULL.

     

Currency

String

       

The currency ISO code for the bank account - ISO 4217.

Can be NULL.

 

CustomerIP

String

   

Shopper IP.

CustomerDetails

Object

2Checkout populates the parameters of the customer entity with information from the customer whose AvangateCustomerReference or ExternalCustomerReference you send during the purchase.

   

Details below. 

 

AvangateCustomerReference

Integer

   

System-generated 2Checkout customer reference. Aggregate subscriptions under the same Customer account if the products they're associated to are purchased by the same shopper by adding the AV_CUSTOMERID (case sensitive) parameter to buy links. The 2Checkout system generates default customer numerical (Integer) IDs (AV_CUSTOMERID) automatically for all orders containing products that feature subscriptions.

 

ExternalCustomerReference

String

   

The external customer reference you control. Aggregate subscriptions under the same Customer account if the products they're associated to are purchased by the same shopper by adding the CUSTOMERID (case sensitive) parameter  to buy links.

 

FirstName

String

   

Customer's first name. 

 

LastName

String

   

Customer's last name.

 

CountryCode

String

   

Customer's country code (ISO 3166 two-letter code).

 

State

String

   

Customer's state. For example, "Alabama","Alaska","Arizona".

 

City

String

   

Customer's city.

 

Address1

String

   

Customer's address.

 

Address2

String

   

Customer's address.

 

Zip

String

   

Zip code.

 

Email

String

   

Customer's email.

 

Phone

String

   

Customer's phone number.

 

Company

String

   

Company name.

 

FiscalCode

String

   

For companies, it needs to be the VAT ID. 2Checkout validates this values and throws an error if the VAT ID is invalid/incorrect. When present, you need to also provide Company name.

 

Can be null for end users.

 

Fax

String

   

Customer's fax number.

 

Enabled

Boolean

   

true or false, depending on whether the customer account is active or inactive. An active customer account features at least one Active or Past due subscription.

 

Trial

Boolean

   

true or false, depending on whether the customer account features only trials or also paid subscriptions.

 

Language

String

   

ISO 639-1 two-letter code. Example: “en.”

 

ExistingCards

Optional (Array of objects)

     

Details below. 

   

TransientToken

Object

     

Populated only when you retrieve customer information by SSOToken.

     

Token

String

       

Token for the EXISTING_PAYMENT_DATA flow. Use it to charge customers using cards they used in the past for purchases from your 2Checkout account.

   

CardType

String

     

visa, visaelectron, mastercard, maestro, amex, discover, dankort, cartebleue, jcb, hipercard, elo

   

LastDigits

String

     

Last four digits of the credit card.

   

ExpirationMonth

String

     

Card expiration month.

   

ExpirationYear

String

     

Card expiration year.

   

NameOnCard

String

     

Card holder name.

Origin

String

 

2Checkout automatically tracks the source of purchases:

 

  • Web – When customers use the desktop version of the 2Checkout shopping cart.
  • API - When customers use a custom, API-based ordering Integererface.
  • Mobile - When customers use the mobile version of the 2Checkout shopping cart.
  • Automatic Billing – For auto-renewals and trial conversions.

AvangateCommission

Integer

 

2Checkout's commission for the order.

OrderFlow

String

 

PURCHASE_ORDER - Sent only when shoppers used Purchase Orders.

REGULAR - Sent in all other cases.

GiftDetails

Object

 

Contains contact details for the recipient of a gift purchase.

 

FirstName

String

   

First name of gift recipient.

 

LastName

String

   

Last name of gift recipient.

 

Email

String

   

Email of gift recipient. 2Checkout uses this email for the delivery/fulfillment process.

 

GiftNote

String

   

Custom text shoppers provide as a message to the gift recipient.

PODetails

Object (optional)

   

Details below. 

 

Status

String

   

PO status. Possible values:

 

PO status API

PO status cPanel

AWAITING_UPLOAD

Awaiting form submission - Waiting for the customer to submit the PO form

TIME_EXPIRED

Expired, form not received - The customer did not submit the PO form

AWAITING_MERCHANT

Awaiting your confirmation - PO approved by 2Checkout, awaiting vendor confirmation

MERCHANT_TIME_EXPIRED

Expired, PO not confirmed - You didn't confirm/reject the PO

AWAITING_MERCHANT

Rejected - You rejected the PO

AWAITING_PAYMENT

Awaiting payment - You approved the PO, waiting for payment

AWAITING_PAYMENT

Expired, not paid - The customer did not complete the PO payment. 2Checkout accepts  payments up to 30 days after the PO payment Integererval expires

NOT_PAID

Canceled, not paid - The customer did not complete the PO payment

NOT_PAID

Canceled by 2Checkout - 2Checkout canceled the PO

NOT_PAID

Canceled via API - You canceled the PO (via API)

PAID

Complete - Customer paid the PO. The order is complete

 

AutoApprove

Boolean

 

TRUE or FALSE, depending on whether you set POs to auto-approve or not.

 

RequireDocumentUpload

Boolean

 

TRUE or FALSE, depending on whether require document upload or not.

 

NetPaymentTerms

Integer

 

The term of net payment in days.

 

CopyPreviousDocuments

Boolean

 

TRUE or FALSE, depending on whether copy documents from previous order or not.

 

PdfFormUrl

String

 

URL of Purchase Order form which needs to be printed, signed and uploaded.

ExtraInformation

Object

 

Details below. 

 

PaymentLink

String

 

 

Can be:

1. The PO doc upload link - If you set AutoApprove as FALSE on the original order and before shoppers upload the PO. 

2. Payment link for orders with POs. Business customers can use the PaymentLink to finalize payment for orders with POs. If you set AutoApprove as TRUE on the original order and if 2Checkout and you approve the PO. 

PartnerCode

String

 

Partner code you configured for your partner. NULL for eStore orders.

PartnerMargin

Float

 

Partner margin you set for the order. NULL for eStore orders.

PartnerMarginPercent

Float

 

The percentage of the partner margin from the net value of the products ordered, minus the value of any discounts. NULL for eStore orders.

ExtraMargin

Float

 

Extra margin you offer by editing partner orders. NULL for eStore orders.

ExtraMarginPercent

Float

 

The percentage of the extra partner margin from the net value of the products ordered, minus the partner margin and the value of any discounts. NULL for eStore orders.

ExtraDiscount

Float

 

Extra discount you offer by editing partner orders. NULL for eStore orders.

ExtraDiscountPercent

Float

 

The percentage of the partner margin from the net value of the products ordered, minus the value of any coupon discounts. NULL for eStore orders.

LocalTime

String

 

Local shopper time in the following format: Y-m-d H:i:s.

This parameter can impact the fraud score of an order when it's missing, NULL or incorrectly formatted.

TestOrder

Boolean

 

True for test orders. False of regular orders.

Errors

Array of strings

 

Payment gateway processing errors.

Items

Array of objects

   

Details below. 

 

ProductDetails

Object

   

Name

String

     

Product name.

   

ExtraInfo

String

     

The text entered in the Additional information field when generating Buy links, or via the INFO[PRODUCT_ID] parameter used in Buy links.

   

RenewalStatus

Boolean

     
  • true for orders renewing subscriptions.
  • false for all other orders: new purchases, upgrades.
   

Subscriptions

Object

     

SubscriptionReference

String

       

Unique, system-generated subscription identifier.

     

PurchaseDate

String

       

The date time stamp when shoppers acquired their subscriptions corresponding to the moment when the 2Checkout system marks the purchase as finished. Format (YYYY-MM-DD HH:mm:ss). Default GMT+02:00.

 

e.g. 2015-08-11 15:18:52

     

SubscriptionStartDate

String

       

 

Example: 2015-09-29 17:57:59

     

ExpirationDate

String

       

The date time stamp of upcoming renewal/expiration for subscriptions not taking Integero account grace period settings.

 

Format (YYYY-MM-DD HH:mm:ss). Default GMT+02:00.

 

e.g. 2015-09-11 15:18:52

     

Lifetime

Boolean

       
  • true – For non-recurring, evergreen subscriptions.
  • false – For recurring subscriptions with a specific billing cycle from 7 days to 36 months.
     

Trial

Boolean

       
  • true – For trial subscriptions.
  • false – For non-trial, recurring subscriptions with a specific billing cycle from 7 days to 36 months.
     

Enabled

Boolean

       
  • true – For active and past due subscriptions.
  • false – For expired and cancelled subscriptions.
     

RecurringEnabled

Boolean

       
  • true – For subscriptions with active recurring options
  • false – For subscriptions without recurring options.
    Tangible   Boolean
       
  • true – For products with physical delivery.
  • false – For products that don't require physical delivery.
    IsDynamic   Boolean
       
  • true – For products created with dynamic information.
  • false – For catalog products.
    ShortDescription   String
        Short product description
    DeliveryInformation   Object
        Details below.
      Delivery String
        Delivery information.
      DownloadFile Object
        Information related to the download file.
      DeliveryDescription String
        Delivery description.
      CodesDescription String
        Description of the codes delivered.
      Codes Array
        Array with the codes delivered.

                   

PriceOptions

Array of objects

   

Array of price option groups.

    Code String
      Pricing option code. 
    Name String
      Pricing option name.
    Required Boolean
     

Possible values:

  • true, if the pricing option is mandatory 
  • false, if the pricing option is optional
   

Options

Optional (array of objects)

     

Array of pricing options.

      Name String
        Pricing option name.
      Value String
        Pricing option code.
      Surcharge Float
        Surcharge of the pricing option. For renewal orders, the renewal price includes the pricing option surcharge from the initial order.
.

Price

Object

   

This object returns the price per unit at order line level.

 

In the case of trials, the object returns the costs for the trial to full subscription conversion.

   

UnitNetPrice

Float

     

The value per product unit, excluding sales tax/VAT expressed in the payment currency.

   

UnitGrossPrice

Float

     

Total value per product unit, including sales tax/VAT expressed in the payment currency. UnitGrossPrice does not reflect any discounts.

   

UnitVAT

Float

     

Sales tax/VAT per product unit expressed in the payment currency.

   

UnitDiscount

Float

     

Value of the discount per product unit expressed in the payment currency.

   

UnitNetDiscountedPrice

Float

     

The value per product unit, expressed in the payment currency, excluding sales tax/VAT, from which 2Checkout deducts the unit discount.

   

UnitGrossDiscountedPrice

Float

     

Total costs shoppers incur per product unit, expressed in the payment currency. This value includes sales tax/VAT, 2Checkout and affiliate commissions, but 2Checkout deducts the value of any discounts.

   

UnitAffiliateCommission

Float

     

Value of the affiliate commission per product unit calculated expressed in the payment currency.

 

2Checkout deducts discounts from the costs incurred by shoppers before calculating affiliate commissions.

 

2Checkout does not take Integero account shipping costs when calculating affiliate commissions.

 

NULL when 2Checkout does not apply an affiliate commission.

   

Currency

String

     

The currency ISO code for the payment - ISO 4217. Example: usd.

   

NetPrice

Float

     

The value per order line, excluding sales tax/VAT expressed in the payment currency.

   

GrossPrice

Float

     

Total value per order line, including sales tax/VAT expressed in the payment currency. UnitGrossPrice does not reflect any discounts.

   

NetDiscountedPrice

Float

     

The NetPrice value per order line (in the payment currency), excluding sales tax/VAT, from which 2Checkout deducts discounts.

   

GrossDiscountedPrice

Float

     

Total costs shoppers incur per order line, expressed in the payment currency. This value includes sales tax/VAT, 2Checkout and affiliate commissions, but 2Checkout deducts the value of any discounts.

 

Example:

  • UnitNetPrice: 99
  • UnitGrossPrice: 120.39
  • UnitVAT: 21.39
  • UnitDiscount: 9.9
  • UnitNetDiscountedPrice: 89.1
  • UnitGrossDiscountedPrice: 110.49
  • UnitAffiliateCommission: 22.28
  • Currency: "usd"
  • NetPrice: 198
  • GrossPrice: 240.77
  • NetDiscountedPrice: 178.2
  • GrossDiscountedPrice: 220.97
  • Discount: 19.8
  • VAT: 42.77
  • AffiliateCommission: 44.56
   

Discount

Float

     

Value of the discounts per order line expressed in the payment currency.

   

VAT

Float

     

Value of sales tax/VAT per order line expressed in the payment currency.

   

AffiliateCommission

Float

     

Value of the affiliate commission per order line, calculated from the NetDiscountedPrice expressed in the payment currency. Or NULL. 2Checkout does not take Integero account shipping costs when calculating affiliate commissions.

    VATPercent Integer
      Percentage of the VAT/tax applied on purchase.
    HandlingFeeNetPrice Integer
      Handling fee applied to your NET price configuration.
    HandlingFeeGrossPrice Integer
      Handling fee applied to your GROSS price configuration.
 

Quantity

Integer

   

Number of units

 

SKU

String

   

SKU identifier.

  LineItemReference String
    System generated reference for the line item.
  PurchaseType String
   

Purchase type for orders placed with dynamic information. Possible values:

  • PRODUCT
  • TAX
  • COUPON
  • SHIPPING
  ExternalReference String
    External order reference.
  SubscriptionStartDate String
    Set subscription starting date. 
 

CrossSell

Object

     

Details below. 

   

ParentCode

String

     

The product code of the master product you set to trigger the campaign.

   

CampaignCode

String

     

Unique, system-generated identifier for cross-sell campaigns.

 

Trial

Object

     

Details below. 

   

Period

Integer

     

The length of the trial subscription lifetime in days.

   

GrossPrice

Float

     

Total trial price in the payment currency before 2Checkout deducts any taxes, discounts, etc.

   

VAT

Float

     

The total value of taxes for the trial in the payment currency, before 2Checkout deducts any discounts.

   

NetPrice

Float

     

Total trial price in the payment currency, not including taxes, before 2Checkout deducts any discounts.

 

AdditionalFields

Optional (array of objects)

     

Details below. 

   

Code

String

     

The alpha-numeric characters, underscores and dashes that are set as the field identifier.

   

Text

String

     

Field text visible to shoppers in the cart.

   

Value

String

     

Selected field value.

 

Promotion

Object

     

Details below. 

   

Name

String

     

Promotion name.

   

Description

String

     

Promotion description.

   

StartDate

String

     

The date when you set the promotion to start. NULL for promotions that start immediately after you create them.

   

EndDate

String

     

The date when you set the promotion to end. NULL for promotions you want active indefinitely.

   

MaximumOrdersNumber

Integer

     

2Checkout only applies the promotion to a maximum number of orders you define.

 

Can be NULL if you want the promotion to apply to an unlimited number of orders.

   

MaximumQuantity

Integer

     

Discount only applies to a maximum number of units purchased through a single order, smaller than the quantity you defined. Shoppers purchase any extra units at full price. Can be NULL if you want the promotion to apply to an unlimited number units.

   

InstantDiscount

Boolean

     

The instant discount option auto-applies the discount for ALL selected products, without the need for shoppers to enter a discount coupon.

   

Coupon

String

     

Promotion coupon/voucher.

   

DiscountLabel

String

     

Discounts can be set as a percentage from the product price or as a fixed amount in the chosen currency.

   

Enabled

String

     

true or false, depending on whether a promotion is active or disabled. 

   

Type

String

     
  • REGULAR – product/cart line level discounts.
  • ORDER – quantity discounts.
  • GLOBAL – order-level discounts.
  • AFFILIATE – for discounts created by affiliates.

Promotions

Array of objects

   

Details below. 

 

Name

String

   

Promotion name.

 

Description

String

   

Promotion description.

 

StartDate

String

   

The date when you set the promotion to start. NULL for promotions that start immediately after you create them.

 

EndDate

String

   

The date when you set the promotion to end. NULL for promotions you want active indefinitely.

 

MaximumOrdersNumber

Integer

   

2Checkout only applies the promotion to a maximum number of orders you define.

 

Can be NULL if you want the promotion to apply to an unlimited number of orders.

 

MaximumQuantity

Integer

   

Discount only applies to a specific number of units purchased at once, smaller than the maximum quantity you defined. Shoppers purchase any extra units at full price. Can be NULL if you want the promotion to apply to an unlimited number units.

 

InstantDiscount

Boolean

   

The instant discount option auto-applies the discount for ALL selected products, without the need for shoppers to enter a discount coupon.

 

Coupon

String

   

Promotion coupon/voucher.

 

DiscountLabel

String

   

Discounts can be set as a percentage from the product price or as a fixed amount in the payment currency.

 

Enabled

String

   

true or false, depending on whether a promotion is active or disabled. 

 

Type

String

   
  • REGULAR – product/cart line level discounts.
  • ORDER – quantity discounts.
  • GLOBAL – order-level discounts.
  • AFFILIATE – for discounts created by affiliates.

AdditionalFields

Array of objects

   

Details below. 

 

Code

String

   

The alpha-numeric characters, underscores and dashes that are set as the field identifier.

 

Text

String

   

Field text visible to shoppers in the cart.

 

Value

String

   

Selected field value.

Currency

String

 

The currency ISO code for the payment - ISO 4217. Example: usd.

NetPrice

Float

 

Order value excluding sales tax/VAT expressed in the payment currency.

GrossPrice

Float

 

Total order value, including sales tax/VAT expressed in the payment currency. GrossPrice does not reflect any discounts.

NetDiscountedPrice

Float

 

The NetPrice order value excluding sales tax/VAT, from which 2Checkout deducts discounts. NetDiscountedPrice is expressed in the payment currency.

GrossDiscountedPrice

Float

 

Total costs shoppers incur, expressed in the payment currency. This value includes sales tax/VAT, 2Checkout and affiliate commissions, but 2Checkout deducts the value of any discounts.

 

For example:

  • Currency: "usd"
  • NetPrice: 396
  • GrossPrice: 486.29
  • NetDiscountedPrice: 376.2
  • GrossDiscountedPrice: 466.49
  • Discount: 19.8
  • VAT: 90.29
  • AffiliateCommission: 94.05

Discount

Float

 

Value of the discounts for an order expressed in the payment currency.

VAT

Float

 

Value of sales tax/VAT expressed in the payment currency.

AffiliateCommission

Float

 

Value of the affiliate commission for the order calculated from the NetDiscountedPrice expressed in the payment currency. Or NULL. 2Checkout does not take Integero account shipping costs when calculating affiliate commissions.

MerchantCode String
  Merchant account code. Can be found in Control Panel, System Settings.

Delete SKU codes

Overview

Use the deleteSku method to remove product SKU codes through an API call using the below parameters.

Request Parameters

Parameters Required Type/Description
productCode Required String.
priceConfigurationCode Required String.
priceConfigurations Required String.

Request Example

<?php

require ('PATH_TO_AUTH');

$product = new \stdClass();
$product->ProductCode= '6B3CB17DDA_COPY1';

$pricingConfiguration = new \stdClass();
$pricingConfiguration->PriceConfigurationCode = 'E684EC99B0';
$pricingConfiguration->SKUs = ['Product_Test_SKU_001050', 'Product_Test_SKU_001053'];

$product->PriceConfigurations = [$pricingConfiguration];

$jsonRpcRequest = array (
    'method' => 'deleteSku',
    'params' => array($sessionID, [$product]),
    'id' => $i++,
    'jsonrpc' => '2.0'
);

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

Response Parameters

Parameters Type/Description
productCode  
priceConfigurationCode  
priceConfigurations  

Response Example

array(1) {
  [0] =>
  class stdClass#5 (4) {
    public $ProductCode =>
    string(16) "6B3CB17DDA_COPY1"
    public $PriceConfigurations =>
    array(1) {
      [0] =>
      class stdClass#6 (3) {
        public $PriceConfigurationCode =>
        string(10) "E684EC99B0"
        public $SKUs =>
        array(2) {
          [0] =>
          string(23) "Product_Test_SKU_001050"
          [1] =>
          string(23) "Product_Test_SKU_001053"
        }
        public $Errors =>
        array(0) {
        }
      }
    }
    public $SKUs =>
    array(0) {
    }
    public $Errors =>
    array(0) {
    }
  }
}

Search SKU codes

Overview

Use the searchSku method to perform product SKU search calls with the below parameters.

Request Parameters

Parameters Required Type Description
ProductCode Required String The product code that you can define for each of your offerings. Needs to be unique.
PricingConfigurations Required Array of objects  

Code

Required String  

Currencies

Required String ISO currency code.

Code

Required String  

PurchaseTypes

Required Array of objects Purchase type identifier. Possible values:
  • NEW_PRODUCT
  • RENEWAL
  • UPGRADE

Code

Required String  

QuantityIntervals

Required Object Numeric identifier of product quantity.

MinQuantity

Required Int  

MaxQuantity

Required Int  

PriceOptionGroups

Required Array of objects  

Code

Required String  

Options

Required Array of objects  

OptionValue

Required String  
Pagination Required Object  

Page

Required Int  

Limit

Required Int  

Request Example

<?php

require ('PATH_TO_AUTH');

$inputSchema = new \stdClass();
$inputSchema->ProductCode= '6B3CB17DDA_COPY1';

$pricingConfiguration = new \stdClass();
$pricingConfiguration->Code = 'E684EC99B0';

$currency = new \stdClass();
$currency->Code = 'EUR';
$pricingConfiguration->Currencies = [$currency];

$purchaseType = new \stdClass();
$purchaseType->Code = 'RENEWAL';
$pricingConfiguration->PurchaseTypes = [$purchaseType];

$quantityIntervals = new \stdClass();
$quantityIntervals->MinQuantity= 1;
$quantityIntervals->MaxQuantity= 10;
$pricingConfiguration->QuantityIntervals = [$quantityIntervals];

$pagination = new \stdClass();
$pagination->Page = 1;
$pagination->Limit = 10;

$inputSchema->PricingConfigurations = [$pricingConfiguration];
$inputSchema->Pagination = $pagination;

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

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

Response Parameters

Parameters Type/Description
Items Object

ProductCode

String

SkuPricingOptions

Array of strings

Code

String

Details

Array

ProductSKU

String

Currency

String

FromQty

String

ToQty

String

PurchaseTypes

String

Groups

Array

GroupCode

String

Options

Array

               Name

String
                                                                                Value String

Errors

Array
Pagination Object

Limit

Int

Page

Int

Count

Int

Response Example

object(stdClass)#22 (2) {
    public $Items" =>
    object(stdClass)#21 (1) {
      public $6B3CB17DDA_COPY1 =>
      object(stdClass)#4 (2) {
        public $ProductCode =>
        string(18) "6B3CB17DDA_COPY1"
        public $SkuPricingOptions =>
        array(1) {
          [0]=>
          object(stdClass)#5 (3) {
            public $Code =>
            string(10) "E684EC99B0"
            public $Details =>
            array(5) {
              [0]=>
              object(stdClass)#6 (7) {
                public $ProductSKU =>
                string(4) "Product_Test_SKU_008899"
                public $Currency =>
                string(4) "EUR"
                public $FromQty =>
                int(1)
                public $ToQty =>
                int(10)
                public $PurchaseType =>
                string(11) "RENEWAL"
                public $Groups =>
                array(1) {
                  [0]=>
                  object(stdClass)#7 (2) {
                    public $GroupCode =>
                    string(7) "GRUP_2"
                    public $Options =>
                    array(1) {
                      [0]=>
                      object(stdClass)#8 (2) {
                        public $Name =>
                        string(7) "grup 2"
                        public $Value =>
                        string(4) "option_code_4"
                      }
                    }
                  }
                }
                public $Options =>
                string(32) "a:1:{i:16885;a:1:{i:0;i:78164;}}"
              }
              [1]=>
              object(stdClass)#9 (7) {
                public $ProductSKU =>
                string(4) "Product_Test_SKU_008902"
                public $Currency =>
                string(4) "EUR"
                public $FromQty =>
                int(1)
                public $ToQty =>
                int(10)
                public $PurchaseType =>
                string(11) "RENEWAL"
                public $Groups =>
                array(1) {
                  [0]=>
                  object(stdClass)#10 (2) {
                    public $GroupCode =>
                    string(7) "GRUP_2"
                    public $Options =>
                    array(1) {
                      [0]=>
                      object(stdClass)#11 (2) {
                        public $Name =>
                        string(6) "grup 2"
                        public $Value =>
                        string(13) "option_code_4"
                      }
                    }
                  }
                }
                public $Options =>
                string(6) "a:0:{}"
              }
            public $Errors =>
            array(0) {
            }
          }
        }
      }
    }
    public $Pagination =>
    object(stdClass)#23 (3) {
      public $Limit =>
      int(10)
      public $Page =>
      int(1)
      public $Count =>
      int(5)
    }

 

Update a subscription

Overview

Change specific details about a subscription. Use the updateSubscription method to change specific details about 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.

Subscription

Required (Object)

 

You need to include the entire Subscription object keeping its structure unchanged (retrieve it using getSubscription) but you can update only specific parameters enumerated below.

 

EndUser

Object

 

 

End user details.

 

ExpirationDate

String

 

 

Subscription expiration date - If you changed the time zone for the 2Checkout API by editing system settings under Account settings, then 2Checkout calculates the ExpirationDate according to your custom configuration. Note: The default 2Checkout API time zone is GMT+02:00.

 

SubscriptionEnabled

Boolean

 

 

Possible values: TRUE/FALSE

 

RecurringEnabled

Boolean

 

 

Possible values: TRUE/FALSE

 

ExternalCustomerReference

String

 

 

Unique customer alphanumeric (string) identifiers that you control. Use this to 

move a subscription from under a customer to another customer entity. 2Checkout moves subscription under the customer for which you provide the External customer reference during the subscription update process. View example.

 

ProductId

Int

 

 

System-generated unique product ID. Needs to be the ID of an existing product in the 2Checkout system created under your account.

The product ID governs the product with which the subscription is associated.

Product types must match Regular - Regular or Bundle - Bundle.

IDs must identify products with the renewal system enabled (max billing cycle 36 months).

 

ProductName

String

 

 

The name of the product for identifier used under ProductID.

 

ProductQuantity

Int

 

 

Ordered quantity.

 

PriceOptionCodes

Array

 

 

Array of product options codes. Pricing options codes are case-sensitive.

To impact the renewal price, the PriceOptionsCodes need to belong to price options of pricing configurations used for the product with which the subscription is associated.

  ActivationKey String
    The subscription activation key. 

 

All other parameters of the Subscription object are non-editable.

The 2Checkout system uses the updated subscription information for:

  • Manual and automatic renewals
  • Upgrades
  • Trial conversions

Response

Parameters Type/Description

Boolean

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

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReferenceTest = 'YOUR_SUBSCRIPTION_REFERENCE';

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

$updatedSubscription = callRPC((Object)$jsonRpcRequest, $host, true);
var_dump ($updatedSubscription);
$updatedSubscription->RecurringEnabled = false;
$updatedSubscription-> SubscriptionEnabled = true;
$updatedSubscription->ExpirationDate = '2020-12-12';

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

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

 

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