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

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.
7. 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%

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

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

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.

Overview

Avangate supports local Brazilian Visa, MasterCard and AMEX credit / debit cards limited to national purchases in the local currency BRL (Brazilian Real). 

Requirements

1. Installments are available only for:
   • Brazilian customers
   • Local Visa, MasterCard or AMEX cards
   • Non-recurring transactions
2. Minimum installment threshold is 5 BRL. Maximum number of installments is 6.
3. 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?

1. Create the Order object.
2. Validate the number of installments available based on total order value. 
3. 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). 

Overview

2Checkout supports local Brazilian Visa, MasterCard and AMEX credit / debit cards limited to national purchases in the local currency BRL (Brazilian Real). 

Requirements

1. Installments are available only for:
   • Brazilian customers
   • Local Visa, MasterCard or AMEX cards
   • Non-recurring transactions
2. Minimum installment threshold is 5 BRL. Maximum number of installments is 6.
3. 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 2Checkout for activation.

How does it work?

1. Create the Order object.
2. Validate the number of installments available based on total order value. 
3. Place the order specifying the number of installments. 

Funds collection for installment payments

2Checkout pays you in full, regardless of the number of installments (this is covered directly by the banks). 

Overview

Use the getContents method to get info on all the products added to cart by the shopper in the current session. Products can be either defined in the catalog, or created with dynamic information.    

Parameters

Response

Request

<?php

require('PATH_TO_AUTH');

$Order = new stdClass();
$Order->RefNo = NULL;
$Order->Currency = 'usd';
$Order->Country = 'US';
$Order->Language = 'en';
$Order->CustomerIP = '91.220.121.21';
$Order->ExternalReference = NULL;
$Order->Source = NULL;
$Order->AffiliateId = NULL;
$Order->CustomerReference = NULL;
$Order->Items = array();
$Order->Items[0] = new stdClass();
$Order->Items[0]->Code = 'my_subscription_1'; // you can also send products with dynamic information
$Order->Items[0]->Quantity = 1;
$Order->Items[0]->PriceOptions = NULL;
$Order->Items[0]->SKU = NULL;
$Order->Items[0]->Price = NULL;
$Order->Items[0]->CrossSell = NULL;
$Order->Items[0]->Trial = false;
$Order->Items[0]->AdditionalFields = NULL;
$Order->Items[0]->Promotion = NULL;
$Order->BillingDetails = new stdClass();
$Order->BillingDetails->FirstName = 'FirstName';
$Order->BillingDetails->LastName = 'LastName';
$Order->BillingDetails->CountryCode = 'us';
$Order->BillingDetails->State = 'California';
$Order->BillingDetails->City = 'LA';
$Order->BillingDetails->Address1 = 'Address example';
$Order->BillingDetails->Address2 = NULL;
$Order->BillingDetails->Zip = '90210';
$Order->BillingDetails->Email = 'customer@email.com';
$Order->BillingDetails->Phone = NULL;
$Order->BillingDetails->Company = NULL;
$Order->DeliveryDetails = NULL;
$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'TEST';
$Order->PaymentDetails->Currency = 'usd';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->CustomerIP = '10.10.10.10';
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = true;
$Order->PaymentDetails->PaymentMethod->CardNumber = "4111111111111111";
$Order->PaymentDetails->PaymentMethod->CardType = 'visa';
$Order->PaymentDetails->PaymentMethod->ExpirationYear = '2019';
$Order->PaymentDetails->PaymentMethod->ExpirationMonth = '12';
$Order->PaymentDetails->PaymentMethod->HolderName = 'John';
$Order->PaymentDetails->PaymentMethod->CCID = '123';
$Order->Promotions = NULL;
$Order->AdditionalFields = NULL;
$Order->LocalTime = NULL;
$Order->GiftDetails = NULL;

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

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

Overview

Retrieve information about the upgrade options for a specific subscription.

Trigger upgrade for your existing subscriptions, or set external references to a subscription by using the API methods displayed below.

Overview

Renew a subscription and collect recurring revenue using the 2Checkout Subscription Reference. You can renew subscriptions for both catalog and dynamic products. The only requirement is to provide a valid subscription reference.

Requirements

To place a renewal order, you need to provide a valid subscription reference number.

Payment methods

You can place renewal orders using the following payment methods:

• Credit cards
• PayPal
• WeChat Pay
• iDEAL
• Purchase Order
• Wire

Use the PaymentDetails object to change the payment method used in the ordering process.

Parameters

Response

 

Request

<?php

require ('PATH_TO_AUTH');

$Order = new stdClass();
$Order->Currency = 'USD';
$Order->Language = "EN";
$Order->Country = 'US';
$Order->CustomerIP = '91.220.121.21';
$Order->Source = "sourceAPI.net";
$Order->LocalTime = date('Y-m-d H:i:s');
$Order->Items = array();

/**/
$Order->Items[0]->RenewalInformation = new stdClass();
$Order->Items[0]->RenewalInformation->SubscriptionReference = 'A8C5671BFE'; //subscription used in the renewal process
$Order->Items[0]->Price = new stdClass();
$Order->Items[0]->Price->Type = 'CUSTOM';
$Order->Items[0]->Price->Amount = '10';
$Order->Items[0]->PriceOptions = array('uniqscale1=4');//

$Order->MachineId = "MachineID";

$Order->BillingDetails = new stdClass();
$Order->BillingDetails->Address1 = 'Bil1ing address';
$Order->BillingDetails->Address2 = 'Billing address 2';
$Order->BillingDetails->City = 'Billing City';
$Order->BillingDetails->State = 'Billing State';
$Order->BillingDetails->CountryCode = 'US';
$Order->BillingDetails->Phone = 1231232123;
$Order->BillingDetails->Email = 'customer_details@test.com';
$Order->BillingDetails->FirstName = 'First';
$Order->BillingDetails->LastName = 'Customer';
$Order->BillingDetails->Company = 'Billing Company';
$Order->BillingDetails->Zip = '55104';

$Order->DeliveryDetails = new stdClass();
$Order->DeliveryDetails->Address1 = 'Bil1ing address';
$Order->DeliveryDetails->Address2 = 'Billing address 2';
$Order->DeliveryDetails->City = 'Billing City';
$Order->DeliveryDetails->State = 'Billing State';
$Order->DeliveryDetails->CountryCode = 'US';
$Order->DeliveryDetails->Phone = '12345';
$Order->DeliveryDetails->Email = 'customer_details@test.com';
$Order->DeliveryDetails->FirstName = 'First';
$Order->DeliveryDetails->LastName = 'Customer';
$Order->DeliveryDetails->Zip = "55104";

$Order->PaymentDetails = new stdClass();
$Order->PaymentDetails->Type = "CC";
$Order->PaymentDetails->Currency = $currency;

$Order->PaymentDetails->PaymentMethod = new stdClass();
/**/
$Order->PaymentDetails->PaymentMethod->CardNumber = "4111111111111111";
$Order->PaymentDetails->PaymentMethod->CardType = "VISA";
$Order->PaymentDetails->PaymentMethod->ExpirationYear = "2019";
$Order->PaymentDetails->PaymentMethod->ExpirationMonth = "12";
$Order->PaymentDetails->PaymentMethod->CCID = "123";
$Order->PaymentDetails->PaymentMethod->HolderName = "John Doe";
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = TRUE;
$Order->PaymentDetails->PaymentMethod->HolderNameTime = 1;
$Order->PaymentDetails->PaymentMethod->CardNumberTime = 1;
/**/


try {
    $newOrder = $client->placeOrder($sessionID, $Order);
}
catch (SoapFault $e) {
    echo "newOrder: " . $e->getMessage();
    exit;
}

var_dump("newOrder", $Order);