Retrieve an order
Overview
Use the getOrder method to retrieve details on a specific order placed with dynamic product information, or catalog products, using the unique, system-generated reference.
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. |
orderReference |
Required (string) |
|
Order reference number of an older order, which is already approved/paid. |
Response
Parameters | Type/Description |
---|---|
Object (orders with catalog products) |
|
Order information | Object (orders with dynamic product information) |
WSOrder | String |
Request
<?php
require ('PATH_TO_AUTH');
$orderReference = 'YOUR_ORDER_REFERENCE';
$jsonRpcRequest = array (
'method' => 'getOrder',
'params' => array($sessionID, $orderReference),
'id' => $i++,
'jsonrpc' => '2.0'
);
var_dump (callRPC((Object)$jsonRpcRequest, $host, true));
Subscription end user update
Overview
Use the updateSubscriptionEndUser method to update the details of a subscription’s end user. This method changes per-subscription end user data and not customer details.
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. |
SubscriptionReference |
Required (string) |
Unique, system-generated subscription identifier. |
|
EndUser |
Required (Object) |
Use this object to update end user information. |
Response
Parameter | Type/Description |
---|---|
Boolean |
true or false depending on whether the changes were successful or not. |
Request
<?php
function callRPC($Request, $hostUrl, $Debug = true) {
$curl = curl_init($hostUrl);
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($curl, CURLOPT_SSLVERSION, 0);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Accept: application/json'));
$RequestString = json_encode($Request);
curl_setopt($curl, CURLOPT_POSTFIELDS, $RequestString);
if ($Debug) {
$RequestString;
}
$ResponseString = curl_exec($curl);
if ($Debug) {
$ResponseString;
}
if (!empty($ResponseString)) {
$Response = json_decode($ResponseString);
if (isset($Response->result)) {
return $Response->result;
}
if (!is_null($Response->error)) {
var_dump($Request->method, $Response->error);
}
} else {
return null;
}
}
$host = 'https://api.avangate.com/rpc/4.0/';
$merchantCode = "YOUR_MERCHANT_CODE";// your account's merchant code available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$key = "YOUR_SECRET_KEY";// your account's secret key available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$string = strlen($merchantCode) . $merchantCode . strlen(gmdate('Y-m-d H:i:s')) . gmdate('Y-m-d H:i:s');
$hash = hash_hmac('md5', $string, $key);
$i = 1; // counter for api calls
// call login
$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);
var_dump($sessionID);
$subscriptionReference = '8F749B63E7';
$EndUser = new stdClass ();
$EndUser->Address1 = 'Address line 1';
$EndUser->Address2 = 'Address line 2';
$EndUser->City = 'LA';
$EndUser->Company = 'Company Name';
$EndUser->CountryCode = "US";
$EndUser->Email = 'customerAPI@avangate.com';
$EndUser->FirstName = 'New Customer 2.0';
$EndUser->Language = 'en';
$EndUser->LastName = 'Avangate';
$EndUser->Phone = '1234567890';
$EndUser->State = 'California';
$EndUser->Zip = '90210';
$EndUser->Fax = null;
$jsonRpcRequest = array (
'method' => 'updateSubscriptionEndUser',
'params' => array($sessionID, $subscriptionReference, $EndUser),
'id' => $i++,
'jsonrpc' => '2.0');
var_dump (callRPC((Object)$jsonRpcRequest, $host, true));
Place a renewal order
Overview
Renew a subscription and collect recurring revenue using the 2Checkout Subscription Reference. You can renew subscriptions for both catalog and dynamic products.
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
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. |
Required (Object) |
|
|
Object designed to collect all data necessary for an order, including billing, product/subscription plan and payment details. To place an order with PayPal rather than PayPal Express, use PAYPAL as the type of the PaymentDetails object and send the shopper email and a return URL as part of the PaymentMethod object. See code sample. |
SubscriptionReference |
Required (String) 2Checkout generated subscription reference number. E.q. A8C5671BFE. |
Response
Parameters | Type/Description |
---|---|
Object |
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);
API Reference
This is a summary of the objects/classes and methods available.
Update coupon
Overview
Use the updatePromotionCoupon method to add single or multiple coupons to a promotion.
Updating a promotion with multiple coupons causes any existing single coupon to be removed.
Parameters
Parameter | Type/Description | |
---|---|---|
promotionCode |
Required (string) |
|
|
The code corresponding to the promotion that you want to update. |
|
promotionCoupon |
Required (object) |
|
|
type |
Required (string) |
|
|
Coupon type. Available values:
|
|
Code/Codes |
Required (string / array of strings) |
|
|
Coupon code (for SINGLE) or array of coupon codes (for MULTIPLE). |
Response
Parameter | Type/Description |
---|---|
promotionCoupon | Object |
Request
<?php
require ('PATH_TO_AUTH');
// Promotion code corresponding to the promotion you want to add coupons to
$promotionCode = '';
// Define single coupon object
$promotionCoupon = new stdClass;
$promotionCoupon->Type = 'SINGLE';
$promotionCoupon->Code = 'YOUR_CODE_HERE';
// Define multiple coupon object
$promotionCoupon = new stdClass;
$promotionCoupon->Type = 'MULTIPLE';
$promotionCoupon->Codes = ['YOUR_CODE_1', 'YOUR_CODE_2'];
try {
$updatedPromotion = $client->addPromotionCoupon ($sessionID, $promotionCode, $promotionCoupon);
}
catch (SoapFault $e) {
echo "UpdatedPromotion: " . $e->getMessage();
exit;
}
var_dump("UpdatedPromotion", $updatedPromotion);
Transition Guide for 2CO Sandbox
Overview
In 2Checkout's legacy checkout system, we have always supported the demo parameter to test the checkout process without actually creating an order. In 2014, we introduced our sandbox environment to provide merchants with a way to completely test the order lifecycle through their API and INS integration.
Over the past couple of years, we have been working to integrate the legacy platform with our new platform's test ordering system so that our merchants can fully test their integration without the need for a separate sandbox account. Since there is no longer a need for it, we are decommissioning the legacy sandbox environment and ask that all remaining sandbox users transition their testing to our test ordering system.
If you are not using 2Checkout's legacy sandbox platform there is no need to read further. We are not making any changes to our production environment.
Demo/Test Ordering System
To place a test order with 2Checkout's legacy checkout system using your production account, you just need to pass the demo parameter with a value of `Y` as we have always supported.
Example
https://www.2checkout.com/checkout/purchase?sid=your-seller-id&mode=2CO&li_0_name=test&li_0_price=1.00&demo=Y
Form:
<form action='https://www.2checkout.com/checkout/purchase' method='post'>
<input type='hidden' name='sid' value='your-seller-id' />
<input type='hidden' name='mode' value='2CO' />
<input type='hidden' name='li_0_name' value='test' />
<input type='hidden' name='li_0_price' value='1.00' />
<input type='hidden' name='demo' value='Y' />
<input name='submit' type='submit' value='Checkout' />
</form>
Example
You can then use the data detailed in this article to test each use case.
To place a test order with 2Checkout's legacy Payment API, just add the demo property to the root of your JSON payload with a value of TRUE.
https://www.2checkout.com/checkout/api/1/your-seller-id/rs/authService
{
"sellerId": "your-seller-id",
"privateKey": "your-private-key",
"merchantOrderId": "123",
"token": "customer-client-side-token",
"currency": "USD",
"total": "0.01",
"billingAddr": {
"name": "John Doe",
"addrLine1": "123 Test St",
"city": "Columbus",
"state": "Ohio",
"zipCode": "43123",
"country": "USA",
"email": "example@2co.com",
"phoneNumber": "5555555555"
},
"demo": true
}
Some legacy accounts may have demo mode disabled. If you are having any problems placing demo orders, contact 2Checkout for assistance.
Test Order Management
To locate your Test orders, log in to your Merchant Control Panel and navigate to Orders & Customers → Order Search, and use the 'Test orders' filter, as shown in this image.
Test orders can be refunded or re-billed (recurring sales) and will send all necessary INS messages just like production orders. More information on the 2Checkout test ordering system can be found in our Knowledge Center.
Recommended resources
Download this solution brief to discover how the Avangate Monetization Platform can maximize your conversion and retention rates.
Pricing configuration
Overview
Use this object to add/create and update/edit pricing configurations for your account. You can assign one or multiple price option groups to pricing configurations.
You identify a pricing configuration using its unique identifier: Code.
Parameters
Parameters | Type/Description | |||
---|---|---|---|---|
Name |
String |
|||
|
Pricing configuration name. |
|||
Default |
Boolean |
|||
|
True for the default pricing configuration |
|||
BillingCountries |
Array of strings |
|||
|
ISO codes of the countries assigned to the pricing configuration. Empty unless a pricing configuration has specific countries assigned. |
|||
PricingSchema |
String |
|||
|
DYNAMIC – With a base price FLAT – Without a base price |
|||
PriceType |
String |
|||
|
Possible values: • NET • GROSS |
|||
DefaultCurrency |
String |
|||
|
The ISO code of the default currency for the pricing configuration |
|||
Prices |
Object |
|||
|
Details below. |
|||
|
Regular |
Array of objects |
||
|
|
Details below. |
||
|
|
Amount |
Int |
|
|
|
|
The price of the product. Use -1 to delete it. |
|
|
|
Currency |
String |
|
|
|
|
ISO code of the currency for the product price. |
|
|
|
MinQuantity |
Int |
|
|
|
|
The minimum quantity of volume discounts. Default is 1. |
|
|
|
MaxQuantity |
Int |
|
|
|
|
The maximum quantity of volume discounts. Default is 99999. |
|
|
|
OptionCodes |
Array of objects |
|
|
|
|
Details below. |
|
|
|
|
Code |
String |
|
|
|
|
System generated pricing options group code (you can also configure it) that the 2Checkout system uses to calculate product prices for pricing configurations without a base price. |
|
|
|
Options |
StringArray |
|
|
|
|
The pricing options group option code you configured that the 2Checkout system uses to calculate product prices for pricing configurations without a base price. |
|
Renewal |
Array of objects |
||
|
|
Details below. |
||
|
|
Amount |
Int |
|
|
|
|
The price of the product. Use -1 to delete it. |
|
|
|
Currency |
String |
|
|
|
|
ISO code of the currency for the product price. |
|
|
|
MinQuantity |
Int |
|
|
|
|
The minimum quantity of volume discounts. Default is 1. |
|
|
|
MaxQuantity |
Int |
|
|
|
|
The maximum quantity of volume discounts. Default is 99999. |
|
|
|
OptionCodes |
Array of objects |
|
|
|
|
Details below. |
|
PriceOptions |
Array of objects |
|||
|
Details below. |
|||
|
Code |
String |
||
|
|
System generated pricing options group code (you can also configure it) that the 2Checkout system uses to calculate product prices for pricing configurations without a base price. |
||
|
Required |
Boolean |
||
|
|
true – you set the price options group as required during the purchase process. false - you did not set the price options group as required during the purchase process. |
Special price promotions
Overview
Create Special price promotions and define the final order price your customers will pay considering any pricing options or volume discounts configured on the product. Use Special promotions to have full control over the discounted price displayed to your customers.
Benefits
- Increase average order value through better incentives
- Improve customer satisfaction by offering the products at the right price
- Extended control over the prices displayed throughout the entire buying experience
Availability
Special price promotions are enabled by default on all 2Checkout accounts.
Limitations
Special price promotions are available through the ConvertPlus ordering flow. API support for creating Special price promotions is not available at this moment.
Once a product is added to a Special price promotion, you cannot update its price, or its volume discounts setup. To update the pricing configuration of a product that is part of an active campaign, remove the product from the promotion and then update its price.
Special price promotions are not available in the Affiliates Network.
How it works
Special price promotions allow you to control the final price paid by the customers, taking into account product pricing configurations/options or volume discounts that may be applied to the order.
Gross / Net product price
If 2Checkout handles the management of taxes on your behalf, then you are able to create products with gross price type (the product price includes the tax/VAT to be collected from the customers). When adding products with gross price type in a Special price promotion, you are able to control the final order price paid by customers including taxes.
Example: Product 2Checkout Monthly Subscription costs $19.99 (including taxes). Let's say a 19% VAT is applied based on customer location. If no promotion is applied, the cart price is:
Now let's use a Special price promotion to define a final order price of $14.99 for product 2Checkout Monthly Subscription. The Special price promotion takes into account the 19% VAT applied to the order and the total order price displayed is $14.99 (including taxes):
Pricing options / Volume discounts
When creating a Special price promotion, you are able to define the final price your customers will pay for each pricing configuration configured. A price matrix is available for defining the order price based on the volume discounts/pricing options set on the product.
The values from the fields left blank are auto-converted by 2Checkout based on exchanged rates from the European Central Bank, from the previous day.
Adding a Special price promotion
To create a Special price promotion, follow the below steps:
- Go to Marketing Tools > Promotions.
- Click on the Special price promotions tab.
- Click Add Special price promotion.
- Give the promotion a suggestive title and description. Shoppers can see the promotion title during purchase.
- Select when you want the promotion to run. You can limit promotions to a specific time interval or let them run indefinitely. To start a promotion as soon as you mark it Active, leave the start date empty. If you don't set the end date, the promotion will stop when the maximum number of orders has been reached or will continue to run if the maximum number of orders is unlimited.
- Choose the coupon/voucher type:
- Single - one voucher to impact multiple orders;
- Multiple - individual and unique, pre-order vouchers.
- Choose whether to restrict the promotion to a number of orders, or apply it for all orders. This option is only available for single coupons.
- Choose whether or not to limit the promotion based on the product quantity. Any product quantity above this limit will be sold at full price.
- Set the default currency of the promotion.
- Fill in the promotion coupon/voucher code. The maximum length of a coupon code is 255 alphanumeric characters.
- Single: enter the coupon values manually
- Multiple: either add the values manually one coupon per line or use the coupon generator available in the Control Panel to generate 5, 10, 20, 30, 50 or 100 vouchers at a time and either append them to an existing list or replace existing items. The generator creates random vouchers that resemble this: D8C10E32. 2Checkout recommends limiting the number of coupon codes to a maximum of 25000.
- Choose whether or not to apply discounts automatically. Only available for single coupons. This option applies discounts to all selected products in all orders, without the need for shoppers to enter the coupon manually.
- Apply promotion to recurring charges. You can apply it to none, to one recurring charge, to all or to a specific number of recurring charges after which the renewal price is recalculated.
- Select the products to be included in the promotion.
- Select the pricing configurations for which the promotion should apply.
- Add the special promotional prices that should be displayed to end-users, when the promotion is active in cart. Filling in the price for the default currency is mandatory. Use the price matrix to define the price for each pricing option/volume discounts threshold active on the product. Set the amount for all currencies, or leave them empty and let 2Checkout convert the amounts automatically.
Extract invoices
Overview
Use the getInvoices method to extract shopper invoices from the Avangate system based on unique order references. The method returns the binary code for invoices in the PDF file format, Base64 encoded (Base64 is used to represent binary data in the ASCII string format).
getInvoices works for COMPLETE orders for which an invoice was already issued. For refunded orders, getInvoices provides two shopper invoices, one for the original order and the second for the refund, reflecting the repayment made.
In the case of cross-selling orders which contain products from different merchants, getInvoice enables you to re-send only the invoices for your own offerings.
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. |
RefNo |
Required (string) |
Unique, system generated reference for orders. |
Response
InvoicesData |
Array of objects |
|
|
|
Details below. |
|
Sale |
String |
|
|
Base64 encoded PDF file containing an invoice for a Complete order. |
|
Cancellation |
String |
|
|
Base64 encoded PDF file containing a cancellation invoice. |
|
Refunds |
Array of string |
|
|
Base64 encoded PDF files containing invoices for Refunds. |
Request
<?php
$host = "https://api.avangate.com";
$client = new SoapClient($host . "/soap/4.0/?wsdl", array(
'location' => $host . "/soap/4.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;
}
$Reference = '43997639';
try {
$invoices = $client->getInvoices($sessionID, $Reference);
}
catch (SoapFault $e) {
echo "invoices: " . $e->getMessage();
exit;
}
var_dump("invoices", $invoices);