3rd Party Apps for the 2checkout Platform
How do I build apps for the 2checkout platform?
- Sign-up for a 2Checkout account.
- Contact 2Checkout with your app proposal.
- 2Checkout reviews your application plan enables 3rd party apps for your account and creates a placeholder for your app.
- 2Checkout supplies you with authentication credentials.
- Build your application, integrate and test it with your account.
- Submit your final application for review.
- 2Checkout evaluates your application. Following the review process, 2Checkout can offer your app to all customers.
Payments for mobile apps (such as applications hosted in Google Play Store ) are not currently supported. However, our platform supports in-app integration using the 2Checkout API (you can integrate our shopping cart in your own application).
Installation
Add the following lines of code at the end of the <body> tag.
<script type="text/javascript" src="https://secure.2checkout.com/cpanel/js/third-party-apps/avangate.js"></script>
<div id="avangate-hero" class="hide"></div>
Authentication
Contact 2Checkout directly to start building applications on top of the 2Checkout platform. 2Checkout supplies you with the public and private authentication keys for your application.
Access requirements
Application authentication tokens work in tandem with user sessions for 2Checkout accounts. Users need to log into their account for 3rd party applications to have access to their data. Once account users log out, the application token expires and access is removed. By default, authentication tokens expire after one (1) hour.
Permanent authentication token
Contact 2Checkout to enable this functionality for your application. Once enabled, to make the auth token permanent use the 'permanentToken' parameter. This cases token expiration to grow to one (1) year.
Client side
1. Include the script from the Installation section in your JavaScript file you to access a global object called avangateCPanel that you can use for all the methods available in the client-side interface.
2. Next, set the PUBLIC_APP_ID and check that the scripts load in your JavaScript file.
var app = {
cPanel : false,
appID : 'PUBLIC_APP_ID',
init : function()
{
this.cPanel = avangateCPanel;
if (this.cPanel.init(this.appID)) {
console.log('everything is ready to be used');
}
}
};
app.init();
3. Check 2Checkout account login by requesting the auth token via JavaScript.
var app = {
cPanel : false,
appID : 'PUBLIC_APP_ID',
init : function()
{
this.cPanel = avangateCPanel;
if (this.cPanel.init(this.appID)) {
console.log('everything is ready to be used');
this.checkLogin();
}
},
checkLogin : function()
{
this.cPanel.authentify({
success: function(response) {
var authToken = response.value.authToken;
},
error: function(response) {
console.log(response.message); // something went wrong
}
});
}
};
app.init();
4. Send the authToken to your server for validation.
var app = {
cPanel : false,
appID : 'PUBLIC_APP_ID',
init : function()
{
this.cPanel = avangateCPanel;
if (this.cPanel.init(this.appID)) {
console.log('everything is ready to be used');
this.checkLogin();
}
},
checkLogin : function()
{
this.cPanel.authentify({
success: function(response) {
var authToken = response.value.authToken; // object {authToken: 'the auth token string', expirationDate: 'the expiration date of the token'}
$.when(
$http('/validateToken').post(authToken)
).then(
function() { //success
//user is logged
},
function() { //fail
// check what went wrong in the ajax call
}
);
},
error: function(response) {
console.log(response.message); // something went wrong
}
});
}
};
app.init();
Server side
This example uses Laravel framework and Guzzle Http library.
namespace App\Http\Controllers;
use Request;
use GuzzleHttp\Client as httpClient;
use App\Http\Controllers\Controller;
class MainController extends Controller {
protected $authInfo = false;
protected $apiBaseUrl = 'https://apps.api.avangate.com/';
// verifies and validates the auth token received via javascript
public function validateToken()
{
$this->authInfo = [
'authToken' => Request::input('authToken'),
'expirationDate' => Request::input('expirationDate'),
];
try {
$httpClient = $this->getHttpClient();
$response = $httpClient->put('verify/');
// to make the auth token permanent just apply the 'permanentToken' param (token expires in 1 year)
// contact Avangate to enable this functionality for your app
//$response = $httpClient->put('verify/', ['body' => ['permanentToken' => 1]]);
} catch (\Exception $e) {
$response = $e->getResponse();
}
return ($response->json() == true);
}
// http client configuration
private function getHttpClient()
{
return new httpClient([
'base_url' => $this->apiBaseUrl,
'timeout' => 2.0,
'defaults' => [
'proxy' => '',
'verify' => false,
'headers' => [
'authToken' => $this->authInfo['authToken'],
'secretID' => env('APP_SECRET'), // your app secret id
'Accept' => 'application/json'
]
]
]);
}
}
Get logged user info
This example uses Laravel framework and Guzzle Http library.
namespace App\Http\Controllers;
use Request;
use GuzzleHttp\Client as httpClient;
use App\Http\Controllers\Controller;
class MainController extends Controller {
protected $authInfo = false;
protected $apiBaseUrl = 'https://apps.api.avangate.com/';
// verifies and validates the auth token received via javascript
public function validateToken()
{
$this->authInfo = [
'authToken' => Request::input('authToken'),
'expirationDate' => Request::input('expirationDate'),
];
try {
$httpClient = $this->getHttpClient();
$response = $httpClient->put('verify/');
} catch (\Exception $e) {
$response = $e->getResponse();
}
if ($response->json() == true) {
$this->getAuthUserInfo();
}
}
/*
retrieves the logged user info
return an array with following structure
[
'Email' => (string),
'FirstName' => (string),
'LastName' => (string),
'VendorInfo' => [
'ClientCode' => (string),
'CompanyName' => (string),
'CommercialName' => (string),
'Homepage' => (string)
]
];
*/
private function getAuthUserInfo()
{
try {
$httpClient = $this->getHttpClient();
$response = $httpClient->get('user_info/');
} catch (\Exception $e) {
$response = $e->getResponse();
}
return $response->json();
}
// http client configuration
private function getHttpClient()
{
return new httpClient([
'base_url' => $this->apiBaseUrl,
'timeout' => 2.0,
'defaults' => [
'proxy' => '',
'verify' => false,
'headers' => [
'authToken' => $this->authInfo['authToken'],
'secretID' => env('APP_SECRET'), // your app secret id
'Accept' => 'application/json'
]
]
]);
}
}
Get API data
The API documentation can be found here.
This example uses Laravel framework and Guzzle Http library. From the API we will use the retrieve subscriptions method.
namespace App\Http\Controllers;
use Request;
use GuzzleHttp\Client as httpClient;
use App\Http\Controllers\Controller;
class MainController extends Controller {
protected $authInfo = false;
protected $apiBaseUrl = 'https://apps.api.avangate.com/';
// verifies and validates the auth token received via javascript
public function validateToken()
{
$this->authInfo = [
'authToken' => Request::input('authToken'),
'expirationDate' => Request::input('expirationDate'),
];
try {
$httpClient = $this->getHttpClient();
$response = $httpClient->put('verify/');
} catch (\Exception $e) {
$response = $e->getResponse();
}
if ($response->json() == true) {
$this->getSubscriptions();
}
}
private function getSubscriptions()
{
try {
$httpClient = $this->getHttpClient();
$response = $httpClient->get('subscriptions/');
} catch (\Exception $e) {
$response = $e->getResponse();
}
return $response->json();
}
// http client configuration
private function getHttpClient()
{
return new httpClient([
'base_url' => $this->apiBaseUrl,
'timeout' => 2.0,
'defaults' => [
'proxy' => '',
'verify' => false,
'headers' => [
'authToken' => $this->authInfo['authToken'],
'secretID' => env('APP_SECRET'), // your app secret id
'Accept' => 'application/json'
]
]
]);
}
}
Get ISE data
The ISE (Instant Search Order Export) documentation can be found here.
This example uses Laravel framework and Guzzle Http library.
namespace App;
use GuzzleHttp\Client as httpClient;
use Illuminate\Support\Facades\Session;
class Order
{
private function generateQuery($data = [])
{
$authInfo = Session::get('authInfo');
$queryParams = [
//required
'APP_CREDENTIALS_TOKEN' => $authInfo['authToken'],
'APP_CREDENTIALS_SECRET_ID' => env('APP_SECRET'),
'STARTDATE' => '2015-01-21 00:00:00',
'ENDDATE' => '2015-01-21 00:00:00',
'ORDERSTATUS' => 'ALL',
'REQ_DATE' => date('YmdHis'),
'PRODUCT_ID' => '',
'COUNTRY_CODE' => '',
'FILTER_STRING' => '',
'FILTER_FIELD' => '',
'HASH' => '',
//optional
'INCLUDE_DELIVERED_CODES' => '',
'INCLUDE_FINANCIAL_DETAILS' => '',
'INCLUDE_EXCHANGE_RATES' => '',
'INCLUDE_PRICING_OPTIONS' => '',
'EXPORT_FORMAT' => 'XML',
];
$queryParams = array_merge($queryParams, $data);
return $queryParams;
}
public function getOrders($searchParams = [])
{
if (!is_array($searchParams)) {
$searchParams = [];
}
$queryParams = $this->generateQuery($searchParams);
try {
$httpClient = $this->getHttpClient();
$response = $httpClient->post('ise/', [
'body' => $queryParams
]);
} catch (\Exception $e) {
$response = $e->getResponse();
}
if ($response->getBody()->getContents() != '') {
$response = $response->xml();
if (isset($response->RESPONSE_MSG)) {
return ['success' => false, 'message' => (string)$response->RESPONSE_MSG];
} else {
return ['success' => true, 'value' => $response->Orders];
}
} else {
return ['success' => false, 'message' => ''];
}
}
private function getHttpClient()
{
return new httpClient([
'base_url' => 'https://secure.avangate.com/action/',
'timeout' => 2.0,
'defaults' => [
'proxy' => '',
'verify' => false,
]
]);
}
}
Download mock application
This example uses Laravel framework and Guzzle Http library.
You can download the app from here.
The app uses an SQLite database for the information and it displays a list of items only if is a valid authentication session in the 2checkout Control Panel.
Download documentation and mock application
Click here to download the full documentation, including the mock application, as an archive that you can unpack and run locally.
