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. |
Custom subscription renewal price
Overview
Charge customers custom prices for the renewal of subscriptions, moving away from the recurring pricing configuration at product level. Use the setCustomRenewalPrice method to set custom renewal prices for subscriptions and control the number of recurring billing cycles the price impact subscribers.
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. |
|
Price |
Required (double) |
|
The custom renewal price you want to charge. |
Currency |
Required (string) |
|
Currency in which prices are expressed. The currency ISO code used for the payment is ISO 4217. The default currency is the same as in the previous payment made by the customer. |
Cycles |
Required (int) |
|
Number of recurring billing cycles for which Avangate charges customers the custom price rather, ignoring product–level recurring pricing configurations. (Can be null - Default value 1). |
ReasonText |
Optional (string) |
|
Save details at the subscription-level about the custom costs. |
Request
<?php
require ('PATH_TO_AUTH');
$subscriptionReference = 'YOUR_REFERENCE';
$Price = 25;
$Currency = 'gbp';
$Cycles = 7;
$ReasonText = null;
$jsonRpcRequest = array (
'method' => 'setCustomRenewalPrice',
'params' => array($sessionID, $subscriptionReference, $Price, $Currency, $Cycles, $ReasonText),
'id' => $i++,
'jsonrpc' => '2.0');
var_dump (callRPC((Object)$jsonRpcRequest, $host, true));
Response
Parameters | Type/Description |
---|---|
Boolean |
true or false depending on whether or not the operation succeeded. |
Single Sign-On in cart
Overview
Use the getSingleSignOnInCart method. Avangate attaches a unique token to links, designed to identify the returning shoppers and support the automatic extraction of payment data and billing information from the Avangate system. For example, you can generate single sign on in cart links for existing customers logged into your website based on their external or Avangate customer IDs.
How does this work?
When accessing the shopping cart using tokenized payment links:
- Avangate prefills automatically customer billing and delivery details associated with their Avangate customer accounts (linked based on their unique customer IDs).
- Avangate presents shoppers with an optimized payment area featuring the credit / debit cards used to make previous purchases / transactions in the Avangate system. Customers have the option of selecting one of the payment methods depending on available card-on-file data.
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. |
IdCustomer |
Required (string) |
Unique customer identifiers. Can be either the ExternalCustomerReference you control or the system-generated AvangateCustomerReference. |
|
CustomerType |
Required (string) |
|
Possible values:
|
Url |
Required (string) |
|
The shopping cart URL. Avangate redirects shoppers to this URL.
Possible values:
Any buy link you generate from the cPanel or using the API. Note: For the time being, payment tokenization does not support Express Payments Checkout or the Avangate mobile shopping cart. |
ValidityTime |
Optional (int) |
|
The time, in seconds, before the single sign-on URL expires. By default, the URL expires after 10 seconds. (optional) |
ValidationIp |
Optional (string) |
|
The IP address of the shopper, necessary for security purposes. Can be an empty string or a valid IP, or null. |
Response
Single sign-on URL |
String |
The generated string is the tokenized time-limited single sign-on URL pointing to Avangate shopping cart.
Note: Each SSO link cleans any previous cart sessions. Shoppers using multiple SSO links would purchase only a single product at a time.
If shoppers add multiple products to cart via SSO buy links and then use a non-SSO link, they’ll purchase all items using the same order. When you use single sign on in cart for customers without card on files in the Avangate system, the generated tokenized link prefills the billing information but the purchase process requires that shoppers provide payment information, such as a credit or debit card.
Important! You can use the value of the logintoken to retrieve customer information by SSO token.
|
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;
}
$IdCustomer = '352365983';
$CustomerType = 'AvangateCustomerReference';
$Url = 'https://store.avancart.com/order/checkout.php?PRODS=4639321&QTY=1&CART=1&CARD=2';
$ValidityTime = 50;
$ValidationIp = null;
try {
$ssoLINK = $client->getSingleSignOnInCart($sessionID, $IdCustomer, $CustomerType, $Url, $ValidityTime, $ValidationIp);
}
catch (SoapFault $e) {
echo "ssoLINK: " . $e->getMessage();
exit;
}
var_dump("ssoLINK", $ssoLINK);
Retrieve order reseller information
Overview
Use this method to extract the reseller information defined for a specific order.
Requirements
Parameters
Parameter | Type/Description |
---|---|
sessionID | Required (string) |
Session identifier, which is the output of the Login method. An exception will be thrown if the values are incorrect. | |
refNo | Required (string) |
The unique, system-generated identifier of a partner order. |
Response
Parameter | Type/Description |
---|---|
Reseller | Object |
Request
<?php
require('PATH_TO_AUTH'); // Authentication example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/SOAP/02Authentication
require('PATH_TO_setPartner'); // setPartner example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/SOAP/06Reference/Partner/00Set_partner
$refNo = 'YOUR_ORDER_REFERENCE';
try {
$reseller= $client->getOrderReseller ($sessionID, $refNo);
} catch (SoapFault $e) {
Echo "Reseller: " . $e->getMessage();
exit;
}
var_dump ("Reseller ", $reseller);
Errors
Error | Description |
---|---|
NOT_FOUND_PARTNER |
Set a partner before invoking the method. |
EMPTY_ORDER_REFERENCE |
Order reference not provided. |
INVALID_REFERENCE |
Invalid order reference. |
INVALID_SUBSCRIPTION_REFERENCE |
No reseller defined for this order reference. |
Update subscription payment information
Overview
Use the updateSubscriptionPaymentInformation method to update the credit card information related to the payment to be made for a subscription. To be able to do this, you need to generate a payment token using the credit card information via the 2Pay.js library, and then use this token in the request of the method as indicated below.
Request Parameters
Parameter Name | Type | Required/Optional | Description |
---|---|---|---|
sessionID |
String |
Required |
The 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. |
subscriptionReference |
String |
Required |
The reference of the subscription for which you want to retrieve the payment information. |
paymentInformation |
Object |
Required |
The payment information object, details below: |
PaymentDetails |
Object |
Required |
The payment details object, details below: |
Type |
String |
Required |
The payment details type. Restricted to EES_TOKEN_PAYMENT for now. |
PaymentMethod |
Object |
Required |
The payment method object, details below: |
EesToken |
String |
Required |
The 2Pay token obtained by integrating the 2Pay.js library. |
Vendor3DSReturnURL | String | Required | URL address to which customers are redirected after the 3DS details get validated by the bank and the order is successfully authorized. |
Vendor3DSCancelURL | String | Required | URL address to which customers are redirected after the 3DS details get validated by the bank and the order is successfully authorized. |
Request Example
<?php
declare(strict_types=1);
class Configuration
{
public const MERCHANT_CODE = '';
public const MERCHANT_KEY = '';
public const URL = 'http://api.2checkout.com/soap/6.0';
public const ACTION = 'updateSubscriptionPaymentInformation';
public const ADDITIONAL_OPTIONS = null;
public const SUBSCRIPTION_REF = 'YC9XXMGOYO';
//array or JSON
public const PAYLOAD = <<<JSON
{
"PaymentDetails": {
"Type": "EES_TOKEN_PAYMENT",
"PaymentMethod": {
"EesToken": "f6347256-bbbb-45a8-be61-e21fe1725f47",
"Vendor3DSReturnURL": "www.3dsReturnURL.com",
"Vendor3DSCancelURL": "www.3dsCancelURL.com"
}
}
}
JSON;
}
class Client
{
public function call(
string $url = Configuration::URL,
$payload = Configuration::PAYLOAD,
string $action = Configuration::ACTION
): ?object
{
if (is_array($payload)) {
$payload = json_encode($payload);
}
if (!empty($payload)) {
// SoapClient works with objects(StdClass)
$payload = json_decode($payload);
}
$soapClient = $this->getClient($url);
$sessionId = $this->getSession($soapClient);
$args = array_filter([$sessionId, Configuration::SUBSCRIPTION_REF, $payload]);
return $soapClient->$action(...$args);
}
public function getClient(string $url): SoapClient
{
return new SoapClient(
$url . '?wsdl',
[
'location' => $url,
'cache_wsdl' => WSDL_CACHE_NONE,
]
);
}
public function getSession(SoapClient $client)
{
$date = gmdate('Y-m-d H:i:s');
$merchantCode = Configuration::MERCHANT_CODE;
$key = Configuration::MERCHANT_KEY;
$string = strlen($merchantCode) . $merchantCode . strlen($date) . $date;
$hash = hash_hmac('md5', $string, $key);
// $client->__setCookie('XDEBUG_SESSION', 'PHPSTORM');
return $client->login($merchantCode, $date, $hash);
}
}
try {
$client = new Client();
var_dump($client->call());
} catch (Exception $ex) {
var_dump($ex);
}
Response
The method responds with Boolean True when the payment information update was successfully performed.
Otherwise, in case of validation or access rights failures, it returns the usual error response with specific messages indicating the cause of the failure.
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV=http://schemas.xmlsoap.org/soap/envelope/ xmlns:ns1="urn:order" xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:SOAP-ENC=http://schemas.xmlsoap.org/soap/encoding/ SOAP-ENV:encodingStyle=http://schemas.xmlsoap.org/soap/encoding/>
<SOAP-ENV:Body>
<ns1:updateSubscriptionPaymentInformationResponse>
<updateSubscriptionPaymentInformationReturn xsi:type="ns1:PaymentDetailsCard">
<CardType xsi:type="xsd:string">visa</CardType>
<FirstDigits xsi:type="xsd:string">4012</FirstDigits>
<LastDigits xsi:type="xsd:string">9936</LastDigits>
<Authorize3DSUrl xsi:type="xsd:string">http://...</Authorize3DSUrl>
</updateSubscriptionPaymentInformationReturn>
</ns1:updateSubscriptionPaymentInformationResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Retrieve specific list of subscriptions
Overview
Extract information on a specific list of subscriptions. Use the getSubscriptions method to retrieve details about a specific list of your account’s subscriptions.
Subscriptions can be retrieved starting with 5 minutes after their orders are generated in the 2Checkout system.
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. |
subscriptionReference |
Required (Array of strings) |
Unique, system-generated subscription identifier. |
|
aggregate |
Required (boolean) |
|
true - search will work across all your aggregated 2Checkout accounts. false - default value. You limit the search to the account whose details you used for authentication. |
Response
Parameters | Type/Description |
---|---|
Array of objects |
Request
<?php
require ('PATH_TO_AUTH');
$SubscriptionReferences = array('REFERENCE1', 'REFERENCE2', 'REFERENCE3');
try {
$ListofSubscriptions = $client->getSubscriptions($sessionID, $SubscriptionReferences);
}
catch (SoapFault $e) {
echo "ListofSubscriptions: " . $e->getMessage();
exit;
}
var_dump("ListofSubscriptions", $ListofSubscriptions);
Test adding product coupons to the InLine Checkout
Overview
Use theTwoCoInlineCart.card.addCoupons(['COUPON'])
method to apply multiple coupons.
Use case - Add Coupons
- Add an HTML link or button in your page like the one below.
- Create a JavaScript click handler to execute the Inline Client desired methods.
- Use the
TwoCoInlineCart.products.add({code, quantity, options})
method to prepare your catalog product. - To apply several coupons to your cart products, use the
TwoCoInlineCart.card.addCoupons(['COUPON'])
method. - To show the cart on your page call the
TwoCoInlineCart.cart.checkout()
method.
Sample request
HTML
<a href="#" class="btn btn-success" id="buy-button">Buy now!</a>
JavaScript
window.document.getElementById('buy-button').addEventListener('click', function() {
TwoCoInlineCart.products.add({
code: "74B8E17CC0"
});
TwoCoInlineCart.cart.addCoupons(['CUPON']);
TwoCoInlineCart.cart.checkout();
});
Demo
After setting the test mode to add coupons to the InLine Checkout using the above method, your cart should look like this:
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).
Update price options
Overview
Use the updatePriceOptionGroup method to update/edit an existing price options group you configured for your account. Price options intervals cannot overlap.
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. |
Required (object) |
|
|
Use this object to update/edit a new price option group for your account. |
You cannot update the Code and Required parameters of the price options group.
Response
bool(true)
Request
<?php
require ('PATH_TO_AUTH');
$SearchOptions = new stdClass ();
$SearchOptions->Name = 'New Users from API';
$SearchOptions->Types = array('INTERVAL', 'RADIO'); //RADIO, CHECKBOX, INTERVAL, COMBO, INTERVAL
$SearchOptions->Limit = 10;
$SearchOptions->Page = 1;
$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'searchPriceOptionGroups',
'params' => array($sessionID, $SearchOptions)
);
$existentPriceOptions = callRPC((Object)$jsonRpcRequest, $host, true);
var_dump ($existentPriceOptions);
$updatedPriceOptions = $existentPriceOptions[0];
$existentPriceOptions[0]->Translations[0]->Name = 'New Users from API3';
$existentPriceOptions[0]->Translations[0]->Language = 'EN';
$updatedPriceOptions = $existentPriceOptions[0];
echo "$updatedPriceOptions->Name";
$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'updatePriceOptionGroup',
'params' => array($sessionID, $updatedPriceOptions)
);
var_dump (callRPC((Object)$jsonRpcRequest, $host, true));
?>