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 |
||
|
|
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 |
||
|
|
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 |
|
|
|
|
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. |
|||
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.`
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. |
Custom store domain for the checkout process
Overview
Use a custom domain to increase your conversion rate:
- Provide your shoppers with a seamless transition from your store or website to checkout.
- Give customers a sense of extra security during the checkout process by purchasing a store domain and SSL certificate.
- Enhance the shopping cart experience with your custom branding elements.
A custom store domain allows you to change the URL of your checkout pages from secure.2checkout.com to mystore.mycompany.com.
Requirements
Contact 2Checkout for availability.
Set up a store domain
To set up a custom store domain, follow these steps:
1. Contact 2Checkout to request a custom domain and choose a domain name.
Contact our Sales team to discuss the terms of your custom domain agreement. Don't forget to choose a domain name for your online store. Most common examples of online store web addresses are:
- https://estore.[your_company_name].com
- https://shop.[your_company_name].com
- https://store.[your_company_name].com
- https://secure.[your_company_name].com
2. Provide your company details.
Following your discussion with our Sales team, send the following company information to our Merchant Support team. This information is used by 2Checkout to generate a Certificate Signing Request (CSR) on your behalf, as the certificate will be hosted on our server. Make sure that the data sent is correct, as it will be included in the CSR file. The information will be validated by the Certificate Authority before the SSL certificate is sold to you.
- Certificates shall be purchased from Certificate Authorities trusted by your customer’s browsers. Such authorities are commonly referred to as “Public” Authorities. and some examples are listed here.
- Certificates shall contain the full hostname of the target, such as store.yourdomain.com. “Wildcard” certificates are not supported.
- Certificate validity should be for 1 year, as browsers have started to not trust certificates with a longer duration.
Information | Details |
---|---|
2Checkout merchant code |
2Checkout generated merchant code. Can be found in Cpanel > System settings. |
Company name |
Your company name. |
Address |
The address of your company. |
City |
City in which your company is located. |
Zip code |
Zip code corresponding to the area in which your company is located. |
Country |
Country in which your company is located. |
State |
State in which your company is located. Use N/A if it doesn’t apply. |
Desired URL |
Your desired custom store domain name. E.q.: https://secure.myshop.com |
3. 2Checkout generates private and public keys and the CSR.
2Checkout uses the information mentioned above to generate the private and public keys as well as the Certificate Signing Request (CSR) necessary to acquire a Secure Sockets Layer (SSL) Certificate from a Certificate Authority. The CSR file generated by 2Checkout will be e-mailed to you by our Vendor Support team, together with instructions on your next steps.
SSL certificates act as a method of securing data transmissions, including sensitive details such as payment information.
While the public key and CSR are shared with you, the private key will be stored only inside 2Checkout’s secure environment, ensuring that SSL security cannot be compromised. 2Checkout ongoing investment in security is reflected by the PCI DSS Certification received yearly.
2Checkout does not accept and will not use SSL certificates purchased based on private/public keys and CSRs you generate yourself or which have been previously used. Custom domains and associated SSL certificates can be used only if 2Checkout is the sole keeper of private keys.
4. Purchase the SSL certificate using the 2Checkout generated CSR.
Use the CSR file provided by 2Checkout to acquire an SSL certificate from your preferred CA. If at any time during the purchase process you’re asked about the server platform type, choose Apache.
When purchasing an SSL certificate you are responsible for:
- Deciding which Certificate Authority to buy it from. We recommend one of the following providers:
- Choosing the type of SSL certificate:
- Extended Validation (EV) SSL Certificate – complex and extensive vetting of your company per the EV Guidelines ratified by the CA/Browser forum in 2007. This is the only type of SSL certificate providing visual feedback to browser users by turning the address bar green for valid EV SSL certificates or red for untrustworthy sites.
- Organization Validation (OV) SSL Certificate – the CA checks to see if your company is a legitimate business by verifying your credentials and if you have the right to use the domain name.
- Domain Validation (DV) SSL Certificate – only name and contact information are checked to see if you have the right to use the domain name.
5. Send the SSL certificate to 2Checkout
Send the SSL certificate by email to supportplus@2checkout.com. 2Checkout will finalize the setup of the custom domain and install the certificate.
6. Update the DNS and buy-links
Update your DNS with a CNAME (Canonical Name) record (host aliases) for the chosen custom domain name to have YourSHOP.YourCompany.com point to the host YourCompany.2checkout.com (once the DNS update is propagated traffic from YourSHOP.YourCompany.com will be guided to YourCompany.2checkout.com).
You’ll need to confirm the availability of YourCompany.2checkout.com with 2Checkout before updating your DNS records.
Once our Vendor Support team confirms the installation of your custom domain, you can create new buy links from the Generate links area. The new links generated from our interface will contain your custom domain name. Your older links having the format secure.2checkout.com remain functional, so both link types can be used for the ordering process.
Retrieve account time zone
Overview
Use the getTimezone method to retrieve information on the time zone used by your account for the Avangate API.
Parameters
Parameters | Type/Description |
---|---|
sessionID |
Required (string) |
|
Session identifier, the output of the Login method. Include sessionID into all your requests. Avangate throws an exception if the values are incorrect. The sessionID expires in 10 minutes. |
Response
Parameters | Type/Description |
---|---|
Timezone |
String |
|
The time zone you selected or the default GMT+02:00 time zone of the Avangate system. |
Request
<?php
require ('PATH_TO_AUTH');
$jsonRpcRequest = array (
'method' => 'getTimezone',
'params' => array($sessionID),
'id' => $i++,
'jsonrpc' => '2.0');
var_dump (callRPC((Object)$jsonRpcRequest, $host, true));
Exchange rate
Overview
2Checkout uses a fully automated exchange rate solution, locking the rate at the moment of purchase for each order, thus eliminating possible fluctuations between anticipated payouts and settlement.
Exchange rate
2Checkout locks the exchange rate as soon as transactions reach Complete status. When transactions are not processed in a like-per-like currency, 2Checkout applies a small mark-up covering the conversion costs and remitting in the settlement currency chosen by you.
The exchange rate for Purchase Orders is locked upon invoice generation.
This applies to all transactions with a different order currency from the payout currency set on the vendor account.
2Checkout updates the exchange rates daily based on two sources:
- The European Central Bank is the primary exchange rate provider
- XE (http://www.xe.com) acts as a fallback provider for currencies not available at the Central European Bank
Updated exchange rates automatically apply to next day purchases.
Refunds
For refunded orders, the exchange rate is calculated when the refund is processed.
Workflow
Control Panel
The exchange rate applied to the total payout amount depends on the currency:
- If the Total is displayed in a payout currency, the exchange rate applied to the Total is the sum of each order's exchange rate.
- If the Total is displayed in a non-payout currency, 2Checkout performs a double conversion applying the mark-up only once.
FAQ
- Where does 2Checkout get the exchange rates from?
- The exchange rates are provided by the European Central Bank (with XE serving as a fallback provider) and updated on a daily basis, applying our own Risk mark-up.
- What is the 2Checkout Risk mark-up?
- The mark-up is a risk management criterion, applied to transactions not processed in a like-for-like currency.
- Are there any differences depending on the payment method?
- Regular transactions: 2Checkout will lock the exchange rate upon marking the order as Complete.
- Purchase Orders: 2Checkout will lock the exchange rate upon generating the invoice (order status: Awaiting payment).
- Channel Manager: 2Checkout will lock the exchange rate at the moment of payment.
- What happens to refunds & chargebacks?
- 2Checkout will apply the exchange rate of the day the refund is processed. The same rule will apply to lost chargeback disputes resulting in a refund.
- How can I change my payout currency?
- You can change the payout currency right from your Merchant Control Panel. However, the new currency will come into effect starting with the next payout cycle.
- Is there a way to extract exchange rate information programmatically via IPN?
- Yes. We expose the FX_RATE, FX_MARKUP, and PAYOUT_CURRENCY parameters via IPN. For more details on how to use them, refer to this article: Instant Payment Notification.
- Can you provide an example as to how exactly is the FX rate calculated?
The following scenario can help you understand how the FX rate is calculated. Let's assume that:
- Product price = 100EUR
- Your payout currency is set to USD
- Your customer chooses to pay in EUR
- Exchange mark-up (FXM) = 4%
- Commission = 6%
In this case,
Product Price EUR - Commission EUR = Amount to be paid in EUR
€100 - €6 = €94
To pay in USD, 2Checkout converts the amount to be paid from EUR to USD and adds the FX Mark-up (FXM), as follows:
EUR to USD = 1.02
EUR to USD + FXM = 0.98
Amount to be paid in USD w/o FXM = $95.55
Amount to be paid in USD w/ FXM = $91.73
Commission - w/ FXM = 9.76%
Additional fields
Overview
This object is returned directly or within a successful response from the following API requests:
Retrieve an additional field Retrieve assigned additional fields Retrieve all additional fields
Additional fields object
Parameters | Object |
---|---|
Label |
String |
|
Field text. |
Code |
String |
|
Field identifier. Alpha-numeric chars, underscores and dashes. |
Type |
String |
|
Field type:
|
ApplyTo |
Sting |
|
|
Values |
Array of values |
|
Custom values you control. |
ValidationRule |
String |
|
The validation rule restricting the type of information shoppers can enter in the additional field during the purchase process. |
Translations |
Array of objects |
|
Details below. |
Label |
String |
|
Field text translated in the language of the Translations object. |
Values |
Object |
|
Custom values you control translated in the language of the Translations object. |
Language |
String |
|
ISO language code. (ISO 639-1 two-letter code). |
Renewal notifications
Overview
One key metric when managing subscriptions is a high renewal rate to grow and maintain a valuable, loyal customer base and secure increased recurring revenues.
For this purpose, you can set renewal notifications that 2Checkout sends to your shoppers. You control the number of emails, as well as the moment in time your shoppers receive these emails.
You can use predesigned templates complete with fresh content (samples below). The new templates have replaced the previous notifications sent out for subscriptions set to be (either automatically or manually) renewed, but any customization you have in place, either in terms of styling or content, continues to be available.
Availability
All 2Checkout accounts.
Renewal notifications
According to the product settings you perform, 2Checkout can automatically send renewal notifications for:
1. Subscriptions where renewal is set to be automatically performed - your shoppers can receive email notifications both before, as well as after the subscription expiration day. Content varies depending on the moment they receive these notifications. Messages can be:
- Notification of upcoming automatic subscription renewals
- Or dunning management notifications containing instructions to update payment information/perform manual renewal as automatic renewal failed.
2. Subscriptions where renewal is manually performed - your shoppers can receive email notifications both before, as well as after the subscription expiration day. Content varies here, as well, depending on the moment they receive these notifications. Emails
- Inform shoppers about the upcoming renewal time and instruct them to perform the payment
- Or contain a subscription expiration notification urging shoppers to manually renew to avoid losing access to their product.
Notification email samples
Email notification sent for automatic renewals
Email notification sent for manual renewals
Preview and test email
Navigate to the Email template manager section to:
- Preview and test current templates for emails sent to your shoppers
- Customize the header and the footer sections by creating custom templates you can assign to your emails
Access the renewal notifications under the Renewal section. Here, you are able to access both the Auto-renewal and Manual renewal emails.
Why don't I see the new template for this email?
The redesigned templates for the renewal notifications have automatically replaced the default templates.
If your preview in the Control Panel does not show the new templates, you are most probably using customized versions that include content and/or styling your company requested at a certain point in time.
You can compare the above samples to your current templates and send us an email if you decide the new ones suit your business needs better. We will work with you on the switch.
Best practices
Find out more details here about how to curb cart abandonment and unfinished payments.
Lock-in price for auto-renewal notifications
Merchants that want to do mass price updates for a region are risking a significant increase in chargebacks and refunds for the subscribers that were already notified that they need to pay a certain renewal price.
Once the shopper is notified about an auto-renewal with a certain price, they should be charged that price, even if the merchant updates the product price settings. But, if the merchant is changing the product price right before the renewal, the subscriber is billed with the new price, which in some cases can be higher than the initial one.
To be compliant and help merchants limit the chargeback rates when price updates that impact many subscriptions take place, we introduced the lock-in price functionality. This is activated by default on all 2Checkout accounts.
The lock-in price for auto-renewal notifications ensures the continuity of the original pricing scheme for a subscription if a merchant decides to change the product pricing after a renewal notification has already been sent. Thanks to this functionality, the shopper is not impacted by any price changes during the next auto-renewal if they have already received the auto-renewal notification.
The price is locked in for the next auto-renewal when the notification is already sent to the shopper in the following scenarios:
- The product price was updated
- The merchant configured a silent upgrade
- The renewal price changed, or a new auto-renewal discount is configured
The locked-in price is ignored in the following scenarios:
- A custom price was set for the subscription via API, Control Panel, or subscription import: The shopper is notified when a custom price is applied
- The shopper manually renews the subscription
- The shopper upgrades the subscription
- The shopper accepted a discount because of a churn prevention campaign
The auto-renewal lock-in price benefits both the merchant and the shopper. Thus, the merchant has fewer disputes and customers canceling a subscription after billing a price different than what was notified, while the shopper avoids an unexpected billing amount being charged automatically.
Workflow
Merchants are notified in the Merchant Control Panel that the new price will not apply for the next renewal of subscriptions where an auto-renewal notification is already sent.
The above note is displayed in the Merchant Control Panel under:
1. Setup > Products > Edit Product Pricing > Pricing configuration > Renewal price section
2. Setup > Renewal > Renewal discounts > Edit renewal discount
Subscription renewal
Overview
Use this section to handle the renewal of your subscriptions.
You can retrieve information regarding the renewal status of a subscription, including the manual renewal link that a customer needs to access in order to renew.
Enable or disable the recurring billing for a subscription using the API methods displayed below.
Orders with installments
Overview
Avangate supports local Brazilian Visa, MasterCard and AMEX credit / debit cards limited to national purchases in the local currency BRL (Brazilian Real).
Requirements
- Installments are available only for:
- Brazilian customers
- Local Visa, MasterCard or AMEX cards
- Non-recurring transactions
- Minimum installment threshold is 5 BRL. Maximum number of installments is 6.
- Mandatory information for payments also includes shopper phone number and Fiscal Code (CPF/CNPJ).
Do local BR cards with / without installments require an addendum to my contract?
Yes. Please contact Avangate for activation.
How does it work?
- Create the Order object.
- Validate the number of installments available based on total order value.
- Place the order specifying the number of installments.
Funds collection for installment payments
Avangate pays you in full, regardless of the number of installments (this is covered directly by the banks).