Subscription import
Overview
Add/import subscriptions in the Avangate system. Include card data with your subscription import only if you contacted Avangate to enable this functionality for your account. Otherwise, the import process results in a failure. Contact Avangate or your account manager directly for more details.
Attributes
Parameters | Type/Description | |||
---|---|---|---|---|
ExternalSubscriptionReference |
Required (string) |
|||
|
Unique identifier for your subscription. Mandatory when importing subscription data. |
|||
StartDate |
Required (string) |
|||
|
Subscription start date(YYYY-MM-DD) - StartDate is mandatory when importing subscription data. If you changed the time zone for the Avangate API by editing system settings under Account settings, then the StartDate you provide must be in accordance with your custom configuration. |
|||
ExpirationDate |
Required (string) |
|||
|
Subscription expiration date(YYYY-MM-DD) - ExpirationDate is mandatory when importing subscription data. If you changed the time zone for the Avangate API by editing system settings under Account settings, then the ExpirationDate you provide must be in accordance with your custom configuration. |
|||
Product |
Required (object) |
|||
|
The product for which Avangate generated the subscription. Details below. |
|||
|
ProductCode |
String |
||
|
|
Unique product identifier that you control. |
||
|
ProductId |
Int |
||
|
|
Unique, system-generated product identifier. |
||
|
ProductName |
String |
||
|
|
Product name. |
||
|
ProductQuantity |
Int |
||
|
|
Ordered number of units. |
||
|
ProductVersion |
String |
||
|
|
Product version. |
||
|
PriceOptionCodes |
Array |
||
|
|
The product options codes the customer selected when acquiring the subscription. Pricing options codes are case sensitive. |
||
EndUser |
Required (object) |
|||
|
The end user of the subscription. Details below. |
|||
|
Person |
Object |
||
Details below. | ||||
|
|
FirstName |
String |
|
|
|
|
End user's first name |
|
|
|
LastName |
String |
|
|
|
|
End user's last name |
|
|
|
CountryCode |
String |
|
|
|
|
End user country code [ISO3166-1 Alpha 2]. |
|
|
|
State |
String |
|
|
|
|
End user state. |
|
|
|
City |
String |
|
|
|
|
End user city. |
|
|
|
Address1 |
String |
|
|
|
|
End user first address line. |
|
|
|
Address2 |
String |
|
|
|
|
End user second address line. |
|
|
|
Zip |
String |
|
|
|
|
End user zip code. |
|
|
|
|
String |
|
|
|
|
End user email address. |
|
|
|
Phone |
String |
|
|
|
|
End user phone number. |
|
|
|
Company |
String |
|
|
|
|
Company name. |
|
|
Fax |
String |
||
|
|
End user fax. |
||
|
Language |
String |
||
|
|
Language [ISO639-2] the Avangate system uses for communications. |
||
DeliveryInfo |
Optional (object) |
|||
|
The object contains information about the delivery/fulfillment made to the customer. |
|||
|
Description |
String |
||
|
|
Delivery description. |
||
|
Codes |
Array of objects |
||
Details below. | ||||
|
|
Code |
String |
|
|
|
|
Delivered activation key/code. |
|
|
|
Description |
String |
|
|
|
|
Code description for dynamic lists from your key generator. |
|
|
|
ExtraInfo |
Object |
|
|
|
|
Info set by your key generator for dynamic lists only. |
|
|
|
|
CodeExtraInfo |
Object |
|
|
|
Type |
String |
|
|
|
Label |
String |
|
|
|
Value |
String |
|
|
File |
Array of objects |
|
Details below. | ||||
|
|
|
Content |
String |
|
|
|
|
Content of the file (base64 encoded). |
|
|
|
ContentLength |
Int |
|
|
|
|
File size. |
|
|
|
Filename |
String |
|
|
|
|
The name of the delivered file. |
|
|
|
FileType |
String |
|
|
|
|
The type of the delivered file. |
PartnerCode |
Optional (string) |
|||
|
|
|||
ExternalCustomerReference |
Optional (string) |
|||
|
Customer identifier you control. |
|||
SubscriptionValue |
Optional (double) |
|||
|
Subscription value. The total costs incurred by the customer through the lifecycle of the subscription before you imported the item into the Avangate system. When you send this parameter you must accompany it by ValueCurrency. |
|||
SubscriptionValueCurrency |
Optional (string) |
|||
|
Mandatory when you also send the Value parameter. The currency associated to the subscription value. |
|||
AdditionalInfo |
Optional (string) |
|||
|
Extra information that you can attach to a subscription, such as the source of the initial purchase. |
|||
NextRenewalPrice |
Optional (double) |
|||
|
The future costs that subscribers would incur when their subscriptions are renewed. When provided, you must accompany it by NextRenewalPriceCurrency and CustomPriceBillingCyclesLeft. |
|||
NextRenewalPriceCurrency |
Optional (string) |
|||
|
Mandatory when you send CustomPriceBillingCyclesLeft. The currency associated with the subscription next renewal price value. |
|||
CustomPriceBillingCyclesLeft |
Optional (string) |
|||
|
Mandatory when you send NextRenewalPrice. Avangate applies the next renewal price to the number of billing cycles you define. |
|||
Test | Optional (integer) | |||
Available only for eStore subscriptions. Use 1 to import a test subscription. Exclude the parameter or set the value to 0 to import regular subscriptions. Test subscriptions enable you to try out flows like manual and auto renewal, and upgrade. | ||||
CardPayment |
Optional (object) |
|||
|
Include payment (credit/debit card) information that Avangate uses for recurring billing to renew imported subscriptions. Importing subscriptions with payment data is available only to eligible Avangate accounts. Contact Avangate directly for additional details. |
Card payment
Add credit/debit card details when importing subscriptions. Avangate uses payment information in the recurring billing process.
For imports of test subscriptions, use the credit card information from this article.
Parameters | Type/Description |
---|---|
CardPayment |
Object |
CardNumber |
Required (string) |
|
The credit/debit card number. |
CardType |
Required (string) |
|
VISA, VISAELECTRON, MASTERCARD, MAESTRO, AMEX, DISCOVER, DANKORT, CARTEBLEUE, JCB. |
ExpirationYear |
Required (string) |
|
The year in which the card expires. |
ExpirationMonth |
Required (string) |
|
The month in which the card expires. |
HolderName |
Required (string) |
|
Card holder name. |
CCID |
Required (string) |
|
Credit Card Identification - an extra ID printed on the card, usually a 3-4 digit number, the CVC2/CVV2. |
HolderNameTime |
Required (int) |
|
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. |
AutoRenewal |
Optional (bool) |
|
True or false, depending on whether the customer or you enabled or disabled subscription auto-renewals. |
CardNumberTime |
Optional (int) |
|
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. |
Offline payments guidance
Use the variables in the list below to customize the Offline payments guidance shopper email according to your needs. Check the 'Mandatory' column to see the variables that are required in your customized version of the e-mail.
Variable name | Description | Test value | Mandatory |
---|---|---|---|
ADDRESS1 | First section of the delivery address | [123, Main Street] | No |
ADDRESS1_D | First section of the delivery address | [123, Main Street] | No |
ADDRESS2 | Second section of the delivery address | 0 | No |
ADDRESS2_D | Second section of the delivery address | 0 | No |
AVANGATE_LOGO | Avangate logo URL | https://secure.avangate.com/images/e...endor_logo.png | Yes |
BANKACCOUNT | Avangate bank account | [123456789] | No |
BANKIBAN | Avangate bank IBAN | [XX12XXXX12345678] | No |
BANKNAME | Avangate bank name | [Bank Name] | No |
BANKROUTINGNUMBER | Avangate bank routing number | [12345678] | No |
BANKSWIFT | Avangate bank swift code | [SWIFTXXXXX] | No |
BOLETO_SLIP_URL | URL pointing to Boleto slip | 0 | No |
BUSINESS_CITY | Avangate city | 0 | No |
BUSINESS_COMPANY | Avangate company name | [Avangate] | Yes |
BUSINESS_COUNTRY | Avangate country | 0 | No |
BUSINESS_FAX | Avangate fax number | 0 | No |
BUSINESS_HOTLINE | Avangate support phone | 0 | No |
BUSINESS_OPEMAIL | Avangate operational email address | 0 | No |
BUSINESS_OPFAX | Avangate operational fax number | 0 | No |
BUSINESS_PHONE | Avangate phone number | 0 | No |
BUSINESS_REG_NUMBER | Avangate registration number | 0 | No |
BUSINESS_STATE | Avangate state | 0 | No |
BUSINESS_STREET | Avangate street address | 0 | No |
BUSINESS_SUPEMAIL | Avangate support email address | support@avangate.com | No |
BUSINESS_VAT_ID | Avangate tax id | 0 | No |
BUSINESS_ZIP | Avangate ZIP code | 0 | No |
CBANKACCOUNT | Shopper's bank account used on the billing information | 0 | No |
CBANKNAME | Shopper's bank name used on the billing information | 0 | No |
CITY | Shopper's city used on the billing information | [Anytown | No |
CITY_D | Shopper's city used on the delivery information | [Anytown | No |
COMMERCIALNAME | Merchant's commercial name | [Software Company Name] | No |
COMPANY | Shopper's company name used on the billing information | [Customer company] | No |
COMPANY_D | Shopper company name used on the delivery information. If no delivery information is available. no company name is displayed. | [Customer company] | No |
COUNTRY | Shopper's country used on the billing information | [U.S.A] | No |
COUNTRY_D | Shopper's country used on the delivery information | [U.S.A] | No |
CURRENCY | Order billing currency | USD] | Yes |
CURRENCY_ORIGINAL | Original order currency (applicable to refunds) | 0 | No |
CUSTOMEREMAIL | Shopper's email address used on the billing information | example@customer-email.com | No |
DELIVERABILITY | Order delivery status | 0 | No |
DELIVRABILITY | The delivery status of the loaded order | 0 | No |
ENCRYPTED_MERCHANT_CODE | Encrypted merchant code | XXXXXXX | No |
FIRSTNAME | Shopper's first name used on the delivery information | [John | No |
FIRSTNAME_D | Shopper's first name used on the delivery information | [John | No |
FISCALCODE | Shopper's fiscal code used on the billing information | 0 | No |
GENERALTOTAL | Total order price | [56.50 | Yes |
GLOBALDISCOUNT | Order total discount | [3.00 | No |
HAS_BACKUPCD | Order has CD delivery | 1 | No |
HAS_RENEWAL_PRODUCTS | Flag that indicates whether at least one product has renewal settings | 0 | No |
HOTLINE_NUMBER | 0 | 0 | No |
HOTLINE_NUMBERS.NG_PHONE[index1] | 0 | 0 | No |
HOTLINE_NUMBERS.NG_PHONE[index1].HotlineName | Countries where Avangate support information is available. | 0 | No |
HOTLINE_NUMBERS.NG_PHONE[index1].HotlineValue | Avangate phone number(s) for shopper support. | 0 | No |
IDCOUNTRY | ID for shopper's country used on the billing information | 0 | No |
IS_RENEWAL | Flag that indicates whether at least one product has renewal settings | 0 | No |
LASTNAME | Shopper's last name used on the delivery information | Doe] | No |
LASTNAME_D | Shopper's last name used on the delivery information | Doe] | No |
LINK2UPLOADPOFILE | Link to the uploaded file when the order has been made | https://secure.avangate.com | No |
NAMES_OF_PRODUCTS | Names of all products in the order, comma separated | 0 | No |
ORDERDATE | Order placement date | [2011-01-01] | Yes |
ORDERFLOW | The purchase flow used to place the order | 0 | No |
ORDER_AMOUNT_ORIGINAL | Original order value (applicable to refunds) | 0 | No |
ORDER_CONF_PDF_URL | Download link for the order confirmation document | 0 | No |
ORDER_DATE_STANDARD_FORMAT | Standard format used for the order placement date | 0 | No |
ORDER_FLOW | Purchase flow used to place the order | 0 | No |
ORDER_STATUS | Order status | 0 | No |
PAYABLE_TO | Payee name (applicable to wire transfer) | [Avangate] | No |
PAYMENT_REFERENCE | Payment reference for wire transfer | 0 | No |
PAYMENT_TYPE_INFO | English payment method name. Includes last four card digits (if applicable). | 0 | No |
PAYTYPE | Identification number for the payment method selected during ordering process | 15 | No |
PAY_BY_CHECK_ADDRESS1 | Avangate address (first section) to be used by shoppers selecting check as payment method | 0 | No |
PAY_BY_CHECK_ADDRESS2 | Avangate address (second section) to be used by shoppers selecting check as payment method | 0 | No |
PAY_BY_CHECK_CITY | Avangate city to be used by shoppers selecting check as payment method | 0 | No |
PAY_BY_CHECK_COMPANY | Avangate company name to be used by shoppers selecting check as payment method | 0 | No |
PAY_BY_CHECK_COUNTRY | Avangate country to be used by shoppers selecting check as payment method | 0 | No |
PAY_BY_CHECK_STATE | Avangate state to be used by shoppers selecting check as payment method | 0 | No |
PAY_BY_CHECK_STREET | Avangate street name to be used by shoppers selecting check as payment method | 0 | No |
PAY_BY_CHECK_ZIP | Avangate ZIP code to be used by shoppers selecting check as payment method | 0 | No |
PHONE_D | Shopper's phone number used on the delivery information | [555-555-555] | No |
PRODUCTS | 0 | No | |
PRODUCTS[index1].DISCOUNT | Product discount value per product line | [2.00 | No |
PRODUCTS[index1].INFO | Additional product information defined by merchant when generating buy links | [Product info 1] | No |
PRODUCTS[index1].LICENSE_TYPE | Type of purchased subscription | 0 | No |
PRODUCTS[index1].PCODE | Product code. | [P_CODE_1] | No |
PRODUCTS[index1].PID | Product ID number | 1001 | No |
PRODUCTS[index1].PNAME | Product name | [Test product name 1] | No |
PRODUCTS[index1].PRICE | Product unit price | [20.00 | No |
PRODUCTS[index1].PROMONAME | Name of the promotion applied to the product | [Some promotion] | No |
PRODUCTS[index1].QUANTITY | Purchased product quantity | [2] | No |
PRODUCTS[index1].SHORT_DESCRIPTION | Short product description | 0 | No |
PRODUCTS[index1].TOTAL | Total gross price per product line (before applying discounts) | [45.60 | No |
PRODUCTS[index1].VAT | VAT/Sales tax value per product line | [3.80 | No |
PRODUCTS_DATA[index1].IdProduct | Product ID number | 0 | No |
PRODUCTS_DATA[index1].PRODUCT_SHORT_DESCRIPTION | Short product description | 0 | No |
PRODUCTS_NO | Number of products in cart | 0 | No |
PRODUCT_OPTIONS[index1][index2] | 0 | 0 | No |
PRODUCT_OPTIONS[index1][index2].OptionText | 0 | 0 | No |
PURCHASEORDERDATA | 0 | 0 | No |
PURCHASEORDERDATA.POrderExtendedData | 0 | 0 | No |
PURCHASEORDERDATA.POrderExtendedData.PurchaseOrderDelay | Number of days for the shopper to make the payment (starting with the moment the Purchase Order was approved by the merchant) | 0 | No |
PURCHASEORDERDATA.POrderExtendedData.PurchaseOrderMaxDate | Date when the Purchase Order expires | 0 | No |
PURCHASEORDERDATA.POrderExtendedStatus | Status of the Purchase Order | 0 | No |
QR_CODE_SRC | The QR code URL to be used for payments with bank/wire transfer. | 0 | No |
REFNO | Order reference number | [9xxxxxx] | Yes |
REGISTRATIONNUMBER | Shopper's registration number used on the billing information | 0 | No |
RETRYLINK | Payment retry link | 0 | No |
RETRY_LINK | Payment retry link | 0 | No |
SELLERCOMPANY | Merchant's company name | 0 | No |
SHIPPING | Shipping fee amount | [0.00 | No |
SHOPPER_REFERENCE_NUMBER | Shopper reference number | PO12345 | No |
STATE | Shopper's state used on the billing information | Anystate | No |
STATE_D | Shopper's state used on the delivery information | Anystate | No |
SUBTOTAL | The order amount without vat and shipping | [56.50 | No |
SUPPORTEMAIL | Merchant support email address | 0 | No |
TOTALEQUIV | The order amount converted to all the merchant's currencies | 0 | No |
UPLOADLINK | File upload link | 0 | No |
UPLOAD_LINK | File upload link | 0 | No |
WEBSITE | Website where the shopper placed the order | http://www.software-company-website.com | Yes |
ZIPCODE | Shopper's ZIP code used on the billing information | 12345] | No |
ZIPCODE_D | Shopper's ZIP code used on the delivery information | 12345] | No |
Refund an order
Overview
Refund a sale made in 2Checkout via the issueRefund API method. You can issue a refund for only a sale line item, issue a partial refund on the total amount, or refund the entire order amount.
Requirements
The payment for the refundable order needs to be collected.
You cannot issue a refund for an amount higher than the total order amount.
Parameters
Parameters | Type/Description | |
---|---|---|
RefNo |
String / Required The order reference number of the sale for which the refund is issued. Example: '721924012'. |
|
Amount |
Double / Required Refundable amount. Required as a supplementary check for partial refunds. Example: '26.00'. |
|
Comment |
String / Optional Comments are displayed to customers in the refund confirmation they receive. Example: 'Let us know if you are satisfied with the refund process'. |
|
Reason |
String / Required In case you have custom refund reasons defined on your account, send one of the reasons. If not, send one of the platform defined reasons. Read more about 2Checkout refund reasons. Example: 'Unwanted auto-renewal'. |
|
Items |
Array / Required only for partial refunds In case you issue a partial refund, send the array with the information below. |
|
ProductCode |
String / Required Send the product code belonging to the products to be refunded. The product code is available at product level, in the Information tab. |
|
Quantity |
Integer / Required Quantity to be refunded. Send only positive values. |
|
Amount |
Double / Required Total amount of the refunded line item, not the unit amount. |
Subscription import
Overview
Add/import subscriptions in the 2Checkout system. Include card data with your subscription import only if you contacted 2Checkout to enable this functionality for your account. Otherwise, the import process results in a failure. Contact 2Checkout or your account manager directly for more details.
Parameters
Parameters | Type/Description | |||
---|---|---|---|---|
ExternalSubscriptionReference |
Required (string) |
|||
|
Unique identifier for your subscription. Mandatory when importing subscription data. |
|||
StartDate |
Required (string) |
|||
|
Subscription start date(YYYY-MM-DD) - StartDate is mandatory when importing subscription data. If you changed the time zone for the 2Checkout API by editing system settings under Account settings, then the StartDate you provide must be in accordance with your custom configuration. |
|||
ExpirationDate |
Required (string) |
|||
|
Subscription expiration date(YYYY-MM-DD) - ExpirationDate is mandatory when importing subscription data. If you changed the time zone for the 2Checkout API by editing system settings under Account settings, then the ExpirationDate you provide must be in accordance with your custom configuration. |
|||
Product |
Required (object) |
|||
|
The product for which 2Checkout generated the subscription. Details below. |
|||
|
ProductCode |
String |
||
|
|
Unique product identifier that you control. |
||
|
ProductId |
Int |
||
|
|
Unique, system-generated product identifier. |
||
|
ProductName |
String |
||
|
|
Product name. |
||
|
ProductQuantity |
Int |
||
|
|
Ordered number of units. |
||
|
ProductVersion |
String |
||
|
|
Product version. |
||
|
PriceOptionCodes |
Array |
||
|
|
The product options codes the customer selected when acquiring the subscription. Pricing options codes are case sensitive. |
||
EndUser |
Required (object) |
|||
|
The end user of the subscription. Details below. |
|||
|
Person |
Object |
||
Details below. | ||||
|
|
FirstName |
String |
|
|
|
|
End user's first name |
|
|
|
LastName |
String |
|
|
|
|
End user's last name |
|
|
|
CountryCode |
String |
|
|
|
|
End user country code [ISO3166-1 Alpha 2]. |
|
|
|
State |
String |
|
|
|
|
End user state. |
|
|
|
City |
String |
|
|
|
|
End user city. |
|
|
|
Address1 |
String |
|
|
|
|
End user first address line. |
|
|
|
Address2 |
String |
|
|
|
|
End user second address line. |
|
|
|
Zip |
String |
|
|
|
|
End user zip code. |
|
|
|
|
String |
|
|
|
|
End user email address. |
|
|
|
Phone |
String |
|
|
|
|
End user phone number. |
|
|
|
Company |
String |
|
|
|
|
Company name. |
|
|
Fax |
String |
||
|
|
End user fax. |
||
|
Language |
String |
||
|
|
Language [ISO639-2] the 2Checkout system uses for communications. |
||
DeliveryInfo |
Optional (object) |
|||
|
The object contains information about the delivery/fulfillment made to the customer. |
|||
|
Description |
String |
||
|
|
Delivery description. |
||
|
Codes |
Array of objects |
||
Details below. | ||||
|
|
Code |
String |
|
|
|
|
Delivered activation key/code. |
|
|
|
Description |
String |
|
|
|
|
Code description for dynamic lists from your key generator. |
|
|
|
ExtraInfo |
Object |
|
|
|
|
Info set by your key generator for dynamic lists only. |
|
|
|
|
CodeExtraInfo |
Object |
|
|
|
Type |
String |
|
|
|
Label |
String |
|
|
|
Value |
String |
|
|
File |
Array of objects |
|
Details below. | ||||
|
|
|
Content |
String |
|
|
|
|
Content of the file (base64 encoded). |
|
|
|
ContentLength |
Int |
|
|
|
|
File size. |
|
|
|
Filename |
String |
|
|
|
|
The name of the delivered file. |
|
|
|
FileType |
String |
|
|
|
|
The type of the delivered file. |
PartnerCode |
Optional (string) |
|||
|
|
|||
ExternalCustomerReference |
Optional (string) |
|||
|
Customer identifier you control. |
|||
SubscriptionValue |
Optional (double) |
|||
|
Subscription value. The total costs incurred by the customer through the lifecycle of the subscription before you imported the item into the 2Checkout system. When you send this parameter you must accompany it by ValueCurrency. |
|||
SubscriptionValueCurrency |
Optional (string) |
|||
|
Mandatory when you also send the Value parameter. The currency associated to the subscription value. |
|||
AdditionalInfo |
Optional (string) |
|||
|
Extra information that you can attach to a subscription, such as the source of the initial purchase. |
|||
NextRenewalPrice |
Optional (double) |
|||
|
The future costs that subscribers would incur when their subscriptions are renewed. When provided, you must accompany it by NextRenewalPriceCurrency and CustomPriceBillingCyclesLeft. |
|||
NextRenewalPriceCurrency |
Optional (string) |
|||
|
Mandatory when you send CustomPriceBillingCyclesLeft. The currency associated with the subscription next renewal price value. |
|||
CustomPriceBillingCyclesLeft |
Optional (string) |
|||
|
Mandatory when you send NextRenewalPrice. 2Checkout applies the next renewal price to the number of billing cycles you define. |
|||
Test | Optional (integer) | |||
Available only for eStore subscriptions. Use 1 to import a test subscription. Exclude the parameter or set the value to 0 to import regular subscriptions. Test subscriptions enable you to try out flows like manual and auto renewal, and upgrade. | ||||
CardPayment |
Optional (object) |
|||
|
Include payment (credit/debit card) information that 2Checkout uses for recurring billing to renew imported subscriptions. Importing subscriptions with payment data is available only to eligible 2Checkout accounts. Contact 2Checkout directly for additional details. |
Card payment
Add credit/debit card details when importing subscriptions. 2Checkout uses payment information in the recurring billing process.
For imports of test subscriptions, use the credit card information from this article.
Parameters | Type/Description |
---|---|
CardPayment |
Object |
CardNumber |
Required (string) |
|
The credit/debit card number. |
CardType |
Required (string) |
|
VISA, VISAELECTRON, MASTERCARD, MAESTRO, AMEX, DISCOVER, DANKORT, CARTEBLEUE, JCB. |
ExpirationYear |
Required (string) |
|
The year in which the card expires. |
ExpirationMonth |
Required (string) |
|
The month in which the card expires. |
HolderName |
Required (string) |
|
Card holder name. |
CCID |
Required (string) |
|
Credit Card Identification - an extra ID printed on the card, usually a 3-4 digit number, the CVC2/CVV2. |
HolderNameTime |
Required (int) |
|
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. |
AutoRenewal |
Optional (bool) |
|
True or false, depending on whether the customer or you enabled or disabled subscription auto-renewals. |
CardNumberTime |
Optional (int) |
|
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. |
Save prices
Overview
Use the savePrices method to update product prices for a specific pricing configuration.
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. |
Prices |
BasicPrice Object |
|
Details below. |
Quantities |
Object |
|
Details below. |
PriceOptions |
Required (PriceOptionsAssigned object) |
|
Details below. |
PricingConfigCode |
Required (string) |
|
System-generated unique pricing configuration code. Read-only. |
type |
Require (string) • REGULAR • RENEWAL |
Parameters | Type/Description |
---|---|
BasicPrice |
Object |
Currency |
String |
|
The currency ISO code used for shipping costs - ISO 4217. |
Amount |
Float |
|
Basic price. |
Parameters | Type/Description |
---|---|
Quantities |
Object |
MinQuantity |
String |
|
The minimum quantity of volume discounts. Default is 1. |
MaxQuantity |
String |
|
The maximum quantity of volume discounts. Default is 99999. |
Parameters | Type/Description |
---|---|
PriceOptionsAssigned |
Object |
Code |
String |
|
Price option identifier. |
Options |
Array of strings |
|
The pricing options group option code you configured that the 2Checkout system uses to calculate product prices for pricing configurations without a base price. |
Response
bool(true)
<?php
require ('PATH_TO_AUTH');
/**
* ProductCode = 'PDOWNFILE'
* Default currency: EUR
*
* Dynamic pricing configuration
*
* Send two prices, including the required one for the default currency
* The method will append the prices for the sent entries, without removing the previous values
*
* If the quantities intervals were not defined then they will be set.
* If the quantities overlap with existing defined intervals, an Exception will be thrown.
*/
// make call
$Prices = array();
$Price = new stdClass(); // BasicPrice object
$Price->Amount = 140;
$Price->Currency = 'USD';
$Prices[] = $Price;
$Price = new stdClass(); // BasicPrice object
$Price->Amount = 80;
$Price->Currency = 'EUR';
$Prices[] = $Price;
$Quantities = new stdClass(); // QuantityInterval object
$Quantities->MinQuantity = 1;
$Quantities->MaxQuantity = 10;
$PriceOptions = array();
$PricingConfigurationCode = '5553603382';
$type = 'regular';
$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'savePrices',
'params' => array($sessionID, $Prices, $Quantities, $PriceOptions, $PricingConfigurationCode, $type)
);
$response = callRPC((Object)$jsonRpcRequest, $host);
var_dump ($response);
// will output:
// bool(true)
/**
* ProductCode = 'PDOWNFILE'
* Default currency: EUR
*
* Flat pricing configuration
* Has the VOLTAGE pricing option group assigned and marked as required.
* If prices are sent WITHOUT setting the pricing option group and options will set the price but without setting values for the options prices.
*/
// Call the login method for authentication
$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; // counter for api calls
$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);
// make call
$Prices = array();
$Price = new stdClass(); // BasicPrice object
$Price->Amount = 80;
$Price->Currency = 'EUR';
$Prices[] = $Price;
// if PricingOption group is not required, will set price for combination of QuantityInterval - no-pricing-option-value.
$PriceOptions = array();
// if PricingOption group is required, then send options by assigning a PriceOptionsAssigned object (group code and options)
// $optionAssigned = new stdClass(); // PriceOptionsAssigned
// $optionAssigned->Code = 'VOLTAGE';
// $optionAssigned->Options = array('220V'); // radio option group
// $PriceOptions = array($optionAssigned);
$Quantities = new stdClass(); // QuantityInterval object
$Quantities->MinQuantity = 1;
$Quantities->MaxQuantity = 99999; // default maximum value
$PricingConfigurationCode = '54AA62CA31'; // flat pricing configuration
$type = 'regular';
$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'savePrices',
'params' => array($sessionID, $Prices, $Quantities, $PriceOptions, $PricingConfigurationCode, $type)
);
$response = callRPC((Object)$jsonRpcRequest, $host);
var_dump ($response);
/**
* ProductCode = 'PDOWNFILE'
* Default currency: EUR
*
* Flat pricing configuration
* Has the COLOR and scalenotmandatory pricing option group assigned and marked as required.
*/
// Call the login method for authentication
$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; // counter for api calls
$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);
// make call
$Prices = array();
$Price = new stdClass(); // BasicPrice object
$Price->Amount = 10;
$Price->Currency = 'EUR';
$Prices[] = $Price;
$optionAssigned = new stdClass(); // PriceOptionsAssigned
$optionAssigned->Code = 'COLOR'; // checkbox pricing option group, multiple values are allowed
$optionAssigned->Options = array('cyan', 'magenta');
$PriceOptions = array($optionAssigned);
$optionAssigned = new stdClass(); // PriceOptionsAssigned
$optionAssigned->Code = 'scalenotmandatory'; // interval pricing option group
$optionAssigned->Options = array('scalenotmandatory-1-5');
$PriceOptions = array($optionAssigned);
$Quantities = new stdClass(); // QuantityInterval object
$Quantities->MinQuantity = 1;
$Quantities->MaxQuantity = 99999; // default maximum value
$PriceOptions = array();
$PricingConfigurationCode = '54AA62CA31'; // flat pricing configuration
$type = 'regular';
$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'savePrices',
'params' => array($sessionID, $Prices, $Quantities, $PriceOptions, $PricingConfigurationCode, $type)
);
$response = callRPC((Object)$jsonRpcRequest, $host);
var_dump ($response);
?>
Orders with dynamic product information
Overview
Dynamic products are a mechanism designed to enable you to pass purchase information directly from your system into 2Checkout without first configuring the products in your Control Panel or via API. Bypass the need for handling 2Checkout's catalog products and create orders with product information sent dynamically via API or through ConvertPlus URL parameters. Receive payments from your customers by using the products defined in your own system, or in your shopping cart applications.
Availability
This functionality is available only for merchants on the 2Sell and 2Subscribe accounts (PSP business model), for orders that are placed both through ConvertPlus/InLine ordering engines and API calls.
Dynamic Products Parameters
2Checkout allows you to create orders and receive payments by using the following product types:
- PRODUCT - Item purchased by the customer. It is mandatory to send the name and price of the product item.
- Products can have pricing and recurring options assigned.
- Products can have pricing and recurring options assigned.
- TAX - Additional fee/charge that will be considered 'Tax' in the ordering process. Taxes may have recurring options assigned.
- SHIPPING - Item that contains the name and amount corresponding to the shipping method.
- COUPON - Item that contains the discount to be applied to the entire order.
Orders with dynamic information allow you to control, without an existing setup, the following product attributes:
- Price
- You have full control over the price applied to the purchase. Example: $20 price for product A.
- Product pricing options (together with name and prices)
- You can pass the pricing options information dynamically. Example: A pricing option named users that adds a surcharge of $5 for option 3-5 users, and $10 for option 5-10 users.
- Product purchase type
- Set the purchase type (tangible or intangible). Example: intangible for products delivered electronically.
- Recurring options
- Set the product recurring options that include the contract length and unit, cycle length and unit, and recurring amount to be charged. Example: a recurring charge of $20, on a monthly basis for the next 2 years.
Reporting dynamic products
Orders placed with dynamic product information are included in your account reports and can be found in your Order Search area of the Control Panel, and in the Products Reports based on which your sales invoices are generated.
Dynamic products are not displayed in the Products section of the 2Checkout Control Panel.
How to place orders with dynamic information
Orders with dynamic products via API
Place orders via 2Checkout's latest API version and send the product information as part of the call. Create orders with dynamic product information, that contain the following product types: product, tax, shipping, and coupon.
Requirements
Product code must be sent as null. The order currency must match the payment currency, otherwise, an error is thrown. The isDynamic parameter of the Items object must be true.
Limitations
Placing an order with both catalog and dynamic product information is not possible. Recurring options can be set only for purchase type PRODUCT and TAX.
How to test it?
You can place test orders via API with dynamic product information. Set the Payment details type to TEST in order to create an order in a test environment.
Place your first order with dynamic products
Read the documentation for guidance:
Orders with dynamic products via convertplus
Use ConvertPlus to create a dynamic ordering process by passing the product information to ConvertPlus through buy links parameters. With ConvertPlus dynamic ordering, you control the product name, price, recurring and pricing options, and many other product properties.
Learn more about ConvertPlus buy link parameters and dynamic ordering.
Alternatively, you can generate buy links for dynamic products directly from your Control Panel. Learn more about ConvertPlus dynamic ordering via Control Panel.
Search leads
Overview
Use the searchLeads method to retrieve leads created in the 2Checkout system.
Request Parameters
Parameters | Required | Type/Description |
---|---|---|
Page | Required | String. The page in the result set. |
Limit | Required | Number. The number of items to be retrieved on each page. |
Request Example
<?php
require ('PATH_TO_AUTH');
$LeadSearchInput = new stdClass();
$LeadSearchInput->Type = "New";
$LeadSearchInput->Language = "BG";
$LeadSearchInput->Country = "RO";
$LeadSearchInput->Page = 1;
$LeadSearchInput->Limit = 200;
$jsonRpcRequest = array (
'method' => 'searchLeads',
'params' => array($sessionID, $LeadSearchInput),
'id' => $i++,
'jsonrpc' => '2.0'
);
var_dump (callRPC((Object)$jsonRpcRequest, $host, true));
Response Example
class stdClass#4 (2) {
public $Items =>
class stdClass#5 (1) {
public $0 =>
class stdClass#6 (14) {
public $LeadCode =>
string(10) "60E6C4B574"
public $GeneratedFrom =>
string(3) "API"
public $CartId =>
string(11) "CartIdValue"
public $Currency =>
string(3) "EUR"
public $Language =>
string(2) "BG"
public $ExternalReference =>
string(18) "REST_API_3CHECKOUT"
public $MachineId =>
string(6) "123asd"
public $LocalTime =>
string(19) "2019-11-05 16:48:28"
public $Items =>
class stdClass#7 (1) {
public $0 =>
class stdClass#8 (15) {
public $Code =>
string(10) "04C26C50F8"
public $Quantity =>
string(1) "2"
public $SKU =>
NULL
public $Name =>
string(5) "softy"
public $Description =>
NULL
public $IsDynamic =>
bool(false)
public $Tangible =>
bool(false)
public $PurchaseType =>
string(7) "PRODUCT"
public $PriceOptions =>
NULL
}
public $RecurringOptions =>
class stdClass#10 (5) {
public $CycleLength =>
NULL
public $CycleUnit =>
NULL
public $CycleAmount =>
NULL
public $ContractLength =>
NULL
public $ContractUnit =>
NULL
}
public $RenewalInformation =>
class stdClass#11 (1) {
public $SubscriptionReference =>
NULL
}
public $MarketingCampaigns =>
class stdClass#12 (3) {
public $Type =>
string(2) "23"
public $ParentCode =>
string(1) "m"
public $CampaignCode =>
string(2) "23"
}
public $Price =>
class stdClass#13 (2) {
public $Amount =>
string(2) "20"
public $Type =>
string(6) "CUSTOM"
}
public $AdditionalFields =>
NULL
public $SubscriptionStartDate =>
string(19) "2019-11-05 16:48:28"
}
}
public $BillingDetails =>
class stdClass#14 (12) {
public $FirstName =>
string(8) "Customer"
public $LastName =>
string(9) "2Checkout"
public $Phone =>
NULL
public $Company =>
NULL
public $FiscalCode =>
string(8) "32423423"
public $Email =>
string(22) "customer@2checkout.com"
public $Address1 =>
string(12) "Test Address"
public $Address2 =>
NULL
public $City =>
string(2) "LA"
public $Zip =>
string(5) "12345"
public $CountryCode =>
string(2) "RO"
public $State =>
string(2) "CA"
}
public $DeliveryDetails =>
class stdClass#15 (12) {
public $FirstName =>
string(8) "Customer"
public $LastName =>
string(9) "2Checkout"
public $Phone =>
NULL
public $Company =>
NULL
public $FiscalCode =>
string(8) "32423423"
public $Email =>
string(22) "customer@2checkout.com"
public $Address1 =>
string(12) "Test Address"
public $Address2 =>
NULL
public $City =>
string(2) "LA"
public $Zip =>
string(5) "12345"
public $CountryCode =>
string(2) "RO"
public $State =>
string(2) "CA"
}
public $DeliveryInformation =>
class stdClass#16 (1) {
public $ShippingMethod =>
class stdClass#17 (1) {
public $Code =>
string(5) "sdfsd"
}
}
public $PaymentDetails =>
class stdClass#18 (4) {
public $Type =>
string(2) "CC"
public $Currency =>
string(3) "EUR"
public $PaymentMethod =>
class stdClass#19 (2) {
public $RecurringEnabled =>
bool(false)
public $CardPayment =>
class stdClass#20 (1) {
public $InstallmentsNumber =>
string(2) "23"
}
}
public $CustomerIP =>
string(7) "1.2.3.4"
}
public $Promotions =>
array(1) {
[0] =>
string(0) ""
}
}
}
public $Pagination =>
class stdClass#21 (3) {
public $Page =>
int(1)
public $Limit =>
int(200)
public $Count =>
int(1)
}
}
User roles
Overview
User privileges define the access level of your Merchant Control Panel users to specific 2Checkout features and modules.
A collection of privileges is called a user role. You can define your own user roles based on specific access levels that you want to grant to your users. You can assign multiple roles to a user.
You need to have two factor authentication enabled in order to add or edit information in the Settings area of your Merchant Control Panel.
Add/Edit users
Follow the steps below to add/edit new users:
- Log in to the 2Checkout Merchant Control Panel using your master account.
- Navigate to the Settings cogwheel in the top right corner.
- Click on User Management.
4. On the User Management page, click on Add user.
5. On the Add user page, fill in the new user account details: Username, Email, First name, Last name, Password, Password lifetime, User status, User role.
6. To edit a user, click on the Edit icon on the Users page.
7. Click Save.
User management options
- You can use the strong password generator that complies with the above requirements to make sure you're using a secure password.
- The user is required to change the password after the first login. This option is enabled by default.
- The reset password option allows you to disable the old password and the user will receive an e-mail for setting a new password.
- You can set passwords to expire in a number of days of your choosing. By default, passwords expire in 90 days.
- Passwords never expire invalidates the password expiration setting. Disabled by default.
Add/Edit user roles
Follow the steps below to add or edit user roles:
- Log in to the 2Checkout Merchant Control Panel using your master account.
- Navigate to the Settings cogwheel in the top right corner.
- Click on User Management.
- On the User Management page, click on the Roles tab.
- On the Roles page, click on Add role.
6. On the Add role page, fill in the role info (Role name, Role description), and then select the privileges you want to assign to that specific role.
7. To edit a role, click on the Roles tab and click on the Edit icon next to the role you want to change (see image at Step 5 above).
8. On the Edit role page, edit/change the role info (Role name, Role description) and then check or uncheck the privileges you want to assign to the role.
9. Click the green Save button at the bottom of the page to save/update the changes.
Assign user roles
Follow the steps below to assign roles to the existing users.
- Log in to the 2Checkout Merchant Control Panel using your master account.
- Navigate to the Settings cogwheel in the top right corner.
- Click on User Management.
- On the User Management page, click on the Users tab.
- Identify the user account that you want to assign a role to and click Edit.
6. On the Edit User page, you can update the User info and also assign/check a role to the user or change the role already assigned to that particular user.
7. Click Save to update changes.
Privileges
Setup
Privilege name | Description |
---|---|
Getting started | Allows users to access the Getting Started screen on the Dashboard and request the account to Go Live. |
Add/Edit products | Controls access to the Products area. |
Edit product pricing | Controls editing privileges of per-product pricing configurations. |
Gift products | Controls access gift product settings. |
Product Upgrade Settings | Controls access to the product upgrade settings. |
Electronic delivery | Controls access to product fulfillment settings. |
Download Insurance Service | Controls access to Download Insurance Service settings. |
Shipping | Controls access to product shipping options. |
Price lists | Controls access to product price list settings. |
Subscriptions | Controls access to subscription renewal settings. |
Generate links - eStore | Controls access to the buy link generation options. |
Interface templates - eStore | Controls access to the cart templates customization options. |
Order Additional Fields | Controls access to the additional order fields settings. |
Ordering options - settings | Controls access to Order settings. |
Ordering options - aftersale message | Controls access to the After-sale message settings. |
Ordering options - web analytics | Controls access to the Web analytics settings. |
Metered Billing | Controls access to usage billing settings. |
Manage Financial Settings | Controls access to the account's financial settings. |
Marketing Tools
Privilege name | Description |
---|---|
Affiliates Management | Controls access to the 2Checkout Affiliate Network settings. |
Promotions | Controls access to promotion settings. |
Cross-Selling and Up-Selling | Controls access to cross-selling and up-selling promotion settings. |
Email marketing program | Controls access to email marketing settings. |
Channel resources - affiliates | Controls access to affiliate channel resources. |
Channel resources - partners | Controls access to partner channel resources. |
Leads Management | Controls access to lead management settings. |
View Avangate Polls | Allows 2Checkout Control Panel polls to be displayed to users whose privileges are governed by the assigned role. Uncheck to hide polls from users. |
Email editor - email viewing rights | Allows users to see emails in the Email editor. |
Email editor - email editing rights | Allows users to edit emails in the Email editor. |
Retention tools |
Only accounts that have the Retention tools package enabled can see this privilege displayed. Allows users to view and manage retention campaigns, and provides access to Enrollment and Churn prevention reports. |
Orders & Reports
Privilege name | Description |
---|---|
Accounting | Controls access to Accounting, Vendor 2 Vendor, and Purchase Order settings. |
View and search eStore order data | Controls access to Order Search. |
Executive Reports |
Controls access to:
|
Business Dynamics | Controls access to Custom Reports. |
Promotions Reports | Controls access to marketing reports. |
A/B Testing | Controls access to A/B testing campaign settings. |
Aggregate Reports | Allows the aggregation of report data from multi-accounts. |
Customer support - eStore | Grants limited order search options for customer support agents. |
Partner order search | Allows users to search and view partner orders. |
Customer support - partners | Grants limited partner order search options for customer support agents. |
Delivery confirmations | Controls access to Fulfillment confirmation settings. |
Proforma payment confirmation | Allows users to confirm proforma payments for direct partner payments. |
Manage order refunds | Allows users to request refunds or order cancelations. Use in conjunction with the Customer support privileges to enable access to order data. |
Access refund requests area | Allows access to the Refunds section, listing all refund requests. Use in conjunction with Manage order refunds and Customer support privileges to enable editing privileges. |
Customers | Controls access to customer management settings. |
Blank & partial searches for eStore | Allows blank and partial order searches. |
Affiliates Reports | Controls access to Top Affiliates and Affiliate Sales reports. |
Vendor to Affiliate Payments | Allows users to make payments to top-performing affiliates. |
API Logs | Controls access to API & webhooks log monitor reports. |
Enable delivery confirmation approval | Allows users to approve/reverse orders that require vendor delivery confirmation. |
Renewal Authorizations Report | Allows users to generate, view, and export authorization reports. |
Restrict export customer details | Allows users to get every detail in the order search export (using the full option template) when disabled. |
Cohorts Reports | Allows users to generate, view, and export cohort reports. |
Subscription Management | Controls access to subscription management settings. |
Subscription Pricing | Controls access to the Update credit card and Change current billing amount options. Use in conjunction with the Subscription Management privilege. |
Partner Reports | Controls access to the Top Partners report. |
Place orders on behalf of customers | Allows users to place orders on behalf of customers. |
Additional fields report | Controls access to the Additional fields report. |
Users Activity | Controls access to the Users Activity report. |
Delete user comments | Allows users to delete their own comments from orders. |
Account Settings
Privilege name | Description |
---|---|
Account information | Controls access to the Account information section. |
User roles management | Controls access to user roles management settings. |
Users management | Controls access to user management settings. |
System settings | Controls access to system settings, such as time zone, IPN, LCN, and other notifications. |
Financial information | Allows users to manage bank and payment information. |
Salesforce settings | Controls access to Salesforce integration settings. |
Partner Management
Privilege name | Description |
---|---|
Restrict to own partners | Limits user access to partner accounts where they are assigned as account managers or backup account managers. |
Proforma invoices | Controls access to partner invoices. |
Partners management | Controls access to partner management settings. |
Partnership programs management | Controls access to partner programs settings. |
Place order | Allows users to place orders on behalf of partners. |
Receive order notification | Allows users to receive notifications from partner orders. |
Refund management | Allows users to manage partner refunds. |
Refund history | Allows users to see previous partner refund requests. |
Third-Party Apps
Privilege name | Description |
---|---|
Use a third-party app | Allows users to use third-party apps. |
Manage third-party apps | Controls access to third-party apps settings. |