Subscription change deal

Use the changeDeal method to change the existing deal for a given subscription and operate the amendment order necessary to transition to the proposed deal immediately. The amendment order will use the due now prices returned by the getDealInfo method when called with the same relevant request parameters.

Request parameters

Parameter	Type / Description
Currency	Required (string) The currency.
Country	Required (string) The country.
Language	Required (string) The language.
CustomerIp	Optional (string) The customer's IP address.
Items	Required (array) Each item corresponds to a subscription.
Items.DealDate	Required (string) The date when the deal is set to come into effect.
Items.SubscriptionReference	Required (string) The subscription code.
Items.ProductCode	Required (string) The product code.
Items.Quantity	Required (string) The product quantity.
Items.DealPriceScenario	Required (string) The upgrade scenario to be applied. Must be one of: using_last_order_price, using_last_product_price, price_total, product_price_difference.
Items.DealSubscriptionScenario	Required (string) The scenario for price calculation. Must be one of prolong, does_not_affect, disable_existing.
Items.PriceOptions	Optional (array) The array of price options.
Items.PriceOptions.Code	Required (string) The price options group code.
Items.PriceOptions.Options	Required (array) The list of price option value (if the group is of type interval) or the price option code (otherwise).
Items.Price	Required (object) The product price.
Items.Price.Amount	Required (float) The actual numeric amount.
Items.Price.Type	Required (string) Describes if the price type is catalog or custom. Can be only CUSTOM.
Items.Price.AmountType	Required (string) Describes if the price is NET or GROSS. Can be on of NET, GROSS.
Items.SubscriptionCustomSettings	Required (object) Product license custom settings.
Items.SubscriptionCustomSettings.CycleLength	Required (int) The length of a single billing cycle.
Items.SubscriptionCustomSettings.CycleUnit	Required (string) The unit of a single billing cycle. Can be one of MONTH, DAY.
Items.SubscriptionCustomSettings.CycleAmount	Required (float) The price of a single billing cycle.
Items.SubscriptionCustomSettings.CycleAmountType	Required (string) Describes the price type. Can be one of NET, GROSS.
Items.SubscriptionCustomSettings.ContractLength	Required (int) The number of billing cycles contained in a single contract.
Items.SubscriptionCustomSettings.ClientDealAutoRenewal	Optional (boolean) CDAR value (default false).
Items.SubscriptionCustomSettings.MerchantDealAutoRenewal	Optional (boolean) MDAR value (default false).
BillingDetails	Required (object) The billing details.
BillingDetails.FirstName	Required (string) The first name.
BillingDetails.LastName	Required (string) The last name.
BillingDetails.CountryCode	Required (string) The country code. Must be one of the seller's associated country codes.
BillingDetails.State	Optional (string) Required only if the business model requires it.
BillingDetails.City	Required (string) The city name.
BillingDetails.Address1	Required (string) The address.
BillingDetails.Zip	Required (string) The zip code.
BillingDetails.Email	Required (string) The email address.
BillingDetails.Phone	Required (string) The phone number.
BillingDetails.Company	Required (string) The company's legal name.
BillingDetails.FiscalCode	Required (string) The fiscal code.
DeliveryDetails	Required (object) The delivery details.
DeliveryDetails.FirstName	Required (string) The first name.
DeliveryDetails.LastName	Required (string) The last name.
DeliveryDetails.CountryCode	Required (string) The country code. Must be one of the seller's associated country codes.
DeliveryDetails.State	Optional (string) Required only if the business model requires it.
DeliveryDetails.City	Required (string) The city name.
DeliveryDetails.Address1	Required (string) The address.
DeliveryDetails.Zip	Required (string) The zip code.
DeliveryDetails.Email	Required (string) The email address.
DeliveryDetails.Phone	Required (string) The phone number.
DeliveryDetails.Company	Required (string) The company's legal name.
PaymentDetails	Optional (object) The payment details.
PaymentDetails.Type	Required (string) Payment type. Can be CC (credit card) or EES_TOKEN_PAYMENT (2payJs token).
PaymentDetails.Currency	Required (string) Payment currency code.
PaymentDetails. CustomerIP	Required (string) Payment customer IP.
PaymentDetails.PaymentMethod	Required (object) The payment method information.
PaymentDetails.PaymentMethod.EesToken	Optional (string) EES token (required when payment type is EES_TOKEN_PAYMENT).
PaymentDetails.PaymentMethod.CardNumber	Optional (int) CC number (required when payment type is CC).
PaymentDetails.PaymentMethod.CardType	Optional (string) CC type (ex: VISA, MC; required when payment type is CC).
PaymentDetails.PaymentMethod.ExpirationYear	Optional (int) 4 digits CC expiration year (required when payment type is CC).
PaymentDetails.PaymentMethod.ExpirationMonth	Optional (int) CC expiration month (required when payment type is CC).
PaymentDetails.PaymentMethod.CCID	Optional (string) CC CVV value (required when payment type is CC).
PaymentDetails.PaymentMethod.HolderName	Optional (string) CC holder name.
PaymentDetails.PaymentMethod.Vendor3DSReturnURL	Required (string) Merchant 3DS return URL.
PaymentDetails.PaymentMethod.Vendor3DSCancelURL	Required (string) Merchant 3DS cancel URL.
PaymentDetails.PaymentMethod.RecurringEnabled	Optional (boolean) Flag to enable recurring on the new license when set true.
ExtraInformation	Optional (object) Order extra information.
ExtraInformation.ProposalId	Optional (string) Related proposal object ID.
ExtraInformation.PurchaseOrderDownloadLink	Optional (string) PO Download link.
ExtraInformation.AMEmailB2B	Optional (string) AM email for B2B.
ExtraInformation.RetryFailedPaymentLink	Optional (string) Retry failed payment link.

Request sample

<?php
declare(strict_types=1);
class Configuration
{
    public const MERCHANT_CODE = '1234554321';
    public const MERCHANT_KEY = 'D+~=z5R+R4])4D5&p56%';
    public const URL = 'http://api.avangate.local/rpc/6.0';
    public const ACTION = 'getDealInfo';
    //array or JSON
    public const PAYLOAD = <<<JSON
{
    "Currency": "usd",
    "Country": "us",
    "Language": "en",
    "CustomerIp": "91.220.121.21",
    "Source": "salesforce_cpq",
    "Items": [\
        {\
            "DealDate": "2021-03-18 13:36:47",\
            "SubscriptionReference": "GUC9PFSIH8",\
            "ProductCode": "PAV2019",\
            "Quantity": 1,\
            "DealPriceScenario": "using_last_order_price",\
            "DealSubscriptionScenario": "prolong",\
            "Price": {\
                "Amount": 50,\
                "Type": "CUSTOM",\
                "AmountType": "GROSS"\
            },\
            "PriceOptions": [\
                {\
                    "Code": "interval_scale_grp1",\
                    "Options": [\
                        "25"\
                    ]\
                },\
                {\
                    "Code": "OPTGRP1",\
                    "Options": [\
                        "OptGrp1Code1"\
                    ]\
                }\
            ],\
            "SubscriptionCustomSettings": {\
                "CycleLength": 1,\
                "CycleUnit": "MONTH",\
                "CycleAmount": 50,\
                "CycleAmountType": "GROSS",\
                "ContractLength": 12,\
                "ClientDealAutoRenewal": true,\
                "MerchantDealAutoRenewal": true\
            }\
        }\
    ],
    "BillingDetails": {
        "FirstName": "Donald",
        "LastName": "Wilson",
        "CountryCode": "us",
        "State": "Texas",
        "City": "Dallas",
        "Address1": "4519 BlueBridge Road",
        "Zip": "02199",
        "Email": "[email protected]",
        "Phone": "6172938133",
        "Company": "Integra Wealth",
        "FiscalCode": "85421564"
    },
    "DeliveryDetails": {
        "FirstName": "Gerard",
        "LastName": "Butler",
        "CountryCode": "us",
        "State": "Texas",
        "City": "Austin",
        "Address1": "2033 Nuzum Court",
        "Zip": "14216",
        "Email": "[email protected]",
        "Phone": "7165708136",
        "Company": "Integra Wealth"
    },
    "PaymentDetails": {
        "Type": "EES_TOKEN_PAYMENT",
        "Currency": "usd",
        "CustomerIP": "91.220.121.21",
        "PaymentMethod": {
            "EesToken": "7886eebb-0aa0-482c-8636-28394e2b714d",
            "RecurringEnabled": true
        }
    },

    "ExtraInformation": {
       "ProposalId": "1de36a0a-a7b6-4cb7-9de5-34c802e4243b",
       "PurchaseOrderDownloadLink": "http://secure.avangate.local/proposal/po/342322/dl",
       "AMEmailB2B": "[email protected]",
       "RetryFailedPaymentLink": "http://secure.avangate.local/proposal/po/342322/retry?ref=[REFNO]"
    }
}
JSON;
}
class Client
{
    private const LOGIN_METHOD = 'login';
    private $calls = 1;
    private $sessionId;
    private function generateAuth(): array
    {
        $merchantCode = Configuration::MERCHANT_CODE;
        $key = Configuration::MERCHANT_KEY;
        $date = gmdate('Y-m-d H:i:s');
        $string = strlen($merchantCode) . $merchantCode . strlen($date) . $date;
        $hash = hash_hmac('md5', $string, $key);
        return compact('merchantCode', 'date', 'hash');
    }
    public function login(string $url)
    {
        $payload = $this->generateAuth();
        $response = $this->call($url, array_values($payload), self::LOGIN_METHOD);
        $this->sessionId = $response['result'];
    }
    public function call(
        string $url = Configuration::URL,
        $payload = Configuration::PAYLOAD,
        string $action = Configuration::ACTION
    ): ?array {
        if (empty($this->sessionId) && $action !== self::LOGIN_METHOD) {
            $this->login($url);
        }
        if(is_string($payload)) {
            $payload = json_decode($payload, true);
        }
        if (!empty($this->sessionId)) {
            $payload = [$this->sessionId, $payload];
        }
        $payload = array_filter($payload);
        $request = json_encode([\
            'jsonrpc' => '2.0',\
            'method' => $action,\
            'params' => $payload,\
            'id' => $this->calls++,\
        ]);
        $curl = curl_init($url);
        curl_setopt($curl, CURLOPT_POST, 1);
        curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
        curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
        curl_setopt($curl, CURLOPT_SSLVERSION, 0);
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Accept: application/json', 'Cookie: XDEBUG_SESSION=PHPSTORM'));
        curl_setopt($curl, CURLOPT_POSTFIELDS, $request);
        $response = curl_exec($curl);
        if(empty($response)) {
            die('Server unavailable');
        }
        echo $response . '</br>';
        return json_decode($response, true);;
    }
}
$client = new Client();
$result = $client->call();
var_dump($result);

Response

The changeDeal method has (almost) the same response parameters as the getDealInfo method, plus the deal order details returned under the DealOrder key. These order details have the same structure as any placeOrder API method response (see here).

[\
    {\
        "SubscriptionReference": "GUC9PFSIH8",\
        "DealPriceScenario": "using_last_order_price",\
        "DealSubscriptionScenario": "prolong",\
        "DealDate": "2021-03-18 13:36:47",\
        "DealDueNowPriceNet": 47.06,\
        "DealDueNowPriceGross": 50,\
        "DealTaxAmount": 2.94,\
        "DealTaxPercent": 6.25,\
        "CurrentInfo": {\
            "ProductCode": "BKG20193",\
            "ProductName": "Backgammon 2019.3",\
            "ProductDescription": "",\
            "BillingPriceNet": 45,\
            "UnitBillingPriceNet": 45,\
            "BillingPriceGross": 47.81,\
            "UnitBillingPriceGross": 47.81,\
            "NoOfBillingCycles": 13,\
            "CurrentBillingCycle": 1,\
            "PayedBillingCycles": 1,\
            "RemainingBillingCycles": 11,\
            "CurrentBillingCycleEndDate": "2021-03-15 11:35:02",\
            "ClientDealAutoRenewal": false,\
            "MerchantDealAutoRenewal": false,\
            "Quantity": 1,\
            "CurrencyCode": "usd",\
            "TaxAmount": 2.81,\
            "TaxPercent": 6.25,\
            "BillingCyclesFrequency": 1,\
            "BillingCycleFrequencyUnit": "MONTH",\
            "ContractLength": 12,\
            "ContractLengthUnit": "MONTH",\
            "ProductOptions": []\
        },\
        "NewDealInfo": {\
            "ProductCode": "PAV2019",\
            "ProductName": "Pipera AntiVirus 2019",\
            "ProductDescription": "",\
            "BillingPriceNet": 47.06,\
            "BillingPriceGross": 50,\
            "NoOfBillingCycles": 12,\
            "CurrentBillingCycle": 1,\
            "PayedBillingCycles": 0,\
            "RemainingBillingCycles": 12,\
            "CurrentBillingCycleEndDate": "2021-04-18 13:36:47",\
            "TaxAmount": 2.94,\
            "TaxPercent": 6.25,\
            "CurrencyCode": "usd",\
            "BillingCyclesFrequency": 1,\
            "BillingCycleFrequencyUnit": "MONTH",\
            "ContractLength": 12,\
            "ContractLengthUnit": "MONTH",\
            "ProductOptions": [\
                {\
                    "Code": "interval_scale_grp1",\
                    "Options": [\
                        "25"\
                    ]\
                },\
                {\
                    "Code": "OPTGRP1",\
                    "Options": [\
                        "OptGrp1Code1"\
                    ]\
                }\
            ]\
        },\
        "TotalsDealInfo": {\
            "DealsNumber": 0,\
            "ContractsNumber": 1,\
            "PaidBillingCycles": 1,\
            "ElapsedBillingCycles": 1\
        },\
        "DealOrder": {\
            "RefNo": "11591805",\
            "OrderNo": 0,\
            "ExternalReference": null,\
            "ShopperRefNo": null,\
            "Status": "AUTHRECEIVED",\
            "ApproveStatus": "WAITING",\
            "VendorApproveStatus": "OK",\
            "MerchantCode": "120000589445",\
            "Language": "en",\
            "OrderDate": "2021-02-15 13:39:29",\
            "FinishDate": null,\
            "Source": null,\
            "Affiliate": {\
                "AffiliateCode": null,\
                "AffiliateSource": null,\
                "AffiliateName": null,\
                "AffiliateUrl": null\
            },\
            "HasShipping": true,\
            "BillingDetails": {\
                "FiscalCode": "85421564",\
                "TaxOffice": null,\
                "Phone": "6172938133",\
                "FirstName": "Donald",\
                "LastName": "Wilson",\
                "Company": "Integra Wealth",\
                "Email": "[email protected]",\
                "Address1": "4519 BlueBridge Road",\
                "Address2": null,\
                "City": "Dallas",\
                "Zip": "02199",\
                "CountryCode": "us",\
                "State": "Texas"\
            },\
            "DeliveryDetails": {\
                "Phone": "7165708136",\
                "FirstName": "Gerard",\
                "LastName": "Butler",\
                "Company": "Integra Wealth",\
                "Email": "[email protected]",\
                "Address1": "2033 Nuzum Court",\
                "Address2": null,\
                "City": "Austin",\
                "Zip": "14216",\
                "CountryCode": "us",\
                "State": "Texas"\
            },\
            "PaymentDetails": {\
                "Type": "CC",\
                "Currency": "usd",\
                "PaymentMethod": {\
                    "FirstDigits": "4111",\
                    "LastDigits": "1111",\
                    "CardType": "visa",\
                    "RecurringEnabled": true,\
                    "Vendor3DSReturnURL": null,\
                    "Vendor3DSCancelURL": null,\
                    "InstallmentsNumber": null\
                },\
                "CustomerIP": "91.220.121.21"\
            },\
            "DeliveryInformation": {\
                "ShippingMethod": {\
                    "Code": null,\
                    "TrackingUrl": null,\
                    "TrackingNumber": null,\
                    "Comment": null\
                }\
            },\
            "CustomerDetails": null,\
            "Origin": "API",\
            "AvangateCommission": 4.4,\
            "OrderFlow": "REGULAR",\
            "GiftDetails": null,\
            "PODetails": null,\
            "ExtraInformation": {\
                "RetryFailedPaymentLink": "http:\/\/secure.avangate.local\/proposal\/po\/342322\/retry?ref=11591805",\
                "ProposalId": "1de36a0a-a7b6-4cb7-9de5-34c802e4243b",\
                "PurchaseOrderDownloadLink": "http:\/\/secure.avangate.local\/proposal\/po\/342322\/dl",\
                "B2B": true,\
                "AMEmailB2B": "[email protected]"\
            },\
            "PartnerCode": null,\
            "PartnerMargin": null,\
            "PartnerMarginPercent": null,\
            "ExtraMargin": null,\
            "ExtraMarginPercent": null,\
            "ExtraDiscount": null,\
            "ExtraDiscountPercent": null,\
            "LocalTime": null,\
            "TestOrder": false,\
            "FxRate": 0.76357124584292,\
            "FxMarkup": 10.456,\
            "PayoutCurrency": "EUR",\
            "DeliveryFinalized": false,\
            "Errors": null,\
            "Items": [\
                {\
                    "ProductDetails": {\
                        "Name": "Pipera AntiVirus 2019",\
                        "ShortDescription": "",\
                        "Tangible": false,\
                        "IsDynamic": false,\
                        "ExtraInfo": null,\
                        "RenewalStatus": false,\
                        "Subscriptions": null,\
                        "DeliveryInformation": {\
                            "Delivery": "NO_DELIVERY",\
                            "DownloadFile": null,\
                            "DeliveryDescription": "",\
                            "CodesDescription": "",\
                            "Codes": []\
                        }\
                    },\
                    "PriceOptions": [\
                        {\
                            "Code": "OPTGRP1",\
                            "Name": "OptGrp1",\
                            "Required": false,\
                            "Options": [\
                                {\
                                    "Name": "2 users",\
                                    "Value": "OptGrp1Code1",\
                                    "Surcharge": "5.00"\
                                }\
                            ]\
                        },\
                        {\
                            "Code": "interval_scale_grp1",\
                            "Name": "Interval scale group1",\
                            "Required": false,\
                            "Options": [\
                                {\
                                    "Name": "Interval scale group1: 25",\
                                    "Value": "interval_scale_grp1=25",\
                                    "Surcharge": "125.00"\
                                }\
                            ]\
                        }\
                    ],\
                    "Price": {\
                        "UnitNetPrice": 47.06,\
                        "UnitGrossPrice": 50,\
                        "UnitVAT": 2.94,\
                        "UnitDiscount": 0,\
                        "UnitNetDiscountedPrice": 47.06,\
                        "UnitGrossDiscountedPrice": 50,\
                        "UnitAffiliateCommission": 0,\
                        "ItemUnitNetPrice": null,\
                        "ItemUnitGrossPrice": null,\
                        "ItemNetPrice": null,\
                        "ItemGrossPrice": null,\
                        "VATPercent": 6.25,\
                        "HandlingFeeNetPrice": 0,\
                        "HandlingFeeGrossPrice": 0,\
                        "Currency": "usd",\
                        "NetPrice": 47.06,\
                        "GrossPrice": 50,\
                        "NetDiscountedPrice": 47.06,\
                        "GrossDiscountedPrice": 50,\
                        "Discount": 0,\
                        "VAT": 2.94,\
                        "AffiliateCommission": 0\
                    },\
                    "LineItemReference": "f703af791bca619bbd42cc6964192456dc243f27",\
                    "PurchaseType": "PRODUCT",\
                    "Code": "PAV2019",\
                    "ExternalReference": "PAV2019QWE",\
                    "Quantity": 1,\
                    "SKU": null,\
                    "CrossSell": null,\
                    "Trial": null,\
                    "AdditionalFields": null,\
                    "Promotion": null,\
                    "RecurringOptions": null,\
                    "SubscriptionStartDate": null,\
                    "SubscriptionCustomSettings": {\
                        "CycleUnit": "MONTH",\
                        "CycleLength": 1,\
                        "CycleAmount": 50,\
                        "CycleAmountType": "GROSS",\
                        "ContractLength": 12,\
                        "MerchantDealAutoRenewal": true,\
                        "ClientDealAutoRenewal": true\
                    }\
                }\
            ],\
            "Promotions": [],\
            "AdditionalFields": null,\
            "CustomParameters": null,\
            "Currency": "usd",\
            "NetPrice": 47.06,\
            "GrossPrice": 50,\
            "NetDiscountedPrice": 47.06,\
            "GrossDiscountedPrice": 50,\
            "Discount": 0,\
            "VAT": 2.94,\
            "AffiliateCommission": 0\
        }\
    }\
]

Error handling

Whenever there is a validation error, an error response is returned, for example:

{
    "error_code": "INVALID_EES_TOKEN",
    "message": "The token is not valid. In order to proceed with the place order a valid token is required"
}

In this case, the deal order is not created, and you must correct the request parameters and retry the API call.

Most of the validation errors are common with the ones listed for the getDealInfo method (see the Errors handling).

Whenever there is a payment level error encountered, the amendment order is still created, and the payment processing error will be returned in the DealOrder.Errors element, in the usual format used by the placeOrder response. Example:

[\
    {\
        "SubscriptionReference": "GUC9PFSIH8",\
        ……\
        "DealOrder": {\
            "RefNo": "11662596",\
            ……\
            "Errors": {\
                  "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."\
            }\
        }\
    }\
]

You can check the list of possible order-level errors on this page.