updates RSS feed

Order with dynamic products

Overview

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

Place orders with dynamic product information

Retrieve an order

Dynamic order object

Parameters Type/Description

RefNo

String
 

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

 

NULL when you place new orders.
ChargebackResolution String
 

Chargeback status information. Possible values:

· OPEN (chargeback is in progress)

· WON (chargeback won by you)

· LOST (chargeback won by the customer)

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

· NONE (no chargeback initiated for the order)

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

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

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

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

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

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

Possible values:

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

OrderNo

String
 

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

ExternalReference

String
 

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

ShopperRefNo

String
 

External shopper identifier.

Status

String
 

The status of the order:

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

ApproveStatus

String
 

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

Possible values:

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

VendorApproveStatus

String
 

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

  • OK
  • WAITING
  • REJECTED

Language

String
 

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

OrderDate

String
 

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

FinishDate

String
 

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

 

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

Source

String
 

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

Maximum length 255 characters. Cannot be null.

AffiliateSource

String
 

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

AffiliateId

Integer
 

Identifier belonging to affiliates who refer orders.

AffiliateName

String
 

Affiliate name.

AffiliateUrl

String
 

Affiliate website URL from the Affiliate Details.

RecurringEnabled

Boolean
 

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

HasShipping

Boolean
 

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

Object

Details below
                                  ShippingMethod

Object

Details below
                                                            Code

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

BillingDetails

Object
   

Details below. 
 

FirstName

String
   

Shopper name.
 

LastName

String
   

Shopper surname.
 

CountryCode

String
   

Shopper country. ISO 3166 two-letter code.
 

State

String – Required for US, Brazil, India and Romania
   

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

City

String
   

Shopper city.
 

Address1

String
   

Shopper address.
 

Address2

String
   

Shopper address.
 

Zip

String
   

ZIP/ Postal code.
 

Email

String
   

Shopper email address.
 

Phone

String
   

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

Company

String
   

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

FiscalCode

String – Required for Brazil
   

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

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

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

• Can be null for end users.

DeliveryDetails

Object

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

Details below. 
 

FirstName

String
   

Shopper name from the delivery details.
 

LastName

String
   

Shopper surname from the delivery details.
 

CountryCode

String
   

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

State

String – Required for US, Brazil and Romania
   

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

City

String
   

Shopper city from the delivery details.
 

Address1

String
   

Shopper address from the delivery details.
 

Address2

String
   

Shopper address from the delivery details.
 

Zip

String
   

ZIP/ Postal code from the delivery details.
 

Email

String
   

Shopper email address from the delivery details.
 

Phone

String
   

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

Company

String
   

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

PaymentDetails

Object
 

Adapt this object to the desired payment method.
 

Type

String
   

The payment method:

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

Currency

String
   

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

PaymentMethod

Object
   

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

 

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

 

null for 0 value orders for which you’re not requiring customers to enter payment details.
                           RecurringEnabled Boolean
    true or false, depending on whether the order has active recurring options
   

PaymentDetailsCard

Object
       

Details below. 
     

CardType

String
       

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

FirstDigits

String
       

First four digits of the credit card.
     

LastDigits

String
       

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

CheckPaymentDetails

Object
     

Details below. 
   

Beneficiary

String
     

The beneficiary of the payment.

Can be NULL.
   

CheckPostalAddress

String
     

The address of the beneficiary.

Can be NULL.
   

Amount

Float
     

The total costs incurred by the customer for an order.

Can be NULL.
   

Currency

String
     

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

Can be NULL.
 

PayPalExpress

Object
       

Details below. 
     

Email

String
       

Email address customers use for their PayPal account.
     

ReturnURL

String
       

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

CancelURL

String
       

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

WirePaymentDetails

Object
     

Details below. 
   

Amount

Float
     

The total costs customers incur.

Can be NULL.
   

Currency

String
     

The currency ISO code of the order - ISO 4217.

Can be NULL.
   

PaymentReference

String
     

Transaction identifier.

Can be NULL.
   

RoutingNumber

String
     

Identification number assigned to financial institutions.

Can be NULL.
   

BankAccounts

Optional (Array of objects)
       

Details below. 
     

Beneficiary

String
       

The beneficiary of the payment.

Can be NULL.
     

BankName

String
       

The name of the beneficiary's bank.

Can be NULL.
     

BankCountry

String
       

The country of the beneficiary's bank.

Can be NULL.
     

BankCity

String
       

The city of the beneficiary's bank.

Can be NULL.
     

BankAddress

String
       

The address of the beneficiary's bank.

Can be NULL.
     

BankAccount

String
       

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

Can be NULL.
     

BankAccountIban

String
       

The IBAN of the beneficiary's bank.

Can be NULL.
     

BankAccountSwiftCode

String
       

The Swift Code of the beneficiary's bank.

Can be NULL.
     

Currency

String
       

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

Can be NULL.
 

CustomerIP

String
   

Shopper IP.

CustomerDetails

Object

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

Details below. 
 

AvangateCustomerReference

Integer
   

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

ExternalCustomerReference

String
   

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

FirstName

String
   

Customer's first name. 
 

LastName

String
   

Customer's last name.
 

CountryCode

String
   

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

State

String
   

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

City

String
   

Customer's city.
 

Address1

String
   

Customer's address.
 

Address2

String
   

Customer's address.
 

Zip

String
   

Zip code.
 

Email

String
   

Customer's email.
 

Phone

String
   

Customer's phone number.
 

Company

String
   

Company name.
 

FiscalCode

String
   

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

 

Can be null for end users.
 

Fax

String
   

Customer's fax number.
 

Enabled

Boolean
   

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

Trial

Boolean
   

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

Language

String
   

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

ExistingCards

Optional (Array of objects)
     

Details below. 
   

TransientToken

Object
     

Populated only when you retrieve customer information by SSOToken.
     

Token

String
       

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

CardType

String
     

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

LastDigits

String
     

Last four digits of the credit card.
   

ExpirationMonth

String
     

Card expiration month.
   

ExpirationYear

String
     

Card expiration year.
   

NameOnCard

String
     

Card holder name.

Origin

String
 

2Checkout automatically tracks the source of purchases:

 

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

AvangateCommission

Integer
 

2Checkout's commission for the order.

OrderFlow

String
 

PURCHASE_ORDER - Sent only when shoppers used Purchase Orders.

REGULAR - Sent in all other cases.

GiftDetails

Object
 

Contains contact details for the recipient of a gift purchase.
 

FirstName

String
   

First name of gift recipient.
 

LastName

String
   

Last name of gift recipient.
 

Email

String
   

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

GiftNote

String
   

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

PODetails

Object (optional)
   

Details below. 
 

Status

String
   

PO status. Possible values:

 

PO status API

PO status cPanel

AWAITING_UPLOAD

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

TIME_EXPIRED

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

AWAITING_MERCHANT

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

MERCHANT_TIME_EXPIRED

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

AWAITING_MERCHANT

Rejected - You rejected the PO

AWAITING_PAYMENT

Awaiting payment - You approved the PO, waiting for payment

AWAITING_PAYMENT

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

NOT_PAID

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

NOT_PAID

Canceled by 2Checkout - 2Checkout canceled the PO

NOT_PAID

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

PAID

Complete - Customer paid the PO. The order is complete
 

AutoApprove

Boolean
 

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

RequireDocumentUpload

Boolean
 

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

NetPaymentTerms

Integer
 

The term of net payment in days.
 

CopyPreviousDocuments

Boolean
 

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

PdfFormUrl

String
 

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

ExtraInformation

Object
 

Details below. 

 

PaymentLink

String

 

 

Can be:

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

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

PartnerCode

String
 

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

PartnerMargin

Float
 

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

PartnerMarginPercent

Float
 

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

ExtraMargin

Float
 

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

ExtraMarginPercent

Float
 

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

ExtraDiscount

Float
 

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

ExtraDiscountPercent

Float
 

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

LocalTime

String
 

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

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

TestOrder

Boolean
 

True for test orders. False of regular orders.

Errors

Array of strings
 

Payment gateway processing errors.

Items

Array of objects
   

Details below. 
 

ProductDetails

Object
   

Name

String
     

Product name.
   

ExtraInfo

String
     

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

RenewalStatus

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

Subscriptions

Object
     

SubscriptionReference

String
       

Unique, system-generated subscription identifier.
     

PurchaseDate

String
       

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

 

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

SubscriptionStartDate

String
       

 

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

ExpirationDate

String
       

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

 

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

 

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

Lifetime

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

Trial

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

Enabled

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

RecurringEnabled

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

                   

PriceOptions

Array of objects
   

Array of price option groups.
    Code String
      Pricing option code. 
    Name String
      Pricing option name.
    Required Boolean
     

Possible values:

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

Options

Optional (array of objects)
     

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

Price

Object
   

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

 

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

UnitNetPrice

Float
     

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

UnitGrossPrice

Float
     

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

UnitVAT

Float
     

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

UnitDiscount

Float
     

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

UnitNetDiscountedPrice

Float
     

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

UnitGrossDiscountedPrice

Float
     

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

UnitAffiliateCommission

Float
     

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

 

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

 

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

 

NULL when 2Checkout does not apply an affiliate commission.
   

Currency

String
     

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

NetPrice

Float
     

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

GrossPrice

Float
     

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

NetDiscountedPrice

Float
     

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

GrossDiscountedPrice

Float
     

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

 

Example:

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

Discount

Float
     

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

VAT

Float
     

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

AffiliateCommission

Float
     

Value of the affiliate commission per order line, calculated from the NetDiscountedPrice expressed in the payment currency. Or NULL. 2Checkout does not take Integero account shipping costs when calculating affiliate commissions.
    VATPercent Integer
      Percentage of the VAT/tax applied on purchase.
    HandlingFeeNetPrice Integer
      Handling fee applied to your NET price configuration.
    HandlingFeeGrossPrice Integer
      Handling fee applied to your GROSS price configuration.
 

Quantity

Integer
   

Number of units
 

SKU

String
   

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

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

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

CrossSell

Object
     

Details below. 
   

ParentCode

String
     

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

CampaignCode

String
     

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

Trial

Object
     

Details below. 
   

Period

Integer
     

The length of the trial subscription lifetime in days.
   

GrossPrice

Float
     

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

VAT

Float
     

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

NetPrice

Float
     

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

AdditionalFields

Optional (array of objects)
     

Details below. 
   

Code

String
     

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

Text

String
     

Field text visible to shoppers in the cart.
   

Value

String
     

Selected field value.
 

Promotion

Object
     

Details below. 
   

Name

String
     

Promotion name.
   

Description

String
     

Promotion description.
   

StartDate

String
     

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

EndDate

String
     

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

MaximumOrdersNumber

Integer
     

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

 

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

MaximumQuantity

Integer
     

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

InstantDiscount

Boolean
     

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

Coupon

String
     

Promotion coupon/voucher.
   

DiscountLabel

String
     

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

Enabled

String
     

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

Type

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

Promotions

Array of objects
   

Details below. 
 

Name

String
   

Promotion name.
 

Description

String
   

Promotion description.
 

StartDate

String
   

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

EndDate

String
   

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

MaximumOrdersNumber

Integer
   

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

 

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

MaximumQuantity

Integer
   

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

InstantDiscount

Boolean
   

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

Coupon

String
   

Promotion coupon/voucher.
 

DiscountLabel

String
   

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

Enabled

String
   

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

Type

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

AdditionalFields

Array of objects
   

Details below. 
 

Code

String
   

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

Text

String
   

Field text visible to shoppers in the cart.
 

Value

String
   

Selected field value.

Currency

String
 

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

NetPrice

Float
 

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

GrossPrice

Float
 

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

NetDiscountedPrice

Float
 

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

GrossDiscountedPrice

Float
 

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

 

For example:

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

Discount

Float
 

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

VAT

Float
 

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

AffiliateCommission

Float
 

Value of the affiliate commission for the order calculated from the NetDiscountedPrice expressed in the payment currency. Or NULL. 2Checkout does not take Integero account shipping costs when calculating affiliate commissions.
MerchantCode String
  Merchant account code. Can be found in Control Panel, System Settings.

Delete SKU codes

Overview

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

Request Parameters

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

Request Example

<?php

require ('PATH_TO_AUTH');

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

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

$product->PriceConfigurations = [$pricingConfiguration];

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

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

Response Parameters

Parameters Type/Description
productCode  
priceConfigurationCode  
priceConfigurations  

Response Example

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

Search SKU codes

Overview

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

Request Parameters

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

Code

 Required String  

Currencies

 Required String ISO currency code.

Code

 Required String  

PurchaseTypes

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

Code

 Required String  

QuantityIntervals

 Required Object Numeric identifier of product quantity.

MinQuantity

 Required Int  

MaxQuantity

 Required Int  

PriceOptionGroups

 Required Array of objects  

Code

 Required String  

Options

 Required Array of objects  

OptionValue

 Required String  
Pagination Required Object  

Page

 Required Int  

Limit

 Required Int  

Request Example

<?php

require ('PATH_TO_AUTH');

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

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

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

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

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

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

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

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

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

Response Parameters

Parameters Type/Description
Items Object

ProductCode

 String

SkuPricingOptions

 Array of strings

Code

 String

Details

 Array

ProductSKU

 String

Currency

 String

FromQty

 String

ToQty

 String

PurchaseTypes

 String

Groups

 Array

GroupCode

 String

Options

 Array

               Name

 String
                                                                                Value String

Errors

 Array
Pagination Object

Limit

 Int

Page

 Int

Count

 Int

Response Example

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

 

Update a subscription

Overview

Change specific details about a subscription. Use the updateSubscription method to change specific details about a subscription.

Parameters

Parameters Type/Description

sessionID

Required (string)

 

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

Subscription

Required (Object)

 

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

 

EndUser

Object

 

 

End user details.

 

ExpirationDate

String

 

 

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

 

SubscriptionEnabled

Boolean

 

 

Possible values: TRUE/FALSE

 

RecurringEnabled

Boolean

 

 

Possible values: TRUE/FALSE

 

ExternalCustomerReference

String

 

 

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

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

 

ProductId

Int

 

 

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

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

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

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

 

ProductName

String

 

 

The name of the product for identifier used under ProductID.

 

ProductQuantity

Int

 

 

Ordered quantity.

 

PriceOptionCodes

Array

 

 

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

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

 

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

The 2Checkout system uses the updated subscription information for:

  • Manual and automatic renewals
  • Upgrades
  • Trial conversions

Response

Parameters Type/Description

Boolean

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

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReferenceTest = 'YOUR_SUBSCRIPTION_REFERENCE';

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

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

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

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

 

Place orders with catalog products

Overview

Use this object to create new orders and collect payments from shoppers using catalog products defined in your Merchant Control Panel.

Supported payment methods

  1. Credit/Debit cards: Visa, Visa Electron, MasterCard, Maestro, Amex, Discover, Dankort, Carte Bancaire, JCB. 2Checkout supports local Brazilian cards.
  2. PayPal and PayPal Express
  3. Purchase Order
  4. SOFORT
  5. Wire
  6. Check
  7. WeChat Pay
  8. iDEAL
  9. TEST orders
  10. Free orders (no payment information required)
  11. One click (1-click) purchases - In addition to the payment methods enumerated above, 2Checkout also supports 1-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.
  12. 2Pay.js

Attributes

 
Parameters Type/Description
Currency Optional (string)
  The currency ISO code for the payment - ISO 4217. Example: “usd.”
Country Optional (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.
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.
MachineId Optional (string)
  Unique, system-generated code for each unique customer, identifying returning customers.
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. If Price Type is set to 'CUSTOM', dynamic pricing can be added to the order via the Amount parameter.
    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.
BillingDetails Required (Object)
    Details below. 
  Person Object
    Details below.
    FirstName Required (string)
      Shopper name.
    LastName Required (string)
      Shopper surname.
    CountryCode Optional (string)
      Shopper country. ISO 3166 two-letter code.
    State String/Optional – Required for US, Canada, Brazil, Turkey, India and Romania
      The state in the shopper's country. Mandatory when you set the Billing Country to US, Canada, Brazil, Turkey, India and Romania. Use case insensitive utf8 strings for the full name, or just the two-letter code.
    City Optional (string)
      Shopper city.
    Address1 Optional (string)
      Shopper address.
    Address2 Optional (string)
      Shopper address.
    Zip Optional (string)
      ZIP/ Postal code.
    Email Optional (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.
    TaxExemptionId  Optional (string)
      Tax Exempt Certification id used to deduct taxes for US orders
Example: 1b80eecc349v
  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).

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

• 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 String/Optional – Required for US, Canada, Brazil, Turkey, India and Romania
                    The state in the shopper's country. Mandatory when you set the Billing Country to US, Canada, Brazil, Turkey, India 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
  • DIRECT_EBANKING
  • 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.
  • WE_CHAT_PAY (for WeChat payments).
  • IDEAL (for iDEAL payments).
  • PURCHASEORDER - use for orders with POs.
  • FREE – for 0 value orders for which you’re not requiring customers to provide payment details.
  • EES_TOKEN_PAYMENT (2Pay.js)

 
  Currency Required (string)
    The currency ISO code for the payment - ISO 4217. Example: “usd.”
  PaymentMethod Optional (object)
   

Object structure and parameters differ according to 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 Required (string)
          The credit/debit card number.
        CardType Required (string)
          visa, visaelectron, mastercard, maestro, amex, discover, dankort, cartebleue, jcb, hipercard, elo
        ExpirationYear Required (string)
          The year in which the card expires.
        ExpirationMonth Required (string)
          The month in which the card expires.
        HolderName Required (string)
          Cardholder name.
        CCID Required (string)
          Credit Card Identification - an extra ID printed on the card, usually a 3-4 digit number, the CVC2/CVV2.
        Vendor3DSReturnURL Required (string)
          URL address to which customers are redirected after the 3DS details get validated by the bank and the order is successfully authorized.
        Vendor3DSCancelURL Required (string)
          URL address to which customers are redirected if the 3DS details were not validated or the order could not be authorized.
        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 enter 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 the 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.
      WE_CHAT_PAY Optional (string)
        Details below
        ReturnURL Optional (string)
          The return URL is the page to which your customers are redirected after their successful payment.
        CancelURL Optional (string)
          The cancel URL is the page to which your customers are redirected after their failed payment attempt.
      IDEAL Optional (string)
        Details below
        ReturnURL Optional (string)
          The return URL is the page to which your customers are redirected after their successful payment.
        CancelURL Optional (string)
          The cancel URL is the page to which your customers are redirected after their failed payment attempt.
        BankCode Required (string)
          String contains the SWIFT code of the bank, the plus sign "+", and the first 3 characters from the bank name. E.q.: in the case of Rabobank, code parameter is "RABONL2U+RAB".
      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 Optional (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 a 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.

 

Update product group

Overview

Use the updateProductGroup method to create a new product group 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.

ProductGroup

Required (object)

 

Use this object to update product groups.

Response

bool(true)

Request

<?php

require ('PATH_TO_AUTH');

$ProductGroup = new stdClass();
$ProductGroup->Name = 'New Product Group from API';
$ProductGroup->Code = 'DBA13A4268';
$ProductGroup->TemplateName = 'Default Template'; // the name of the cart template you want to associate with the product group
$ProductGroup->Description = 'This is a generic description';
$ProductGroup->Enabled = false;

try {
    $UpdatedProductGroup = $client->updateProductGroup($sessionID, $ProductGroup);
}

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

var_dump("UpdatedProductGroup", $UpdatedProductGroup);


?>

Update promotion coupon

Overview

Use the updatePromotionCoupon method to add single or multiple coupons to a promotion.

Updating a promotion with multiple coupons causes any existing single coupon to be removed.

Parameters

Parameter Type/Description

sessionID

Required (string)

 

Output of the Login method.

promotionCode

Required (string)

 

The code corresponding to the promotion that you want to update.

promotionCoupon

Required (object)

 

type

Required (string)

 

 

Coupon type. Available values:

  • SINGLE, use in conjunction with Code
  • MULTIPLE, use in conjunction with Codes

 

Code/Codes

Required (string / array of strings)

 

 

Coupon code (for SINGLE) or array of coupon codes (for MULTIPLE).

Response

Parameter Type/Description
promotionCoupon Object

Request

<?php

function callRPC($Request, $host, $Debug = true) {
    $curl = curl_init($host);
    curl_setopt($curl, CURLOPT_POST, 1);
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($curl, CURLOPT_VERBOSE, true);
    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'));
    $RequestString = json_encode($Request);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $RequestString);
    if ($Debug) {
        $RequestString;
    }
    $ResponseString = curl_exec($curl);
    if ($Debug) {
        $ResponseString;
    }
    if (!empty($ResponseString)) {
        var_dump($ResponseString);
        $Response = json_decode($ResponseString);
        if (isset($Response->result)) {
            return $Response->result;
        }
        if (!is_null($Response->error)) {
            var_dump($Request->method, $Response->error);
        }
    } else {
        return null;
    }
}

$host = 'https://api.avangate.com/rpc/3.1/';

$merchantCode = "YOUR_MERCHANT_CODE"; // your account's merchant code available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$key = "YOUR_SECRET_KEY"; // your account's secret key available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php

$string = strlen($merchantCode) . $merchantCode . strlen(gmdate('Y-m-d H:i:s')) . gmdate('Y-m-d H:i:s');
$hash = hash_hmac('md5', $string, $key);

$i = 1;

$jsonRpcRequest = new stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method = 'login';
$jsonRpcRequest->params = array($merchantCode, gmdate('Y-m-d H:i:s'), $hash);
$jsonRpcRequest->id = $i++;

$sessionID = callRPC($jsonRpcRequest, $host);

// Promotion code corresponding to the promotion you want to add coupons to
$promotionCode = '';

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

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

$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'updatePromotionCoupon',
'params' => array($sessionID, $promotionCode, $promotionCoupon)
);
var_dump (callRPC($jsonRpcRequest, $host));

Automatic channel renewals (Direct Renewal)

Overview

Automatic Channel Renewals (Direct Renewal) enables customers who have purchased products from your partners to renew their subscriptions directly through 2Checkout or via your website. Partners will be credited for the initial subscription renewal and subsequent renewals, receiving commissions based on the Direct Renewal margins you control.

Requirements

Direct Renewal has two prerequisites.

  1. Your partners accept enrolment into the program.
  2. Partner-sold subscriptions have end-user information attached.

Availability

Channel Manager: You need to have the Channel Manager module activated. Contact 2Checkout directly if you would like to start taking advantage of the platform in your relationship with customers.

How does Direct Renewal work?

  1. Shoppers purchase your products from a company you partnered with.
  2. You enable Direct Renewal for partners and set Direct Renewal margins, specifying the margins you'll pay for the renewals made directly by end-users on your website or via 2Checkout.
  3. Partners accept the Direct Renewal program, add end-user information to subscriptions/licenses they sold, and configure a payment option used to pay their margins.
  4. 2Checkout will send Manual Renewal notifications to shoppers ahead of the expiration deadline of their subscriptions/licenses (according to the settings you used to configure email notifications for renewals on e-commerce). When contacting end-users directly based on the info attached, 2Checkout will prompt them to renew. If the renewal is successful, the partner will be credited based on the Direct Renewal margins. The email is sent in the shopper's language if the partner has also specified the communication language when inserting end-user data.
  5. When end users click the renewal link provided via email, they are redirected to your shopping cart, prefilled with their customer data and geo-localized according to their browser language.
    • If customers leave the shopping cart ahead of placing the order, their subscriptions will not be renewed directly and partners will be able to renew them themselves.
    • If customers place the renewal order but the payment fails or the order fails to reach the complete status, the subscription is transferred to eStore, just as if the item had been sold directly by you, and 2Checkout will start attempts to recover it per the unfinished payment settings in the leads management area of the Control Panel. Partners will no longer be able to renew these items themselves.
  6. When customers place renewal orders, they also get the option of enabling auto-renewal going forward.
  7. At the same time, end-users have the option of contacting you directly via your website and renew.
  8. After the renewal orders are placed, users receive all the notifications and support as if they would have purchased the product directly from you - including access to Customer portal - myAccount area for self-service (optional). Their subscriptions also behave the same as if they were acquired directly from you.
  9. 2Checkout tracks the source of the subscription/license renewal, and if the initial orders have been referred to by your partners, will credit the sale to their account and pay the margins per the Direct Renewal margins you configured.

Subscriptions continue to be renewed automatically by 2Checkout each billing cycle, or manually by customers after the initial direct renewal. Partners can no longer renew such subscriptions themselves or edit end-user information. However, they will continue to receive margins for each purchase throughout the duration of their partnership with you.

How to enable Direct Renewal?

You can enable Direct Renewal in two ways:

  1. Per partner
  2. Per partnership program

Enable Direct Renewal for a partner

  1. Go to Partner management -> Partners.
  2. Edit or create the partner for which you'll enable the Direct Renewal program and click to edit its details.
  3. Click on the Commercial Settings tab and scroll down to the Other settings area. Make sure that the Create individual settings option is selected under Partnership details.
  4. Check the checkbox next to the Enable Direct Renewal option.
  5. Scroll further down and in the Partner margin area, specify the Direct Renewal margins (the commission for renewals performed directly by 2Checkout or tracked via your website which were initially referred by partners).
    • You can set general margins, that will apply to all partner orders.
    • You also have the option of setting margins per product and groups of products.

When Direct Renewal is enabled it impacts all subscriptions referred by your partners. Leaving the Direct Renewal margins field empty or not defining margins for specific products or groups of products will result in zero partner margins for subscription renewed by customers directly via 2Checkout or through your website.

Click Save changes to make sure that the Direct Renewal is activated for this partner.

Note: Direct Renewal is an opt-in program, which means that once activated by you, partners need to accept enrollment.

Enable Direct Renewal for a partnership program

  1. Go to Partner management -> Partnership programs. 
  2. Identify or create the partnership program for which you'll enable the Direct Renewal program and click to edit its details.
  3. Click the Commercial Settings tab and scroll down to the Other settings area.
  4. Check the checkbox next to the Enable Direct Renewal option.
  5. Scroll further down and in the Partner margin area, specify the Direct Renewal margins (the commission for renewals performed directly by 2Checkout or tracked via your website which were initially referred by partners).
    • You can set general margins, that will apply to all partner orders.
    • You also have the option of setting margins per product and groups of products.

When Direct Renewal is enabled it impacts all subscriptions referred by your partners. Leaving the Direct Renewal margins field empty or not defining margins for specific products or groups of products will result in zero partner margins for subscription renewed by customers directly via 2Checkout or through your website.

Click Save changes to make sure that the Direct Renewal is activated for this partner.

Note: Direct Renewal is an opt-in program, which means that once activated by you, partners need to accept enrolment.

Partners are automatically notified via email when Direct Renewal is enabled for their accounts

The 2Checkout system is designed to provide automatic notifications to partners when you enable Direct Renewal for their accounts. Emails are sent:

  • To specific partners when Direct Renewal is activated for their standalone accounts.
  • To partners part of a partnership program when Direct Renewal is enabled for the entire program.
  • To partners, part of a partnership program when you swap their current program with Direct Renewal disabled for a new one with Direct Renewal enabled.

Email notifications are sent in bulk at specific intervals.

Disable Direct Renewal

To disable Direct Renewal for a partner or a partnership program, follow steps 1 through 3 mentioned above in each case, and uncheck the checkbox next to the Enable Direct Renewal option. Click Save changes for the modification to be applied.

F.A.Q.

  1. What happens when the direct renewal program is disabled?
    • End users that haven't done so already, will no longer be able to renew their subscriptions directly via your website or through 2Checkout, but only through the partner which referred the initial purchase. 2Checkout will continue to control the renewal process for all subscriptions already renewed directly and partners will no longer receive margins for future transactions.
  2. Where can I see subscriptions renewed directly by end-users as a result of the Direct Renewal program?
  3. Where can I see orders for subscriptions renewed directly by end-users?
    • Go to Orders and customers -> Order search and make sure the eStore tab is selected.
  4. What are the possible Direct Renewal statuses?
    • Pending: Waiting for partner enrollment.
    • Active: Partner for which Direct Renewal was enabled.
    • Inactive: Partners for which Direct Renewal is not enabled.
    • Denied: Partners that rejected enrollment.
  5. As a partner, do I lose control over subscription/license renewals if I accept enrollment into the Direct Renewal program?
    • By taking advantage of Direct Renewal you offer end-users the option to renew their subscriptions/licenses themselves, for those items that you don't want to renew yourself. While you will be able to access information on subscriptions/licenses renewed directly, as well as receive margins for each renewal, you will no longer be able to renew the subscription/license yourself or edit end-user information.

Tiered charges

Overview

Use tiered/scale pricing to create variable cost tiers (scales/intervals) impacting product unit price and provide cost benefits and incentives to shoppers to purchase large volumes. Tiered (scale) pricing configurations enable you to change the per-unit cost gradually for multiple tiers defined based on the quantities purchased.

Example of a product with a flat charge of $100:

Quantity interval Cost per unit
1 to 3 $100
3 to 6 $90
7 to 10 $80

For this example, a shopper purchasing 6 units would pay 90*6= $540 on top of the $100 flat charge, or $640 in total.

Availability

Requirements

Set up tiered (scale) charges

To add a usage component to a subscription you need to create a new pricing options group for metered resources. 

  1. Navigate to Products under Setup, search for or add/import the product you want to set usage pricing, and click to edit it.
  2. Select the Pricing tab and click to Edit the Pricing configuration that will be used to define usage costs.
  3. On the editing screen of the pricing configuration, scroll down to the bottom and click on Create new pricing options group in the Pricing options groups area.
  4. Enter the Group name (Required) - this label is displayed to shoppers in the cart and is included on invoices. 
  5. Enter the Group description (Optional) - This text is displayed to shoppers in the cart and is included on invoices. 
  6. Select the type: Scale - Regular - for a tiered charge.
  7. Enter a unique alphanumeric/string code (Required) - this is an identifier used in the 2Checkout API, product import/export, and for Buy Links query parameters.
  8. Add the first scale.
  9. Specify the interval.
  10. Define impact on price per unit of tiered/metered resources (available only for products with dynamic pricing (with base price) configurations).
  11. Add - add a specific cost for each unit of tiered/metered resource in each available currency for your account. 
  12. Subtract - subtract a specific price for each unit of tiered/metered resource.
  13. Define impact on subscription lifecycle
  14. Adds - Add the desired number of months to the default billing cycle interval of a subscription. Adding one month to a monthly subscription purchased on April 22nd pushes the expiration/renewal deadline to June 22nd. 
  15. Subtracts - Subtract the desired number of months to the default billing cycle interval of a subscription. Subtracting 12 months from a 2-year subscription purchased on April 22nd, 2016, pushed the expiration/renewal deadline to April 22nd, 2017 instead of April 22nd, 2018. 
  16. Non-recurring - Increase the lifetime of a subscription indefinitely at the moment of purchase, making it evergreen. 
  17. When you're done defining the scale usage intervals click Save group. Localization: To localize the usage pricing options group to another market, select the desired language from the list of options available for your account, and repeat the steps described above.
  18. The newly created pricing options group is available on the pricing configuration edit page. Scroll down to the bottom of the screen to identify it by the unique name you assigned to it in the Available pricing options groups area and click the Use with this product link.
  19. Hit Save to associate the usage pricing options group with the pricing configuration you're editing.

Multiple scales

Take advantage of multiple variable pricing scales/intervals for the same product. When defining the price for your offerings, you'll be able to create multiple scale pricing options groups and associate them to the same product. Once assigned to a product, the scaled pricing options group contribute to generating the price of purchases, per the offering's configuration, in accordance with the options selected by the shopper.

  1. Products With a base price configuration can feature as many scale pricing options groups as you wish. However, only the use of a single usage pricing options group is supported at this point in time.
  2. Products Without a base price configuration can feature only a single scale pricing options group and do not support the use of usage pricing options groups.

 

 

Product With a base price

Product Without a base price

Number of scale pricing options

Unlimited

1

Number of usage scale pricing options

1

Not available

 

 

Multiple scales use cases

2Checkout's multiple scale capabilities can be used to create complex pricing schemas designed to control the costs paid by customers through the use of a multi-tiered charge model.

1. In the example below, a customer purchasing a single subscription for 15 seats and including 200 support calls will pay $150 + $800 on top of the offering's default price.

Product/Service

Pricing

Scale intervals

Impact on price per unit

Number of seats

1 to 10

Do nothing

11 to 50

Add $10 per unit

51 to 100

Add $8 per unit

Support calls

1 to 100

Add $5 per unit

101 to 500

Add $4 per unit

500 to 2000

Add $3 per unit

 

2. In the example below, a customer purchasing a subscription for 5 users, with a total of 200GB of storage, allowing the synching of 15 devices, will pay $450 + $1.600 + $3.450.

 

Product/Service

Pricing

Scale intervals

Impact on price per unit

Number of users

1 to 3

Add $100 per unit

4 to 10

Add $90 per unit

11 to 20

Add $80 per unit

GBs of storage used

1 to 25

Do nothing

26 to 50

Add $10 per unit

51 to 100

Add $9 per unit

101 to 500

Add $8 per unit

No. of synchronized devices

1 to 12

Add $250 per unit

13 to 29

Add $230 per unit

30 to 50

Add $200 per unit

Scale Pricing vs. Volume discounts

Unlike Volume discounts, focused exclusively on decreasing the cost per unit as the number of items added to cart increases, Scale Pricing involves multiple parameters unrelated to the actual volume of products your customers orders. Use Volume discounts to lower the price per unit for orders containing large quantities of your product.

Leverage scale pricing options to also reduce the price per unit, but in relation to variables beyond quantity, such as the number of seats/users/PCs for a single product subscription.

The two pricing options share the same core concept, namely the more customers buy the less they pay per unit, but control completely different factors, and can in fact be used in concert for the same order.

Scale pricing option parameters in Buy Links

Let's assume that you created a Users scale pricing options group with the unique code: users, and two options: 1 to 10 ($99 per user) and 11 to 50 ($88 per user).

If you want to build the Buy Link for a product using the Users scale pricing options group and charge customers for 35 users, the parameter should be formatted as such: OPTIONS=users=35, including both the unique code of the pricing options group and the specific value of the scale pricing interval.

FAQ

Can I modify scale pricing options?

All pricing scales you created are available in the Pricing options groups area under the Pricing tab for all of your products.

You can always select the Group name / label in order to access an overview of the options, and click on edit to alter the values as needed. Always make sure to save the group once you introduced modifications.

 

Can the same pricing scale be applied to different products?

Yes. But please keep in mind that the settings for a pricing scale are global, so if you edit them for one product, they will be automatically impact all others that they're associated with.

 

Can I delete a pricing scale?

No. Existing pricing group options, including scale intervals, can only be deactivated per product, and will no longer impact the price of that specific item.

Consider overhauling unused, irrelevant or obsolete pricing group options by changing all parameters including Group name, Group description, and options type, in order to obtain completely new options. Reusing older pricing options groups is as easy as editing them, and this recycling process ensures that the Pricing options groups area never gets too crowded.

 

What happens when a customer chooses a Scale interval I haven't defined?

Only the pricing intervals that you configure will be available to your customers. They won't be able to select a scale interval that has not been configured for a specific product.

 

What's the difference between Scale Pricing and Volume Discounts? 
Volume discounts are financial incentives you can offer customers that acquire large quantities of your products (multiple units). Buyers are incentivized to buy more through price discounts that increase proportionally with the volume of their order.

Scale pricing enable you to offer your customers the possibility of correlating financial incentives with product utilization, by associating the subscriptions they purchase with large numbers of users, seats, PCs, etc. The pecuniary rewards available with scale pricing extend beyond buying in bulk, to shoppers acquiring a single subscription for use by a large volume of users, or for multiple seats/PCs, etc., for example.

 

Why should I use Scale pricing and not Volume discounts?

It really depends on the customer needs you're trying to meet. With Volume discounts you can offer, let say, 20 subscriptions at a slashed price. With Scale pricing you allow them to buy a single subscriptions but for 20 users/seats. But also 20 subscriptions, each for 20 users. It's really up to you what pricing configuration to use, 2Checkout just makes sure you have more options in this regard than any other platform on the market.

Need help?

Do you have a question? If you didn’t find the answer you are looking for in our documentation, you can contact our Support teams for more information. If you have a technical issue or question, please contact us. We are happy to help.

Get in touch

Not yet a Verifone customer?

We’ll help you choose the right payment solution for your business, wherever you want to sell, in-person or online. Our team of experts will happily discuss your needs.

Contact sales Get Started
Verifone logo