| Verifone Developer Portal

Overview

Use this object to create new orders and collect payments from shoppers.

Supported payment methods

Credit/Debit cards: Visa, Visa electron, MasterCard, Maestro, Amex, Discover, Dankort, Carte Bleue, JCB. 2Checkout supports local Brazilian cards.
PayPal and PayPal Express
Purchase Order
Wire
Check
Previous order references - In addition to the payment methods enumerated above, 2Checkout also supports1-click purchase flows in which you use valid previous order references belonging to returning customers to pay for new orders with their previously used cards and PayPal accounts.

Currency support

You can find more details about the currencies available for each payment method here and here.

Parameters

Order object parameters									Type/Description
RefNo									Optional (string)
									Unique, system-generated, order reference number. Do not include it when placing new orders or send it as NULL.
Currency									Required (string)
									The currency ISO code for the payment - ISO 4217. Example: “usd.”
Country									Required (string)
									Shopper country. ISO 3166 two-letter code. Example: “us.”
Language									Optional (string)
									ISO 639-1 two-letter code. Language used for the purchase process. Example: “en.”
ExternalReference									Optional (string)
									Set external reference identifiers for orders. Enables you to replicate the functionality of the REF parameter included in 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.
Source									Optional (string)
									The link source for the sales. Enables you to replicate the functionality of the SRC (separate link identifier) parameter when included into Buy Links. Use the SRC parameter to track sale sources. Maximum length 255 characters.
AffiliateId									Optional (int)
									Identifier belonging to affiliates who refer orders.
CustomerReference									Optional (Int)
									System-generated 2Checkout customer reference. Aggregate subscriptions under the same Customer account 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.
Items									Required (array of objects)
									Details below.
	OrderItem								Object
									Details below.
			Code						Required (string)
									Unique product identifier your control. Max length 256 characters.
			Quantity						Required (integer)
									Number of units
			PriceOptions						Optional (array of strings)
									Array of price option codes.
			SKU						Optional (string)
									SKU identifier.
			Price						Object - Can be NULL
							OrderPrice		Object - Can be NULL
								Currency	Optional (string)
									The currency ISO code for the payment - ISO 4217. Example: usd.
								NetPrice	Optional (double)
									Order value excluding sales tax/VAT expressed in the payment currency.
								GrossPrice	Optional (double)
									Total order value, including sales tax/VAT expressed in the payment currency. GrossPrice does not reflect any discounts.
								NetDiscountedPrice	Optional (double)
									The NetPrice order value excluding sales tax/VAT, from which 2Checkout deducts discounts. NetDiscountedPrice is expressed in the payment currency.
								GrossDiscountedPrice	Optional (double)
									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	Optional (double)
									Value of the discounts for an order expressed in the payment currency.
								VAT	Optional (double)
									Value of sales tax/VAT expressed in the payment currency.
								AffiliateCommission	Optional (double)
									Value of the affiliate commission for the order calculated from the NetDiscountedPrice expressed in the payment currency. Or NULL. 2Checkout does not take into account shipping costs when calculating affiliate commissions.
							UnitNetPrice		Optional (double)
									The value per product unit, excluding sales tax/VAT expressed in the payment currency.
							UnitGrossPrice		Optional (double)
									Total value per product unit, including sales tax/VAT expressed in the payment currency. UnitGrossPrice does not reflect any discounts.
							UnitVAT		Optional (double)
									Sales tax/VAT per product unit expressed in the payment currency.
							UnitDiscount		Optional (double)
									Value of the discount per product unit expressed in the payment currency.
							UnitNetDiscountedPrice		Optional (double)
									The value per product unit, expressed in the payment currency, excluding sales tax/VAT, from which 2Checkout deducts the unit discount.
							UnitGrossDiscountedPrice		Optional (double)
									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		Optional (double)
									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 into account shipping costs when calculating affiliate commissions. NULL when 2Checkout does not apply an affiliate commission.
			CrossSell						Object – Can be NULL
									Details below.
					ParentCode				Optional (string)
									The product code of the master product you set to trigger the campaign.
					CampaignCode				Optional (string)
									Unique, system-generated identifier for cross-sell campaigns.
			Trial						Optional (Object) – Can be NULL
									Details below.
					Period				Optional (integer)
									The length of the trial subscription lifetime in days.
					Price				Optional (double)
									Total trial price in the payment currency before 2Checkout deducts any taxes, discounts, etc.
			AdditionalFields						Optional (array of objects) – Can be NULL
					AdditionalFieldSet				Optional (Object) – Can be NULL
							Code		Optional (string)
									The alpha-numeric characters, underscores and dashes that are set as the field identifier.
							Value		Optional (string)
									Selected field value.
			SubscriptionStartDate						Optional (string)
									Specify the date time stamp when the subscription becomes active. Format 2016-07-02 22:22:22 (YYYY-MM-DD HH:mm:ss). Available for JSON-RPC and REST. Send empty or NULL to activate subscriptions on the same date when customers purchase them. You can exclude HH:mm:ss when sending the date and include only YYYY-MM-DD. In this case, 2Checkout uses 00:00:01. Default time zone GMT+02:00.
			Promotion						Optional (Object)
									Details below.
					Name				Optional (string)
									Promotion name.
					Description				Optional (string)
									Promotion description.
					StartDate				Optional (string)
									The date when you set the promotion to start. NULL for promotions that start immediately after you create them.
					EndDate				Optional (string)
									The date when you set the promotion to end. NULL for promotions you want active indefinitely.
					MaximumOrdersNumber				Optional (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				Optional (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				Optional (boolean)
									The instant discount option auto-applies the discount for ALL selected products, without the need for shoppers to enter a discount coupon.
					Coupon				Optional (string)
									Promotion coupon/voucher.
					DiscountLabel				Optional (string)
									Discounts can be set as a percentage from the product price or as a fixed amount in the chosen currency.
					Enabled				Optional (string)
									true or false, depending on whether a promotion is active or disabled.
					Type				Optional (string)
									REGULAR – product/cart line level discounts. ORDER – quantity discounts. GLOBAL – order-level discounts.
BillingDetails									Required (Object)
									Details below.
	Person								Object
										Details below.
		FirstName								Required (string)
										Shopper name.
		LastName								Required (string)
										Shopper surname.
		CountryCode								Required (string)
										Shopper country. ISO 3166 two-letter code.
		State								Required (string) for US, Brazil and Romania
										The state in the shopper's country. 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								Required (string)
										Shopper city.
		Address1								Required (string)
										Shopper address.
		Address2								Optional (string)
										Shopper address.
		Zip								Required (string) for US, Brazil and Romania
										ZIP/ Postal code.
		Email								Required (string)
										Shopper email address.
		Phone								Optional (string)
										Shopper phone number. Mandatory when you set Brazil as the Billing Country. Can be NULL.
		Company								Optional (string)
										Company name. Can be null for end users. When present, you also need to provide the FiscalCode.
	FiscalCode									Optional (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 you set Brazil as the Billing Country. For Brazilian customers it represents the Fiscal Code (CPF/CNPJ). • Can be NULL for end users.
DeliveryDetails										Required (Object)
										Details below.
	Person									Object
										Details below.
		FirstName								Required (string)
										Shopper name from the delivery details.
		LastName								Required (string)
										Shopper surname from the delivery details.
		CountryCode								Optional (string)
										Shopper country. ISO 3166 two-letter code from the delivery details.
		State								Optional (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								Optional (string)
										Shopper city from the delivery details.
		Address1								Optional (string)
										Shopper address from the delivery details.
		Address2								Optional (string)
										Shopper address from the delivery details.
		Zip								Optional (string)
										ZIP/ Postal code from the delivery details.
		Email								Optional (string)
										Shopper email address from the delivery details.
		Phone								Optional (string)
										Shopper phone number from the delivery details. Mandatory when you set Brazil as the Billing Country. Can be NULL.
		Company								Optional (string)
										Company name from the delivery details. Can be null for end users. When present, you also need to provide the FiscalCode.
PaymentDetails									Required (Object)
									Adapt this object to the desired payment method.
	Type								Required (string)
									The payment method: CC (credit/debit card - including local Brazilian cards). ENCRYPTED_PAYMENT_DATA (client-side encryption) PAYPAL PAYPAL_EXPRESS 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.
	Currency								Required (string)
									The currency ISO code for the payment - ISO 4217. Example: “usd.”
	PaymentMethod								Required (string)
									Object structure and parameters differ according to the payment method selected and API method (placing orders (POST) vs. retrieving order data (GET)). NULL for 0 value orders for which you’re not requiring customers to enter payment details.
	RecurringEnabled								Optional (boolean)
									true – shopper checks the auto-renewal checkbox and 2Checkout charges subscription renewals using a recurring billing process. false – shopper doesn’t check the auto-renewal checkbox.
				CardPayment					Optional (object)
									Details below.
						CardNumber			Optional (string)
									The credit/debit card number.
						CardType			Optional (string)
									visa, visaelectron, mastercard, maestro, amex, discover, dankort, cartebleue, jcb, hipercard, elo
						ExpirationYear			Optional (string)
									The year in which the card expires.
						ExpirationMonth			Optional (string)
									The month in which the card expires.
						HolderName			Optional (string)
									Card holder name.
						CCID			Optional (string)
									Credit Card Identification - an extra ID printed on the card, usually a 3-4 digit number, the CVC2/CVV2.
						HolderNameTime			Optional (float)
									The interval of time in seconds in which shoppers enter their name in the HolderName field. An abnormally short interval is usually a red flag for fraud attempts. Can be NULL, but not a negative number.
						CardNumberTime			Optional (float)
									The interval of time in seconds in which shopper enters their card number in the CardNumber field. An abnormally short interval is usually a red flag for fraud attempts. Can be NULL, but not a negative number.
						InstallmentsNumber			Optional (Int)
									Number of installments. Available only when customers un Brazil pay with Visa or MasterCard using Brazilian Real as the order currency. Use 1 or exclude the parameter for full payments.
				PayPalExpress					Optional (object)
									Details below.
						Email			Optional (string)
									Email address customers use for their PayPal account.
						ReturnURL			Optional (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 in to PayPal and approves the payment. Typically, this is a secure page (https://...) on your site.
						CancelURL			Optional (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.
				PreviousOrder					Optional (Object)
									Details below.
						RefNo			Optional (string)
									Order reference a previous purchase that reached the Approved/Complete status. You can use order for which customers paid with credit/debit cards or with PayPal. The status of the order should be AUTHRECEIVED or COMPLETE. Check the validity of references with the isValidOrderReference method. The 2Checkout system blocks you from using references for fraudulent or potentially fraudulent orders.
				PurchaseOrderPaymentDetails					Optional (Object)
									Details below.
						InternalPONumber			Optional (string)
									Identifier that business customers use internally in their organization to track and manage Purchase Orders (PO). Can be NULL.
						AutoApprove			Optional (boolean)
									TRUE - requires activation of the PO AutoApprove package (If the package is inactive 2Checkout returns an error). Please contact 2Checkout. When AutoApprove is TRUE, 2Checkout no longer requires that business customers upload a PO document. As such, PO orders are automatically approved for your account, without a PO doc. 2Checkout sets the PURCHASE_PENDING status for auto-approved PO orders. FALSE - Default. Send this if the PO AutoApprove package is not available for your account. 2Checkout uses the same flow as cart purchases with Purchase Orders for business customers placing orders with POs via API. This means that customers receive the same emails as if they made the purchase using the cart and need to update the PO document, which is reviewed by 2Checkout and that you need to approve. 2Checkout sets the AVAITING_UPLOAD status for POs andUnfinished for their orders. Can be NULL.
				EXISTING_PAYMENT_DATA					Optional (Object)
									By using EXISTING_PAYMENT_DAT you no longer require shoppers to enter any payment details.
						TransientToken			Optional (string)
									Returned as a part of the process of retrieving customer information by SSOToken.
	CustomerIP								Required (string)
									Shopper IP.
Promotions									Optional (Array of strings)
									Array of promotion codes.
AdditionalFields
									Details below.
	Code								Optional (string)
									The alpha-numeric characters, underscores and dashes that are set as the field identifier.
	Text								Optional (string)
									Field text visible to shoppers in the cart.
	Value								Optional (string)
									Selected field value.
LocalTime									Optional (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.
GiftDetails									Optional (object)
									Contains contact details for the recipient of gift purchase.
	FirstName								Optional (string)
									First name of gift recipient.
	LastName								Optional (string)
									Last name of gift recipient.
	Email								Optional (string)
									Email of gift recipient. 2Checkout uses this email for the delivery/fulfillment process.
	GiftNote								Optional (string)
									Custom text shoppers provide as a message to the gift recipient.

Overview

Charge customers custom prices for the renewal of subscriptions, moving away from the recurring pricing configuration at product level. Use the setCustomRenewalPrice method to set custom renewal prices for subscriptions and control the number of recurring billing cycles the price impact subscribers.

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.
Price	Required (double)
	The custom renewal price you want to charge.
Currency	Required (string)
	Currency in which prices are expressed. The currency ISO code used for the payment is ISO 4217. The default currency is the same as in the previous payment made by the customer.
Cycles	Required (int)
	Number of recurring billing cycles for which 2Checkout charges customers the custom price rather, ignoring product–level recurring pricing configurations. (Can be null - Default value 1).
ReasonText	Optional (string)
	Save details at the subscription-level about the custom costs.

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_REFERENCE';
$Price = 25;
$Currency = 'gbp';
$Cycles = 7;
$ReasonText = null;


try {
    $CustomPrice = $client->setCustomRenewalPrice($sessionID, $subscriptionReference, $Price, $Currency, $Cycles, $ReasonText);
}
catch (SoapFault $e) {
    echo "CustomPrice: " . $e->getMessage();
    exit;
}
var_dump("CustomPrice", $CustomPrice);

Response

Parameters	Type/Description
Boolean	true or false depending on whether or not the operation succeeded.

Set cross-selling settings

Overview

Use the setCrossSellSettings method to customize the way your cross-sell campaigns are displayed in the shopping cart.

Request parameters

Parameters	Type	Required	Description
displayShortDescription	Boolean	Optional	Determines if the product short description is displayed next to the thumbnail or not.
displayProductsMax	Int	Optional	The maximum number of recommended products; We recommend adding a maximum of 3 products as cross-selling options.
maxThumbSize	Int	Optional	Maximum product thumbnail size. Must be any of [60, 80, 100, 150].

Response

The response of the setCrossSellSettings method is the input object with the settings updated.

Request sample

<?php 

require ('PATH_TO_AUTH'); 

$jsonRpcRequest = array( 

    'jsonrpc' => '2.0', 
    'method' => 'setCrossSellSettings', 
    'params' => [ 
        $sessionID, 
        [ 
            'displayProductsMax' => 10, 
            'maxThumbSize' => 100, 
            'displayShortDescription' => false, 
        ] 
    ], 
    'id' => $i++ 
); 

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

Retrieve price option groups

Overview

Use the searchPriceOptionGroups to extract information on the price option groups you configured.

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.
PriceOptionGroupSearch	Optional (object)
	Details below.

PriceOptionGroupSearch	Object
Name	Optional (string)
	The name of the pricing options groups configured in the Avangate system. Can be NULL.
Types	Optional (array)
	Possible values: · RADIO · CHECKBOX · INTERVAL · COMBO Can be NULL.
Limit	Optional (int)
	Number of results displayed per page. Default maximum value is 10. Can be NULL.
Page	Optional (int)
	A specific page of search results. Default value is 1. Can be NULL.

Response

PriceOptionGroup

Array of objects

Request

<?php

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


function hmac($key, $data)
{
    $b = 64; // byte length for md5
    if (strlen($key) > $b) {
        $key = pack("H*", md5($key));
    }
    
    $key    = str_pad($key, $b, chr(0x00));
    $ipad   = str_pad('', $b, chr(0x36));
    $opad   = str_pad('', $b, chr(0x5c));
    $k_ipad = $key ^ $ipad;
    $k_opad = $key ^ $opad;
    return md5($k_opad . pack("H*", md5($k_ipad . $data)));
}

$merchantCode = "YOURCODE123"; //your account's merchant code available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$key          = "SECRET_KEY"; //your account's secret key available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$now          = gmdate('Y-m-d H:i:s'); //date_default_timezone_set('UTC')

$string = strlen($merchantCode) . $merchantCode . strlen($now) . $now;
$hash   = hmac($key, $string);

try {
    $sessionID = $client->login($merchantCode, $now, $hash);
}

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

$SearchOptions       = new stdClass();
$SearchOptions->Name = 'New Users from API';

$SearchOptions->Types = array(
    'INTERVAL',
    'RADIO',
    'COMBO',
    'CHECKBOX'
); //RADIO, CHECKBOX, INTERVAL, COMBO, INTERVAL

$SearchOptions->Limit = 10;
$SearchOptions->Page  = 1;

try {
    $existentPriceOptions = $client->searchPriceOptionGroups($sessionID, $SearchOptions);
}

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

var_dump("existentPriceOptionst", $existentPriceOptions);

?>

Override configured product prices

Overview

On the fly pricing allows you to quickly set up special or limited time sales links.

Availability

All 2Checkout accounts that use catalog products in the default ordering flows, ConvertPlus, and Inline Checkout.

Default Ordering Flow

Requirements for default ordering flows

Set up prices on-the-fly to override the prices you already configured in the 2Checkout Control Panel by sending additional parameters in the HTTPS GET request.

When you use the PRICES (PRICES[Product ID][Currency]) query parameter in checkout links, you need to accompany it with the PHASH parameter. This serves to block any tampering with the costs displayed as query parameters.

Checkout parameter guidance is available here enabling you to generate on-the-fly-price links dynamically in your own website / application.

Configure on-the-fly-pricing for default ordering flows

In the Generate Sales Links area, select a purchase flow and a product.
Under Main settings check the On the fly pricing option.
Define the price per total quantity in each currency available for your account. Set up only the default currency and let 2Checkout convert that value in any currency shoppers select while purchasing. The price displayed in the shopping cart is Gross or Net, depending on the default price settings for each product. If you want the final price in this sales link to be the full price customers pay (including tax if applicable), set the product price type to gross in the product details page.
Enter price option IDs in the Additional pricing options area to offer a specific configuration of your product to shoppers. While they won't impact the initial purchase, 2Checkout uses price options to calculate renewal charges per your product's configuration.
Control who purchases special offers by setting an expiration deadline for the link or by inserting a unique link identifier to limit usage to the first IP from which a shopper accesses it.

ConvertPlus Ordering Flow

Requirements for convertplus ordering flow

The on-the-fly pricing feature is available for ConvertPlus only via custom buy-links.

When you use the prod, price (value and currency), qty, opt, and coupon parameters in the custom ConvertPlus buy-link, you need to include them in the Buy-Links Signature. This serves to block any tampering with the costs displayed as query parameters. The coupon field will still be available in the shopping cart if active promotions are defined at product level. In order to fully lock the product details, you must also add the lock parameter to the custom buy-link.

ConvertPlus parameter guidance is available here enabling you to generate on-the-fly-price links dynamically on your own website/application.

You need to define prices in the default cart currency for all products included in the buy-link. Otherwise, the products will be invalidated and will not be added to the cart.

In case you define custom prices for multiple other currencies, in addition to the default currency, you need to set them for all products included in the buy-link. The cart will check that there are available custom prices for the currency selected by the shopper and will display them. Otherwise, the cart will convert the custom prices defined for all products in the default currency.

Renew a subscription

Overview

Renew a subscription in the 2Checkout system on-demand, controlling the number of days, price, and currency of the extension. Use the renewSubscription method to renew 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. 2Checkout charges customers using the payment data attached to subscriptions. In the case of credit/debit cards, if customers update their payment information in myAccount or if you update these details on behalf of your subscribers, the 2Checkout system uses the latest card info provided to charge subscription renewals.
days	Required (int)
	The number of days the 2Checkout system extends the lifetime of the subscription.
price	Required (double)
	The price that 2Checkout charges the customer for the renewal. The type of price, Gross or Net, is decided by the product setting in the Merchant Control Panel.
currency	Required (string)
	The currency associated to the renewal price - ISO 4217 code.

Response

Parameters	Type/Description
Boolean	true or false depending on whether or not the operation succeeded.

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = '30E47F8699';
$Days = 4;
$Price = 50;
$Currency = 'eur';

try {
    $CustomPrice = $client->renewSubscription($sessionID, $subscriptionReference, $Days, $Price, $Currency);
}
catch (SoapFault $e) {
    echo "CustomPrice: " . $e->getMessage();
    exit;
}
var_dump("CustomPrice", $CustomPrice);

Subscription

Overview

Retrieve information and manage subscriptions for your account. Subscriptions can be retrieved starting with 5 minutes after their orders are generated in the 2Checkout system.

Parameters				Type/Description
SubscriptionReference				String
				Unique, system-generated subscription identifier.
StartDate				String
				Subscription start date(YYYY-MM-DD) - StartDate is mandatory when importing subscription data. If you changed the time zone for the Avangate API by editing system settings under Account settings, then the StartDate you provide must be in accordance with your custom configuration.
ExpirationDate				String
				Subscription expiration date(YYYY-MM-DD) - ExpirationDate is mandatory when importing subscription data. If you changed the time zone for the Avangate API by editing system settings under Account settings, then the ExpirationDate you provide must be in accordance with your custom configuration.
RecurringEnabled				Boolean
				Possible values: TRUE – recurring billing/automatic subscription renewals enabled FALSE– recurring billing/automatic subscription renewals disabled
SubscriptionEnabled				Boolean Possible values: TRUE –subscription enabled FALSE–subscription disabled
Product				Required (object)
				The product for which Avangate generated the subscription. Details below.
	ProductCode			String
				Unique product identifier that you control.
	ProductId			Int
				Unique, system-generated product identifier.
	ProductName			String
				Product name.
	ProductQuantity			Int
				Ordered number of units.
	ProductVersion			String
				Product version.
	PriceOptionCodes			Array
				The product options codes the customer selected when acquiring the subscription. Pricing options codes are case sensitive.
EndUser				Object
				The end user of the subscription. Details below.
	Person			Object
		FirstName		String
				End user's first name
		LastName		String
				End user's last name
		CountryCode		String
				End user country code [ISO3166-1 Alpha 2].
		State		String
				End user state.
		City		String
				End user city.
		Address1		String
				End user first address line.
		Address2		String
				End user second address line.
		Zip		String
				End user zip code.
		Email		String
				End user email address.
		Phone		String
				End user phone number.
		Company		String
				Company name.
	Fax			String
				End user fax.
	Language			String
				Language [ISO639-2] the Avangate system uses for communications.
SKU				String
				Stock keeping unit you defined.
DeliveryInfo				Object
				The object contains information about the delivery/fulfillment made to the customer.
	Description			String
				Delivery description.
	Codes			Array of objects
		Code		String
				Activation key/license code of the first order from this subscription. Use getSubscriptionHistory method if you want to retrieve the activation keys/license codes for all orders belonging to a subscription.
		Description		String
				Code description for dynamic lists from your key generator.
		ExtraInfo		Object
				Info set by your key generator for dynamic lists only.
			CodeExtraInfo	Object
			Type	String
			Label	String
			Value	String
		File		Array of objects
			Content	String
				Content of the file (base64 encoded).
			ContentLength	Int
				File size.
			Filename	String
				The name of the delivered file.
			FileType	String
				The type of the delivered file.
ReceiveNotifications				Boolean
				1 – Subscribe: Avangate sends subscription notifications to the end user. 0 – Unsubscribe – Avangate does not send subscription notifications to the end user.
Lifetime				Boolean
				Possible values: True – the subscription is evergreen False – the subscription has a recurring billing cycle less than or equal to three years.
PartnerCode				String
				Empty: for ecommerce orders Partner Code
AvangateCustomerReference				Int
				Unique, system-generated customer identifier.
ExternalCustomerReference				String
				Customer identifier that you control.
TestSubscription				Boolean
				True for test subscriptions, false otherwise.
IsTrial				Boolean
				True for trial subscriptions, false otherwise.

Tracking capabilities in ConvertPlus and InLine Shopping Carts

Overview

Read below to find out how to take advantage of the tracking capabilities in ConvertPlus and InLine shopping carts.

Adobe Analytics

Our merchants can now implement the Adobe Analytics tracking tools, to help track and monitor their ConvertPlus and InLine checkout orders and further improve the shopping experience and increase the conversion rate. More information can be found here.

Google Analytics 4

In ConvertPlus and InLine shopping carts, you can implement Google Analytics 4 directly (without Google Tag Manager) simply by adding your Google Analytics Measurement ID in the section Google Analytics 4 in your Merchant Control Panel. This way you will receive cart eCommerce information directly in your Google Analytics 4 account. More information on the implementation can be found here.

Google Universal Analytics

Google Universal Analytics could be implemented in ConvertPlus and InLine shopping carts, by adding the Google Analytics Tracking ID in the section Google Universal Analytics in your Merchant Control Panel. However, this is a deprecated version of Google Analytics that will be sunset starting July 1st, 2023, for free Universal Analytics properties and starting July 1st, 2024, for 360 Universal Analytics properties. We strongly recommend you migrate to Google Analytics 4 as soon as possible.

Google Tag Manager for Google Analytics 4

You can also implement Google Tag Manager (GTM) in both your ConvertPlus or InLine carts and further add multiple tracking scripts.

We are currently supporting 2 dataLayers versions for Google Tag Manager – one dataLayer on the Google Universal Analytics format - section Google Tag Manager (with UA) from Merchant Control Panel and one on the Google Analytics 4 format - section Google Tag Manager (with GA4) from Merchant Control Panel. Since Google Universal Analytics will be sunset starting July 1st, 2023, for free Universal Analytics properties and starting July 1st, 2024, for 360 Universal Analytics properties, we recommend you use the dataLayer on the Google Analytics 4 format, by adding your Google Tag Manager Container ID in the section Google Tag Manager (with GA4) in your Merchant Control Panel.

Adding Google Analytics 4 through Google Tag Manager (GTM) using the Google Analytics 4 dataLayer format

To implement Google Analytics 4 through Google Tag Manager, add your Google Tag Manager Container ID in the section Google Tag Manager (with GA4) in your Merchant Control Panel and follow this step-by-step guide.

After implementation, you will be sending shopping cart eCommerce information to your Google Analytics 4 like:

product data at checkout – when the shoppers open the cart with certain products
product data when items are viewed in a list (for example cross-sell products)
product data at a remove from the cart – when a product is deleted from the cart
product data at add to cart – when a product is added to the cart from a list of cross-sell products for example
product data at purchase – when a successful order is completed for a product (name, price, quantity, product coupon data)

You will also be sending purchase data to your Google Analytics 4 (transaction id, purchase value, tax, shipping).

Other tracking capabilities through Google Tag Manager (GTM)

In addition to Google Analytics 4, you can also use Facebook Pixel, Google Ads, or any other desired tracking scripts through Google Tag Manager and send eCommerce information to those tools.

The Google Tag Manager script is placed in an iFrame with a data layer that includes extensive shopping cart information.

To see the information available in the data layer, follow these steps:

Open the browser console.
Select tracking.avangate.net from the top left corner of the console.
Type dataLayer in the console, as in the image below.

Under the ecommerce object, you can find product, checkout, and purchase details about the cart. This information is then passed to Google Analytics 4.

The cartUpdated event also provides further information about the cart (country, currency, language, page name, whether the product is catalog or dynamic, whether the flow is for new acquisitions or manual renewals, whether the order is a test one or not).

Tracking limitations in ConvertPlus and InLine carts

To ensure high-level security, the Google Tag Manager script is placed in an iFrame and not directly in the shopping cart, and the tracking scripts you are adding will only be able to pull information that is available in the data layer of the iFrame. For this reason, tools used for generating heatmaps, click maps, or user recordings, like Hotjar, will not be able to capture any information from the shopping cart, as the shopping cart screen information is not available in the iFrame.

A/B testing tools like Optimizely or Visual Website Optimizer will not work either when their scripts are placed in the Google Tag Manager, as those scripts will run in an iFrame and not in the actual cart.

Assign a PricingOption Group

Overview

Use the assignPricingConfigurationOptionGroup method to assign a PricingOption Group to a PricingConfiguration.

Parameters

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.
PricingConfigurationCode	Required (string)
	Unique, system-generated pricing configuration identifier.
PriceOptionsGroupAssigned	Required (Object)
	Details below.

PriceOptionsGroupAssigned	Object
Code	Required (string)
	PricingOption Group identifier.
Required	Required (Object)
	True or false depending on whether the pricing options group is required during the purchase process or not.

Response

bool(true)

Request

<?php

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


function hmac($key, $data)
{
    $b = 64; // byte length for md5
    if (strlen($key) > $b) {
        $key = pack("H*", md5($key));
    }
    
    $key    = str_pad($key, $b, chr(0x00));
    $ipad   = str_pad('', $b, chr(0x36));
    $opad   = str_pad('', $b, chr(0x5c));
    $k_ipad = $key ^ $ipad;
    $k_opad = $key ^ $opad;
    return md5($k_opad . pack("H*", md5($k_ipad . $data)));
}

$merchantCode = "YOURCODE123"; //your account's merchant code available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$key          = "SECRET_KEY"; //your account's secret key available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$now          = gmdate('Y-m-d H:i:s'); //date_default_timezone_set('UTC')

$string = strlen($merchantCode) . $merchantCode . strlen($now) . $now;
$hash   = hmac($key, $string);

try {
    $sessionID = $client->login($merchantCode, $now, $hash);
}

catch (SoapFault $e) {
    echo "Authentication: " . $e->getMessage();
    exit;
}
 
$PricingConfigurationCode = 'C4940279';
$PriceOptionsGroupAssigned = new stdClass();
$PriceOptionsGroupAssigned->Code = 'USERSUSERS';
$PriceOptionsGroupAssigned->Required = TRUE;
 
try {
    $AssignedOption = $client-> assignPricingConfigurationOptionGroup ($sessionID, $PricingConfigurationCode, $PriceOptionsGroupAssigned);
}

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

var_dump("Options", $AssignedOption);
 
 
 
?>

Subscription change deal

Overview

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

Request example

<?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": "dwilson@test.com",
        "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": "gerard.butler@integrawealth.net",
        "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": "test@email.org",
       "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": "dwilson@test.com",
                "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": "gerard.butler@integrawealth.net",
                "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": "test@email.org"
            },
            "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, this will trigger an error response is returned, like below:

{
    "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, as indicated, 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 as well, for 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.

Overview

Supported payment methods

Currency support

Parameters

Overview

Parameters

Request

Response

Overview

Request parameters

Response

Request sample

Overview

Parameters

Response

Request

Overview

Availability

Default Ordering Flow

Requirements for default ordering flows

Configure on-the-fly-pricing for default ordering flows

ConvertPlus Ordering Flow

Requirements for convertplus ordering flow

Overview

Parameters

Response

Request

Overview

Overview

Adobe Analytics

Google Analytics 4

Google Universal Analytics

Google Tag Manager for Google Analytics 4

Adding Google Analytics 4 through Google Tag Manager (GTM) using the Google Analytics 4 dataLayer format

Other tracking capabilities through Google Tag Manager (GTM)

Tracking limitations in ConvertPlus and InLine carts

Overview

Parameters

Response

Request

Overview

Request parameters

Request example

Response

Error handling

Need help?

Not yet a Verifone customer?