Overview

Use the updatePricingConfiguration method to update/edit an existing pricing configuration.

Requirements

You cannot modify:

• The pricing configuration CODE.
• The PricingSchema from DYNAMIC to FLAT or vice versa.
• The intervals of an existing pricing configuration (MinQuantity and MaxQuantity). 

Parameters

Response

bool(true)

Request

<?php

require ('PATH_TO_AUTH');

$ProductCode = 'YOUR_PRODUCT_CODE';

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

$existingPricingConfig = callRPC((Object)$jsonRpcRequest, $host);
var_dump ($existingPricingConfig );
die;
$existingPricingConfig[1]->Prices->Regular[0]->Currency = 'USD';
$existingPricingConfig[1]->Prices->Regular[0]->Amount = 99;
$newPriceConfig = $existingPricingConfig[1];

$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'updatePricingConfiguration',
'params' => array($sessionID, $newPriceConfig, $ProductCode) //Use product ID and not product code for API versions smaller than 2.5
);

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

?>

Overview

Use the getSingleSignOnByCustomer method to create Single Sign-On links into 2Checkout myAccount based on customer references (IDs). Use either the 2Checkout Customer Reference or the External Customer Reference to identify specific customers.

Parameters

Response

Request

<?php
$host   = "https://api.2checkout.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.2checkout.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.2checkout.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 = '2CheckoutCustomerReference';
$Page = 'my_license';
$Request = null;
$ValidityTime = 50;
$ValidationIp = null;
try {
    $ssoLINK = $client->getSingleSignOnByCustomer($sessionID, $IdCustomer, $CustomerType, $Page, $Request, $ValidityTime, $ValidationIp);
}
catch (SoapFault $e) {
    echo "ssoLINK: " . $e->getMessage();
    exit;
}
var_dump("ssoLINK", $ssoLINK);

Overview

Place an order with dynamic order information without requiring any payment information from the customers.

Requirements

The final order price has to be 0. Either use products with zero price, or add a promotion for 100% of the total order price. Recurring options should not be sent. Set the PaymentDetails type to FREE.

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';//"10.10.13.37";
$Order->Source = "sourceAPI.net";
$Order->LocalTime = date('Y-m-d H:i:s');
$Order->CustomerReference = 421820775;
$Order->Items = array();

/**
 * 1st Product
 */
$Order->Items[0] = new stdClass();
$Order->Items[0]->Code = null;
$Order->Items[0]->Quantity = 2;
$Order->Items[0]->PurchaseType = 'PRODUCT';
$Order->Items[0]->Tangible = false; // physical
$Order->Items[0]->IsDynamic = true;
$Order->Items[0]->Price = new stdClass();
$Order->Items[0]->Price->Amount = 0; // should be 0
$Order->Items[0]->Price->Type = 'CUSTOM';
$Order->Items[0]->ProductTaxCategoryUUID = '2ad5ecfe-508d-4852-bd24-d400c297523b';
$Order->Items[0]->PriceType = 'GROSS'; // optional, can be GROSS or NET; GROSS is default;
$Order->Items[0]->Name = 'Dynamic Product 1 '. date("Y-m-d H:i:s");
$Order->Items[0]->Description = 'Description Produs OTF';

$Order->Items[0]->PriceOptions = [];
$priceOption = new stdClass();
$priceOption->Name = 'Name';
$priceOption->Value = 'Value';
$priceOption->Surcharge = 0;
$Order->Items[0]->PriceOptions[] = $priceOption;

$priceOption1 = new stdClass();
$priceOption1->Name = 'Name';
$priceOption1->Value = 'Value123';
$priceOption1->Surcharge = 0;
$Order->Items[0]->PriceOptions[] = $priceOption1;

$priceOption2 = new stdClass();
$priceOption2->Name = 'Name1';
$priceOption2->Value = 'Value1';
$priceOption2->Surcharge = 0;
$Order->Items[0]->PriceOptions[] = $priceOption2;



/*
 * 3rd Product - SHIPPING
 */

$Order->Items[2] = new stdClass();
$Order->Items[2]->Name = 'Shipping Item '. date("Y-m-d H:i:s");
$Order->Items[2]->PurchaseType = 'SHIPPING';
$Order->Items[2]->Quantity = 1;
$Order->Items[2]->Price = new stdClass();
$Order->Items[2]->Price->Amount = 0; // should be 0
$Order->Items[2]->IsDynamic = true;

/**
 * 4th Product - TAX
 */
$Order->Items[3] = new stdClass();
$Order->Items[3]->Name = 'Tax Item '. date("Y-m-d H:i:s");
$Order->Items[3]->PurchaseType = 'TAX';
$Order->Items[3]->Quantity = 1;
$Order->Items[3]->Price = new stdClass();
$Order->Items[3]->Price->Amount = 0; // should be 0
$Order->Items[3]->IsDynamic = true;


/**
 * 5th Product - COUPON
 */
$Order->Items[4] = new stdClass();
$Order->Items[4]->Name = 'Coupon Item '. date("Y-m-d H:i:s");
$Order->Items[4]->PurchaseType = 'COUPON';
$Order->Items[4]->Quantity = 0;
$Order->Items[4]->Price = new stdClass();
$Order->Items[4]->Price->Amount = 0; // should be 0, or the amount should be the opposite to the one send in the order
$Order->Items[4]->IsDynamic = true;
$Order->Items[0]->ProductTaxCategoryUUID = '2ad5ecfe-508d-4852-bd24-d400c297523b';
$Order->Items[0]->PriceType = 'GROSS'; // optional, can be GROSS or NET; GROSS is default;

/**/

$additionalField1 = new stdClass();
$additionalField1->Code = "additional_field_order_1";
$additionalField1->Text = "REST";
$additionalField1->Value = "1";

$Order->AdditionalFields = array();

$additionalField1 = new stdClass();
$additionalField1->Code = "REST";
$additionalField1->Text = "REST";
$additionalField1->Value = "REST";

$Order->MachineId = 'machineIdTestDan';
$Order->Discount = null;
$Order->ExternalReference = null;

$Order->BillingDetails = new stdClass();
$Order->BillingDetails->Address1 = 'John';
$Order->BillingDetails->Address2 = 'Doe';
$Order->BillingDetails->City = 'New York City';
$Order->BillingDetails->State = 'New York';
$Order->BillingDetails->CountryCode = 'US';
$Order->BillingDetails->Phone = 12345;
$Order->BillingDetails->Email = 'shopper@avangate.com';
$Order->BillingDetails->FirstName = 'John';
$Order->BillingDetails->LastName = 'Doe';
$Order->BillingDetails->Company = 'ABC Company';
$Order->BillingDetails->Zip = '12345';
$Order->BillingDetails->FiscalCode = 13205628845;

/**/
$Order->DeliveryDetails = new stdClass();
$Order->DeliveryDetails->Address1 = 'Delivery details 1';
$Order->DeliveryDetails->Address2 = 'Delivery detais 2';
$Order->DeliveryDetails->City = 'New York City';
$Order->DeliveryDetails->State = 'New York';
$Order->DeliveryDetails->CountryCode = 'US';
$Order->DeliveryDetails->Phone = '12345';
$Order->DeliveryDetails->Email = 'customer@email.com';
$Order->DeliveryDetails->FirstName = 'John';
$Order->DeliveryDetails->LastName = 'Doe';
$Order->DeliveryDetails->Zip = 12345;
/**/

$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'FREE';
$Order->PaymentDetails->Currency = 'usd';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = false;


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

$order = callRPC($jsonRpcRequest, $host);
var_dump($order);

Overview

Use the getSKUCodeByDetails method to retrieve an SKU based on its included details.

Parameters

Response

{SKUCode} // eg: SKU-EUR-1-10-N-A

Request

<?php
require ('PATH_TO_AUTH');

$skuDetailsObject = new \stdClass();
$skuDetailsObject->PricingConfigurationCode = 'YOUR_CODE';
$skuDetailsObject->Currency = 'USD';
$skuDetailsObject->PurchaseType = 'NEW_PRODUCT';
$skuDetailsObject->PriceOptions = ['A'];
$skuDetailsObject->Quantity = 1;

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

$getSkuCodeByDetails = callRPC($jsonRpcRequest, $host);
var_dump($getSkuCodeByDetails);

Overview

Place a test order using catalog products defined in your Control Panel.

Requirements

Set the Payment details type to TEST in order to create an order in a test environment.

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';
$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]->SubscriptionStartDate = NULL; //If empty or null, subscriptions become active when purchase is made.

$Order->BillingDetails = new stdClass();
$Order->BillingDetails->FirstName = 'John';
$Order->BillingDetails->LastName = 'Doe';
$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 = 'cosmin.deftu@2checkout.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' => 'placeOrder',
'params' => array($sessionID, $Order),
'id' => $i++,
'jsonrpc' => '2.0'
);

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

Overview

Place an order with dynamic order information without requiring any payment information from the customers.

Requirements

The final order price has to be 0. Either use products with zero price, or add a promotion for 100% of the total order price. Recurring options should not be sent. Set the PaymentDetails type to FREE.

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';//"10.10.13.37";
$Order->Source = "sourceAPI.net";
$Order->LocalTime = date('Y-m-d H:i:s');
$Order->CustomerReference = 421820775;
$Order->Items = array();

/**
 * 1st Product
 */
$Order->Items[0] = new stdClass();
$Order->Items[0]->Code = null;
$Order->Items[0]->Quantity = 2;
$Order->Items[0]->PurchaseType = 'PRODUCT';
$Order->Items[0]->Tangible = false; // physical
$Order->Items[0]->IsDynamic = true;
$Order->Items[0]->Price = new stdClass();
$Order->Items[0]->Price->Amount = 0; // should be 0
$Order->Items[0]->Price->Type = 'CUSTOM';
$Order->Items[0]->Name = 'Dynamic Product 1 '. date("Y-m-d H:i:s");
$Order->Items[0]->Description = 'Description Produs OTF';

$Order->Items[0]->PriceOptions = [];
$priceOption = new stdClass();
$priceOption->Name = 'Name';
$priceOption->Value = 'Value';
$priceOption->Surcharge = 0;
$Order->Items[0]->PriceOptions[] = $priceOption;

$priceOption1 = new stdClass();
$priceOption1->Name = 'Name';
$priceOption1->Value = 'Value123';
$priceOption1->Surcharge = 0;
$Order->Items[0]->PriceOptions[] = $priceOption1;

$priceOption2 = new stdClass();
$priceOption2->Name = 'Name1';
$priceOption2->Value = 'Value1';
$priceOption2->Surcharge = 0;
$Order->Items[0]->PriceOptions[] = $priceOption2;



/*
 * 3rd Product - SHIPPING
 */

$Order->Items[2] = new stdClass();
$Order->Items[2]->Name = 'Shipping Item '. date("Y-m-d H:i:s");
$Order->Items[2]->PurchaseType = 'SHIPPING';
$Order->Items[2]->Quantity = 1;
$Order->Items[2]->Price = new stdClass();
$Order->Items[2]->Price->Amount = 0; // should be 0
$Order->Items[2]->IsDynamic = true;

/**
 * 4th Product - TAX
 */
$Order->Items[3] = new stdClass();
$Order->Items[3]->Name = 'Tax Item '. date("Y-m-d H:i:s");
$Order->Items[3]->PurchaseType = 'TAX';
$Order->Items[3]->Quantity = 1;
$Order->Items[3]->Price = new stdClass();
$Order->Items[3]->Price->Amount = 0; // should be 0
$Order->Items[3]->IsDynamic = true;


/**
 * 5th Product - COUPON
 */
$Order->Items[4] = new stdClass();
$Order->Items[4]->Name = 'Coupon Item '. date("Y-m-d H:i:s");
$Order->Items[4]->PurchaseType = 'COUPON';
$Order->Items[4]->Quantity = 0;
$Order->Items[4]->Price = new stdClass();
$Order->Items[4]->Price->Amount = 0; // should be 0, or the amount should be the opposite to the one send in the order
$Order->Items[4]->IsDynamic = true;

/**/

$additionalField1 = new stdClass();
$additionalField1->Code = "additional_field_order_1";
$additionalField1->Text = "REST";
$additionalField1->Value = "1";

$Order->AdditionalFields = array();

$additionalField1 = new stdClass();
$additionalField1->Code = "REST";
$additionalField1->Text = "REST";
$additionalField1->Value = "REST";

$Order->MachineId = 'machineIdTestDan';
$Order->Discount = null;
$Order->ExternalReference = null;

$Order->BillingDetails = new stdClass();
$Order->BillingDetails->Address1 = 'John';
$Order->BillingDetails->Address2 = 'Doe';
$Order->BillingDetails->City = 'New York City';
$Order->BillingDetails->State = 'New York';
$Order->BillingDetails->CountryCode = 'US';
$Order->BillingDetails->Phone = 12345;
$Order->BillingDetails->Email = 'shopper@2checkout.com';
$Order->BillingDetails->FirstName = 'John';
$Order->BillingDetails->LastName = 'Doe';
$Order->BillingDetails->Company = 'ABC Company';
$Order->BillingDetails->Zip = '12345';
$Order->BillingDetails->FiscalCode = 13205628845;

/**/
$Order->DeliveryDetails = new stdClass();
$Order->DeliveryDetails->Address1 = 'Delivery details 1';
$Order->DeliveryDetails->Address2 = 'Delivery detais 2';
$Order->DeliveryDetails->City = 'New York City';
$Order->DeliveryDetails->State = 'New York';
$Order->DeliveryDetails->CountryCode = 'US';
$Order->DeliveryDetails->Phone = '12345';
$Order->DeliveryDetails->Email = 'customer@email.com';
$Order->DeliveryDetails->FirstName = 'John';
$Order->DeliveryDetails->LastName = 'Doe';
$Order->DeliveryDetails->Zip = 12345;
/**/

$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'FREE';
$Order->PaymentDetails->Currency = 'usd';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = false;

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

var_dump("newOrder", $newOrder);

Overview

Use the getSingleSignOnByCustomer method to create Single Sign On links into 2Checkout myAccount based on customer references (IDs). Use either the 2Checkout Customer Reference or the External Customer Reference to identify specific customers.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$idCustomer = '352365983';
$customerType = '2CheckoutCustomerReference';
$page = 'my_license';
$request = null;
$validityTime = 50;
$validationIp = null;
$languageCode = 'en';

try {
    $ssoLINK = $client->getSingleSignOnByCustomer(
        $sessionID,
        $idCustomer,
        $customerType,
        $page,
        $request,
        $validityTime,
        $validationIp,
        $languageCode // optional
    );
}
catch (SoapFault $e) {
    echo "ssoLINK: " . $e->getMessage();
    exit;
}
var_dump("ssoLINK", $ssoLINK);

Overview

Use the getNextRenewalPrice method to retrieve information on the costs customers incur on the next renewal for a subscription, per the recurring billing configuration.

Parameters

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';
$Currency = 'eur';

try {
    $renewalDetails = $client->getNextRenewalPrice($sessionID, $subscriptionReference, $Currency);
}
catch (SoapFault $e) {
    echo "renewalDetails: " . $e->getMessage();
    exit;
}
var_dump("renewalDetails", $renewalDetails);

Response

Overview

E-wallets are online payment methods where the order is registered by 2Checkout, but the shopper has to reach a 3rd party's website in order to authenticate and finalize the payment. PayPal is one of the most used E-wallet solutions that dominate the eCommerce world, but other local players, especially in Asian countries, are starting to gain market share.

The following payment methods are supported for the E-wallet (online payment methods) flow PayPal, Alipay, WeChat, iDeal.

Availability

Available to all 2Checkout accounts.

PayPal

Payment method Object structure

Request example

{
   "Language":"en",
   "Country":"US",
   "CustomerIP":"10.10.10.10",
   "Source":"Website",
   "ExternalCustomerReference":"externalCustomerId",
   "Currency":"USD",
   "MachineId":"123456789",
   "Items":[
      {
         "Code":"DD996A4DB3",
         "Quantity":1
      }
   ],
   "BillingDetails":{
      "FirstName":"Customer First Name",
      "LastName":"Customer Last Name",
      "CountryCode":"US",
      "State":"New York",
      "City":"New York",
      "Address1":"Example Street",
      "Zip":"10005",
      "Email":"customer@email.com"
   },
   "PaymentDetails":{
      "Type":"PAYPAL",
      "Currency":"USD",
      "PaymentMethod":{
         "RecurringEnabled":false,
         "ReturnURL":"http:\/\/mywebsite.com\/order\/",
         "Email":"customer@email.com"
      }
   }
}

Redirecting shoppers to PayPal

If the order is placed successfully, the 2Checkout API responds with the complete order information. Inside the PaymentDetails node, you will find the PaymentMethod node that contains the RedirectURL. 

The shopper needs to be redirected to this URL that takes them to the PayPal website to finalize the payment. Once the payment is finalized, shoppers are redirected back to the ReturnURL. 

PayPal Express - Alternative Flow

In some checkout flows, the user experience might require some details filled in by the shopper on PayPal's side. In order to streamline the checkout experience, this information can be used when placing orders by using the PayPal Express payment method. 

These are the required steps for the PayPal Express flow:

1. First, you must retrieve the RedirectURL from PayPal by calling the getPayPalExpressCheckoutRedirectURL method for JSON-RPC and SOAP, or by making a PUT request to /paymentmethods/PAYPAL_EXPRESS/redirecturl/ on REST.
2. The body of the request must contain the order object with, at a minimum, the product information as well as the payment details: the customer's email address and a ReturnURL, the page on the shop's side where the shopper is redirected after the flow is completed on the PayPal's side. 
3. The ReturnURL parses the response that PayPal sends in order to fetch the needed information and finalize the payment. 
4. The getPayPalExpressCheckoutRedirectURL method will return a URL where the shopper needs to be redirected in order to complete the payment.
5. Once the shopper completes the payment, PayPal returns the shopper to the URL provided in the ReturnURL. The information provided by the shopper on PayPal's side is available in the GET parameters of the ReturnURL (all information is MIME base64 encoded):

• billing details (under the billingDetails key)
• delivery details (under the deliveryDetails key)
• a token in the URL.

6. If the shopper cancels their payment, then the cancel key will be returned in the URL. 

7. The information provided in the billing and delivery details must be filled in the order object. 

The payment method object will look like this:

In JSON, this looks like:

    "PaymentDetails": {
        "Type": "PAYPAL_EXPRESS",
        "Currency": "EUR",
        "CustomerIP": "91.220.121.21",
        "PaymentMethod": {
            "Email": "customer@email.com",
            "Token": "EC-470284976K7901234",
            "ReturnURL": "http://shop.com/place_order_api_json_paypal_express_response.php",
            "CancelURL": "http://shop.com/place_order_api_json_paypal_express_response.php?cancel=true"
        }
    }

Alipay

Payment method object structure

Alipay does not require any mandatory fields to be sent in the PaymentDetails node of the request.

Request example

{
   "Language":"en",
   "Country":"HK",
   "CustomerIP":"10.10.10.10",
   "Source":"Website",
   "ExternalCustomerReference":"externalCustomerId",
   "Currency":"CNY",
   "MachineId":"123456789",
   "Items":[
      {
         "Code":"DD996A4DB3",
         "Quantity":1
      }
   ],
   "BillingDetails":{
      "FirstName":"Customer First Name",
      "LastName":"Customer Last Name",
      "CountryCode":"HK",
      "State":"Hong Kong",
      "City":"Hong Kong",
      "Address1":"Example Street",
      "Zip":"999077",
      "Email":"example@email.com"
   },
   "PaymentDetails":{
      "Type":"ALIPAY",
      "Currency":"CNY",
      "PaymentMethod":{
         "RecurringEnabled":false
      }
   }
}

Redirecting shoppers to Alipay

If the order is placed successfully, the 2Checkout API responds with the complete order information. Inside the PaymentDetails node, you will find the PaymentMethod/Redirect node that contains the URL. 

The shopper needs to be redirected to this URL. This takes them to the Alipay website, where they can finalize the payment. 

WeChat

Payment method object structure

Request example

{
   "Language":"en",
   "Country":"CN",
   "CustomerIP":"10.10.10.10",
   "Source":"Website",
   "ExternalCustomerReference":"externalCustomerId",
   "Currency":"USD",
   "MachineId":"123456789",
   "Items":[
      {
         "Code":"DD996A4DB3",
         "Quantity":1
      }
   ],
   "BillingDetails":{
      "FirstName":"Customer First Name",
      "LastName":"Customer Last Name",
      "CountryCode":"CN",
      "State":"Beijing",
      "City":"Beijing",
      "Address1":"Example Street",
      "Zip":"102629",
      "Email":"example@email.com"
   },
   "PaymentDetails":{
      "Type":"WE_CHAT_PAY",
      "Currency":"USD",
      "PaymentMethod":{
         "RecurringEnabled":false,
         "ReturnURL":"http:\/\/yourreturnurl.com",
         "CancelURL":"http:\/\/yourcancelurl.com"
      }
   }
}

Redirecting shoppers to WeChat

If the order is placed successfully, the 2Checkout API responds with the complete order information. Inside the PaymentDetails node, you will find the PaymentMethod/Authorize node that contains the Href, Method, and Params node. 

The shopper needs to be redirected to this Href, using the Method mentioned in the API response. Additionally, the parameters in the Params node need to be sent as key-value pairs in the request.

This takes shoppers to the WeChat website, where they can finalize the payment. 

iDeal

iDeal is a standardized online banking-based payment method tailored to users in the Netherlands. iDEAL supports online payments via secure online transfers directly between bank accounts. 

To place an order with iDeal, the shopper needs to select the bank that they use. The full list of supported banks can be queried via API by calling the getIdealIssuerBanks method (SOAP and JSON-RPC) or making a GET request /paymentmethods​/IDEAL​/issuerbanks​/ on REST.

The output of this API call is the list of supported banks, as code (to be used when placing the order), and the user-readable name of the bank.

[
   {
      "Code":"ABNANL2A+ABN",
      "Name":"ABN AMRO"
   },
   {
      "Code":"RABONL2U+RAB",
      "Name":"Rabobank"
   },
   {
      "Code":"INGBNL2A+ING",
      "Name":"ING"
   }
]

Payment method Object structure

 Request example

{
   "Language":"en",
   "Country":"NL",
   "CustomerIP":"10.10.10.10",
   "Source":"Website",
   "ExternalCustomerReference":"externalCustomerId",
   "Currency":"EUR",
   "MachineId":"123456789",
   "Items":[
      {
         "Code":"DD996A4DB3",
         "Quantity":1
      }
   ],
   "BillingDetails":{
      "FirstName":"Customer First Name",
      "LastName":"Customer Last Name",
      "CountryCode":"NL",
      "State":"North Holand",
      "City":"Amsterdam",
      "Address1":"Example Street",
      "Zip":"1183",
      "Email":"example@email.com"
   },
   "PaymentDetails":{
      "Type":"IDEAL",
      "Currency":"EUR",
      "PaymentMethod":{
         "ReturnURL":"http:\/\/yourreturnurl.com",
         "CancelURL":"http:\/\/yourcancelurl.com",
         "BankCode":"RABONL2U+RAB"
      }
   }
}

Redirecting shoppers to finalize the payment

Once the order has successfully been placed, in the response in the PaymentDetails/PaymentMethod/Authorize node, you have the information needed to compose the URL where the shopper needs to finalize the payment.

The shopper needs to reach the Href via the Method HTTP method, with the key-values in the Params in the request parameters.

 "PaymentDetails":{
      "Type":"IDEAL",
      "Currency":"eur",
      "PaymentMethod":{
         "Authorize":{
            "Href":"https:\/\/api.avangate.com\/6.0\/scripts\/ideal\/authorize",
            "Method":"GET",
            "Params":{
               "avng8apitoken":"ukaiuljobm84jmt3"
            },
            "AvangateId":null
         },
         "ReturnURL":"http:\/\/yourreturnurl.com",
         "CancelURL":"http:\/\/yourcancelurl.com",
         "BankCode":"RABONL2U+RAB",
         "RecurringEnabled":false
      },
      "CustomerIP":"5.12.32.22"
   },

Once the shopper has finalized the payment, the order will be marked with 'status = Complete'.

Integration test cases

1. Build a request in order to place a new order, with all the relevant information. Make sure that when the order is sent in the API, the response contains an order object (order was placed successfully).
2. Make sure that you handle the redirect to the 3rd party site.
3. If you have any additional webhook integrations, make sure that the webhooks are correctly configured and that the notifications are received and processed successfully. 

Overview

Set up the 2Pay.js drop-in payments client to accept payments on your website. To collect payments you need to create a payment form, tokenize sensitive card information, and use that token to create a charge. 

Use the below method to set the language when generating the card component.

Use Case

1. Create a form with id="payment-form":

<form type="post" id="payment-form">
  <div class="form-group">
    <label for="name" class="label control-label">Name</label>
    <input type="text" id="name" class="field form-control">
  </div>
  <button class="btn btn-primary" type="submit">Generate token</button>
</form>

2. Inside the form, add an element with id="card-element". The form should now look like this: 

<form type="post" id="payment-form">
  <div class="form-group">
    <label for="name" class="label control-label">Name</label>
    <input type="text" id="name" class="field form-control">
  </div>

  <div id="card-element">
    <!-- A TCO IFRAME will be inserted here. -->
  </div>

  <button class="btn btn-primary" type="submit">Generate token</button>
</form>

3. Include the 2Pay.js drop-in payments client JavaScript:

<script type="text/javascript" src="https://2pay-js.2checkout.com/v1/2pay.js"></script>

4. Insert the following configuration JavaScript to set the language when adding the card component, and generate the token request:

window.addEventListener('load', function() {
  // Initialize the JS Payments SDK client.
  let jsPaymentClient = new  TwoPayClient('AVLRNG');
  
  // Set the desired language to be used inside the iframe.
  jsPaymentClient.setup.setLanguage('ro');
  
  // Create the component that will hold the card fields.
  let component = jsPaymentClient.components.create('card');
  
  // Mount the card fields component in the desired HTML tag. This is where the iframe will be located.
  component.mount('#card-element');

  // Handle form submission.
  document.getElementById('payment-form').addEventListener('submit', (event) => {
    event.preventDefault();
    
    // Extract the Name field value
    const billingDetails = {
      name: document.querySelector('#name').value
    };

    // Call the generate method using the component as the first parameter
    // and the billing details as the second one
    jsPaymentClient.tokens.generate(component, billingDetails).then((response) => {
      console.log(response.token);
    }).catch((error) => {
      console.error(error);
    });
  });
});

5. Place the order using the generated token.

Demo

After performing the steps above, your implementation should look like this: