| Verifone Developer Portal

Search partners

Overview

Search partners using their company name or contact email. If a generic string is provided, the system searches for matches in company names and contact emails for all your partners.

Parameters

Parameters	Type/Description
sessionID	Required (string)
	Session identifier, output by the Login method. An exception will be thrown if the values are incorrect.
searchString	Required (string)
	Can be either the company name or contact email of the partner. The system searches generic strings in both the names of the companies as well as the contact email addresses.

Response

Parameters	Type/Description
Partner	Array of objects

Request

<?php

require('PATH_TO_AUTH'); // Authentication example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/SOAP/02Authentication

$searchString = 'YOUR_SEARCH_STRING'; // String to search partners by

try {
    $PartnerSearch= $client->searchPartners($sessionID, $searchString);
} catch (SoapFault $e) {
    echo "Partner: " . $e->getMessage();
    exit;
}

var_dump ("Partner", $PartnerSearch);

Errors

Error	Description
INVALID_SEARCH	Invalid value. Please use a string to search.

Track sales with custom parameters

Overview

Define multiple URL parameters to track your sales through the 2Checkout system. The custom URL parameters can be used for tracking at both product and order level.

Availability

All 2Checkout accounts.

Create custom parameters

Follow the steps below to create custom parameters to add to products and buy links.

Log into your 2Checkout Merchant Control Panel account.
Go to Setup → Ordering options.
Scroll down to Additional order fields and click on 'Click here to create and manage additional fields and collect extra information from shoppers at checkout or track orders'.

4. Use the Add new field section to define each new field.

Enter the Field identifier. This reference is used to create the URL parameter that you can use in buy links. Use unique identifiers for all your fields. Note: This field accepts only alpha-numeric characters. If you leave this field empty, 2Checkout generates a random value as an identifier.
Enter the Field text (the name of the field).
Set the Field type to Hidden. Otherwise, otherwise the field will be a Textbox, Checkbox, or Listbox, all of which are visible in the shopping cart. Hidden fields help you create custom URL tracking parameters and they are invisible to shoppers.
Use the Apply to drop-down to choose whether the field should apply at the product or order level.
Use the Validation rule field to specify the regular expression to validate the field values.
Click Create field to save the new field.

Assign custom parameters to products

Follow the steps in the Create custom parameters section to create a new Hidden parameter and apply it at the Product level.

Next, follow the steps below to assign the parameter to a product.

Once logged in to your Merchant Control Panel, go to Setup and click on Products.
Click Edit on the product you want to assign the parameter to.

3. Go to the Information tab and scroll to the bottom of the screen. You'll find the previously defined parameter in the Order additional fields section. All new parameters are disabled by default.

4. Check the Enabled option on the Order page column corresponding to the parameter you want to use.

5. Click Save.

Assign custom parameters to orders

Follow the steps in the Create custom parameters section to create a new Hidden parameter and apply it at the Order level.

Next, follow the steps below to assign the parameter to an order.

Log into your 2Checkout Merchant Control Panel account.
Go to Setup → Ordering options.
Scroll down to Additional order fields.
Check the checkbox next to the parameter you want to use.

5. Click Save settings at the bottom of the page.

Build buy-links using custom parameters

Build buy-links with per-product parameters

Let's assume you created customparameter for Product A with the ID 1234567, and the 2Checkout system created the ADDITIONAL_customparameter[1234567] URL parameter.

To track sales of this product using customparameter, add ADDITIONAL_customparameter[1234567] to the buy link as such:

https://secure.2checkout.com/order/checkout.php?PRODS=1234567&ADDITIONAL_customparameter[1234567]=CustomTrackingSource1

You can assign the desired values to custom URL parameters to best serve you in the sales tracking process.

Build buy-links with per-order parameters

Let's assume you created customparameter for orders, and the 2Checkout system created the ADDITIONAL_customparameter URL parameter.

To track orders using customparameter, add ADDITIONAL_customparameter to the buy link as such:

https://secure.2checkout.com/order/checkout.php?PRODS=1234567&ADDITIONAL_customparameter=CustomTrackingSourceForOrders

You can assign the desired values to custom URL parameters to best serve you in the sales tracking process.

Search promotions

Overview

Use the searchPromotions method to extract information on promotions you set up for your account.

Parameters

Parameters	Type/Description
sessionID	Required (string)
	Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect. The sessionID expires in 10 minutes.
Types	StringArray
	Discount type: REGULAR GLOBAL SPECIAL_PRICE RENEWAL
Channel	String
	Channel: ECOMMERCE CHANNEL_MANAGER ALL
ProductCode	String
	Unique code that you set for each of your products.
Pagination	Object. Details below.
Limit	Int
	Set a limit for the number of results that should be returned.
Page	Int
	Set the number of pages that should be returned.
Coupons	String
	A string composed by comma-separated coupon codes (XYX,GGG,BBBB, etc).

Response

Parameters	Type/Description
Promotion	Array of objects

Request

<?php

require ('PATH_TO_AUTH');

$searchOptions = new stdClass();
$searchOptions->Types = array ('REGULAR');
$searchOptions->Channel = 'ECOMMERCE';
$searchOptions->ProductCode = 'Product_Code_1';
$searchOptions->Enabled = TRUE;
$searchOptions->Limit = 99;
$searchOptions->Page = 1;
$searchOptions->Coupons = “81XS55D1,E14SSF17;

try {
    $Discounts = $client->searchPromotions($sessionID, $SearchOptions);
}

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

var_dump("Promotions", $Discounts);

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.

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.

Affiliate

Object

Details below.

AffiliateCode

String

The unique code of the affiliate who refer orders.

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.

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, Turkey, India and Romania

The state in the shopper's country. Mandatory when you set the Billing Country to US, Turkey, 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, Turkey, and Romania

The state in the shopper's country from the delivery details. Mandatory when you set the Billing Country to US, Turkey, 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.

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.

RecurringEnabled

Boolean

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

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.

Pricing configuration

Overview

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

Retrieve a pricing configuration by name Retrieve a pricing configuration by code Retrieve pricing configurations

Pricing configuration object

Parameters				Type/Description
Name				String
				Pricing configuration name.
Code				String
				System-generated identifier. Read-only.
Default				Boolean
				True for the default pricing configuration
BillingCountries				Array of strings
				ISO codes of the countries assigned to the pricing configuration. Empty unless a pricing configuration has specific countries assigned.
PricingSchema				String
				DYNAMIC – With a base price FLAT – Without a base price
PriceType				String
				Possible values: • NET • GROSS
DefaultCurrency				String
				The ISO code of the default currency for the pricing configuration.
Prices				Object
				Details below.
	Regular			Array of objects
				Details below.
		Amount		Int
				The price of the product. Use -1 to delete it.
		Currency		String
				ISO code of the currency for the product price.
		MinQuantity		Int
				The minimum quantity of volume discounts. Default is 1.
		MaxQuantity		Int
				The maximum quantity of volume discounts. Default is 99999.
		OptionCodes		Array of objects
				Details below.
			Code	String
				System generated pricing options group code (you can also configure it) that the 2Checkout system uses to calculate product prices for pricing configurations without a base price.
			Options	StringArray
				The pricing options group option code you configured that the 2Checkout system uses to calculate product prices for pricing configurations without a base price.
	Renewal			Array of objects
				Details below.
		Amount		Int
				The price of the product. Use -1 to delete it.
		Currency		String
				ISO code of the currency for the product price.
		MinQuantity		Int
				The minimum quantity of volume discounts. Default is 1.
		MaxQuantity		Int
				The maximum quantity of volume discounts. Default is 99999.
		OptionCodes		Array of objects
				Details below.
PriceOptions				Array of objects
				Details below.
	Code			String
				System generated pricing options group code (you can also configure it) that the 2Checkout system uses to calculate product prices for pricing configurations without a base price.
	Required			Boolean
				true – you set the price options group as required during the purchase process. false - you did not set the price options group as required during the purchase process.

Retrieve upsell settings

Overview

Use the getDisplayType method to extract information for the upselling display type for your campaigns.

Request parameters

Parameter	Type	Required/Optional	Description
sessionID	String	Required	Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect. The sessionID expires in 10 minutes.

Response

The getDisplayType method will return the UpsellingDisplayType value with one of "overlay" or "interstitial".

Request sample

<?php 

          require ('PATH_TO_AUTH'); 

          try { 

            $upSellSettingsResponse = $client->getDisplayType($sessionID); 

          } catch (SoapFault $e) { 

            echo  $e->getMessage(); 

          }

Search methods pagination

Overview

Starting with 2Checkout API 5.0, search methods are including the option of pagination. Pagination has been developed for decreasing the request loading time, while allowing you to better handle the returning responses.

How it works?

Pagination works on all the search methods existing on 2Checkout API 5.0. The default pagination behavior is to display page 1 with 10 results. The maximum number of items displayed on a single page is 200.

Parameters

To use pagination, include the Pagination object inside the search method call, using the parameters below:

Parameters		Type/Description
Pagination		Object
		Details below.
	Page	Int
		Set the number of pages that should be returned.
	Limit	Int
		Set a limit for the number of results that should be returned.

Response

The response of search methods that are including pagination will contain a new object, with the following parameters:

Parameters		Type/Description
Pagination		Object
		Details below
	Page	Int
		Set the number of pages that should be returned.
	Limit	Int
		Set a limit for the number of results that should be returned.
	Count	Int
		Number of total results returned

Sample request

The below PHP sample includes a search method for subscriptions.

<?php

require('PATH_TO_AUTH');

$SubscriptionSearch = new stdClass();
$SubscriptionSearch->CustomerEmail  = 'email@avangate.com';
$SubscriptionSearch->DeliveredCode = null;
$SubscriptionSearch->AvangateCustomerReference = null;
$SubscriptionSearch->ExternalCustomerReference = null;
$SubscriptionSearch->Aggregate = false;
$SubscriptionSearch->SubscriptionEnabled = null; //true false null
$SubscriptionSearch->RecurringEnabled = null; // true - autorenewal, false - manual renewal, null = both(default)
$SubscriptionSearch->ProductCodes = null; //array('Product_Code1', 'Product_Code2');
$SubscriptionSearch->CountryCodes = null;//array ('au')
$SubscriptionSearch->PurchasedAfter = null;
$SubscriptionSearch->PurchasedBefore = null;
$SubscriptionSearch->ExpireAfter = null;
$SubscriptionSearch->ExpireBefore = null;
$SubscriptionSearch->LifetimeSubscription = null;
$SubscriptionSearch->Type = 'regular'; //'trial', 'regular', 'regularfromtrial'
$SubscriptionSearch->TestSubscription = null; // true, false, null = both(default)
$SubscriptionSearch->Pagination = new stdClass();
$SubscriptionSearch->Pagination->Page = 1; // set the number of pages for the response
$SubscriptionSearch->Pagination->Limit = 200; // set the limit for the values from the response

try {
    $accountSubscriptions = $client->searchSubscriptions($sessionID, $SubscriptionSearch);
}
catch (SoapFault $e) {
    echo "accountSubscriptions: " . $e->getMessage();
    exit;
}
var_dump("accountSubscriptions", $accountSubscriptions);

Enable/Disable products

Overview

Use the setProductStatus method to enable / disable subscription plans/products for your account.

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.
productCode	Required (string)
	Use this object to configure your subscription plan/products. You can set all Product parameters except AvangateID. The Avangate system sets the unique product ID. The AvangateID is not editable.
Status	Required (Boolean)
	True or False, depending on whether you want to enable or disable a subscription plan/product.

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

$ProductCode = 'ABC4643116';

try {
    $ProductStatus = $client->setProductStatus($sessionID, $ProductCode, true); // TRUE to enable a product - FALSE to disable a product
}

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

var_dump("ProductStatus", $ProductStatus);

?>

Dynamic 3D Secure

Overview

3D Secure is a system designed to increase the security of online transactions using cards by checking customer identities before allowing them to finalize a purchase. 3D Secure works by redirecting customers to pages provided by their banks, where they need to enter additional security tokens or password to trigger the completion of the charge. By using 3D Secure, you get additional protection from liability for fraudulent card payments, with customers having to go through an extra layer of authentication.

Description

Dynamic 3D Secure is based on the 3D Secure service offered by Visa and MasterCard, which is an additional security layer for authenticating cardholders online. 2Checkout uses Dynamic 3D secure to bring increased transaction acceptance levels on a per-country basis and extra protection against fraudulent purchases.

Availability

All 2Checkout accounts.

Dynamic 3D Secure workflow

Based on a set of specific filters and corresponding thresholds, 2Checkout enables or disables 3D Secure in real-time for online transactions. This approach provides a seamless payment experience for low-risk shoppers and optimized conversion rates for your business.

The filters used to determine whether or not 3D Secure should be enabled include:

Card issuing country
Billing country
IP country
Transaction amount

2Checkout enables 3D Secure for transactions which it evaluates and flags with a high degree of risk, based on specific filter thresholds. Safe transactions go through without 3D Secure.

2Checkout also offers the possibility to disable 3D Secure for all transactions in a specific country, bypassing all the filters. Contact 2Checkout to inquire about switching off Dynamic 3D Secure for your account.

Benefits

2Checkout uses Dynamic 3D Secure to bring increased transaction acceptance levels and extra protection against fraudulent purchases. The added value Dynamic 3D Secure brings to the table consists in real-time transaction evaluation methods that determine whether or not 3D Secure should be enabled.

Dynamic 3D Secure improves the overall shopping experience on multiple levels:

Increased authorization rates - tests have shown that 3D Secure can have an overwhelmingly positive impact in specific countries.
Mitigated fraud risks - using 3D Secure for risky transactions decreases fraud rate.
Fewer chargebacks - the use of 3D Secure can reduce the number of chargebacks in situations such as fraudulent or unrecognized transactions.

Electronic delivery email

Overview

2Checkout sends out the electronic delivery email automatically to fulfill orders - delivering binary keys, activation codes, Download Software Insurance details or product files to your shoppers.

As of July 13th, 2016, you can use a redesigned template complete with fresh content. The new template has replaced the previous electronic delivery email, but any customization you have in place, either in terms of styling or content, continues to be available.

Availability

All 2Checkout accounts.

What is the purpose of this email?

2Checkout sends the electronic delivery email for those products where you set fulfillment to be performed through 2Checkout delivery.

Email content

Depending on what actions need to be performed by your clients to receive access to your products, the email includes one or several of the following:

Product/Subscription plan information.
Activation keys/codes accompanied by short descriptions.
Downloadable product files, and download insurance service.
Technical and payment support contact details.

Sample

Is this the only email my shoppers receive after placing an order?

2Checkout can send the electronic delivery email either standalone or combined with the payment receipt notification (in one single email).

Depending on your account's setup, for each order containing at least one product configured with 2Checkout delivery your shoppers can receive:

Default: One email containing both the payment receipt and the electronic delivery messages
Two email notifications: The payment receipt and the electronic delivery messages, separately
Three email notifications: An order confirmation email, plus the payment receipt and the electronic delivery messages, separately

Contact 2Checkout to change your default configuration if you find another setup better suited for your customers.

Preview and test email

Navigate to the Email template manager section to:

Preview and test current templates for emails sent to your shoppers
Customize the header and the footer sections by creating custom templates you can assign to your emails

Access the electronic delivery email under the section with the same name.

Why don't I see the new template for the electronic delivery email?

The redesigned template for the electronic delivery email has automatically replaced default templates.

If your preview of electronic delivery email does not show the new template, you are most probably using a customized version, that includes content and/or styling your company requested at a certain point in time.

You can compare the above sample to your current template and send us an email if you decide the new one suits your business needs better. We will work with you on the switch.

Overview

Parameters

Response

Request

Errors

Overview

Availability

Create custom parameters

Assign custom parameters to products

Assign custom parameters to orders

Build buy-links using custom parameters

Build buy-links with per-product parameters

Build buy-links with per-order parameters

Overview

Parameters

Response

Request

Overview

Dynamic order object

Overview

Pricing configuration object

Overview

Request parameters

Response

Request sample

Overview

How it works?

Parameters

Response

Sample request

Overview

Parameters

Response

Request

Overview

Description

Availability

Dynamic 3D Secure workflow

Benefits

Overview

Availability

What is the purpose of this email?

Email content

Sample

Is this the only email my shoppers receive after placing an order?

Preview and test email

Why don't I see the new template for the electronic delivery email?

Need help?

Not yet a Verifone customer?