Overview

Use the OrderSearchOptions object to configure your search order options via JSON-RPC API 6.0.

Object parameters

Overview

Use the deletePromotionCoupon method to remove single or multiple coupons from a promotion.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

// Promotion code corresponding to the promotion you want to remove coupons from
$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'];

try {
    $updatedPromotion = $client->addPromotionCoupon ($sessionID, $promotionCode, $promotionCoupon);
}

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

var_dump("UpdatedPromotion", $updatedPromotion);

Overview

2Checkout offers support for both standard and ZIP+4 ZIP codes.

Standard US ZIP codes

The standard ZIP code notation used by the United States Postal service uses five digits to identify a delivery area.

An example of a standard US ZIP code is 90210.

ZIP+4 codes

In addition to the classic five-digit ZIP codes used in the United States, 2Checkout also supports the use of ZIP+4 add-on ZIP codes, important when shipping physical goods.

The ZIP+4 system uses the basic five-digit code together with four additional digits to identify a geographic segment located within a five-digit delivery area. The segment can be a city block, a group of apartments or other mail receiving units that could benefit from the use of an additional identifier.

An example of a ZIP+4 ZIP code is 99577-0727.

Overview

Use the variables in the list below to customize the Payment failed (Direct Debit) shopper email notifications according to your needs.

Check the 'Mandatory' column to see the variables that are required in your customized version of the e-mail.

Overview

Copy card-on-file data available in the 2Checkout system from a source subscription to an imported target subscription. 2Checkout uses the existing payment information to charge customers as a part of the recurring billing (renewal) process.

Use the copyPaymentInfo method.

Requirements

The imported target subscription and the source subscription must belong to the same customer. The 2Checkout system checks to make sure that the 2Checkout Customer Reference (an internal identifier) coincides for the customer accounts associated to the target and source subscriptions.

Availability

Please contact 2Checkout directly if you wish to take advantage of this feature.

How does this method work?

1. Customer A purchases Subscription A using a VISA credit card and you import Subscription B for the same customer with no data or with an AMEX card.
2. When 2Checkout renews Subscription A, it charges Customer A using the VISA, while using the AMEX (if the data was provided) for Subscription B charges.
3. When you copy the payment data from Subscription A to Subscription B, the 2Checkout system uses the VISA credit card to renew both subscriptions according to with their respective recurring billing cycles. 2Checkout charges customers during the recurring billing process for the imported target subscription using the payment method they used to purchase the source subscription.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

var_dump($sessionID);
$TargetSubscription = 'FFAE3C9429';
$SourceSubscription = '9F4154733C';

$jsonRpcRequest = array (
'method' => 'copyPaymentInfo',
'params' => array($sessionID, $TargetSubscription, $SourceSubscription),
'id' => $i++,
'jsonrpc' => '2.0');

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

?>

Overview

When placing an order on behalf of your partners, you can purchase subscription renewals in addition to new subscriptions and upgrades.

Requirements

• It's mandatory that the products remain associated with the same price list as the original subscriptions and assigned to the same partners to provide them with the possibility of ordering renewals or to place renewal orders on their behalf.
• Products that are not part of price lists assigned to partners will not be available as subscription renewal options.
• Renewals are only available for active and expired subscriptions, but not for disabled items. As long as expired subscriptions are still in their grace period (featuring the Past due status), renewing them is also a valid option.
• When configuring a product with recurring billing, make sure to generate a subscription under the Renewal tab. Products can only be renewed only if a subscription was generated when ordering on behalf of your partners.
• Active subscriptions can only be renewed if only 90 days or less remain until their expiration deadline.

Place renewal partner orders

1. Go to Orders & customers.
2. Click Place partner order.
3. Select the partner for which you're ordering the renewal, either by typing the name in the Select partner box or by using the drop-down menu available. Alternatively, provided that you already placed orders on behalf of your partners, a list of Last used partners will be available in this area, and clicking on a name will automatically select it.
4. You'll now get the possibility to order a new subscription, a renewal or an upgrade. Select Renewal to move to the next stage.
5. Click Add order.
6. Find the specific subscription for which you're ordering a renewal, by searching for criteria such as Name/Company, email, order reference, external reference PO, 2Checkout Subscription Reference, subscription code, partner invoice number or SKU. Apply available filters as needed including subscription status and subscription expiration date to narrow down the results.
7. Search for subscriptions you want to renew (this area is designed to list all active and expired subscriptions when you first access it, but you can still enter query parameters and hit the Search button to have the system display only specific products).
8. The results returned for the search include active and expired subscriptions previously purchased by /for the selected partner. Disabled subscriptions, as well as those for which you haven't generated a subscription, will not be listed here, even if they were acquired by/for the selected partner. Renewals can be ordered individually, one at a time, but you also have the option to bulk renew a number of selected items.
9. Check the boxes next to the products you want to be renewed and hit the Renew selected subscriptions button.
10. Add extra margin/discount options to decrease the cost of renewal for your partner. Extra margins and discounts are entirely optional and completely under your control.
    
    • Discount. Apply a discount to the product(s) value in this order. The discount is deducted from the total price of the products before the partner margin is applied.
    • Extra margin. Offer an extra margin to your partner only for this order. The extra margin is deducted from the total price of the products after the discount and partner margin is applied.
11. Click Place order.
12. Order confirmation. Orders placed by you on behalf of your partners are confirmed automatically, regardless of the order confirmation settings of the partner account.
13. Attach end-user information. For renewals, the 2Checkout system is designed to copy the end-user information attached to the original subscription. However, when such data is not available, you'll need to provide it for the order to move to the fulfillment stage (if they are required according to the Partner commercial settings). The partner on whose behalf you're placing the renewal order can also provide the end-user details.
14. Attach reseller information. Reseller information is copied automatically from the original subscription as a part of the renewal process. Similarly, when such data is not available, you'll need to provide it for the order to move to the fulfillment stage, if the reseller information is required according to that Partner's commercial settings. The partner on whose behalf you're placing the renewal order can also provide the end-user details.
15. Pay partner invoices. You can generate partner invoices manually or automatically, depending on your partner account settings. If the order is placed without any available credit, or your partners do not enjoy a credit limit - they will first need to pay the partner invoice that gets generated automatically when the order is confirmed, and only then will the process advance to the fulfillment stage. To manually issue a partner invoice, go to Orders & customers -> Partner partner invoices.
16. Click Save.
17. On the next screen, you'll have the option to notify your partner of the newly generated partner invoice or to cancel it if necessary.
18. Delivery/fulfillment. When delivery/fulfillment is handled by 2Checkout, not required or has been confirmed by you, the system will give green light to deliveries immediately for an order that is paid in full or placed within available credit. When setting up partner accounts, you can configure automated reminders for expiring subscriptions. Email subscription renewal notifications can be sent to partners, to end-user or both. End-user notifications are sent only if email addresses are available. These notifications will be generated when the Subscription is about to expire and will provide the partners' contact details. You also have the option of sending automated subscription renewal emails to partners, providing a "Subscription Expiration report" designed to help them decide which subscriptions to renew. Once a renewal order is logged by the system, the validity of existing subscriptions will be extended and new activation keys will be generated, with 2Checkout proceeding to deliver them to either the partners or directly to end-users, depending on the settings of the partner accounts.

Canceling partner orders

To cancel an order:

1. Go to Order search -> Partner orders.
2. Identify the item you'd like to call off.
3. Click to view the order.
4. Click Cancel.

Canceling orders automatically disables all associated subscriptions.

F.A.Q.

Can I edit pricing details for placed orders?

Yes. If no partner invoice was generated then you'll be able to add extra margin and to increase the discount. When the partner invoice was already issued, you'll need to first cancel it to edit the order's extra margin and discount.

Overview

Design multiple partnership programs and let your partners decide which is the right one for them.

After defining the partnership programs you can assign partners to it and apply settings to multiple partners at once.

Add partnership programs 

Follow the steps below to add a new partnership program.

1. Login to the 2Checkout Merchant Control Panel.
2. Go to Partner management -> Partnership programs.
3. Click Add partnership program.
4. Fill in the partnership program general information:
   
   • Program Title - mandatory;
   • Description - non-mandatory but offers useful information to partners.
5. Click Commercial Settings.
6. Choose how you want your partner to pay for orders, how the delivery should take place and how renewals are handled. These are not mandatory settings, so configure them at your will.
   
   • Offer a credit limit. This represents the amount a partner is allowed to owe you for placed and delivered orders. Credit limits set to 10.000 USD allow partners to place and receive orders in that amount, sending the payment at a later date. After this limit is reached, future orders will not be delivered until the credit limit has been restored. When choosing this option, you need to decide on:
     
     • Credit limit - maximum amount of credit your partners can use to place orders before sending the payment.
     • Warning level - when available credit decreases to the specified warning level, your partners are notified by email.
   • License settings. Define requirements regarding subscription delivery and management:
     
     • Requires end user information  - delivery of activation keys takes place after the end user information gets attached to the order. If your key generator requires end user information, this information is mandatory before delivering the keys even if the box remains unchecked.
     • Requires reseller information -  delivery of the activation keys takes place after the reseller information gets attached to the order. If your key generator requires reseller information, this information is mandatory before delivering the keys even if the box remains unchecked.
     • Email license keys to - define who receives the activation information. Select at least one of the two options available to ensure the success of the fulfillment/delivery process.
       
       • End users
       • Partner
   • Other settings
     
     • Partner offers tech support to end user - partner contact information is listed as technical/installation support in the electronic delivery email sent to the end users.
     • Orders are confirmed automatically - change default order approval settings: by default, each partner order has to be manually reviewed and approved.
     • Order cancellation period - time period after order placement during which the order can be cancelled;
     • Enable Direct Renewal - enable end users who purchased products from your partners to renew subscriptions via your website or via 2Checkout while crediting the partners with the commissions you set. 2Checkout automatically notifies partners via email when you enable Direct Renewal.
     • Email subscription expiration notifications to:
       
       • End users (if end user information is available)
       • Partner
   • Partner margin
     
     • None - the offered partner margin is set to 0. In return, you may want to offer special prices to a partner directly from the pricing configuration/price list, or you may want to add partner margin when placing an order.
     • General margin - set a general margin for new acquisitions or renewals.
     • Margin per product/category - set specific margins for products or categories.
7. Click Assign Partners.
8. Click the unassigned partners that you want to be part of your partnership program.
9. Click Review and Apply.
10. Review the partnership program information.
11. Click Save and Apply to Partners.

Overview

Renew a subscription and collect recurring revenue using the 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/Debit cards: Visa, Visa Electron, MasterCard, Maestro, Amex, Discover, Dankort, Carte Bleue, JCB. 2Checkout supports local Brazilian cards.
• PayPal and PayPal Express
• Purchase Order
• Wire
• Check
• WeChat Pay
• iDEAL
• Alipay
• Trustly
• TEST orders
• Free orders (no payment information required)
• Previous order references - 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.
• Order with installments
• ApplePay
• 2Pay.js
• Boleto/Pix
• Google Pay

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;
/**/


$jsonRpcRequest = new stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method = 'placeOrder';
$jsonRpcRequest->params = array($sessionID, $Order);
$jsonRpcRequest->id = $i++;

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

var_dump ($placeOrder);

Overview

Use the convertTrial method to convert a trial to a paid subscription. In the eventuality of a conversion failure, you can use convertTrial again for the same trial subscription only after you let 24 hours pass since the initial attempt. The Avangate system attempts to automatically convert trials before they expire to full subscriptions, unless you made an attempt that failed less than 24 hours before the scheduled expiration deadline.

In case the trial conversion fails due to a transaction issue, the Avangate system sends unfinished payment follow-up emails to customers, provided that you set up lead management for your account.

Parameters

Response

Request

<?php
$host   = "https://api.avangate.com";
$client = new SoapClient($host . "/soap/3.0/?wsdl", array(
    'location' => $host . "/soap/3.0/",
    "stream_context" => stream_context_create(array(
        'ssl' => array(
            'verify_peer' => false,
            'verify_peer_name' => false
        )
    ))
));

function hmac($key, $data)
{
    $b = 64; // byte length for md5
    if (strlen($key) > $b) {
        $key = pack("H*", md5($key));
    }
    
    $key    = str_pad($key, $b, chr(0x00));
    $ipad   = str_pad('', $b, chr(0x36));
    $opad   = str_pad('', $b, chr(0x5c));
    $k_ipad = $key ^ $ipad;
    $k_opad = $key ^ $opad;
    return md5($k_opad . pack("H*", md5($k_ipad . $data)));
}
$merchantCode = "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
$now          = gmdate('Y-m-d H:i:s'); //date_default_timezone_set('UTC')
$string = strlen($merchantCode) . $merchantCode . strlen($now) . $now;
$hash   = hmac($key, $string);
try {
    $sessionID = $client->login($merchantCode, $now, $hash);
}
catch (SoapFault $e) {
    echo "Authentication: " . $e->getMessage();
    exit;
}
$SubscriptionReference = '30E47F8699';
$ExtendSubscriptionFromPaymentDate = true; //false can also be used if you want the subscription start date to be the moment when the trial was set to initially expire.
try {
    $convertedTrial = $client->convertTrial($sessionID, $SubscriptionReference, $ExtendSubscriptionFromPaymentDate);
}
catch (SoapFault $e) {
    echo "convertedTrial: " . $e->getMessage();
    exit;
}
var_dump("convertedTrial", $convertedTrial);