API Reference

This API reference consists of all the APIs provided by Paymentwall. The Paymentwall API can be interacted with HTTPS requests to obtain certain information from Paymentwall. Typically a JSON object including the required details will be returned except Widget API & Checkout API, which redirect your customer to Paymentwall for hosted checkout payment experience.

If you have any suggestions or confusion about our reference pages, please create a issue directly on our Github.

Library:

https://github.com/paymentwall/paymentwall-php

Library

https://github.com/paymentwall/paymentwall-node

Library

https://github.com/paymentwall/paymentwall-java

Library

https://github.com/paymentwall/paymentwall-ruby

Library

 https://github.com/paymentwall/paymentwall-python

Library

https://github.com/paymentwall/paymentwall-dotnet

Digital Goods

You can set either onetime payment or subscription in products section for your projects. Refer to product configuration for Digital Goods.

Parameters
Name Description
key
required
string
The project key which can be found in Merchant Area→ My Projects.
uid
required
string
ID of the end-user in your system. The maximum length is 64.
widget
required
string
Widget code. Can be obtained in the widget sections of your projects.
email
required
string
The email of end users. Paymentwall will automatically send a payment receipt to the user once his payment is successfully performed.
history[registration_date]
required
string
Unix timestamp of the registration date. The limitation of length is 10.
ps
required
string
It determines which payment method to be shown on payment page. Required to be in lowercase. Set it to all if you want to use selection form of payment methods provided by Paymentwall. Refer to payment system shortcodes to get the payment method code.
sign_version
required
integer
The signature version. Version 2 uses MD5 and version 3 represents SHA256.
sign
required
string lowercase
The signature of widget.
Refer to signature calculation for more details.
default_goodsid
string
The id of the product which you want to be chosen by default in the widget.
hide_goodsid[]
array
Id of the products that should not be displayed in the widget (e.g. &hide_goodsid[0]=product_1&hide_goodsid[1]=product_2). The array needs to be indexed explicitly for correct request signature calculation (e.g. hide_goodsid[0]=product_1 and not hide_goodsid[]=product_1).
display_goodsid
array
Id of the product to display in the widget e.g. display_goodsid[0]=product_1&display_goodsid[1]=product_2, which should be indexed explicitly.
tokidoki_plan_id
required for subscription
string
Id of the Tokidoki subscription plan.

You can also add optional parameters for extra needs or user profile parameters for risk scoring.

Endpoint

GET https://api.paymentwall.com/api/subscription

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');
Paymentwall_Config::getInstance()->set(array(
    'api_type' => Paymentwall_Config::API_GOODS,
    'public_key' => 'YOUR_PROJECT_KEY',
    'private_key' => 'YOUR_SECRET_KEY'
));

$widget = new Paymentwall_Widget(
    'userid', // uid
    'p1', // widget
    array() // Product parts, leave empty for Widget API
    array(
        'email' => 'user@hostname.com', 
        'history[registration_date]' => 'registered_date_of_user',
        'ps' => 'all' // Replace the value of 'ps' with specific payment system short code for Widget API uni
        'addtional_param_name' => 'addtional_param_value'
    )
);

echo $widget->getHtmlCode();
?>

Endpoint

GET https://api.paymentwall.com/api/subscription

Sample Request

var Paymentwall = require('paymentwall');
Paymentwall.Configure(
    Paymentwall.Base.API_GOODS,
    'YOUR_PROJECT_KEY',
    'YOUR_SECRET_KEY'
);

var widget = new Paymentwall.Widget(
    'user4002', // uid
    'p1', // widget
    [], // Product parts, leave empty for Widget API
    {	
        'email': 'user@hostname.com',
        'history[registration_date]': 'registered_date_of_user',
        'ps': 'all', // Replace the value of 'ps' with specific payment system short code for Widget API uni
        'additional_param_name': 'additional_param_value'
    }
);
widget.getHtmlCode();

Endpoint

GET https://api.paymentwall.com/api/subscription

Sample Request

Config.getInstance().setLocalApiType(Config.API_GOODS);
Config.getInstance().setPublicKey("YOUR_PROJECT_KEY");
Config.getInstance().setPrivateKey("YOUR_SECRET_KEY");

WidgetBuilder widgetBuilder = new WidgetBuilder("USER_ID", "p1");

widgetBuilder.setExtraParams(new LinkedHashMap<String, String>(){
{
    put("email", "YOUR_CUSTOMER_EMAIL");
    put("history[registration_date]","REGISTRATION_DATE");
    put("ps","all"); // Replace the value of 'ps' with specific payment system short code for Widget API uni
}
});

Widget widget = widgetBuilder.build();

return widget.getHtmlCode();

Endpoint

GET https://api.paymentwall.com/api/subscription

Sample Request

require 'paymentwall' # alternatively, require_relative '/path/to/paymentwall-ruby/lib/paymentwall.rb'
Paymentwall::Base::setApiType(Paymentwall::Base::API_GOODS)
Paymentwall::Base::setAppKey('YOUR_PROJECT_KEY')
Paymentwall::Base::setSecretKey('YOUR_SECRET_KEY')

widget = Paymentwall::Widget.new(
    'user40012', # uid
    'p1', # widget
    [], # Product parts, leave empty for Widget API
    {
        'email' => 'user@hostname.com',
        'history[registration_date]' => 'registered_date_of_user',
        'ps' => 'all', // Replace the value of 'ps' with specific payment system short code for Widget API uni
        'additional_param_name' => 'additional_param_value'
    }
)
puts widget.getHtmlCode()

Endpoint

GET https://api.paymentwall.com/api/subscription

Sample Request

from paymentwall import *
Paymentwall.set_api_type(Paymentwall.API_GOODS)
Paymentwall.set_app_key('YOUR_PROJECT_KEY')
Paymentwall.set_secret_key('YOUR_SECRET_KEY')

widget = Widget(
    'user4522', # uid
    'fp', # widget
    [], # Product parts, leave empty for Widget API
    {
        'email' => 'user@hostname.com',
        'history[registration_date]' => 'registered_date_of_user',
        'ps' => 'all', // Replace the value of 'ps' with specific payment system short code for Widget API uni
        'additional_param_name' => 'additional_param_value'
    }
)
print(widget.get_html_code())

Endpoint

GET https://api.paymentwall.com/api/subscription

Sample Request

using Paymentwall;

Paymentwall_Base.setApiType(Paymentwall_Base.API_GOODS);
Paymentwall_Base.setAppKey("YOUR_PROJECT_KEY"); 
Paymentwall_Base.setSecretKey("YOUR_SECRET_KEY");

widget = Widget(
    'user4522', # uid
    'p1', # widget
    [], # Product parts, leave empty for Widget API
    {
        'email' => 'user@hostname.com',
        'history[registration_date]' => 'registered_date_of_user',
        'ps' => 'all', // Replace the value of 'ps' with specific payment system short code for Widget API uni
        'additional_param_name' => 'additional_param_value'
    }
)
print(widget.get_html_code())

Endpoint

GET https://api.paymentwall.com/api/subscription

Tokidoki

Tokidoki is Paymentwall Subscription Management solution, which allows merchants to control their customers’ subscription payments on recurring basis.

We offer Tokidoki API for recurring billing plan and obtain package details.

Build Widget

Tokidoki API is for implementing subscription solution when product information is stored in Merchant Area Tokidoki section.

Please pass X-ApiKey through HttpHeader, the value is Project Key,which can be found in Merchant Area.

Parameters
Name Description
key
required
string
The project key which can be found in Merchant Area→ My Projects.
user_email
required
string
Email of the end-user in your system.
package_id
required
int
If you use stored package, It can be found in Merchant Area–>Tokidoki–>Packages section
It’s not required if request already contains package_sku_id
package_sku_id
required
varchar
Each package will be identified by an unique SKU ID. This is the SKU ID that you already inputted when you setup your package in Tokidoki section
It’s not required if request already contains package_id
custom
optional
array
Refer to more optional parameters for extra needs or user profile parameters for risk scoring.
tokidoki
required
boolean
If you would like to flexible subscription, You must add ‘tokidoki’ parameter with value 1 .

Endpoint

POST https://api.paymentwall.com/developers/tokidoki-api/widget-url

Sample Request for stored package

<?php
require_once('path/to/lib/paymentwall.php');
$key = 'YOUR_PROJECT_KEY';
$params = [
    'user_email' => 'YOUR_EMAIL@email.com',
    'package_id' => '29',
    'custom' => [
        'success_url' => 'https://www.xxx.com',
        'failure_url' => 'https://www.yyy.com'
        ]
    ];

$curlOptions = [
    CURLOPT_HEADER => false,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ApiKey:' . $key
        ],
        CURLOPT_POSTFIELDS => json_encode($params)
    ];

$endpoint = 'https://api.paymentwall.com/developers/tokidoki-api/widget-url';

$curl = curl_init();
curl_setopt_array($curl, $curlOptions);
curl_setopt($curl, CURLOPT_URL, $endpoint);
$content = curl_exec($curl);
curl_close($curl);

$response = json_decode($content, true);

if ($response['success'] == 1) {
    echo $response['data'] . PHP_EOL;
} else {
    echo $response['error'] . PHP_EOL;
}
?>

Sample Request for flexible package

<?php
require_once("/path/to/lib/paymentwall.php");

Paymentwall_Config::getInstance()->set(array(
'api_type' => Paymentwall_Config::API_GOODS,
'public_key' => 'YOUR_PROJECT_KEY',
'private_key' => 'YOUR_SECRET_KEY'
));

$productParams = [
'amount' => '1',
'currencyCode' => 'USD',
'name' => 'PRODUCT_NAME',
'productId' => 'PRODUCT_ID',
'productType' => 'subscription',
'periodLength' => '2',
'periodType' => 'month',//period type: day, week, month
'recurring' => '1'
];

$extraParams = [
'tokidoki' => '1',
'email' => 'user@hostname.com'
];

$product = new Paymentwall_Product(
$productParams['productId'],
$productParams['amount'],
$productParams['currencyCode'],
$productParams['name'],
$productParams['productType'],
$productParams['periodLength'],
$productParams['periodType'],
$productParams['recurring']
);

$widget = new Paymentwall_Widget(
'user@hostname.com', // uid
'p1', // widget
[$product],
$extraParams
);

echo $widget->getHtmlCode();
?>

List all current packages

The API is designed to obtain subscription package details.

Please pass X-ApiKey through HttpHeader, the value is Project Key,which can be found in Merchant Area.

Endpoint

GET https://api.paymentwall.com/developers/tokidoki-api/packages

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');

$key = 'YOUR_PROJECT_KEY';

$curlOptions = [
    CURLOPT_HEADER => false,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ApiKey: ' . $key
        ]
    ];

$endpoint = 'https://api.paymentwall.com/developers/tokidoki-api/packages';

$curl = curl_init();
curl_setopt_array($curl, $curlOptions);
curl_setopt($curl, CURLOPT_URL, $endpoint);
$content = curl_exec($curl);
curl_close($curl);

$response = json_decode($content, true);


if ($response['success'] == 1) {
    var_dump($response['data']) . PHP_EOL;
} else {
    var_dump($response['error']) . PHP_EOL;
}
?>

Show details a package

The API is designed to show details a package.

Please pass X-ApiKey through HttpHeader, the value is Project Key,which can be found in Merchant Area.

Parameters
Name Description
package_id
required
int
Package ID.

Endpoint

GET https://api.paymentwall.com/developers/tokidoki-api/packages?package_id={package_id}

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');

$key = 'YOUR_PROJECT_KEY';

$curlOptions = [
    CURLOPT_HEADER => false,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ApiKey: ' . $key
        ]
    ];

$endpoint = 'https://api.paymentwall.com/developers/tokidoki-api/packages?package_id=12';

$curl = curl_init();
curl_setopt_array($curl, $curlOptions);
curl_setopt($curl, CURLOPT_URL, $endpoint);
$content = curl_exec($curl);
curl_close($curl);

$response = json_decode($content, true);


if ($response['success'] == 1) {
    var_dump($response['data']) . PHP_EOL;
} else {
    var_dump($response['error']) . PHP_EOL;
}
?>

Create new package

The API is designed to help for merchant create new a package.

Please pass X-ApiKey through HttpHeader, the value is Project Key,which can be found in Merchant Area.

Note: Data post must be json.

Parameters
Name Description
name
required
varchar
Package name.
sku_id
required
varchar
Package skui id.
price
required
decimal
Package price.
currency_code
required
varchar
Package currency code.
period_length
required
smallint
Recurring billing duration.
period_type
required
tinyint
Recurring period type.
period_limit
required
tinyint
Recurring limited/unlimited.
active
required
tinyint
Package active.

Endpoint

POST https://api.paymentwall.com/developers/tokidoki-api/create-package

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');
$key = 'YOUR_PROJECT_KEY';
$params = [
    'name' => 'Package Example',
    'sku_id' => 'package_example',
    'price' => '123',
    'currency_code' => 'USD',
    'period_length' => '1',
    'period_type' => 'month',
    'period_limit' => '6'
    'active' => 1
    ];

$curlOptions = [
    CURLOPT_HEADER => false,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ApiKey:' . $key
        ],
        CURLOPT_POSTFIELDS => json_encode($params)
    ];

$endpoint = 'https://api.paymentwall.com/developers/tokidoki-api/create-package';

$curl = curl_init();
curl_setopt_array($curl, $curlOptions);
curl_setopt($curl, CURLOPT_URL, $endpoint);
$content = curl_exec($curl);
curl_close($curl);

$response = json_decode($content, true);

if ($response['success'] == 1) {
    echo $response['data'] . PHP_EOL;
} else {
    echo $response['error'] . PHP_EOL;
}
?>

Update a package

The API is designed to help for merchant update a package.

Please pass X-ApiKey through HttpHeader, the value is Project Key,which can be found in Merchant Area.

Note: Data post must is json

Parameters
Name Description
package_id
required
int
Package ID.
name
required
varchar
Package name.
price
required
decimal
Package price.
currency_code
required
varchar
Package currency code.
period_length
required
smallint
Recurring billing duration.
period_type
required
tinyint
Recurring period type.
period_limit
required
tinyint
Recurring limited/unlimited.
active
optional
tinyint
Package active.

Endpoint

POST https://api.paymentwall.com/developers/tokidoki-api/update-package

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');
$key = 'YOUR_PROJECT_KEY';
$params = [
    'name' => 'Update Package Example',
    'sku_id' => 'update_package_example',
    'price' => '12',
    'currency_code' => 'USD',
    'period_length' => '1',
    'period_type' => 'month',
    'period_limit' => '6'
    'active' => 1
    ];

$curlOptions = [
    CURLOPT_HEADER => false,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ApiKey:' . $key
        ],
        CURLOPT_POSTFIELDS => json_encode($params)
    ];

$endpoint = 'https://api.paymentwall.com/developers/tokidoki-api/update-package';

$curl = curl_init();
curl_setopt_array($curl, $curlOptions);
curl_setopt($curl, CURLOPT_URL, $endpoint);
$content = curl_exec($curl);
curl_close($curl);

$response = json_decode($content, true);

if ($response['success'] == 1) {
    $response['data'] . PHP_EOL;
} else {
    echo $response['error'] . PHP_EOL;
}
?>

Remove a package

The API is designed to help for merchant remove a package.

Please pass X-ApiKey through HttpHeader, the value is Project Key,which can be found in Merchant Area.

Note: Data post must is json

Parameters
Name Description
package_id
required
int
Package ID.

Endpoint

POST https://api.paymentwall.com/developers/tokidoki-api/remove-package

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');
$key = 'YOUR_PROJECT_KEY';
$params = [
    'package_id' => '12'
    ];

$curlOptions = [
    CURLOPT_HEADER => false,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ApiKey:' . $key
        ],
        CURLOPT_POSTFIELDS => json_encode($params)
    ];

$endpoint = 'https://api.paymentwall.com/developers/tokidoki-api/remove-package';

$curl = curl_init();
curl_setopt_array($curl, $curlOptions);
curl_setopt($curl, CURLOPT_URL, $endpoint);
$content = curl_exec($curl);
curl_close($curl);

$response = json_decode($content, true);

if ($response['success'] == 1) {
    echo 'Delete package success!';
} else {
    echo $response['error'] . PHP_EOL;
}
?>

List all current subscriptions

The API is designed to get all current subscriptions in the system. In addition, You can list subscriptions by page.

Please pass X-ApiKey through HttpHeader, the value is Project Key,which can be found in Merchant Area.

Endpoint

GET https://api.paymentwall.com/developers/tokidoki-api/subscriptions

GET https://api.paymentwall.com/developers/tokidoki-api/subscriptions?page={number_page}

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');

$key = 'YOUR_PROJECT_KEY';

$curlOptions = [
    CURLOPT_HEADER => false,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ApiKey: ' . $key
        ]
    ];

$endpoint = 'https://api.paymentwall.com/developers/tokidoki-api/subscriptions';

$curl = curl_init();
curl_setopt_array($curl, $curlOptions);
curl_setopt($curl, CURLOPT_URL, $endpoint);
$content = curl_exec($curl);
curl_close($curl);

$response = json_decode($content, true);


if ($response['success'] == 1) {
    var_dump($response['data']) . PHP_EOL;
} else {
    var_dump($response['error']) . PHP_EOL;
}
?>

Show details a subscription

The API is designed to get a subscriptions in the system by subscription ID or customer email.

Please pass X-ApiKey through HttpHeader, the value is Project Key,which can be found in Merchant Area.

Endpoint

GET https://api.paymentwall.com/developers/tokidoki-api/subscriptions?subscription_id={subscription_id}

GET https://api.paymentwall.com/developers/tokidoki-api/subscriptions?subscriber_email={email}

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');

$key = 'YOUR_PROJECT_KEY';

$curlOptions = [
    CURLOPT_HEADER => false,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ApiKey: ' . $key
        ]
    ];

$endpoint = 'https://api.paymentwall.com/developers/tokidoki-api/subscription_id=100345523';
//$endpoint = 'https://api.paymentwall.com/developers/tokidoki-api/subscriber_email=user@hostname.com';//remove this comment if find the subscriptions by customer email
$curl = curl_init();
curl_setopt_array($curl, $curlOptions);
curl_setopt($curl, CURLOPT_URL, $endpoint);
$content = curl_exec($curl);
curl_close($curl);

$response = json_decode($content, true);


if ($response['success'] == 1) {
    var_dump($response['data']) . PHP_EOL;
} else {
    var_dump($response['error']) . PHP_EOL;
}
?>

Cancel a subscription

The API is designed to cancel a subscription in the system.

Please pass X-ApiKey through HttpHeader, the value is Project Key,which can be found in Merchant Area. Note: Data post must is json data.

Parameters
Name Description
subscription_id
required
int
Subscription ID.
cancel_type
required
boolean
There 2 types of cancel: cancel immediately by value is 0 and cancel at end period with value is 1.

Endpoint

POST https://api.paymentwall.com/developers/tokidoki-api/cancel-subscription

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');
$key = 'YOUR_PROJECT_KEY';
$params = [
    'subscription_id' => '100345523',
    ];

$curlOptions = [
    CURLOPT_HEADER => false,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ApiKey:' . $key
        ],
        CURLOPT_POSTFIELDS => json_encode($params)
    ];

$endpoint = 'https://api.paymentwall.com/developers/tokidoki-api/cancel-subscription';

$curl = curl_init();
curl_setopt_array($curl, $curlOptions);
curl_setopt($curl, CURLOPT_URL, $endpoint);
$content = curl_exec($curl);
curl_close($curl);

$response = json_decode($content, true);

if ($response['success'] == 1) {
    echo "Remove pending cancellation the subscription successfully!";
} else {
    echo $response['error'] . PHP_EOL;
}
?>

Change subscription’s package

Tokidoki offers the ability to change subscription’s package. We provide possibility to upgrade/downgrade from stored package to stored package, non-stored (flexible) package to non-stored package, stored package to flexible package and vice-versa.

Please pass X-ApiKey through HttpHeader, the value is Project Key,which can be found in Merchant Area.

Parameters
Paramerters Description
subscription_id
required
int
Subscription ID.
package_id
required
int
Package ID. If you would like to stored package
name
required
varchar
Package name If you would like to flexible package
sku_id
required
varchar
Package sku id with flexible package
price
required
decimal
Package price with flexible package
currency_code
required
varchar
Currency code with flexible package
period_length
required
smallint
recurring billing duration with flexible package
period_type
required
tinyint
recurring period type with flexible package
recurring_limit
required
tinyint
recurring limmited/unlimited with flexible package

Endpoint

POST https://api.paymentwall.com/developers/tokidoki-api/request-change-package

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');
$key = 'YOUR_PROJECT_KEY';
$params = [
    'subscription_id' => '1001101',
    'package_id' => '29'
    ]; //with stored package

//$params = [
    'subscription_id' => '1001101',
    'name' => 'Package Example',
    'sku_id' => 'package_example',
    'price' => '123',
    'currency_code' => 'USD',
    'period_length' => '1',
    'period_type' => 'month',
    'period_limit' => '6'
    ]; //with flexible package

$curlOptions = [
    CURLOPT_HEADER => false,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ApiKey:' . $key
        ],
        CURLOPT_POSTFIELDS => json_encode($params)
    ];

$endpoint = 'https://api.paymentwall.com/developers/tokidoki-api/request-change-package';

$curl = curl_init();
curl_setopt_array($curl, $curlOptions);
curl_setopt($curl, CURLOPT_URL, $endpoint);
$content = curl_exec($curl);
curl_close($curl);

$response = json_decode($content, true);

if ($response['success'] == 1) {
    echo 'Request change subscription's package successfully!;
} else {
    echo $response['error'] . PHP_EOL;
}
?>

Remove change package request

The API is designed to remove change (upgrade/downgrade) the package of a subscriptions in the system when That subscription have a request change package.

Please pass X-ApiKey through HttpHeader, the value is Project Key,which can be found in Merchant Area.

Parameters
Name Description
subscription_id
required
int
Subscription ID.

Endpoint

POST https://api.paymentwall.com/developers/tokidoki-api/remove-change-package

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');
$key = 'YOUR_PROJECT_KEY';
$params = [
    'subscription_id' => '100345523'
    ];

$curlOptions = [
    CURLOPT_HEADER => false,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ApiKey:' . $key
        ],
        CURLOPT_POSTFIELDS => json_encode($params)
    ];

$endpoint = 'https://api.paymentwall.com/developers/tokidoki-api/remove-change-package';

$curl = curl_init();
curl_setopt_array($curl, $curlOptions);
curl_setopt($curl, CURLOPT_URL, $endpoint);
$content = curl_exec($curl);
curl_close($curl);

$response = json_decode($content, true);

if ($response['success'] == 1) {
    echo 'Remove change package successfully!';
} else {
    echo $response['error'] . PHP_EOL;
}
?>

Remove pending cancel subscription

The API is designed to remove pending cancel of a subscriptions in the system when That subscription have a request cancel at end period.

Please pass X-ApiKey through HttpHeader, the value is Project Key,which can be found in Merchant Area.

Parameters
Name Description
subscription_id
required
int
Subscription ID.

List all current transactions

The API is designed to get all currently transactions in the system.

Please pass X-ApiKey through HttpHeader, the value is Project Key,which can be found in Merchant Area.

Endpoint

GET https://api.paymentwall.com/developers/tokidoki-api/transactions

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');

$key = 'YOUR_PROJECT_KEY';

$curlOptions = [
    CURLOPT_HEADER => false,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ApiKey: ' . $key
        ]
    ];

$endpoint = 'https://api.paymentwall.com/developers/tokidoki-api/transactions';

$curl = curl_init();
curl_setopt_array($curl, $curlOptions);
curl_setopt($curl, CURLOPT_URL, $endpoint);
$content = curl_exec($curl);
curl_close($curl);

$response = json_decode($content, true);


if ($response['success'] == 1) {
    var_dump($response['data']) . PHP_EOL;
} else {
    var_dump($response['error']) . PHP_EOL;
}
?>

Show details a transaction

The API is designed to show details a transaction in the system by transaction ID.

Please pass X-ApiKey through HttpHeader, the value is Project Key,which can be found in Merchant Area.

Name Description
transaction_id
required
int
Transaction ID.

Endpoint

GET https://api.paymentwall.com/developers/tokidoki-api/packages?transaction_id={transaction_id}

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');

$key = 'YOUR_PROJECT_KEY';

$curlOptions = [
    CURLOPT_HEADER => false,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ApiKey: ' . $key
        ]
    ];

$endpoint = 'https://api.paymentwall.com/developers/tokidoki-api/packages?transaction_id=1003708';

$curl = curl_init();
curl_setopt_array($curl, $curlOptions);
curl_setopt($curl, CURLOPT_URL, $endpoint);
$content = curl_exec($curl);
curl_close($curl);

$response = json_decode($content, true);


if ($response['success'] == 1) {
    var_dump($response['data']) . PHP_EOL;
} else {
    var_dump($response['error']) . PHP_EOL;
}
?>

Onetime payment

Parameters
Name Description
key
required
string
The project key which can be found in Merchant Area→ My Projects.
uid
required
string
ID of the end-user in your system. The maximum length is 64.
widget
required
string
Widget code. Can be obtained in the widget sections of your projects.
email
required
string
The email of end users. Paymentwall will automatically send a payment receipt to the user once his payment is successfully performed.
history[registration_date]
required
string
Unix timestamp of the registration date. The limitation of length is 10.
amount
required
double
The amount of your product. The minimum transaction limit is USD 0.3 or equivalent in other currencies.. 2 decimal places are expected.
currencyCode
required
string
Currency code of your product. Format by ISO 4217. 3 letters.
ag_name
required
string
Your product name. The maximum length is 256.
ag_external_id
required
string
ID of your product. Order reference ID could also be set here. We will communicate back to you via the pingback as goodsid parameter. The maximum length is 256.
ag_type
required
string
The payment type of your product. For onetime payment, it is required to be set to fixed.
ps
required
string
It determines which payment method to be shown on payment page. Required to be in lowercase. Set it to all if you want to use selection form of payment methods provided by Paymentwall. Refer to payment system shortcodes to get the payment method code.
sign_version
required
string
The signature version. Version 2 uses MD5 and version 3 represents SHA256.
sign
required
string lowercase
The signature of widget. Refer to signature calculation for more details.

You can also add optional parameters for extra needs or user profile parameters for risk scoring.

Endpoint

GET https://api.paymentwall.com/api/subscription

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');
Paymentwall_Config::getInstance()->set(array(
    'api_type' => Paymentwall_Config::API_GOODS,
    'public_key' => 'YOUR_PROJECT_KEY',
    'private_key' => 'YOUR_SECRET_KEY'
));

$widget = new Paymentwall_Widget(
    'user40012', // uid
    'p1', // widget
    array(
        new Paymentwall_Product(
        'product301', // ag_external_id
        9.99, // amount
        'USD', // currencyCode
        'Gold Membership', // ag_name
        Paymentwall_Product::TYPE_FIXED // ag_type
        )
    ),
    array(
        'email' => 'user@hostname.com', 
        'history[registration_date]' => 'registered_date_of_user',
        'ps' => 'all', // Replace it with specific payment system short code for single payment methods
        'addtional_param_name' => 'addtional_param_value'
    )
);
echo $widget->getUrl();
?>

Endpoint

GET https://api.paymentwall.com/api/subscription

Sample Request

var Paymentwall = require('paymentwall');
Paymentwall.Configure(
    Paymentwall.Base.API_GOODS,
    'YOUR_PROJECT_KEY',
    'YOUR_SECRET_KEY'
);

var widget = new Paymentwall.Widget(
    'user40012', // uid
    'p1', // widget 
    [
        new Paymentwall.Product(
            'product301', // ag_external_id
            9.99, // amount
            'USD', // currencycode
            Paymentwall.Product.TYPE_FIXED // ag_type
        )
    ],
    {
        'email': 'user@hostname.com',
        'history[registration_date]': 'registered_date_of_user',
        'ps': 'all', // Replace it with specific payment system short code for single payment methods
        'additional_param_name': 'additional_param_value'
    }
);
widget.getUrl();

Endpoint

GET https://api.paymentwall.com/api/subscription

Sample Request

Config.getInstance().setLocalApiType(Config.API_GOODS);
Config.getInstance().setPublicKey("YOUR_PROJECT_KEY");
Config.getInstance().setPrivateKey("YOUR_SECRET_KEY");

WidgetBuilder widgetBuilder = new WidgetBuilder("USER_ID", "p1");

widgetBuilder.setProduct( 
    new ProductBuilder("YOUR_PRODUCT_ID") {
    {
        setAmount(0.99);
        setCurrencyCode("USD");
        setName("YOUR_PRODUCT_NAME");
        setProductType(Product.TYPE_FIXED);
    }
}.build());

widgetBuilder.setExtraParams(new LinkedHashMap<String, String>(){
{
    put("email", "YOUR_CUSTOMER_EMAIL");
    put("history[registration_date]","REGISTRATION_DATE");
    put("ps","all"); // Replace it with specific payment system short code for single payment methods
}
});

Widget widget = widgetBuilder.build();

return widget.getUrl();

Endpoint

GET https://api.paymentwall.com/api/subscription

Sample Request

require 'paymentwall' # alternatively, require_relative '/path/to/paymentwall-ruby/lib/paymentwall.rb'
Paymentwall::Base::setApiType(Paymentwall::Base::API_GOODS)
Paymentwall::Base::setAppKey('YOUR_PROJECT_KEY')
Paymentwall::Base::setSecretKey('YOUR_SECRET_KEY')

widget = Paymentwall::Widget.new(
    'user40012', # uid
    'p1', # widget
    [
        Paymentwall::Product.new(
            'product301', # ag_external_id
            9.99, # amount
            'USD', # currencyCode
            'Gold Membership', # ag_name
            Paymentwall::Product::TYPE_FIXED # ag_type
        )
    ],
    {
        'email' => 'user@hostname.com',
        'history[registration_date]' => 'registered_date_of_user',
        'ps' => 'all', # Replace it with specific payment system short code for single payment methods
        'additional_param_name' => 'additional_param_value'
    }
)
puts widget.getUrl()

Endpoint

GET https://api.paymentwall.com/api/subscription

Sample Request

from paymentwall import *
Paymentwall.set_api_type(Paymentwall.API_GOODS)
Paymentwall.set_app_key('YOUR_PROJECT_KEY')
Paymentwall.set_secret_key('YOUR_SECRET_KEY')

product = Product(
    'product301', # ag_external_id
    12.12, # amount
    'USD', # currencyCode
    'test', # ag_name
    Product.TYPE_FIXED # ag_type
)

widget = Widget(
    'user4522', # uid
    'p1', # widget
    [product],
    {
        'email' : 'user@hostname.com',
        'history[registration_date]' => 'registered_date_of_user',
        'ps' : 'all', # Replace it with specific payment system short code for single payment methods
        'additional_param_name' : 'additional_param_value'
    }
)
print(widget.get_url())

Endpoint

GET https://api.paymentwall.com/api/subscription

Sample Request

using Paymentwall;

Paymentwall_Base.setApiType(Paymentwall_Base.API_GOODS);
Paymentwall_Base.setAppKey("YOUR_PROJECT_KEY"); 
Paymentwall_Base.setSecretKey("YOUR_SECRET_KEY");

List<Paymentwall_Product> productList = new List<Paymentwall_Product>();
Paymentwall_Product product = new Paymentwall_Product(
    "product301", // ag_external_id
    9.99, // amount
    "USD", // currencyCode
    "Gold Membership", // ag_name
    Paymentwall_Product.TYPE_FIXED, //ag_type
    );
productList.Add(product);
Paymentwall_Widget widget = new Paymentwall_Widget(
    "user40012", // uid
    "p1", // widget
    productList,
    new Dictionary<string, string>() {
        {
            'email' => 'user@hostname.com',
            'history[registration_date]' => 'registered_date_of_user',
            'ps' => 'all', // Replace it with specific payment system short code for single payment methods
            'additional_param_name' => 'additional_param_value'
        }
    }
);
Response.Write(widget.getUrl());

Endpoint

GET https://api.paymentwall.com/api/subscription

Subscription

Parameters
Name Description
key
required
string
The project key which can be found in Merchant Area→ My Projects.
uid
required
string
ID of the end-user in your system. The maximum length is 64.
widget
required
string
Widget code. Can be obtained in the widget sections of your projects.
email
required
string
The email of end users. Paymentwall will automatically send a payment receipt to the user once his payment is successfully performed.
history[registration_date]
required
string
Unix timestamp of the registration date. The limitation of length is 10.
amount
required
double
The amount of your product. The minimum transaction limit is USD 0.3 or equivalent in other currencies.. 2 decimal places are expected.
currencyCode
required
string
Currency code of your product. Format by ISO 4217. 3 letters.
ag_name
required
string
Your product name. The maximum length is 256.
ag_external_id
required
string
ID of your product. Reference ID could also be set here. We will communicate back to you via the pingback as goodsid parameter. The maximum length is 256.
ag_type
required
string
The payment type of your product. For subscription, it is required to be set to subscription.
ag_period_length
required
integer
The length of your subscription duration.
ag_period_type
required
string
The type of your subscription duration. Required to be set to following types, day/week/month/year.
ag_recurring
required
integer
The value could be either 1 or 0. Wether the product is recurring. If product is trial it should always be 1. By default, recurring billing is only supported for product with duration of at least 3 days and less than 1 year.
ag_trial
integer
The value could be either 1 or 0 (1 means trial). If trial is enabled, parameters with * are required.
post_trial_amount*
double
The amount of money of your product after trial period. 2 decimal places are requested.
post_trial_currencyCode*
string
Currency code of your product after trial period. Format by ISO 4217. 3 letters.
ag_post_trial_name*
string
Your product name after trial period. The maximum length is 256.
ag_post_trial_external_id*
string
ID of your product after trial period. The maximum length is 256.
ag_post_trial_period_type*
string
The type of subscription duration for your products after trial period. Required to be set to following types, day/week/month/year.
ag_post_trial_period_length*
integer
The length of subscription duration for your products after trial period.
ps
required
string
It determines which payment method to be shown on payment page. Required to be in lowercase. Set it to all if you want to use selection form of payment methods provided by Paymentwall. Refer to payment system shortcodes to get the payment method code.
sign_version
required
string
The signature version. Version 2 uses MD5 and version 3 represents SHA256.
sign
required
string lowercase
The signature of widget. Refer to signature calculation for more details.

You can also add optional parameters for extra needs or user profile parameters for risk scoring.

Endpoint

GET https://api.paymentwall.com/api/subscription

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');
Paymentwall_Config::getInstance()->set(array(
    'api_type' => Paymentwall_Config::API_GOODS,
    'public_key' => 'YOUR_PROJECT_KEY',
    'private_key' => 'YOUR_SECRET_KEY'
));

$widget = new Paymentwall_Widget(
    'user40012', // uid
    'p1', // widget
    array(
        new Paymentwall_Product(
        'product301', // ag_external_id
        9.99, // amount
        'USD', // currencyCode
        'Gold Membership', // ag_name
        Paymentwall_Product::TYPE_SUBSCRIPTION, // ag_type
        1, // ag_period_length
        Paymentwall_Product::PERIOD_TYPE_MONTH, // ag_period_type
        true // ag_recurring
        )
    ),
    array(
        'email' => 'user@hostname.com', 
        'history[registration_date]' => 'registered_date_of_user',
        'ps' => 'all', // Replace it with specific payment system short code for single payment methods
        'addtional_param_name' => 'addtional_param_value' 
    )
);
echo $widget->getUrl();
?>

Endpoint

GET https://api.paymentwall.com/api/subscription

Sample Request

var Paymentwall = require('paymentwall');
Paymentwall.Configure(
    Paymentwall.Base.API_GOODS,
    'YOUR_PROJECT_KEY',
    'YOUR_SECRET_KEY'
);

var widget = new Paymentwall.Widget(
    'user40012', // uid
    'p1', // widget 
    [
        new Paymentwall.Product(
            'product301', // ag_external_id
            9.99, // amount
            'USD', // currencyCode
            Paymentwall.Product.TYPE_SUBSCRIPTION, // ag_type
            1, // ag_period_length
            Paymentwall.Product.PERIOD_TYPE_MONTH, // ag_period_type
            true // ag_recurring
        )
    ],
    {
        'email': 'user@hostname.com',
        'history[registration_date]': 'registered_date_of_user',
        'ps': 'all', // Replace it with specific payment system short code for single payment methods
        'additional_param_name': 'additional_param_value'
    }
);
widget.getUrl();

Endpoint

GET https://api.paymentwall.com/api/subscription

Sample Request

Config.getInstance().setLocalApiType(Config.API_GOODS);
Config.getInstance().setPublicKey("YOUR_PROJECT_KEY");
Config.getInstance().setPrivateKey("YOUR_SECRET_KEY");

WidgetBuilder widgetBuilder = new WidgetBuilder("USER_ID", "p1");

widgetBuilder.setProduct( 
    new ProductBuilder("YOUR_PRODUCT_ID") {
    {
        setAmount(0.99);
        setCurrencyCode("USD");
        setName("YOUR_PRODUCT_NAME");
        setProductType(Product.TYPE_SUBSCRIPTION);
        setPeriodType("month");
        setPeriodLength(3);
    }
}.build());

widgetBuilder.setExtraParams(new LinkedHashMap<String, String>(){
{
    put("email", "YOUR_CUSTOMER_EMAIL");
    put("history[registration_date]","REGISTRATION_DATE");
    put("ps","all"); // Replace it with specific payment system short code for single payment methods
}
});

Widget widget = widgetBuilder.build();

return widget.getUrl();

Endpoint

GET https://api.paymentwall.com/api/subscription

Sample Request

require 'paymentwall' # alternatively, require_relative '/path/to/paymentwall-ruby/lib/paymentwall.rb'
Paymentwall::Base::setApiType(Paymentwall::Base::API_GOODS)
Paymentwall::Base::setAppKey('YOUR_PROJECT_KEY')
Paymentwall::Base::setSecretKey('YOUR_SECRET_KEY')

widget = Paymentwall::Widget.new(
    'user40012', # uid
    'p1', # widget
    [
        Paymentwall::Product.new(
            'product301', # ag_external_id
            9.99, # amount
            'USD', # currencyCode
            'Gold Membership', # ag_name
            Paymentwall::Product::TYPE_SUBSCRIPTION, # ag_type
            1, # ag_period_length
            Paymentwall::Product::PERIOD_TYPE_MONTH, # ag_period
            true # recurring
        )
    ],
    {
        'email' => 'user@hostname.com',
        'history[registration_date]' => 'registered_date_of_user',
        'ps' => 'all', # Replace it with specific payment system short code for single payment methods
        'additional_param_name' => 'additional_param_value'
    }
)
puts widget.getUrl()

Endpoint

GET https://api.paymentwall.com/api/subscription

Sample Request

from paymentwall import *
Paymentwall.set_api_type(Paymentwall.API_GOODS)
Paymentwall.set_app_key('YOUR_PROJECT_KEY')
Paymentwall.set_secret_key('YOUR_SECRET_KEY')

product = Product(
    'product301',              # id of the product in your system 
    12.12,                     # price
    'USD',                     # currency code
    'test',                    # product name
    Product.TYPE_SUBSCRIPTION, # this is a time-based product
    1,                         # duration is 1
    Product.PERIOD_TYPE_WEEK,  #               week
    True                       # recurring
)

widget = Widget(
    'user4522', # uid
    'p1', # widget
    [product], 
    {
        'email' : 'user@hostname.com',
        'history[registration_date]' => 'registered_date_of_user',
        'ps' : 'all', # Replace it with specific payment system short code for single payment methods
        'additional_param_name' : 'additional_param_value'
    }
)
print(widget.get_url())

Endpoint

GET https://api.paymentwall.com/api/subscription

Sample Request

using Paymentwall;

Paymentwall_Base.setApiType(Paymentwall_Base.API_GOODS);
Paymentwall_Base.setAppKey("YOUR_PROJECT_KEY"); 
Paymentwall_Base.setSecretKey("YOUR_SECRET_KEY");

List<Paymentwall_Product> productList = new List<Paymentwall_Product>();
Paymentwall_Product product = new Paymentwall_Product(
    "product301", // ag_external_id
    9.99, // amount
    "USD", // currencyCode
    "Gold Membership", // ag_name
    Paymentwall_Product.TYPE_SUBSCRIPTION, // ag_type
    1, // ag_period_length
    Paymentwall_Product.PERIOD_TYPE_YEAR, // ag_period_type
    true // ag_recurring
);
productList.Add(product);
Paymentwall_Widget widget = new Paymentwall_Widget(
    "user40012", 
    "p1", 
    productList,
    new Dictionary<string, string>() {
        {
            'email' => 'user@hostname.com',
            'history[registration_date]' => 'registered_date_of_user',
            'ps' => 'all', // Replace it with specific payment system short code for single payment methods
            'additional_param_name' => 'additional_param_value'
        }
    }
);
Response.Write(widget.getUrl());

Endpoint

GET https://api.paymentwall.com/api/subscription

User Profile

This is a list of additional risk parameters that can be used for risk scoring and risk assessment in order to prevent fraudulent payments. The risk parameters can be passed along with parameters in either widget API or checkout API for Paymentwall to account for the relevant merchant data when calculating the risk score and during risk review by Paymentwall risk agents.


At the point when an end-user wishes to make a payment, his registration details may be passed to Paymentwall that provides payment processing services, in order for Paymentwall to better protect service and end-users from unauthorized payments.

Parameters
Name Description
customer[birthday]
string
Unix timestamp of user’s birthday, seconds since Jan 01 1970.
customer[sex]
string
Male or female.
customer[username]
string
Username on the website, if applicable and different from uid parameter.
customer[firstname]
string
Given name of the user.
customer[lastname]
string
Family name of the user.
customer[city]
string
City name.
customer[state]
string
State/province name.
customer[address]
string
The address of customer.
customer[country]
string
Country code, ISO 3166-1 alpha-2, e.g. DE.
customer[zip]
string
ZIP/postal code.
history[membership]
string
Type of membership or loyalty program status at the time right before the payment is being made, if applicable. E.g.: no, gold, silver. Alternatively, in-game level can be passed in format 15/100 (15 out of 100).
history[membership_date]
string
Unix timestamp of last membership update.
history[registration_date]
string
Unix timestamp of the registration date.
history[registration_country]
string
Country code of the country used for the registration, ISO 3166-1 alpha-2.
history[registration_age]
string
Age used for the registration.
history[registration_ip]
string
IP address used for the registration.
history[registration_email]
string
Email address used for the registration.
history[registration_email_verified]
string
Whether the user is verified. 0 or 1.
history[registration_name]
string
First name(s) used for the registration.
history[registration_lastname]
string
Last name(s) used for the registration.
history[registration_source]
string
Identifier of the source where the registration is coming from; use cases: affiliate, referrer, website banner; example: history[registration_source]=affiliate_4312.
history[logins_number]
string
The times of logins since registration date.
history[payments_number]
string
The count of of successful payments made.
history[payments_amount]
string
Cumulative payments by the user converted into USD.
history[followers]
string
Followers, subscribers, friends and etc.
history[messages_sent]
string
The count of messages sent to other users.
history[messages_sent_last_24hours]
string
The count of messages sent to other users in the last 24 hours.
history[messages_received]
string
The count of messages received from other users.
history[interactions]
string
The count of people the user interacted with in total.
history[interactions_last_24hours]
string
The count of people the user interacted with in the last 24 hours.
history[customer_rating]
string
Customer rating out of 100, assigned by provider company or its members.
history[risk_score]
recommend
string
Fraud score or risk score within your system if applicable. varies from 0 to 100 where 0 is the most reliable user and 100 is the most fraudulent.
history[complaints]
string
Number of cases when the user had a complaint.
history[was_banned]
recommend
string
1 or 0 if the user was ever banned.
history[delivered_products]
string
The count of successfully delivered products (if applicable).
history[cancelled_payments]
string
The count of cancelled payments during user’s lifetime if any.

Optional

Optional parameters could be added as additional parameters in either widget API or checkout API for extra needs.

Parameters
Name Description
success_url
string
URL of the page where the end-user should be redirected to after the payment is complete. Additionally, $ref can be added as a placeholder in success_url to pass transaction id. E.g. https://website.com/thank-you?transaction_id=$ref
failure_url
string
URL of the page where the end-user should be redirected to after the payment is failed. It is used when the payment cannot be completed. For credit card, user won’t be redirected to the failure_url page as he may solve some errors by using another card.
pingback_url
string
Optional URL of pingback listener script where pingbacks should be sent. It overrides the default Pingback URL which sets up in Project Settings in Merchant Area. Please send request to devsupport@paymentwall.com for activating this feature.
logo_url
string
Optional URL of the logo to be shown on the widget. Project Logo can also be specifed in Project Settings. logo_url overrides such static project logo.
project_name
string
Optional Public Project Name displayed to end-users in the widget and on the payment receipt. Public Project Name can also be set in the Project Settings. project_name overrides this value.
lang
string
Language code to override the default geo-targeted language of the widget. 2 letters. eg: en. See language codes.
evaluation
integer
The value could be either 1 or 0. For test environment only.
If 1, everyone can see the content without being logged into the merchant account in the same browser session.
country_code
string
The length must be 2-character according to ISO 3166-1 alpha-2 code of the country. Required to be in uppercase. It overrides the location detected by ip.
merchant_order_id
string
When we get a request of checkout API, merchant-order-id is checked. If it is the same, we will warn users that the transaction has been made. Using merchant_order_id can help you to prevent duplicate orders. Please send email to devsupport@paymentwall.com to request for this feature.
logo_url
string
Custom company logo url specified.
project_name
string
Custom project name to be displayed on the widget.
ts
string
Time when request was initiated, represented as Unix timestamp - seconds since the Unix epoch (January 1 1970 00:00:00 GMT). If it’s older then 60 minutes, user sees an error message. Recommended for preventing widget from being shared.

Invoice

Paymentwall supports smart and organized e-invoicing solution. To activate it, please send email to devsupport@paymentwall.com with your email address in Paymentwall account.

Refer Invoice document to generate invoices via Paymentwall Merchant area.

Parameters
Parameter Description
invoice_number
required
string
Official Invoice number based on your paybook.
currency
required
string
Refer to currency codes
date
required
string
Invoice date in mm/dd/yyyy format
due_date
required
string
Invoice due date in mm/dd/yyyy format
contacts
required
array
Array of your client’s details. Please refer Contact parameters
items
required
array
Array of your item’s details. Please refer Items parameters
taxes
array
Array of your Invoice taxes. Please refer Taxes and Discount of Invoice parameters
discounts
array
Array of your Invoice discounts. Please refer Tax and Discount of Invoice parameters
key
required
string
Your project public key
sign
required
string
Your signature based on your invoice parameters. Please refer to Signature Calculation
sign_version
required
string
Version of signature

Endpoint

POST https://api.paymentwall.com/developers/invoice-api/invoice

Sample Request

<?php
$params = json_encode(array(
    'invoice_number'=>'INV-00123',
    'currency'=>'USD',
    'date'=>'07/07/2017',
    'due_date'=>'09/10/2019',
    'contacts'=> array(
        'company_name'=>'ABCD Industries',
        'salutation'=>'Mr.',
        'first_name'=>'John',
        'last_name'=>'Doe',
        'email'=>'john@doe.com',
        'title'=>'CEO',
        'country'=>'US',
        'city'=>'Palo Alto',
        'address'=>'326 Market Street',
        'zipcode'=>'94103',
        'phone_number'=>'(800)5551000',
        'note'=>'This will show on your Invoice'
    ),
    'items'=> array(
        array(
            'quantity'=>20,
            'title'=>'Red apple',
            'description'=>'Fresh apples',
            'unit_cost'=>2,
            'currency'=>'USD',
            'tax'=> array(
                'type'=>'percentage',
                'value'=>'10'
            ),
            'discount'=> array(
                'type'=>'percentage',
                'value'=>'17'
            )
        ),
        array(
            'quantity'=>10,
            'title'=>'Green apple',
            'description'=>'Fresh apples',
            'unit_cost'=>2,
            'currency'=>'USD',
            'tax'=> array(
                'type'=>'percentage',
                'value'=>'10'
            ),
            'discount'=> array(
                'type'=>'percentage',
                'value'=>'17'
            )
        )
    ),
    'taxes'=> array(
        array(
            'type'=>'percentage',
            'value'=>'20',
            'name'=>'VAT EU'
        ),
        array(
            'type'=>'percentage',
            'value'=>'10',
            'name'=>'USA NATIONAL TAX'
        )
    ),
    'discounts'=> array(
        'type'=>'percentage',
        'value'=>'50',
        'name'=>'1 000 000 user discount'
    ),
    'key'=>'YOUR_PROJECT_KEY'
));

$post = curl_init();
curl_setopt($post, CURLOPT_URL, 'https://api.paymentwall.com/developers/invoice-api/invoice');
curl_setopt($post, CURLOPT_HTTPHEADER, array(
    'X-ApiKey: YOUR_SECRET_KEY'
));
curl_setopt($post, CURLOPT_POST, 1);
curl_setopt($post, CURLOPT_POSTFIELDS, $params);
curl_exec($post);
?>

Endpoint

POST https://api.paymentwall.com/developers/invoice-api/invoice

Endpoint

POST https://api.paymentwall.com/developers/invoice-api/invoice

Endpoint

POST https://api.paymentwall.com/developers/invoice-api/invoice

Endpoint

POST https://api.paymentwall.com/developers/invoice-api/invoice

Endpoint

POST https://api.paymentwall.com/developers/invoice-api/invoice

Endpoint

POST https://api.paymentwall.com/developers/invoice-api/invoice

Sample Request

curl https://api.paymentwall.com/developers/invoice-api/invoice \
-H "X-ApiKey: [YOUR_SECRET_KEY]" \
-d "invoice_number":"INV-00355" \
-d "currency":"USD" \
-d "date":"05/05/2017" \
-d "due_date":"06/05/2017"\
-d "contacts":[{
        "company_name":"ABCD Industries",
        "salutation":"Mr.",
        "first_name":"John",
        "last_name":"Doe",
        "email":"liangnexcolor@gmail.com",
        "title":"CEO",
        "country":"US",
        "city":"Palo Alto",
        "address":"326 Market Street",
        "zipcode":"94103",
        "phone_number":"(800)5551000",
        "note":"This will show on your Invoice"
    }] \
-d "items":[{
        "quantity":5,
        "title":"Red apple",
        "description":"Fresh apples",
        "unit_cost":10,
        "currency":"USD",
        "tax":{
            "type":"percentage",
            "value":"1"
        },
        "discount":{
            "type":"percentage",
            "value":"1"}
      },{
        "quantity":10,
        "title":"Green apple",
        "description":"Fresh apples",
        "unit_cost":10,
        "currency":"USD",
        "tax":{
            "type":"percentage",
            "value":"1"
        },
        "discount":{
            "type":"percentage",
            "value":"2"}
    }] \
-d "taxes":[{
        "type":"percentage",
        "value":"THE-TAX-VALUE",
        "name":"USA NATIONAL TAX"
    }] \
-d "discounts":[{
        "type":"percentage",
        "value":"THE-PERCENTAGE-VALUE",
        "name":"Royalty User Discount"
    }] \
-d "key":"[YOUR_PROJECT_KEY]"

Contacts

Parameters
Parameter Description
company_name
string
Company name
salutation
string
Mr./Ms./Dr.
first_name
required
string
First name of your client
last_name
required
string
Last name of your client
email
required
string
Email address of your client
title
string
Position in company_name
country
string
Country of your client
city
string
City of your client
address
string
Address of your client
zipcode
string
Zip code of your client
phone_number
string
Phone number of your client
note
string
Internal information about this client

Items

Parameters
Parameter Description
quantity
required
int
Number of item which your client orders
unit_cost
required
float
Price point of item
currency
required
string
Currency code in ISO 4217
Currency of Invoice and Items must be same.
title
required
string
Name of Item
description
string
Item description
tax
array
Item tax. Please refer Taxes and Discount of Items parameters
discount
array
Item discount. Please refer Taxes and Discount of Items parameters

Invoice tax/discount

Parameters
Parameter Description
type
required
string
percentage
Type of tax / discount. Currently only percentage is available.
value
required
float
Value of tax / discount. Example: 10.00 for 10.00%
name
required
string
Name of tax / discount

Item tax/discount

Parameters
Parameter Description
type
required
string
percentage
Type of tax / discount of this item. Currently only percentage is available.
value
required
float
Value of tax / discount of this item. Example: 10.00 for 10.00%

Invoice response attributes

Invoice email will be sent automatically to the contacts[email] and you will get invoice overview in json format.Below are the attributes of response.

Attributes
Parameter Description
invoice_number Your invoice number passed in requests
application_id Your project id in Paymentwall
date Unix Timestamp value of the date you set for invoice
due_date Unix Timestamp value of the due date you set for invoice
currency Code of the currency you set for invoice in ISO 4217 format
status Status of Invoice. sent / paid / outstanding
email Client’s email. Invoice is sent to this email address
total_amount Total price of invoice after invoice tax / invoice discount is applied
sub_total_amount Total price of invoice products without invoice tax / invoice discount
invoice_id Internal invoice ID
public_id Public invoice ID sent to client
status_formatted Formatted version of Invoice status
due_date_formatted Formatted version of invoice due date
date_formatted Formatted version of invoice date
view_url URL to see the invoice
payment_url URL to make payment for the invoice
pdf_url URL to download PDF version of the invoice
owner Array of your company information. You can set the information at Invoice > Settings tab. Please refer Invoice for details

The other attributes are same with the parameters you sent over request to Invoice API.

Sample Response

[
    {
        "invoice_number": "INV-00355",
        "application_id": 166111,
        "date": 1493960400,
        "due_date": 1491368400,
        "currency": "USD",
        "status": "sent",
        "email": "liangnexcolor@gmail.com",
        "total_amount": "149.4800",
        "sub_total_amount": "149.4800",
        "invoice_id": 6893,
        "public_id": "95NMR5ODQUWM0YPJ2XQ5",
        "status_formatted": "Sent",
        "due_date_formatted": "04\/05\/2017",
        "date_formatted": "05\/05\/2017",
        "view_url": "https:\/\/api.paymentwall.com\/api\/invoice\/view?key=cd36b8635c7296dad972a239142c4b84&uid=liangnexcolor%40gmail.com&sign_version=2&id=95NMR5ODQUWM0YPJ2XQ5&sign=bd1fe15077982c3ecf609b3f75f86592",
        "payment_url": "https:\/\/api.paymentwall.com\/api\/invoice\/?key=cd36b8635c7296dad972a239142c4b84&uid=liangnexcolor%40gmail.com&sign_version=2&id=95NMR5ODQUWM0YPJ2XQ5&sign=bd1fe15077982c3ecf609b3f75f86592",
        "pdf_url": "https:\/\/api.paymentwall.com\/api\/invoice\/download-pdf?key=cd36b8635c7296dad972a239142c4b84&uid=liangnexcolor%40gmail.com&sign_version=2&id=95NMR5ODQUWM0YPJ2XQ5&sign=bd1fe15077982c3ecf609b3f75f86592",
        "owner": {
            "company_name": "Liang's company",
            "country_name": "China",
            "address": "4th middle road, North",
            "city": "BeiJing",
            "state": 699,
            "first_name": "",
            "last_name": "",
            "zipcode": "100085",
            "logo_url": "https:\/\/api.paymentwall.com\/\/images\/logo2.png"
        },
        "currency_code": "USD",
        "sub_total_amount_formatted": "149.48 USD",
        "total_amount_formatted": "149.48 USD",
        "items": [
            {
                "application_id": 166111,
                "title": "Red apple",
                "description": "Fresh apples",
                "unit_cost": "10.00",
                "currency": "USD",
                "tax": {
                    "type": "percentage",
                    "value": "1"
                },
                "discount": {
                    "type": "percentage",
                    "value": "1"
                },
                "item_id": 8347,
                "quantity": "10.00",
                "line_total": 99.99,
                "line_total_formatted": "99.99 USD",
                "unit_cost_formatted": "10.00 USD"
            },
            {
                "application_id": 166111,
                "title": "Green apple",
                "description": "Fresh apples",
                "unit_cost": "10.00",
                "currency": "USD",
                "tax": {
                    "type": "percentage",
                    "value": "1"
                },
                "discount": {
                    "type": "percentage",
                    "value": "2"
                },
                "item_id": 8348,
                "quantity": "5.00",
                "line_total": 49.49,
                "line_total_formatted": "49.49 USD",
                "unit_cost_formatted": "10.00 USD"
            }
        ],
        "contacts": [
            {
                "application_id": 166111,
                "first_name": "John",
                "last_name": "Doe",
                "salutation": "Mr.",
                "email": "liangnexcolor@gmail.com",
                "company_name": "ABCD Industries",
                "title": "CEO",
                "address": "326 Market Street",
                "country": "US",
                "country_formatted": "United States",
                "city": "Palo Alto",
                "zipcode": "94103",
                "phone_number": "(800)5551000",
                "note": "This will show on your Invoice",
                "contact_id": 7275
            }
        ],
        "taxes": [
            
        ],
        "discounts": [
            
        ],
        "bank_details": [
            
        ],
        "show_pay_button": true
    }
]

Sample Response

[
    {
        "invoice_number": "INV-00355",
        "application_id": 166111,
        "date": 1493960400,
        "due_date": 1491368400,
        "currency": "USD",
        "status": "sent",
        "email": "liangnexcolor@gmail.com",
        "total_amount": "149.4800",
        "sub_total_amount": "149.4800",
        "invoice_id": 6893,
        "public_id": "95NMR5ODQUWM0YPJ2XQ5",
        "status_formatted": "Sent",
        "due_date_formatted": "04\/05\/2017",
        "date_formatted": "05\/05\/2017",
        "view_url": "https:\/\/api.paymentwall.com\/api\/invoice\/view?key=cd36b8635c7296dad972a239142c4b84&uid=liangnexcolor%40gmail.com&sign_version=2&id=95NMR5ODQUWM0YPJ2XQ5&sign=bd1fe15077982c3ecf609b3f75f86592",
        "payment_url": "https:\/\/api.paymentwall.com\/api\/invoice\/?key=cd36b8635c7296dad972a239142c4b84&uid=liangnexcolor%40gmail.com&sign_version=2&id=95NMR5ODQUWM0YPJ2XQ5&sign=bd1fe15077982c3ecf609b3f75f86592",
        "pdf_url": "https:\/\/api.paymentwall.com\/api\/invoice\/download-pdf?key=cd36b8635c7296dad972a239142c4b84&uid=liangnexcolor%40gmail.com&sign_version=2&id=95NMR5ODQUWM0YPJ2XQ5&sign=bd1fe15077982c3ecf609b3f75f86592",
        "owner": {
            "company_name": "Liang's company",
            "country_name": "China",
            "address": "4th middle road, North",
            "city": "BeiJing",
            "state": 699,
            "first_name": "",
            "last_name": "",
            "zipcode": "100085",
            "logo_url": "https:\/\/api.paymentwall.com\/\/images\/logo2.png"
        },
        "currency_code": "USD",
        "sub_total_amount_formatted": "149.48 USD",
        "total_amount_formatted": "149.48 USD",
        "items": [
            {
                "application_id": 166111,
                "title": "Red apple",
                "description": "Fresh apples",
                "unit_cost": "10.00",
                "currency": "USD",
                "tax": {
                    "type": "percentage",
                    "value": "1"
                },
                "discount": {
                    "type": "percentage",
                    "value": "1"
                },
                "item_id": 8347,
                "quantity": "10.00",
                "line_total": 99.99,
                "line_total_formatted": "99.99 USD",
                "unit_cost_formatted": "10.00 USD"
            },
            {
                "application_id": 166111,
                "title": "Green apple",
                "description": "Fresh apples",
                "unit_cost": "10.00",
                "currency": "USD",
                "tax": {
                    "type": "percentage",
                    "value": "1"
                },
                "discount": {
                    "type": "percentage",
                    "value": "2"
                },
                "item_id": 8348,
                "quantity": "5.00",
                "line_total": 49.49,
                "line_total_formatted": "49.49 USD",
                "unit_cost_formatted": "10.00 USD"
            }
        ],
        "contacts": [
            {
                "application_id": 166111,
                "first_name": "John",
                "last_name": "Doe",
                "salutation": "Mr.",
                "email": "liangnexcolor@gmail.com",
                "company_name": "ABCD Industries",
                "title": "CEO",
                "address": "326 Market Street",
                "country": "US",
                "country_formatted": "United States",
                "city": "Palo Alto",
                "zipcode": "94103",
                "phone_number": "(800)5551000",
                "note": "This will show on your Invoice",
                "contact_id": 7275
            }
        ],
        "taxes": [
            
        ],
        "discounts": [
            
        ],
        "bank_details": [
            
        ],
        "show_pay_button": true
    }
]

Sample Response

[
    {
        "invoice_number": "INV-00355",
        "application_id": 166111,
        "date": 1493960400,
        "due_date": 1491368400,
        "currency": "USD",
        "status": "sent",
        "email": "liangnexcolor@gmail.com",
        "total_amount": "149.4800",
        "sub_total_amount": "149.4800",
        "invoice_id": 6893,
        "public_id": "95NMR5ODQUWM0YPJ2XQ5",
        "status_formatted": "Sent",
        "due_date_formatted": "04\/05\/2017",
        "date_formatted": "05\/05\/2017",
        "view_url": "https:\/\/api.paymentwall.com\/api\/invoice\/view?key=cd36b8635c7296dad972a239142c4b84&uid=liangnexcolor%40gmail.com&sign_version=2&id=95NMR5ODQUWM0YPJ2XQ5&sign=bd1fe15077982c3ecf609b3f75f86592",
        "payment_url": "https:\/\/api.paymentwall.com\/api\/invoice\/?key=cd36b8635c7296dad972a239142c4b84&uid=liangnexcolor%40gmail.com&sign_version=2&id=95NMR5ODQUWM0YPJ2XQ5&sign=bd1fe15077982c3ecf609b3f75f86592",
        "pdf_url": "https:\/\/api.paymentwall.com\/api\/invoice\/download-pdf?key=cd36b8635c7296dad972a239142c4b84&uid=liangnexcolor%40gmail.com&sign_version=2&id=95NMR5ODQUWM0YPJ2XQ5&sign=bd1fe15077982c3ecf609b3f75f86592",
        "owner": {
            "company_name": "Liang's company",
            "country_name": "China",
            "address": "4th middle road, North",
            "city": "BeiJing",
            "state": 699,
            "first_name": "",
            "last_name": "",
            "zipcode": "100085",
            "logo_url": "https:\/\/api.paymentwall.com\/\/images\/logo2.png"
        },
        "currency_code": "USD",
        "sub_total_amount_formatted": "149.48 USD",
        "total_amount_formatted": "149.48 USD",
        "items": [
            {
                "application_id": 166111,
                "title": "Red apple",
                "description": "Fresh apples",
                "unit_cost": "10.00",
                "currency": "USD",
                "tax": {
                    "type": "percentage",
                    "value": "1"
                },
                "discount": {
                    "type": "percentage",
                    "value": "1"
                },
                "item_id": 8347,
                "quantity": "10.00",
                "line_total": 99.99,
                "line_total_formatted": "99.99 USD",
                "unit_cost_formatted": "10.00 USD"
            },
            {
                "application_id": 166111,
                "title": "Green apple",
                "description": "Fresh apples",
                "unit_cost": "10.00",
                "currency": "USD",
                "tax": {
                    "type": "percentage",
                    "value": "1"
                },
                "discount": {
                    "type": "percentage",
                    "value": "2"
                },
                "item_id": 8348,
                "quantity": "5.00",
                "line_total": 49.49,
                "line_total_formatted": "49.49 USD",
                "unit_cost_formatted": "10.00 USD"
            }
        ],
        "contacts": [
            {
                "application_id": 166111,
                "first_name": "John",
                "last_name": "Doe",
                "salutation": "Mr.",
                "email": "liangnexcolor@gmail.com",
                "company_name": "ABCD Industries",
                "title": "CEO",
                "address": "326 Market Street",
                "country": "US",
                "country_formatted": "United States",
                "city": "Palo Alto",
                "zipcode": "94103",
                "phone_number": "(800)5551000",
                "note": "This will show on your Invoice",
                "contact_id": 7275
            }
        ],
        "taxes": [
            
        ],
        "discounts": [
            
        ],
        "bank_details": [
            
        ],
        "show_pay_button": true
    }
]

Sample Response

[
    {
        "invoice_number": "INV-00355",
        "application_id": 166111,
        "date": 1493960400,
        "due_date": 1491368400,
        "currency": "USD",
        "status": "sent",
        "email": "liangnexcolor@gmail.com",
        "total_amount": "149.4800",
        "sub_total_amount": "149.4800",
        "invoice_id": 6893,
        "public_id": "95NMR5ODQUWM0YPJ2XQ5",
        "status_formatted": "Sent",
        "due_date_formatted": "04\/05\/2017",
        "date_formatted": "05\/05\/2017",
        "view_url": "https:\/\/api.paymentwall.com\/api\/invoice\/view?key=cd36b8635c7296dad972a239142c4b84&uid=liangnexcolor%40gmail.com&sign_version=2&id=95NMR5ODQUWM0YPJ2XQ5&sign=bd1fe15077982c3ecf609b3f75f86592",
        "payment_url": "https:\/\/api.paymentwall.com\/api\/invoice\/?key=cd36b8635c7296dad972a239142c4b84&uid=liangnexcolor%40gmail.com&sign_version=2&id=95NMR5ODQUWM0YPJ2XQ5&sign=bd1fe15077982c3ecf609b3f75f86592",
        "pdf_url": "https:\/\/api.paymentwall.com\/api\/invoice\/download-pdf?key=cd36b8635c7296dad972a239142c4b84&uid=liangnexcolor%40gmail.com&sign_version=2&id=95NMR5ODQUWM0YPJ2XQ5&sign=bd1fe15077982c3ecf609b3f75f86592",
        "owner": {
            "company_name": "Liang's company",
            "country_name": "China",
            "address": "4th middle road, North",
            "city": "BeiJing",
            "state": 699,
            "first_name": "",
            "last_name": "",
            "zipcode": "100085",
            "logo_url": "https:\/\/api.paymentwall.com\/\/images\/logo2.png"
        },
        "currency_code": "USD",
        "sub_total_amount_formatted": "149.48 USD",
        "total_amount_formatted": "149.48 USD",
        "items": [
            {
                "application_id": 166111,
                "title": "Red apple",
                "description": "Fresh apples",
                "unit_cost": "10.00",
                "currency": "USD",
                "tax": {
                    "type": "percentage",
                    "value": "1"
                },
                "discount": {
                    "type": "percentage",
                    "value": "1"
                },
                "item_id": 8347,
                "quantity": "10.00",
                "line_total": 99.99,
                "line_total_formatted": "99.99 USD",
                "unit_cost_formatted": "10.00 USD"
            },
            {
                "application_id": 166111,
                "title": "Green apple",
                "description": "Fresh apples",
                "unit_cost": "10.00",
                "currency": "USD",
                "tax": {
                    "type": "percentage",
                    "value": "1"
                },
                "discount": {
                    "type": "percentage",
                    "value": "2"
                },
                "item_id": 8348,
                "quantity": "5.00",
                "line_total": 49.49,
                "line_total_formatted": "49.49 USD",
                "unit_cost_formatted": "10.00 USD"
            }
        ],
        "contacts": [
            {
                "application_id": 166111,
                "first_name": "John",
                "last_name": "Doe",
                "salutation": "Mr.",
                "email": "liangnexcolor@gmail.com",
                "company_name": "ABCD Industries",
                "title": "CEO",
                "address": "326 Market Street",
                "country": "US",
                "country_formatted": "United States",
                "city": "Palo Alto",
                "zipcode": "94103",
                "phone_number": "(800)5551000",
                "note": "This will show on your Invoice",
                "contact_id": 7275
            }
        ],
        "taxes": [
            
        ],
        "discounts": [
            
        ],
        "bank_details": [
            
        ],
        "show_pay_button": true
    }
]

Sample Response

[
    {
        "invoice_number": "INV-00355",
        "application_id": 166111,
        "date": 1493960400,
        "due_date": 1491368400,
        "currency": "USD",
        "status": "sent",
        "email": "liangnexcolor@gmail.com",
        "total_amount": "149.4800",
        "sub_total_amount": "149.4800",
        "invoice_id": 6893,
        "public_id": "95NMR5ODQUWM0YPJ2XQ5",
        "status_formatted": "Sent",
        "due_date_formatted": "04\/05\/2017",
        "date_formatted": "05\/05\/2017",
        "view_url": "https:\/\/api.paymentwall.com\/api\/invoice\/view?key=cd36b8635c7296dad972a239142c4b84&uid=liangnexcolor%40gmail.com&sign_version=2&id=95NMR5ODQUWM0YPJ2XQ5&sign=bd1fe15077982c3ecf609b3f75f86592",
        "payment_url": "https:\/\/api.paymentwall.com\/api\/invoice\/?key=cd36b8635c7296dad972a239142c4b84&uid=liangnexcolor%40gmail.com&sign_version=2&id=95NMR5ODQUWM0YPJ2XQ5&sign=bd1fe15077982c3ecf609b3f75f86592",
        "pdf_url": "https:\/\/api.paymentwall.com\/api\/invoice\/download-pdf?key=cd36b8635c7296dad972a239142c4b84&uid=liangnexcolor%40gmail.com&sign_version=2&id=95NMR5ODQUWM0YPJ2XQ5&sign=bd1fe15077982c3ecf609b3f75f86592",
        "owner": {
            "company_name": "Liang's company",
            "country_name": "China",
            "address": "4th middle road, North",
            "city": "BeiJing",
            "state": 699,
            "first_name": "",
            "last_name": "",
            "zipcode": "100085",
            "logo_url": "https:\/\/api.paymentwall.com\/\/images\/logo2.png"
        },
        "currency_code": "USD",
        "sub_total_amount_formatted": "149.48 USD",
        "total_amount_formatted": "149.48 USD",
        "items": [
            {
                "application_id": 166111,
                "title": "Red apple",
                "description": "Fresh apples",
                "unit_cost": "10.00",
                "currency": "USD",
                "tax": {
                    "type": "percentage",
                    "value": "1"
                },
                "discount": {
                    "type": "percentage",
                    "value": "1"
                },
                "item_id": 8347,
                "quantity": "10.00",
                "line_total": 99.99,
                "line_total_formatted": "99.99 USD",
                "unit_cost_formatted": "10.00 USD"
            },
            {
                "application_id": 166111,
                "title": "Green apple",
                "description": "Fresh apples",
                "unit_cost": "10.00",
                "currency": "USD",
                "tax": {
                    "type": "percentage",
                    "value": "1"
                },
                "discount": {
                    "type": "percentage",
                    "value": "2"
                },
                "item_id": 8348,
                "quantity": "5.00",
                "line_total": 49.49,
                "line_total_formatted": "49.49 USD",
                "unit_cost_formatted": "10.00 USD"
            }
        ],
        "contacts": [
            {
                "application_id": 166111,
                "first_name": "John",
                "last_name": "Doe",
                "salutation": "Mr.",
                "email": "liangnexcolor@gmail.com",
                "company_name": "ABCD Industries",
                "title": "CEO",
                "address": "326 Market Street",
                "country": "US",
                "country_formatted": "United States",
                "city": "Palo Alto",
                "zipcode": "94103",
                "phone_number": "(800)5551000",
                "note": "This will show on your Invoice",
                "contact_id": 7275
            }
        ],
        "taxes": [
            
        ],
        "discounts": [
            
        ],
        "bank_details": [
            
        ],
        "show_pay_button": true
    }
]

Sample Response

[
    {
        "invoice_number": "INV-00355",
        "application_id": 166111,
        "date": 1493960400,
        "due_date": 1491368400,
        "currency": "USD",
        "status": "sent",
        "email": "liangnexcolor@gmail.com",
        "total_amount": "149.4800",
        "sub_total_amount": "149.4800",
        "invoice_id": 6893,
        "public_id": "95NMR5ODQUWM0YPJ2XQ5",
        "status_formatted": "Sent",
        "due_date_formatted": "04\/05\/2017",
        "date_formatted": "05\/05\/2017",
        "view_url": "https:\/\/api.paymentwall.com\/api\/invoice\/view?key=cd36b8635c7296dad972a239142c4b84&uid=liangnexcolor%40gmail.com&sign_version=2&id=95NMR5ODQUWM0YPJ2XQ5&sign=bd1fe15077982c3ecf609b3f75f86592",
        "payment_url": "https:\/\/api.paymentwall.com\/api\/invoice\/?key=cd36b8635c7296dad972a239142c4b84&uid=liangnexcolor%40gmail.com&sign_version=2&id=95NMR5ODQUWM0YPJ2XQ5&sign=bd1fe15077982c3ecf609b3f75f86592",
        "pdf_url": "https:\/\/api.paymentwall.com\/api\/invoice\/download-pdf?key=cd36b8635c7296dad972a239142c4b84&uid=liangnexcolor%40gmail.com&sign_version=2&id=95NMR5ODQUWM0YPJ2XQ5&sign=bd1fe15077982c3ecf609b3f75f86592",
        "owner": {
            "company_name": "Liang's company",
            "country_name": "China",
            "address": "4th middle road, North",
            "city": "BeiJing",
            "state": 699,
            "first_name": "",
            "last_name": "",
            "zipcode": "100085",
            "logo_url": "https:\/\/api.paymentwall.com\/\/images\/logo2.png"
        },
        "currency_code": "USD",
        "sub_total_amount_formatted": "149.48 USD",
        "total_amount_formatted": "149.48 USD",
        "items": [
            {
                "application_id": 166111,
                "title": "Red apple",
                "description": "Fresh apples",
                "unit_cost": "10.00",
                "currency": "USD",
                "tax": {
                    "type": "percentage",
                    "value": "1"
                },
                "discount": {
                    "type": "percentage",
                    "value": "1"
                },
                "item_id": 8347,
                "quantity": "10.00",
                "line_total": 99.99,
                "line_total_formatted": "99.99 USD",
                "unit_cost_formatted": "10.00 USD"
            },
            {
                "application_id": 166111,
                "title": "Green apple",
                "description": "Fresh apples",
                "unit_cost": "10.00",
                "currency": "USD",
                "tax": {
                    "type": "percentage",
                    "value": "1"
                },
                "discount": {
                    "type": "percentage",
                    "value": "2"
                },
                "item_id": 8348,
                "quantity": "5.00",
                "line_total": 49.49,
                "line_total_formatted": "49.49 USD",
                "unit_cost_formatted": "10.00 USD"
            }
        ],
        "contacts": [
            {
                "application_id": 166111,
                "first_name": "John",
                "last_name": "Doe",
                "salutation": "Mr.",
                "email": "liangnexcolor@gmail.com",
                "company_name": "ABCD Industries",
                "title": "CEO",
                "address": "326 Market Street",
                "country": "US",
                "country_formatted": "United States",
                "city": "Palo Alto",
                "zipcode": "94103",
                "phone_number": "(800)5551000",
                "note": "This will show on your Invoice",
                "contact_id": 7275
            }
        ],
        "taxes": [
            
        ],
        "discounts": [
            
        ],
        "bank_details": [
            
        ],
        "show_pay_button": true
    }
]

Sample Response

[
    {
        "invoice_number": "INV-00355",
        "application_id": 166111,
        "date": 1493960400,
        "due_date": 1491368400,
        "currency": "USD",
        "status": "sent",
        "email": "liangnexcolor@gmail.com",
        "total_amount": "149.4800",
        "sub_total_amount": "149.4800",
        "invoice_id": 6893,
        "public_id": "95NMR5ODQUWM0YPJ2XQ5",
        "status_formatted": "Sent",
        "due_date_formatted": "06\/05\/2017",
        "date_formatted": "05\/05\/2017",
        "view_url": "https:\/\/api.paymentwall.com\/api\/invoice\/view?key=cd36b8635c7296dad972a239142c4b84&uid=liangnexcolor%40gmail.com&sign_version=2&id=95NMR5ODQUWM0YPJ2XQ5&sign=bd1fe15077982c3ecf609b3f75f86592",
        "payment_url": "https:\/\/api.paymentwall.com\/api\/invoice\/?key=cd36b8635c7296dad972a239142c4b84&uid=liangnexcolor%40gmail.com&sign_version=2&id=95NMR5ODQUWM0YPJ2XQ5&sign=bd1fe15077982c3ecf609b3f75f86592",
        "pdf_url": "https:\/\/api.paymentwall.com\/api\/invoice\/download-pdf?key=cd36b8635c7296dad972a239142c4b84&uid=liangnexcolor%40gmail.com&sign_version=2&id=95NMR5ODQUWM0YPJ2XQ5&sign=bd1fe15077982c3ecf609b3f75f86592",
        "owner": {
            "company_name": "Liang's company",
            "country_name": "China",
            "address": "4th middle road, North",
            "city": "BeiJing",
            "state": 699,
            "first_name": "",
            "last_name": "",
            "zipcode": "100085",
            "logo_url": "https:\/\/api.paymentwall.com\/\/images\/logo2.png"
        },
        "currency_code": "USD",
        "sub_total_amount_formatted": "149.48 USD",
        "total_amount_formatted": "149.48 USD",
        "items": [
            {
                "application_id": 166111,
                "title": "Red apple",
                "description": "Fresh apples",
                "unit_cost": "10.00",
                "currency": "USD",
                "tax": {
                    "type": "percentage",
                    "value": "1"
                },
                "discount": {
                    "type": "percentage",
                    "value": "1"
                },
                "item_id": 8347,
                "quantity": "10.00",
                "line_total": 99.99,
                "line_total_formatted": "99.99 USD",
                "unit_cost_formatted": "10.00 USD"
            },
            {
                "application_id": 166111,
                "title": "Green apple",
                "description": "Fresh apples",
                "unit_cost": "10.00",
                "currency": "USD",
                "tax": {
                    "type": "percentage",
                    "value": "1"
                },
                "discount": {
                    "type": "percentage",
                    "value": "2"
                },
                "item_id": 8348,
                "quantity": "5.00",
                "line_total": 49.49,
                "line_total_formatted": "49.49 USD",
                "unit_cost_formatted": "10.00 USD"
            }
        ],
        "contacts": [
            {
                "application_id": 166111,
                "first_name": "John",
                "last_name": "Doe",
                "salutation": "Mr.",
                "email": "liangnexcolor@gmail.com",
                "company_name": "ABCD Industries",
                "title": "CEO",
                "address": "326 Market Street",
                "country": "US",
                "country_formatted": "United States",
                "city": "Palo Alto",
                "zipcode": "94103",
                "phone_number": "(800)5551000",
                "note": "This will show on your Invoice",
                "contact_id": 7275
            }
        ],
        "taxes": [
            
        ],
        "discounts": [
            
        ],
        "bank_details": [
            
        ],
        "show_pay_button": true
    }
]

Onetime token

Only PCI DSS certified merchants can use this API, which can help you to obtain one-time token without using Brick.js, but it will NOT return fingerprint.

browser_ip and browser_domain are required to replace fingerprint in this case.

Parameters
name description
public_key
required
string
The project key which can be found in Merchant Area→ My Projects.
card[number]
required
number
User’s Card number, the max length should be 16 digits.
card[exp_month]
required
number
Expiration month, 2 digits from 01 to 12.
card[exp_year]
required
number
Expiration year, 4 digits.
card[cvv]
required
number
CVC/CVV, 3-4 digits depends on the type of credit cards.

An error object will be returned if there is any mistakes in your request, refer to error codes and find solutions accordingly.

Endpoint

 POST https://pwgateway.com/api/token (Live environment)
 
 POST https://api.paymentwall.com/api/brick/token (Sandbox environment)

Sample Request

<?php
$tokenModel = new Paymentwall_OneTimeToken();
$token =  $tokenModel->create(array(
    'public_key' => 'YOUR_PUBLIC_KEY',
    'card[number]' => '4242424242424242',
    'card[exp_month]' => '11',
    'card[exp_year]' => '19',
    'card[cvv]' => '123'
));
// send token to charge via $token->getToken();
?>

Endpoint

 POST https://pwgateway.com/api/token (Live environment)
 
 POST https://api.paymentwall.com/api/brick/token (Sandbox environment)

Sample Request

var onetimetoken = new Paymentwall.Onetimetoken(
    4000000000000002, // Card number
    01,               // Expiration month
    2020,             // Expiration year
    123               // CVC/CVV
);

onetimetoken.createOnetimetoken(function(response){
    if(response.isSuccessful()){
        if(response.isActivated()){
            token = response.getOnetimeToken();
            card = response.getCardInfo();
        }
    } else{
        error_code = response.getErrorCode();
        error_details = response.getErrorDetails();
    };
});

Endpoint

 POST https://pwgateway.com/api/token (Live environment)
 
 POST https://api.paymentwall.com/api/brick/token (Sandbox environment)

Sample Request

OneTimeToken token = new OneTimeToken();
token = (OneTimeToken) token.create(new LinkedHashMap<String, String>(){{
    put("public_key", Config.getInstance().getPublicKey());
    put("card[number]", "4000000000000002");
    put("card[exp_month]", "01");
    put("card[exp_year]", "2020");
    put("card[cvv]", "123");
}});
return token.getToken();

Endpoint

POST https://pwgateway.com/api/token (Live environment)
 
POST https://api.paymentwall.com/api/brick/token (Sandbox environment)

Endpoint

POST https://pwgateway.com/api/token (Live environment)
 
POST https://api.paymentwall.com/api/brick/token (Sandbox environment)

Endpoint

POST https://pwgateway.com/api/token (Live environment)
 
POST https://api.paymentwall.com/api/brick/token (Sandbox environment)

Endpoint

 POST https://pwgateway.com/api/token (Live environment)
 
 POST https://api.paymentwall.com/api/brick/token (Sandbox environment)

Sample Request

curl https://pwgateway.com/api/token \
-d "public_key=YOUR_PUBLIC_KEY" \
-d "card[number]=4000000000000002" \
-d "card[exp_month]=01" \
-d "card[exp_year]=2021" \
-d "card[cvv]=123"

The onetime token object

Attributes
name description
type Object type.
token Value of one time token.
expires_in The remaining time before onetime token expiration, in seconds.
active Whether this token is activated.
card[type] The type of credit cards, could be Visa, Mastercard, Amex, etc.
card[last4] The last 4 digits of credit cards.
card[bin] First 6 digits of credit cards.
card[exp_month] The expire month of user’s credit card.
card[exp_year] The expire year of user’s credit card.

Sample onetime token

{  
    "type":"token",
    "token":"ot_f1e69de76a2eeeefa7532d4301609497",
    "expires_in":290,
    "active":1,
    "card":{  
        "type":"Visa",
        "last4":"0002",
        "bin":"400000",
        "exp_month":"01",
        "exp_year":"2020"
    }
}

Sample onetime token

{    
    "type":"token",
    "token":"ot_f1e69de76a2eeeefa7532d4301609497",
    "expires_in":290,
    "active":1,
    "card":{    
        "type":"Visa",
        "last4":"0002",
        "bin":"400000",
        "exp_month":"01",
        "exp_year":"2020"
    }
}

Sample onetime token

{    
    "type":"token",
    "token":"ot_f1e69de76a2eeeefa7532d4301609497",
    "expires_in":290,
    "active":1,
    "card":{    
        "type":"Visa",
        "last4":"0002",
        "bin":"400000",
        "exp_month":"01",
        "exp_year":"2020"
    }
}

Sample onetime token

{    
    "type":"token",
    "token":"ot_f1e69de76a2eeeefa7532d4301609497",
    "expires_in":290,
    "active":1,
    "card":{    
        "type":"Visa",
        "last4":"0002",
        "bin":"400000",
        "exp_month":"01",
        "exp_year":"2020"
    }
}

Sample onetime token

{    
    "type":"token",
    "token":"ot_f1e69de76a2eeeefa7532d4301609497",
    "expires_in":290,
    "active":1,
    "card":{    
        "type":"Visa",
        "last4":"0002",
        "bin":"400000",
        "exp_month":"01",
        "exp_year":"2020"
    }
}

Sample onetime token

{    
    "type":"token",
    "token":"ot_f1e69de76a2eeeefa7532d4301609497",
    "expires_in":290,
    "active":1,
    "card":{    
        "type":"Visa",
        "last4":"0002",
        "bin":"400000",
        "exp_month":"01",
        "exp_year":"2020"
    }
}

Sample onetime token

{    
    "type":"token",
    "token":"ot_f1e69de76a2eeeefa7532d4301609497",
    "expires_in":290,
    "active":1,
    "card":{    
        "type":"Visa",
        "last4":"0002",
        "bin":"400000",
        "exp_month":"01",
        "exp_year":"2020"
    }
}

Charge

The Private API key is expected to be sent as the value of custom HTTPS header X-ApiKey by using this API. It can only be used for server-to-server calls and should never be exposed to end-users.

Parameters
Name Description
amount
required
number
Amount to be charged. The minimum transaction limit is USD 0.3 or equivalent in other currencies.. 2 decimal places is expected.
currency
required
string
Code of the currency, Refer to currency codes.
browser_ip
string
IP address of End-user.
browser_domain
string
Domain of the website where the payment is originating.
description
required
string
Description for the payment.
email
required
string
Email of end-users.
history[registration_date]
required
history[registration_date]
Unix timestamp of the transaction date. Length limitation is 10.
fingerprint
required
string
Unique fingerprint generated by Paymentwall for each transaction. If Brick.js is used, parameter brick_fingerprint will be sent to your backend directly.
You can not obtain brick_fingerprint if Brick.js is not used. In this case, fingerprint is no longer required, you need to use browser_ip and browser_domain instead. E.g. Mobile SDK, onetime token API
token
required
string
The value of One-time token or permanent token.
Charge with a permanent token will work only with same uid.
customer[firstname]
required
string
The first name of card holder.
customer[lastname]
required
string
The last name of card holder.
lang
string
Language code for email receipt localization, format ISO alpha-2, supported languages.
options[capture]
boolean
Whether or not to immediately capture the charge. Default is true. If you don’t want to capture it at once, you can pass options[capture]=0.
plan
required
string
Identifies the product ID, send back as goodsid parameter in pingbacks.
store_card
boolean
Whether to tokenize credit card details for subsequent purchases and return Permanent Token parameter in charge object. Default value is 1.
uid
string
End user id in merchant system. If you pass it to us, we will send it back as uid parameter in pingbacks. If omitted, email will be the value of uid parameter in pingbacks.
custom
array
Parameters defined by merchant in request. To receive these values via pingbacks, please add custom pingback parameter with name=custom and value=OWN.
secure_redirect_url
string
For 3D Secure payments: URL of the billing page where brick_secure_token and brick_charge_id should be sent via POST after the user completes 3D Secure step. It is recommended to embed brick_fingerprint and brick_token into this URL along with the order ID to subsequently pass them into the Charge.
secure_token
string
3D Secure token returned to the website after the user completing the 3D Secure step. Required for submitting additional information after 3D Secure step.
charge_id
string
ID of the transaction which is generated by 3D secure step.
secure
boolean
3D Secure flow is enforced if secure=1 is passed.
recurring
boolean
Required when building your own recurring billing system, please contact integration@paymentwall.com to activate related settings
Value: recurring=1
recurring_id
string
Required when building your own recurring billing system, please contact integration@paymentwall.com to activate related settings
Value: ref id of initial charge request.
Please pass the parameter for every recurring charge request (initial charge request is excluded).
reference_id
string
Required for EMV 3DS (3DS 2.0). The session reference ID of 3DS transaction.

3DS 2.0 only supports from Brick.js version 1.6.0

An error object will be returned if there is any mistakes in your request, refer to error codes and find solutions accordingly.

Endpoint

POST https://api.paymentwall.com/api/brick/charge

Sample Request

<?php
Paymentwall_Config::getInstance()->set(array(
    'private_key' => 'YOUR_PRIVATE_KEY'
));

$parameters = $_POST;
$chargeInfo = array(
    'email' => $parameters['email'],
    'history[registration_date]' => '1489655092',
    'amount' => 9.99,
    'currency' => 'USD',
    'token' => $parameters['brick_token'],
    'fingerprint' => $parameters['brick_fingerprint'],
    'description' => 'Order #123'
);

$charge = new Paymentwall_Charge();
$charge->create($chargeInfo);
?>

Endpoint

POST https://api.paymentwall.com/api/brick/charge

Sample Request

// We are using Express framework in this sample

var Paymentwall = require('paymentwall');
Paymentwall.Configure(                                                        
    Paymentwall.Base.API_GOODS,
    'YOUR_PUBLIC_KEY',
    'YOUR_PRIVATE_KEY'
);

//custom parameters
var custom = {
    'YOUR_CUSTOM_PARAMETER_NAME': 'YOUR_CUSTOM_PARAMETER_VALUE'
};

var parameters = req.body;
var charge = new Paymentwall.Charge(
    0.5, //price
    'USD', //currency code
    'description', //description of the product
    req.body.email, // user's email
    req.body.brick_fingerprint, // fingerprint generated by Brick.js
    req.body.brick_token, //one-time token
    custom 
);

charge.createCharge(function(brick_response){ }

Endpoint

POST https://api.paymentwall.com/api/brick/charge

Sample Request

Config.getInstance().setPublicKey("YOUR_APPLICATION_KEY");
Config.getInstance().setPrivateKey("YOUR_SECRET_KEY");

LinkedHashMap<String,String> chargemap = new LinkedHashMap<String, String>();
chargemap.put("token", request.getParameter("brick_token"); 
chargemap.put("email", "test@paymentwall.com");
chargemap.put("currency", "USD");
chargemap.put("amount", "9.99");
chargemap.put("fingerprint", request.getParameter("brick_fingerprint"));
chargemap.put("description", "description");
chargemap.put("additional_parameter_name", "additonal_parameter_value");
Charge charge = new Charge();
charge = (Charge)charge.create(chargemap);

Endpoint

POST https://api.paymentwall.com/api/brick/charge

Endpoint

POST https://api.paymentwall.com/api/brick/charge


Void a charge

Endpoint

POST https://api.paymentwall.com/api/brick/charge/$chargeid/void

Endpoint

POST https://api.paymentwall.com/api/brick/charge


Void a charge

Endpoint

POST https://api.paymentwall.com/api/brick/charge/$chargeid/void

Endpoint

POST https://api.paymentwall.com/api/brick/charge

Sample Request

curl https://api.paymentwall.com/api/brick/charge \
-H "X-ApiKey: [YOUR_PRIVATE_KEY]" \
-d "token=[TOKEN]" \
-d "amount=9.99" \
-d "currency=USD" \
-d "email=user@host.com" \
-d "fingerprint=[FINGERPRINT_BY_BRICK.JS]" \
-d "description=TestItem"


Void a Charge

Endpoint

POST https://api.paymentwall.com/api/brick/charge/$chargeid/void

Sample Request

curl https://api.paymentwall.com/api/brick/charge/t123456/void \
-H "X-ApiKey: [YOUR_PRIVATE_KEY]" \

The charge object

Attributes
Name Description
amount Price of product.
amount_paid Payment amount. It Depends on what currency enduser is billed.
captured Whether the payment is captured.
card[country] Country of where user’s credit card is issued.
card[exp_month] Expiration month of user’s credit card.
card[exp_year] Expiration year of user’s credit card.
card[name] Credit card holder name.
card[token] Permanent token. Refer to guide of permanent token.
card[type] Credit card type.
created Time when charge object is created, in unix timestamp.
currency Currency of product.
currency_paid Currency of end-user payment.
id ID of charge object.
refunded Whether the payment is refunded.
risk Whether the payment is approved by Paymentwall risk system.
secure Whether 3D Secure is applied.
support_link The link to get help for payment.

Sample charge object

{
    "amount": "9.99",
    "amount_paid": "8.96",
    "captured": false,
    "card": {
        "country": "US",
        "exp_month": "12",
        "exp_year": "2019",
        "last4": "9999",
        "name": "John Doe",
        "token": "2857a8cefec761ef7cdb3f97abf4c7b1",
        "type": "Visa"
    },
    "created": 1482314785,
    "currency": "USD",
    "currency_paid": "EUR",
    "id": "104872652",
    "object": "charge",
    "refunded": false,
    "risk": "approved",
    "secure": false,
    "support_link": "https://api.paymentwall.com/api/account/email-viewer?..."
}

Sample charge object

{
    "amount": "9.99",
    "amount_paid": "8.96",
    "captured": false,
    "card": {
        "country": "US",
        "exp_month": "12",
        "exp_year": "2019",
        "last4": "9999",
        "name": "John Doe",
        "token": "2857a8cefec761ef7cdb3f97abf4c7b1",
        "type": "Visa"
    },
    "created": 1482314785,
    "currency": "USD",
    "currency_paid": "EUR",
    "id": "104872652",
    "object": "charge",
    "refunded": false,
    "risk": "approved",
    "secure": false,
    "support_link": "https://api.paymentwall.com/api/account/email-viewer?..."
}

Sample charge object

{
    "amount": "9.99",
    "amount_paid": "8.96",
    "captured": false,
    "card": {
        "country": "US",
        "exp_month": "12",
        "exp_year": "2019",
        "last4": "9999",
        "name": "John Doe",
        "token": "2857a8cefec761ef7cdb3f97abf4c7b1",
        "type": "Visa"
    },
    "created": 1482314785,
    "currency": "USD",
    "currency_paid": "EUR",
    "id": "104872652",
    "object": "charge",
    "refunded": false,
    "risk": "approved",
    "secure": false,
    "support_link": "https://api.paymentwall.com/api/account/email-viewer?..."
}

Sample charge object

{
    "amount": "9.99",
    "amount_paid": "8.96",
    "captured": false,
    "card": {
        "country": "US",
        "exp_month": "12",
        "exp_year": "2019",
        "last4": "9999",
        "name": "John Doe",
        "token": "2857a8cefec761ef7cdb3f97abf4c7b1",
        "type": "Visa"
    },
    "created": 1482314785,
    "currency": "USD",
    "currency_paid": "EUR",
    "id": "104872652",
    "object": "charge",
    "refunded": false,
    "risk": "approved",
    "secure": false,
    "support_link": "https://api.paymentwall.com/api/account/email-viewer?..."
}

Sample charge object

{
    "amount": "9.99",
    "amount_paid": "8.96",
    "captured": false,
    "card": {
        "country": "US",
        "exp_month": "12",
        "exp_year": "2019",
        "last4": "9999",
        "name": "John Doe",
        "token": "2857a8cefec761ef7cdb3f97abf4c7b1",
        "type": "Visa"
    },
    "created": 1482314785,
    "currency": "USD",
    "currency_paid": "EUR",
    "id": "104872652",
    "object": "charge",
    "refunded": false,
    "risk": "approved",
    "secure": false,
    "support_link": "https://api.paymentwall.com/api/account/email-viewer?..."
}

Sample charge object

{
    "amount": "9.99",
    "amount_paid": "8.96",
    "captured": false,
    "card": {
        "country": "US",
        "exp_month": "12",
        "exp_year": "2019",
        "last4": "9999",
        "name": "John Doe",
        "token": "2857a8cefec761ef7cdb3f97abf4c7b1",
        "type": "Visa"
    },
    "created": 1482314785,
    "currency": "USD",
    "currency_paid": "EUR",
    "id": "104872652",
    "object": "charge",
    "refunded": false,
    "risk": "approved",
    "secure": false,
    "support_link": "https://api.paymentwall.com/api/account/email-viewer?..."
}

Sample charge object

{
    "amount": "9.99",
    "amount_paid": "8.96",
    "captured": false,
    "card": {
        "country": "US",
        "exp_month": "12",
        "exp_year": "2019",
        "last4": "9999",
        "name": "John Doe",
        "token": "2857a8cefec761ef7cdb3f97abf4c7b1",
        "type": "Visa"
    },
    "created": 1482314785,
    "currency": "USD",
    "currency_paid": "EUR",
    "id": "104872652",
    "object": "charge",
    "refunded": false,
    "risk": "approved",
    "secure": false,
    "support_link": "https://api.paymentwall.com/api/account/email-viewer?..."
}

Obtain charge details

Obtain a created charge details by using chargeid.

The Private API key is expected to be sent as the value of custom HTTPS header X-ApiKey by using this API. It can only be used for server-to-server calls and should never be exposed to end-users. You will have it been accomplished automatically if you are using our API libraries.

Parameters
Name Description
chargeid
required
string
The id of created charge object.

Endpoint

GET https://api.paymentwall.com/api/brick/charge/$chargeid

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');
Paymentwall_Config::getInstance()->set(array(
    'private_key' => 'YOUR_PRIVATE_KEY'
));
$charge = new Paymentwall_Charge($chargeid);
$charge->get();
$response=$charge->getRawResponseData();
echo $response;
?>

Endpoint

GET https://api.paymentwall.com/api/brick/charge/$chargeid

Sample Request

var charge = new Paymentwall.Charge();
charge.otherOperation(chargeid,'detail',function(brick_response){
    brick_response.getFullResponse('JSON');
});

Endpoint

GET https://api.paymentwall.com/api/brick/charge/$chargeid

Endpoint

GET https://api.paymentwall.com/api/brick/charge/$chargeid

Endpoint

GET https://api.paymentwall.com/api/brick/charge/$chargeid

Endpoint

GET https://api.paymentwall.com/api/brick/charge/$chargeid

Endpoint

GET https://api.paymentwall.com/api/brick/charge/$chargeid

Sample Request

curl https://api.paymentwall.com/api/brick/charge/[chargeId] \
-H "X-ApiKey: [YOUR_PRIVATE_KEY]" \

Refund a charge

Refund a charge by using its chargeid.

The Private API key is expected to be sent as the value of custom HTTPS header X-ApiKey by using this API. It can only be used for server-to-server calls and should never be exposed to end-users. You will have it been accomplished automatically if you are using our API libraries.

Parameters
Name Description
chargeid
required
string
The id of created charge object.

Endpoint

POST https://api.paymentwall.com/api/brick/charge/$chargeid/refund

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');
Paymentwall_Config::getInstance()->set(array(
    'private_key' => 'YOUR_PRIVATE_KEY'
));
$charge = new Paymentwall_Charge($chargeid);
$charge->refund();
$response=$charge->getPublicData();
echo $response;
?>

Endpoint

POST https://api.paymentwall.com/api/brick/charge/$chargeid/refund

Sample Request

var charge = new Paymentwall.Charge();
charge.otherOperation(chargeid,'refund',function(brick_response){
    brick_response.getFullResponse('JSON');
});

Endpoint

POST https://api.paymentwall.com/api/brick/charge/$chargeid/refund

Sample Request

import import com.paymentwall.java.Charge;

Charge charge = new Charge("CHARGE_ID");
charge = (Charge)charge.refund();
return charge.isRefunded();

Endpoint

POST https://api.paymentwall.com/api/brick/charge/$chargeid/refund

Endpoint

POST https://api.paymentwall.com/api/brick/charge/$chargeid/refund

Endpoint

POST https://api.paymentwall.com/api/brick/charge/$chargeid/refund

Endpoint

POST https://api.paymentwall.com/api/brick/charge/$chargeid/refund

Sample Request

curl https://api.paymentwall.com/api/brick/charge/[chargeId]/refund \
-H "X-ApiKey: [YOUR_PRIVATE_KEY]" \

Capture a charge

Capture the pre-authorization funds for a created charge. Refer to authorize and capture.

The Private API key is expected to be sent as the value of custom HTTPS header X-ApiKey by using this API. It can only be used for server-to-server calls and should never be exposed to end-users. You will have it been accomplished automatically if you are using our API libraries.

Parameters
Name Description
chargeid
required
string
The id of created charge object.

Endpoint

POST https://api.paymentwall.com/api/brick/charge/$chargeid/capture

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');
Paymentwall_Config::getInstance()->set(array(
    'private_key' => 'YOUR_PRIVATE_KEY'
));
$charge = new Paymentwall_Charge($chargeid);
$charge->capture();
$response=$charge->getPublicData();
echo $response;
?>

Endpoint

POST https://api.paymentwall.com/api/brick/charge/$chargeid/capture

Sample Request

var charge = new Paymentwall.Charge();
charge.otherOperation(chargeid,'capture',function(brick_response){
    brick_response.getFullResponse('JSON');
});

Endpoint

POST https://api.paymentwall.com/api/brick/charge/$chargeid/capture

Endpoint

POST https://api.paymentwall.com/api/brick/charge/$chargeid/capture

Endpoint

POST https://api.paymentwall.com/api/brick/charge/$chargeid/capture

Endpoint

POST https://api.paymentwall.com/api/brick/charge/$chargeid/capture

Endpoint

POST https://api.paymentwall.com/api/brick/charge/$chargeid/capture

Sample Request

curl https://api.paymentwall.com/api/brick/charge/t123456/capture \
-H "X-ApiKey: [YOUR_PRIVATE_KEY]" \

Void a charge

Void the pre-authorization funds for a created charge.

The Private API key is expected to be sent as the value of custom HTTPS header X-ApiKey by using this API. It can only be used for server-to-server calls and should never be exposed to end-users. You will have it been accomplished automatically if you are using our API libraries.

Parameters
Name Description
chargeid
required
string
The id of created charge object.

Endpoint

POST https://api.paymentwall.com/api/brick/charge/$chargeid/void

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');
Paymentwall_Config::getInstance()->set(array(
    'private_key' => 'YOUR_PRIVATE_KEY'
));
$charge = new Paymentwall_Charge($chargeid);
$charge->void();
$response=$charge->getPublicData();
echo $response;
?>

Endpoint

POST https://api.paymentwall.com/api/brick/charge/$chargeid/void

Sample Request

var charge = new Paymentwall.Charge();
charge.otherOperation(chargeid,'void',function(brick_response){
    brick_response.getFullResponse('JSON');
});

Endpoint

POST https://api.paymentwall.com/api/brick/charge/$chargeid/void

Endpoint

POST https://api.paymentwall.com/api/brick/charge/$chargeid/void

Endpoint

POST https://api.paymentwall.com/api/brick/charge/$chargeid/void

Endpoint

POST https://api.paymentwall.com/api/brick/charge/$chargeid/void

Endpoint

POST https://api.paymentwall.com/api/brick/charge/$chargeid/void

Subscription

The Private API key is expected to be sent as the value of custom HTTPS header X-ApiKey by using this API. It can only be used for server-to-server calls and should never be exposed to end-users. You will have it been accomplished automatically if you are using our API libraries.

Parameters
Name Description
amount
required
number
Amount to be charged. The minimum transaction limit is USD 0.3 or equivalent in other currencies.. 2 decimal places is expected.
currency
required
string
Code of the currency. Refer to currency codes.
browser_ip
string
IP address of End-user.
browser_domain
string
Domain of the website where the payment is originating from.
description
required
string
Description for the payment.
email
required
string
Email of end-users.
history[registration_date]
required
history[registration_date]
Unix timestamp of the transaction date. Length limitation is 10.
fingerprint
required
string
Unique fingerprint generated by Paymentwall for each transaction. If Brick.js is used, parameter brick_fingerprint will be sent to your backend directly.
You can not obtain brick_fingerprint if Brick.js is not used. In this case, fingerprint is no longer required, you need to use browser_ip and browser_domain instead. E.g. Mobile SDK, onetime token API
token
required
string
The value of one-time token or permanent token.
customer[firstname]
required
string
The first name of card holder.
customer[lastname]
required
string
The last name of card holder.
lang
string
Language code for email receipt localization, format ISO alpha-2, supported languages.
options[capture]
boolean
Whether or not to immediately capture the charge. Default is true. If you don’t want to capture it at once, you can pass options[capture]=0.
plan
required
string
Identifies the product ID, send back as goodsid parameter in pingbacks.
period
required
string
day/week/month/year
period_duration
required
number
Number of periods mentioned in the period parameter. By default minimum duration for recurring is 3 days. This can be adjusted by contacting devsupport@paymentwall.com.
trial[amount]
number
Trial amount. Free trials are also supported, please contact devsupport@paymentwall.com to have free trials active for your account
trial[currency]
string
Currency code of trail product.
trial[period]
number
Trial recurring period
trial[period_duration]
string
Trial recurring period duration. By default minimum duration is 3 days. This can be adjusted by contacting devsupport@paymentwall.com
uid
string
End user id in merchant system. If you pass it to us, we will send it back as uid parameter in Pingbacks. If omitted, email will be the value of uid parameter in Pingbacks.
custom
array
Parameters defined by merchant in request.To receive these values via Pingbacks, please add custom pingback parameter with name=custom and value=OWN.
tokidoki
boolean
For using TokiDoki recurring billing engine that supports more features such as dunning management, custom email reminders please pass tokidoki=1

An error object will be returned if there is any mistakes in your request, refer to error codes and find solutions accordingly.

Endpoint

POST https://api.paymentwall.com/api/brick/subscription

Sample Request

<?php
Paymentwall_Config::getInstance()->set(array(
    'public_key' => 'YOUR_PUBLIC_KEY',
    'private_key' => 'YOUR_PRIVATE_KEY'
));

$parameters = $_POST;
$subscriptionInfo = array(
    'token' => $_POST['brick_token'],
    'email' => $_POST['email'],
    'currency' => 'USD',
    'amount' => 10,
    'fingerprint' => $_POST['brick_fingerprint'],
    'plan' => 'product_123',
    'description' => 'Order #123',
    'period' => 'week',
    'period_duration' => 2,
    // for using the TokiDoki Recurring Billing
    'tokidoki' => 1, 
    // if trial, add following parameters
    'trial[amount]' => 1,
    'trial[currency]' => 'USD',
    'trial[period]'   => 'month',
    'trial[period_duration]' => 1
);

$subscription = new Paymentwall_Subscription();
$subscription->create($subscriptionInfo);
?>

Endpoint

POST https://api.paymentwall.com/api/brick/subscription

Sample Request

// We are using Express framework in this sample

var Paymentwall = require('paymentwall');
Paymentwall.Configure(                                                        
    Paymentwall.Base.API_GOODS,
    'YOUR_PUBLIC_KEY',
    'YOUR_PRIVATE_KEY'
);

//custom parameters
var custom = {
    'plan': 'product_123', // your product id
    'YOUR_CUSTOM_PARAMETER_NAME': 'YOUR_CUSTOM_PARAMETER_VALUE'
};

var trial = {
    amount: 0.5,
    currency: 'USD',
    period: 'day',
    period_duration: 3
}

var parameters = req.body;
var subscription = new Paymentwall.Subscription(
    0.5, //price
    'USD', //currency code
    'description', //description of the product
    req.body.email, // user's email
    req.body.brick_fingerprint, // fingerprint generated by Brick.js
    req.body.brick_token, //one-time token
    'week', // period
    2, // period_duration
    trial,
    custom 
);

subscription.createSubscription(function(brick_response){
    // Handle response
});

Subscription Request
Endpoint

POST https://api.paymentwall.com/api/brick/subscription

Sample Request

Config.getInstance().setPublicKey("YOUR_APPLICATION_KEY");
Config.getInstance().setPrivateKey("YOUR_SECRET_KEY");

LinkedHashMap<String, String> subscriptionmap = new LinkedHashMap<String, String>();

subscriptionmap.put("token", request.getParameter("brick_token"));
subscriptionmap.put("email", request.getParameter("email"));
subscriptionmap.put("currency", "USD");
subscriptionmap.put("amount", "9.99");
subscriptionmap.put("description", "YOUR-DESCRIPTION");
subscriptionmap.put("fingerprint", request.getParameter("brick_fingerprint"));
subscriptionmap.put("plan", "YOUR-PRODUCT-ID");
subscriptionmap.put("period", "week");
subscriptionmap.put("period_duration", "1");

subscriptionmap.put("trail[amount]", "0.5");
subscriptionmap.put("trail[currency]", "USD");
subscriptionmap.put("trail[period]", "day");
subscriptionmap.put("trail[period_duration]", "3");
Subscription subscription = new Subscription();
subscription = (Subscription) subscription.create(subscriptionmap);


Cancel a Subscription

Endpoint

POST https://api.paymentwall.com/api/brick/subscription/$id/cancel

Code Sample

Subscription subscription = new Subscription("SUBSCRIPTION_ID");
    subscription = (Subscription)(subscription.cancel());
return subscription.isActive();

Endpoint

POST https://api.paymentwall.com/api/brick/subscription


Cancel a Subscription

Endpoint

POST https://api.paymentwall.com/api/brick/subscription/$id/cancel

Endpoint

POST https://api.paymentwall.com/api/brick/subscription


Cancel a Subscription

Endpoint

POST https://api.paymentwall.com/api/brick/subscription/$id/cancel

Subscription Request
Endpoint

POST https://api.paymentwall.com/api/brick/subscription


Get Subscription details

Endpoint

GET https://api.paymentwall.com/api/brick/subscription/$id


Cancel a Subscription

Endpoint

POST https://api.paymentwall.com/api/brick/subscription/$id/cancel

Subscription request

Endpoint

POST https://api.paymentwall.com/api/brick/subscription

Sample Request

curl https://api.paymentwall.com/api/brick/subscription \
-H "X-ApiKey: [YOUR_PRIVATE_KEY]" \
-d "token=[TOKEN]" \
-d "email=user@host.com" \
-d "history[registration_date]=1489655092"
-d "currency=USD" \
-d "amount=10" \
-d "fingerprint=[FINGERPRINT_BY_BRICK.JS]" \
-d "description=Order #123" \
-d "plan=product_123" \
-d "period=week" \
-d "period_duration=2"

The subscription object

The array trial will be included in if trial product is enabled for its post-trial subscription.

Attributes
Name Description
active Whether the subscription is activated.
charges The charge ids in history payments.
date_next Next charge date, in unix timestamp.
date_started Subscription start date, in unix timestamp.
expired Whether the subscription is expired.
id Subscription id.
is_trial Whether the subscription is in trial period.
object Object type.
payments_limit The remaining recurring billing time.
period The subscription period, could be day/week/month.
period_duration Length of subscription period.
started Whether the subscription is started.
trial[active] Whether the trial period is activated.
trial[date_next] Next charge date, in unix timestamp.
trial[date_started] Trial period start date, in unix timestamp.
trial[expired] Whether the subscription is expired.
trial[id] Subscription id.
trial[is_trial] Whether the subscription is in trial period.
trial[object] Object type.
trial[payments_limit] The remaining recurring billing time of trial product.
trial[period] The trial period, could be day/week/month.
trial[period_duration] Length of trial period.
trial[started] Whether the trial period is started.

Subscription response object example

{
    "active": 1,
    "charges": {
        "0": "49393608",
        "1": "49393609"
    },
    "date_next": 1419784432,
    "date_started": 1419525232,
    "expired": 0,
    "id": "VCBZT392SW",
    "is_trial": 0,
    "object": "subscription",
    "payments_limit": 0,
    "period": "day",
    "period_duration": 3,
    "started": 1
}

Subscription object example for trail product

{
    "trial": {
        "active": 0,
        "date_next": 1419525232,
        "date_started": 1419438832,
        "expired": 1,
        "id": "VCBZT392SW",
        "is_trial": 1,
        "object": "subscription",
        "payments_limit": 1,
        "period": "day",
        "period_duration": 1,
        "started": 1
    }
}

Subscription response object example

{
  "active": 1,
  "charges": {
    "0": "49393608",
    "1": "49393609"
  },
  "date_next": 1419784432,
  "date_started": 1419525232,
  "expired": 0,
  "id": "VCBZT392SW",
  "is_trial": 0,
  "object": "subscription",
  "payments_limit": 0,
  "period": "day",
  "period_duration": 3,
  "started": 1
}

Subscription object example for trail product

{
  "trial": {
    "active": 0,
    "date_next": 1419525232,
    "date_started": 1419438832,
    "expired": 1,
    "id": "VCBZT392SW",
    "is_trial": 1,
    "object": "subscription",
    "payments_limit": 1,
    "period": "day",
    "period_duration": 1,
    "started": 1
  }
}

Subscription response object example

{
    "active": 1,
    "charges": {
        "0": "49393608",
        "1": "49393609"
    },
    "date_next": 1419784432,
    "date_started": 1419525232,
    "expired": 0,
    "id": "VCBZT392SW",
    "is_trial": 0,
    "object": "subscription",
    "payments_limit": 0,
    "period": "day",
    "period_duration": 3,
    "started": 1
}

Subscription object example for trail product

{
    "trial": {
        "active": 0,
        "date_next": 1419525232,
        "date_started": 1419438832,
        "expired": 1,
        "id": "VCBZT392SW",
        "is_trial": 1,
        "object": "subscription",
        "payments_limit": 1,
        "period": "day",
        "period_duration": 1,
        "started": 1
    }
}

Subscription response object example

{
    "active": 1,
    "charges": {
        "0": "49393608",
        "1": "49393609"
    },
    "date_next": 1419784432,
    "date_started": 1419525232,
    "expired": 0,
    "id": "VCBZT392SW",
    "is_trial": 0,
    "object": "subscription",
    "payments_limit": 0,
    "period": "day",
    "period_duration": 3,
    "started": 1
}

Subscription object example for trail product

{
    "trial": {
        "active": 0,
        "date_next": 1419525232,
        "date_started": 1419438832,
        "expired": 1,
        "id": "VCBZT392SW",
        "is_trial": 1,
        "object": "subscription",
        "payments_limit": 1,
        "period": "day",
        "period_duration": 1,
        "started": 1
    }
}

Subscription response object example

{
    "active": 1,
    "charges": {
        "0": "49393608",
        "1": "49393609"
    },
    "date_next": 1419784432,
    "date_started": 1419525232,
    "expired": 0,
    "id": "VCBZT392SW",
    "is_trial": 0,
    "object": "subscription",
    "payments_limit": 0,
    "period": "day",
    "period_duration": 3,
    "started": 1
}

Subscription object example for trail product

{
    "trial": {
        "active": 0,
        "date_next": 1419525232,
        "date_started": 1419438832,
        "expired": 1,
        "id": "VCBZT392SW",
        "is_trial": 1,
        "object": "subscription",
        "payments_limit": 1,
        "period": "day",
        "period_duration": 1,
        "started": 1
    }
}

Subscription response object example

{
    "active": 1,
    "charges": {
        "0": "49393608",
        "1": "49393609"
    },
    "date_next": 1419784432,
    "date_started": 1419525232,
    "expired": 0,
    "id": "VCBZT392SW",
    "is_trial": 0,
    "object": "subscription",
    "payments_limit": 0,
    "period": "day",
    "period_duration": 3,
    "started": 1
}

Subscription object example for trail product

{
    "trial": {
        "active": 0,
        "date_next": 1419525232,
        "date_started": 1419438832,
        "expired": 1,
        "id": "VCBZT392SW",
        "is_trial": 1,
        "object": "subscription",
        "payments_limit": 1,
        "period": "day",
        "period_duration": 1,
        "started": 1
    }
}

Subscription response object example

{
    "active": 1,
    "charges": {
        "0": "49393608",
        "1": "49393609"
    },
    "date_next": 1419784432,
    "date_started": 1419525232,
    "expired": 0,
    "id": "VCBZT392SW",
    "is_trial": 0,
    "object": "subscription",
    "payments_limit": 0,
    "period": "day",
    "period_duration": 3,
    "started": 1
}

Subscription object example for trial product

{
    "trial": {
        "active": 0,
        "date_next": 1419525232,
        "date_started": 1419438832,
        "expired": 1,
        "id": "VCBZT392SW",
        "is_trial": 1,
        "object": "subscription",
        "payments_limit": 1,
        "period": "day",
        "period_duration": 1,
        "started": 1
    }
}

Obtain subscription details

Obtain a created charge details by using subscriptionid.

The Private API key is expected to be sent as the value of custom HTTPS header X-ApiKey by using this API. It can only be used for server-to-server calls and should never be exposed to end-users. You will have it been accomplished automatically if you are using our API libraries.

Parameters
Name Description
subscriptionid
required
string
The id of created subscription object.

Endpoint

GET https://api.paymentwall.com/api/brick/subscription/$id

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');
Paymentwall_Config::getInstance()->set(array(
    'private_key' => 'YOUR_PRIVATE_KEY'
));
$subscription = new Paymentwall_Subscription($subscriptionid);
$subscription->get();
$response=$subscription->getRawResponseData();
echo $response;
?>

Endpoint

GET https://api.paymentwall.com/api/brick/subscription/$id

Sample Request

var subscription = new Paymentwall.Subscription();
subscription.otherOperation(subscriptionid,'detail',function(response){
    response.getFullResponse('JSON');
});

Endpoint

GET https://api.paymentwall.com/api/brick/subscription/$id

Endpoint

GET https://api.paymentwall.com/api/brick/subscription/$id

Endpoint

GET https://api.paymentwall.com/api/brick/subscription/$id

Endpoint

GET https://api.paymentwall.com/api/brick/subscription/$id

Endpoint

GET https://api.paymentwall.com/api/brick/subscription/$id

Sample Request

curl https://api.paymentwall.com/api/brick/subscription/[subscriptionid] \
-H "X-ApiKey: [YOUR_PRIVATE_KEY]" \

Cancel a subscription

Cancel an active subscription using subscriptionid.

The Private API key is expected to be sent as the value of custom HTTPS header X-ApiKey by using this API. It can only be used for server-to-server calls and should never be exposed to end-users. You will have it been accomplished automatically if you are using our API libraries.

Parameters
Name Description
subscriptionid
required
string
The id of created subscription object.

Endpoint

POST https://api.paymentwall.com/api/brick/subscription/$id/cancel

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');
Paymentwall_Config::getInstance()->set(array(
    'private_key' => 'YOUR_PRIVATE_KEY'
));
$subscription = new Paymentwall_Subscription($subscriptionid);
$subscription->cancel();
$response=$subscription->getPublicData();
echo $response;
?>

Endpoint

POST https://api.paymentwall.com/api/brick/subscription/$id/cancel

Sample Request

var subscription = new Paymentwall.Subscription();
subscription.otherOperation(subscriptionid,'cancel',function(response){
    // response is a new Response Object Entity (defined in paymentwall/lib/Response/Abstract)
    response.getFullResponse('JSON');
});

Endpoint

POST https://api.paymentwall.com/api/brick/subscription/$id/cancel

Endpoint

POST https://api.paymentwall.com/api/brick/subscription/$id/cancel

Endpoint

POST https://api.paymentwall.com/api/brick/subscription/$id/cancel

Endpoint

POST https://api.paymentwall.com/api/brick/subscription/$id/cancel

Endpoint

POST https://api.paymentwall.com/api/brick/subscription/$id/cancel

Sample Request

curl https://api.paymentwall.com/api/brick/subscription/[subscriptionid]/cancel \
-H "X-ApiKey: [YOUR_PRIVATE_KEY]" \

Tokenization API

Brick Tokenization API accepts one-time token generated using Brick.js along with user information parameters and initiates a Auth / Void Transaction. Once the process is complete, the API returns Brick permanent token which can be used multiple times for charging.

Headers
Name Description
x-apikey
required
string
Your Brick Test / Live Private Key
Parameters
Name Description
token
required
string
One time token generated using Brick.js
email
required
email
User’s Email address
firstname
required
string
First Name of the user
lastname
required
string
Last Name of the user

Endpoint

POST https://api.paymentwall.com/api/brick/tokenize

Get token

Get token API is for you to get the token for the transactions with Mobiamo

To activate it please email us at devsupport@paymentwall.com.

Parameter
Name Description
key
required
string
The project key which can be found in Merchant Area→ My Projects.
uid
required
string
ID of the end-user in your system. The maximum length is 64.
sign_version
required
string
The signature version. Version 2 uses MD5 and version 3 represents SHA256.
ts
required
string
Unix timestamp when the request was initiated, in seconds.
sign
required
string lowercase
The signature of request. Refer to signature calculation for more details.

Get token response

Attributes
Name Description
success Status of the request. Either true or false
token The API token. This will be attached in the header in the next requests.
expire_time The validation period of the token. If the token is invalid or expired, you must call this API again to get the new token.

Endpoint:

POST https://api.paymentwall.com/api/mobiamo/token

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');
Paymentwall_Config::getInstance()->set(array(
    'public_key' => 'YOUR_PROJECT_KEY',
    'private_key' => 'YOUR_SECRET_KEY'
));

$mobiamo = new Paymentwall_Mobiamo();
$tokenParams = [
	'uid' => 'test'
]

$response = $mobiamo->getToken($tokenParams);
$token = $response['token'];
// store this token to use for next requests
?>

Sample Response

{
    "success": true,
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1MDM2NDQ3NzIsImp0aSI6Ik5IcWN0QjZEbGR3bjNmQWxSZ1VuXC8zWkRhQjI1R1dvZlpSelJcL0JMYzNhTT0iLCJleHAiOjE1MDM3MzExNzIsImRhdGEiOnsibWVyY2hhbnRJZCI6IjIiLCJ0aW1lc3RhbXAiOiIxNTAzNjQ0NzEzIiwicHJvamVjdF9pZCI6IjE4MjgxNSJ9fQ.R5jLTYV23qRDaMbHZlun6MDFbWfK9xXTMzPIzNglr0A",
    "expire_time": 86400
}

Initiate payment

This API is to initate the payment with Mobiamo and get the flow to instruct the users to make payment.

token is expected to be sent as the value of custom HTTP header parameter Token by using this API.

Parameters
Name Description
key
required
string
The project key which can be found in Merchant Area→ My Projects.
uid
required
string
ID of the end-user in your system. The maximum length is 64.
amount
required
double
The amount of your product. It should be set according to the price points.
currency
required
string
Currency code of your product. Needs to be used along with amount. 3 letters. Refer to currency codes.
country
required
string
Country code in ISO 3166-1 alpha-2 format.
product_name
required
string
Your product name. The maximum length is 256.
product_id
required
string
ID of your product. We will communicate back to you via the pingback as goodsid parameter. The maximum length is 256.
is_recurring
optional
boolean
Can be either true or false. Whether the product is recurring. By default, recurring billing is only supported for product with duration of at least 3 days and less than 1 year.
period
optional
string
The type of your subscription duration. Required to be set to following types, value: day - week - month.
period_value
optional
integer
The length of your subscription duration.
carrier
optional
string
The ID of the mobile carrier. This parameter is required in some countries. The list of ID can be found in Mobiamo Carriers.
msisdn
optional
string
User’s phone number in international format: [country code] + [mobile number without 0 at the beginning]
mnc
optional
string
Mobile network code. Required along with mcc to identify user’s carrier and provide relevant instructions.
mcc
optional
string
Mobile country code.
options[confirmation_message]
optional
string
Custom message to be sent to the user upon successful payment. Limit to 90 chars.

Response

Attributes
Name Description
success Status of the request. Either true or false
ref Reference ID of the transaction
flow The flow of how to make payment:
1. code: users send keyword to shortcode in instructions to receive a pin code. Then you send this code in process payment request.
2. msisdn: users enters phone number. The you send this phone number in process payment request.
3. redirect: You need to redirect users to the redirect_url in the instructions.
The flow depends on the country
price An array includes information about the product.
instructions Instruction parameters for users to make payment:
1. Flow code: keyword and shortcode are included
2. Flow redirect: redirect_url is included
error Error description in case of failed request.
code Error code in case of failed request.

Endpoint:

POST https://api.paymentwall.com/api/mobiamo/init-payment

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');
Paymentwall_Config::getInstance()->set(array(
    'public_key' => 'YOUR_PROJECT_KEY',
    'private_key' => 'YOUR_SECRET_KEY'
));

$mobiamo = new Paymentwall_Mobiamo();
$initParams = [
	'uid' => 'test', 
	'amount' => 2000, 
	'currency' => 'PHP', //currency of payment in ISO 4217 format
	'country' => 'PH', //country of payment in ISO alpha-2 format
	'product_id' => 'product101', //product id of payment
	'product_name' => 'Test Product', //product name of payment
	'carrier' => '255' //mandatory in some countries - Given id of user's operator
];

//token returned from get token step above
$response = $mobiamo->initPayment($token, $initParams);

$ref = $response['ref'];
// store this token to use for next request
?>

Sample Response

{
    "ref": "21180452",
    "flow": "msisdn",
    "instructions": {},
    "price": {
        "amount": 2000,
        "currency": "PHP",
        "formatted": "PHP 2,000.00",
        "carriers": [{
            "id": 255,
            "name": "Globe"
        }]
    },
    "product_name": "coins",
    "success": true
}

Process payment

This API is to process the payment with the data collected from the users.

token is expected to be sent as the value of custom HTTP header parameter Token by using this API.

Parameters
Name Description
key
required
string
The project key which can be found in Merchant Area→ My Projects.
uid
required
string
ID of the end-user in your system. The maximum length is 64.
ref
required
string
Reference ID of the transaction
flow
required
string
The flow returned from initiate payment request
data
required
string
The data you collect from users
1. Flow code: users’ submitted pin code
2. Flow msisdn: users’ submitted phone number

Response

Attributes
Name Description
success Status of the request. Either true or false
flow The next flow for users to make payment. This is only applicable in certain countries. If it’s empty, transaction is completed
instructions Instruction for users to make payment if applicable.
error Error description in case of failed request.
code Error code in case of failed request.

Endpoint:

POST https://api.paymentwall.com/api/mobiamo/process-payment

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');
Paymentwall_Config::getInstance()->set(array(
    'public_key' => 'YOUR_PROJECT_KEY',
    'private_key' => 'YOUR_SECRET_KEY'
));

$model = new Paymentwall_Mobiamo();
$processParams = [
	'uid' => 'test', 
	'ref' => $ref, //reference id returned from initiate payment request 
	'flow' => 'msisdn', //flow returned from initiate payment request
	'data' => '6312345678' //value can be: code user received after sending message / phone number of user
];

//token returned from get token step above
$response = $model->processPayment($token, $processParams);
?>

Sample Response

{
    "success": true,
    "instructions": {
        "shortcode": "2800",
        "keyword": "PW2000",
        "info": "VAT included. For customer support, please contact us at support@mobiamo.com"
    },
    "flow": "code" //Only return if this payment requires next processing step. values can be: code - user send keyword to shortcode in instructions/ msisdn - user input phone number / redirect - redirect user to redirect_url in intructions / 	
}

Get transaction details

This API allows you to get the information about the transactions with Mobiamo API

token is expected to be sent as the value of custom HTTP header parameter Token by using this API.

Parameters
Name Description
key
required
string
The project key which can be found in Merchant Area→ My Projects.
uid
required
string
ID of the end-user in your system. The maximum length is 64.
ref
required
string
Reference ID of the transaction

Response

Attributes
Name Description
success Status of the request. Either true or false
ref Reference ID of the transaction
completed Whether the transaction has been completed or not. Can be either true or false
amount The price of the product
currency Currency code of the product
country Country code in ISO 3166-1 alpha-2 format of the transaction
product_name The product name
product_id ID of the product
is_recurring Can be either true or false. Whether the product is recurring
period The type of your subscription duration
period_value The length of your subscription duration
error Error description in case of failed request.
code Error code in case of failed request.

Endpoint:

POST https://api.paymentwall.com/api/mobiamo/get-payment

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');
Paymentwall_Config::getInstance()->set(array(
    'public_key' => 'YOUR_PROJECT_KEY',
    'private_key' => 'YOUR_SECRET_KEY'
));

$mobiamo = new Paymentwall_Mobiamo();
$getPaymentParams = [
    'uid' => 'test', 
    'ref' => $ref, //reference id returned from initiate payment request 
];

//token returned from get token step above
$response = $mobiamo->processPayment($token, $getPaymentParams);
?>

Sample Response

{
    "success" => true,
    "completed" => true, //value: true/false - indicate this payment was already successfull or not
    "amount" => 2000,
    "currency" => "PHP",
    "country" => "PH",
    "product_name" => "Test Product",
    "msisdn" => "63123456789",
    "ref" => "w123456789"
}

Pricepoint

Price Points API allows merchants to retrieve the list of mobiamo price points for a country.

Parameters
Name Description
country_code
required
string
Country code in ISO 3166-1 alpha-2 format.
currency_converted
string
Currency code in ISO 4217 format to be used for converting the price point amounts from local currency to the converted currency.
key
required
string
The project key which can be found in Merchant Area→ My Projects.
ps
required
string
The value must be mobiamo.
sign_version
required
integer
Signature version. Version 2 uses MD5 and version 3 uses SHA256.
sign
required
string lowercase
The request signature. Refer to Signature Calculation for more details.

Endpoint

GET https://api.paymentwall.com/api/price-points/

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');

$params = array(
    'country_code'=>'GB',
    'key'=>'YOUR_PROJECT_KEY',
    'ps'=>'mobilegateway', 
    'sign_version'=>2
);

Paymentwall_Config::getInstance()->set(array('private_key' => 'YOUR_SECRET_KEY'));
$params['sign'] = (new Paymentwall_Signature_Widget())->calculate(
    $params,
    $params['sign_version']
    );

$url = 'https://api.paymentwall.com/api/price-points/?'.http_build_query($params);

$curl = curl_init($url);

curl_setopt($curl,CURLOPT_RETURNTRANSFER,TRUE);
$response = curl_exec($curl);
echo $response;
?>

Sample Response

[{
    "amount": 1,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 1.14
}, {
    "amount": 1.5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 1.7
}, {
    "amount": 2,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 2.27
}, {
    "amount": 2.5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 2.84
}, {
    "amount": 3,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 3.41
}, {
    "amount": 4.5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 5.11
}, {
    "amount": 5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 5.68
}, {
    "amount": 10,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 11.36
}]

Endpoint

GET https://api.paymentwall.com/api/price-points/

Sample Response

[{
    "amount": 1,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 1.14
}, {
    "amount": 1.5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 1.7
}, {
    "amount": 2,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 2.27
}, {
    "amount": 2.5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 2.84
}, {
    "amount": 3,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 3.41
}, {
    "amount": 4.5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 5.11
}, {
    "amount": 5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 5.68
}, {
    "amount": 10,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 11.36
}]

Endpoint

GET https://api.paymentwall.com/api/price-points/

Sample Response

[{
    "amount": 1,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 1.14
}, {
    "amount": 1.5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 1.7
}, {
    "amount": 2,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 2.27
}, {
    "amount": 2.5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 2.84
}, {
    "amount": 3,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 3.41
}, {
    "amount": 4.5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 5.11
}, {
    "amount": 5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 5.68
}, {
    "amount": 10,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 11.36
}]

Endpoint

GET https://api.paymentwall.com/api/price-points/

Sample Response

[{
    "amount": 1,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 1.14
}, {
    "amount": 1.5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 1.7
}, {
    "amount": 2,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 2.27
}, {
    "amount": 2.5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 2.84
}, {
    "amount": 3,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 3.41
}, {
    "amount": 4.5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 5.11
}, {
    "amount": 5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 5.68
}, {
    "amount": 10,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 11.36
}]

Endpoint

GET https://api.paymentwall.com/api/price-points/

Sample Response

[{
    "amount": 1,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 1.14
}, {
    "amount": 1.5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 1.7
}, {
    "amount": 2,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 2.27
}, {
    "amount": 2.5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 2.84
}, {
    "amount": 3,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 3.41
}, {
    "amount": 4.5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 5.11
}, {
    "amount": 5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 5.68
}, {
    "amount": 10,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 11.36
}]

Endpoint

GET https://api.paymentwall.com/api/price-points/

Sample Response

[{
    "amount": 1,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 1.14
}, {
    "amount": 1.5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 1.7
}, {
    "amount": 2,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 2.27
}, {
    "amount": 2.5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 2.84
}, {
    "amount": 3,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 3.41
}, {
    "amount": 4.5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 5.11
}, {
    "amount": 5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 5.68
}, {
    "amount": 10,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 11.36
}]

Endpoint

GET https://api.paymentwall.com/api/price-points/

Sample Response

[{
    "amount": 1,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 1.14
}, {
    "amount": 1.5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 1.7
}, {
    "amount": 2,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 2.27
}, {
    "amount": 2.5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 2.84
}, {
    "amount": 3,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 3.41
}, {
    "amount": 4.5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 5.11
}, {
    "amount": 5,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 5.68
}, {
    "amount": 10,
    "currency": "GBP",
    "currency_converted": "EUR",
    "amount_converted": 11.36
}]

Response Codes

Following are the Response codes provided by Mobiamo APIs

Possible Values

Code Description
W1 This session has expired
W3 Wrong project secret key
W4 Wrong project key
W5 Parameter key or uid is missing
W13 Bad request params
W14 Price not found
W15 Service is unavailable at this time
W16 Payment system was blocked for user
18 Signature is invalid
W19 Api is not activated

Generate ePIN

You can use this api to generate ePin if you are a MINT reseller.

Parameters
Parameters Description
auth[key]
required
string
API Public Key
Can be obtained under Settings of the Reseller Account
auth[timestamp]
required
int
Current UNIX time
auth[sign]
required
string
The request signature
Refer to this link for signature algorithm
params[serviceId]
int
ID of the service to generate
Default value is 0, ePIN generated can be used in all services
params[currencyCode]
required
string(3)
ISO 4217 currency code of the ePIN value
params[ePinNominalValue]
required
int
Value of the ePIN
params[ePinsCount]
int
Quantity of the ePINs to generate
Default value is 1.
params[countryCode]
string(2)
ISO 3166-1 alpha-2 code of the country of service
params[activationRequired]
boolean
Can be either 0 or 1
If [1], it generates Inactive ePins. If [0] or omitted, it generates Active ePins.
params[test]
boolean
Can be either 0 or 1.
If [1], you will receive one of test keys to verify the response.

Endpoint

POST  https://api.paymentwall.com/pwapi/partners-mint (MINT app)
POST: https://api.paymentwall.com/pwapi/mint (MINT reseller)

Sample Request

<?php
$secret = 'YOUR_SECRET_KEY';

$params = array(
    'params[serviceId]' => 0,
    'params[currencyCode]' => 'USD',
    'params[ePinNominalValue]' => 5,
    'params[ePinsCount]' => 1,
    'params[countryCode]' => 'US',
    'params[activationRequired]' => 1,
    'params[test]' => 1
);
$auth = [
    'auth[key]' => 'YOUR_AUTH_KEY',
    'auth[timestamp]' => time()
];
ksort($params);
$auth['auth[sign]'] = md5($auth['auth[key]'] . $auth['auth[timestamp]'] . implode('', $params) . $secret);

$postParams = array_merge($auth, $params);

$post = curl_init();
curl_setopt($post, CURLOPT_URL, 'https://api.paymentwall.com/pwapi/mint');
curl_setopt($post, CURLOPT_POST, 1);
curl_setopt($post, CURLOPT_POSTFIELDS, $postParams);
$response = curl_exec($post);
echo $response;
?>

Sample Response

{
    "success": true,
    "data": [{
        "pin_id": 52775,
        "pin_code": "5311 8601 2711 2955",
        "pin_time_expired": 1521796425,
        "pin_generated_time": 1490260425,
        "pin_nominal_value": "5.0000",
        "cu_code": "USD",
        "cu_id": 1,
        "pin_tr_amount": "5.0000"
    }],
    "reference": "186177"
}

Endpoint

POST  https://api.paymentwall.com/pwapi/partners-mint (MINT app)
POST: https://api.paymentwall.com/pwapi/mint (MINT reseller)

Sample Response

{
    "success": true,
    "data": [{
        "pin_id": 52775,
        "pin_code": "5311 8601 2711 2955",
        "pin_time_expired": 1521796425,
        "pin_generated_time": 1490260425,
        "pin_nominal_value": "5.0000",
        "cu_code": "USD",
        "cu_id": 1,
        "pin_tr_amount": "5.0000"
    }],
    "reference": "186177"
}

Endpoint

POST  https://api.paymentwall.com/pwapi/partners-mint (MINT app)
POST: https://api.paymentwall.com/pwapi/mint (MINT reseller)

Sample Response

{
    "success": true,
    "data": [{
        "pin_id": 52775,
        "pin_code": "5311 8601 2711 2955",
        "pin_time_expired": 1521796425,
        "pin_generated_time": 1490260425,
        "pin_nominal_value": "5.0000",
        "cu_code": "USD",
        "cu_id": 1,
        "pin_tr_amount": "5.0000"
    }],
    "reference": "186177"
}

Endpoint

POST  https://api.paymentwall.com/pwapi/partners-mint (MINT app)
POST: https://api.paymentwall.com/pwapi/mint (MINT reseller)

Sample Response

{
    "success": true,
    "data": [{
        "pin_id": 52775,
        "pin_code": "5311 8601 2711 2955",
        "pin_time_expired": 1521796425,
        "pin_generated_time": 1490260425,
        "pin_nominal_value": "5.0000",
        "cu_code": "USD",
        "cu_id": 1,
        "pin_tr_amount": "5.0000"
    }],
    "reference": "186177"
}

Endpoint

POST  https://api.paymentwall.com/pwapi/partners-mint (MINT app)
POST: https://api.paymentwall.com/pwapi/mint (MINT reseller)

Sample Response

{
    "success": true,
    "data": [{
        "pin_id": 52775,
        "pin_code": "5311 8601 2711 2955",
        "pin_time_expired": 1521796425,
        "pin_generated_time": 1490260425,
        "pin_nominal_value": "5.0000",
        "cu_code": "USD",
        "cu_id": 1,
        "pin_tr_amount": "5.0000"
    }],
    "reference": "186177"
}

Endpoint

POST  https://api.paymentwall.com/pwapi/partners-mint (MINT app)
POST: https://api.paymentwall.com/pwapi/mint (MINT reseller)

Sample Response

{
    "success": true,
    "data": [{
        "pin_id": 52775,
        "pin_code": "5311 8601 2711 2955",
        "pin_time_expired": 1521796425,
        "pin_generated_time": 1490260425,
        "pin_nominal_value": "5.0000",
        "cu_code": "USD",
        "cu_id": 1,
        "pin_tr_amount": "5.0000"
    }],
    "reference": "186177"
}

Endpoint

POST  https://api.paymentwall.com/pwapi/partners-mint (MINT app)
POST: https://api.paymentwall.com/pwapi/mint (MINT reseller)

Sample Response

{
    "success": true,
    "data": [{
        "pin_id": 52775,
        "pin_code": "5311 8601 2711 2955",
        "pin_time_expired": 1521796425,
        "pin_generated_time": 1490260425,
        "pin_nominal_value": "5.0000",
        "cu_code": "USD",
        "cu_id": 1,
        "pin_tr_amount": "5.0000"
    }],
    "reference": "186177"
}

Get ePIN balance

Parameters
Parameter Description
auth[key]
required
string
API Public Key
Can be obtained under Settings of the Reseller Account
auth[timestamp]
required
int
Current UNIX time
auth[sign]
required
string
The request signature
Refer to this link for signature algorithm

Endpoint

GET https://api.paymentwall.com/pwapi/mint-balances

Sample Request

<?php
$secret='YOUR_SECRET_KEY';

$params =[];
$auth = [
    'auth[key]' => 'YOUR_AUTH_KEY',
    'auth[timestamp]' => time()
];
$auth['auth[sign]'] = md5($auth['auth[key]'] . $auth['auth[timestamp]'] . implode('', $params) . $secret);

$url = 'https://api.paymentwall.com/pwapi/mint-balances?'.http_build_query($auth);

$curl = curl_init($url);
curl_setopt($curl,CURLOPT_RETURNTRANSFER,TRUE);
$response = curl_exec($curl);
echo $response
?>

Sample Response

{
    "success": true,
    "data": [{
        "cu_code": "USD",
        "balance_amount": "9944.0655"
    }],
    "reference": "186178"
}

Endpoint

GET https://api.paymentwall.com/pwapi/mint-balances

Sample Response

{
    "success": true,
    "data": [{
        "cu_code": "USD",
        "balance_amount": "9944.0655"
    }],
    "reference": "186178"
}

Endpoint

GET https://api.paymentwall.com/pwapi/mint-balances

Sample Response

{
    "success": true,
    "data": [{
    "cu_code": "USD",
        "balance_amount": "9944.0655"
    }],
    "reference": "186178"
}

Endpoint

GET https://api.paymentwall.com/pwapi/mint-balances

Sample Response

{
    "success": true,
    "data": [{
        "cu_code": "USD",
        "balance_amount": "9944.0655"
    }],
    "reference": "186178"
}

Endpoint

GET https://api.paymentwall.com/pwapi/mint-balances

Sample Response

{
    "success": true,
    "data": [{
        "cu_code": "USD",
        "balance_amount": "9944.0655"
    }],
    "reference": "186178"
}

Endpoint

GET https://api.paymentwall.com/pwapi/mint-balances

Sample Response

{
    "success": true,
    "data": [{
        "cu_code": "USD",
        "balance_amount": "9944.0655"
    }],
    "reference": "186178"
}

Endpoint

GET https://api.paymentwall.com/pwapi/mint-balances

Sample Response

{
    "success": true,
    "data": [{
        "cu_code": "USD",
        "balance_amount": "9944.0655"
    }],
    "reference": "186178"
}

MINT redemption

This API is for merchants to allows users to redeem a MINT ePin.

Parameters
Parameter Description
amount
required
int
The amount of money to pay
currency
required
string
Currency code of the ePIN. Refer to currency codes.
epin
required
array
List of ePINs to redeem
Currently, it is only possible to redeem one ePin at a time.
app_key
required
string
The project key which can be found in Merchant Area→ My Projects.
user_id
required
string
ID of the user in merchant’s system

Endpoint

POST https://api.paymentwall.com/api/pure-mint/payment

Sample Request

<?php
$params = array(
    'amount' => 0.12,
    'currency' => 'USD',
    'epin[0]' => '8661217792834101',
    'app_key' => 'YOUR_PROJECT_KEY',
    'user_id' => 'user101'
);

$post = curl_init();

curl_setopt($post, CURLOPT_URL, 'https://api.paymentwall.com/api/pure-mint/payment');
curl_setopt($post, CURLOPT_POST, 1);
curl_setopt($post, CURLOPT_POSTFIELDS, $params);
$response = curl_exec($post);

echo $response;
?>

Sample Response

{
    "change_amount" : 0.12,                 
    "change_currency" : "USD",              
    "success" : 1                         
}

Endpoint

POST https://api.paymentwall.com/api/pure-mint/payment

Response

{
    "change_amount" : 0.12,                                 
    "change_currency" : "USD",                            
    "success" : 1                                                 
}

Endpoint

POST https://api.paymentwall.com/api/pure-mint/payment

Response

{
    "change_amount" : 0.12,                 
    "change_currency" : "USD",              
    "success" : 1                         
}

Endpoint

POST https://api.paymentwall.com/api/pure-mint/payment

Response

{
    "change_amount" : 0.12,                 
    "change_currency" : "USD",              
    "success" : 1                         
}

Endpoint

POST https://api.paymentwall.com/api/pure-mint/payment

Response

{
    "change_amount" : 0.12,                                 
    "change_currency" : "USD",                            
    "success" : 1                                                 
}

Endpoint

POST https://api.paymentwall.com/api/pure-mint/payment

Response

{
    "change_amount" : 0.12,                 
    "change_currency" : "USD",              
    "success" : 1                         
}

Endpoint

POST https://api.paymentwall.com/api/pure-mint/payment

Sample Request

curl https://api.paymentwall.com/api/pure-mint/payment \ 
-d "amount=0.12" \
-d "currency=USD" \
-d "epin=[YOUR-EPIN]" \
-d "app_key=[YOUR-PROJECT-KEY]" \
-d "user_id=[YOUR-USER-ID]"

Sample Response

{
    "change_amount" : 0.12,                 
    "change_currency" : "USD",              
    "success" : 1                         
}

Error codes

Codes
Error codes Description
1001 General internal error
1002 Application not loaded
1003 User banned
2001 Empty E-Pin
2002 Empty project key
2003 Wrong amount
2004 Wrong currency
2005 Epin is not array
2006 Empty user id
3001 Mint is not activated for this project
3002 Epin expired
3003 Epin is not activated
3004 Epin duplicate
3005 Epin is not available for this application
3006 Epin is invalid
3007 Only one epin is allowed
3008 Epin tracking failure
3009 Epin insufficient funds
4001 Maximum attempts exceeded

Reporting API

Reporting API allows merchants to pull reports from their Paymentwall Merchant Account via API.

This API can be activated for your Paymentwall Merchant Account by request.
To activate it please email us at devsupport@paymentwall.com.

Parameters
Parameter Description
search[date_from]
required
date
Date from in mm/dd/yyyy format, e.g. 11/30/2014
search[date_to]
required
date
Date to in mm/dd/yyyy format, e.g. 12/31/2014
search[s]
required
int
Required value: 1
search[transactionType]
required
string
payments or offers
project_public_key
required
string
Public Key of your project for which the report is pulled, has to be used in combination with Header X-ApiKey = Project Secret Key; Can be skipped if Header X-ApiKey = Merchant Secret Key (older version)
Request Headers
Parameter Description
X-ApiKey Your Project Secret Key. Required for Authentication. Also supports older version where your Merchant Secret Key is used, generated by Paymentwall (different from project key).

Endpoint

POST https://api.paymentwall.com/developers/reports/transactions-export

Sample request

<?phprequire_once('paymentwall-php/lib/paymentwall.php');

$config = Paymentwall_Config::getInstance();
$config->set(array('private_key' => 'YOUR_PRIVATE_KEY', 'public_key' => 'YOUR_PUBLIC_KEY'));

$params = array(
    'project_public_key' => $config->getPublicKey(),
    'search' => array(
      'date_from' => "07/01/2019",
      'date_to' => "03/01/2020",
      's' => 1,
      'transactionType' => 'payments'
    ),
);

$headers = array('X-ApiKey:' . $config->getPrivateKey());

$url = 'https://api.paymentwall.com/developers/reports/transactions-export?'.http_build_query($params);

$post = curl_init();
curl_setopt($post, CURLOPT_URL, $url);
curl_setopt($post, CURLOPT_HTTPHEADER, $headers);
curl_setopt($post, CURLOPT_RETURNTRANSFER, TRUE);
$response = curl_exec($post);

echo ($response != "") ? $response : "NOK";

Cancellation

This API allows to issue a request to refund a transaction or to cancel a recurring billing payment. If the response is successful, a ticket will be created under Research and Refund in your account.

Note : If you are using test project key, ticket will not be generated. Please try again with LIVE project key with real transaction.

Parameters
Parameter Description
key
required
string
The project key which can be found in Merchant Area→ My Projects.
ref
required
string
Payment reference ID.
Can be obtained from parameter ref in pingback request.
type
required
integer
Type of the ticket:
1. Refund
2. Recurring billing cancellation
3. Others
5. Partial refunds
message
required
string
Description of the ticket, a short instruction about the reason of cancellation is expected.
sign_version
required
integer
Signature version
Version 2 employs MD5 and version 3 uses SHA256.
sign
required
string lowercase
The request signature. Refer to Signature Calculation for more details.
test_mode
integer
Either 0 or 1.
1 means that the API is used in test mode, in this case no real ref is required.
uid
string
ID of end-users in your system. ref is not required if uid is submitted.
amount
double
Amount to be refunded to the customer in case of partial refunds (type=5).
Add Custom Pingback parameter “CURRENCY_CODE” in your project settings to retrive the currency in which the user was charged to calculate partial refund amount.

Endpoint

POST https://api.paymentwall.com/developers/api/ticket

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');
$params = array(
    'key' => 'YOUR_PROJECT_KEY',
    'ref' => 't1234',
    'uid' => 'user40012',
    'sign_version' => 2,
    'type' => 1,
    'message' => 'cancelled order',
    'test_mode' => 1
);

Paymentwall_Config::getInstance()->set(array('private_key' => 'YOUR_SECRET_KEY'));
$params['sign'] = (new Paymentwall_Signature_Widget())->calculate(
    $params,
    $params['sign_version']
);

$post = curl_init();
curl_setopt($post, CURLOPT_URL, 'https://api.paymentwall.com/developers/api/ticket');
curl_setopt($post, CURLOPT_POST, 1);
curl_setopt($post, CURLOPT_POSTFIELDS, $params);
$response = curl_exec($post);
echo $response;

Sample Response

{"result":1}

Endpoint

POST https://api.paymentwall.com/developers/api/ticket

Sample Response

{"result":1}

Endpoint

POST https://api.paymentwall.com/developers/api/ticket

Sample Response

{"result":1}

Endpoint

POST https://api.paymentwall.com/developers/api/ticket

Sample Response

{"result":1}

Endpoint

POST https://api.paymentwall.com/developers/api/ticket

Sample Response

{"result":1}

Endpoint

POST https://api.paymentwall.com/developers/api/ticket

Sample Response

{"result":1}

Endpoint

POST https://api.paymentwall.com/developers/api/ticket

Sample Request

curl https://api.paymentwall.com/developers/api/ticket \
-d "key=[YOUR_PROJECT_KEY]" \
-d "ref=t1234" \
-d "uid=user40012" \
-d "type=1" \
-d "message=cancelled order" \
-d "is_test=1" \
-d "sign_version=2" \
-d "sign=[SIGNATURE]" \

Sample Response

{"result":1}

Coupon

Coupon API allows merchants to create coupons for discounts, promotions and special offers.

Creating a coupon

Parameters
Parameter Description
key
required
string
The project key which can be found in Merchant Area→ My Projects.
timestamp
required
int
Current UNIX time
sign
required
string
The Request Signature
All parameters must be put into signature calculation.
You MUST use SHA256 for signature algorithm.
percent_off
required*
int
Discount percentage
Value can be from 1 to 99.
amount_off
required*
int
Discount amount
currency_code
required*
string
ISO 4217 currency code of the discount amount
name
string
Coupon name, default value is null.
number_of_coupons
int
Number of coupons to be created
If multiple coupons are created and code parameter is provided, the coupon will be generated as follows: code+‘random string’.
If there is no code parameter in the request, a ‘random string’ will be generated as the coupon code. Defaul value is 1.
code
string
If number_of_coupons equals to 1, this parameter is the coupon code.
If number_of_coupons is more than 1, coupon codes will be generated using the following algorithm: code + 7 random digits.
activate
boolean
Either 1 or 0
Activating coupon after creating.
max_redemptions
int
The number of times that coupon can be redeemed
expiration_date
int
Coupon expiration date
The expiration_date MUST be greater than the timestamp.

Either percent_off or amount_off should be included in the request, currency_code is required if you are using amount_off.

Endpoint

POST https://api.paymentwall.com/api/coupon

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');
$params = array(
    'key' => 'YOUR_PROJECT_KEY',
    'timestamp' => time(),
    'percent_off' => 10,
    'name' => 'Coupon_1',
    'number_of_coupons' => 1,
    'code' => 'TESTCOUPON_1',
    'activate' => 'Yes',
    'max_redemptions' => 1,
    'expiration_date' => '08/20/2017',
    'available_applications' => 'ALL'
);

Paymentwall_Config::getInstance()->set(array('private_key' => 'YOUR_SERCRET_KEY'));
$params['sign'] = (new Paymentwall_Signature_Widget())->calculate(
    $params,
    3 //signature version must be 3
);

$post = curl_init();
curl_setopt($post, CURLOPT_URL, 'https://api.paymentwall.com/api/coupon');
curl_setopt($post, CURLOPT_POST, 1);
curl_setopt($post, CURLOPT_POSTFIELDS, $params);
$response = curl_exec($post);
echo $response;
?>

Sample Response

{
    "name": "Coupon_1",
    "times_redeemed": 0,
    "max_redemptions": 1,
    "expiration_date": "08\/20\/2017",
    "status": "active",
    "code": "TESTCOUPON_1",
    "currency": null,
    "percent_off": 10,
    "amount_off": null
}

Endpoint

POST https://api.paymentwall.com/api/coupon

Sample Response

{
    "name": "Coupon_1",
    "times_redeemed": 0,
    "max_redemptions": 1,
    "expiration_date": "07\/20\/2017",
    "status": "active",
    "code": "TESTCOUPON_1",
    "currency": null,
    "percent_off": 10,
    "amount_off": null
}

Endpoint

POST https://api.paymentwall.com/api/coupon

Sample Response

{
    "name": "Coupon_1",
    "times_redeemed": 0,
    "max_redemptions": 1,
    "expiration_date": "07\/20\/2017",
    "status": "active",
    "code": "TESTCOUPON_1",
    "currency": null,
    "percent_off": 10,
    "amount_off": null
}

Endpoint

POST https://api.paymentwall.com/api/coupon

Sample Response

{
	"name": "Coupon_1",
	"times_redeemed": 0,
	"max_redemptions": 1,
	"expiration_date": "07\/20\/2017",
	"status": "active",
	"code": "TESTCOUPON_1",
	"currency": null,
	"percent_off": 10,
	"amount_off": null
}

Endpoint

POST https://api.paymentwall.com/api/coupon

Sample Response

{
    "name": "Coupon_1",
    "times_redeemed": 0,
    "max_redemptions": 1,
    "expiration_date": "07\/20\/2017",
    "status": "active",
    "code": "TESTCOUPON_1",
    "currency": null,
    "percent_off": 10,
    "amount_off": null
}

Endpoint

POST https://api.paymentwall.com/api/coupon

Sample Response

{
    "name": "Coupon_1",
    "times_redeemed": 0,
    "max_redemptions": 1,
    "expiration_date": "07\/20\/2017",
    "status": "active",
    "code": "TESTCOUPON_1",
    "currency": null,
    "percent_off": 10,
    "amount_off": null
}

Endpoint

POST https://api.paymentwall.com/api/coupon

Sample Response

{
    "name": "Coupon_1",
    "times_redeemed": 0,
    "max_redemptions": 1,
    "expiration_date": "07\/20\/2017",
    "status": "active",
    "code": "TESTCOUPON_1",
    "currency": null,
    "percent_off": 10,
    "amount_off": null
}

Retrieving information about a coupon

Parameters
Parameter Description
key
required
string
The project key which can be found in Merchant Area→ My Projects.
code
required
string
Eg: TESTCOUPON
Code of coupon
history[registration_date]
required
int
eg: 1484900291
Current UNIX time
sign
required
string
The Request Signature
All parameters must be put into signature calculation.
You MUST use SHA256 for signature algorithm.

Endpoint

GET https://api.paymentwall.com/api/coupon

Sample Response

require_once('path/to/lib/paymentwall.php');
$params = array(
    'key' => 'YOUR_PROJECT_KEY',
    'code' => 'TESTCOUPON_1',
    'timestamp' => time(),
);

Paymentwall_Config::getInstance()->set(array('private_key' => 'YOUR_SECRET_KEY'));
$params['sign'] = (new Paymentwall_Signature_Widget())->calculate(
    $params,
    3 //signature version
);

$url = 'https://api.paymentwall.com/api/coupon?'.http_build_query($params);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER,TRUE);
$response = curl_exec($curl);
echo $response;
?>

Sample Response

{
    "name": "Coupon_1",
    "times_redeemed": 1,
    "max_redemptions": 2,
    "expiration_date": "08\/20\/2017",
    "status": "active",
    "code": "TESTCOUPON_1",
    "currency": null,
    "percent_off": 10,
    "amount_off": null
}

Endpoint

GET https://api.paymentwall.com/api/coupon

Sample Response

{
    "name": "Coupon_1",
    "times_redeemed": 1,
    "max_redemptions": 2,
    "expiration_date": "07\/20\/2017",
    "status": "active",
    "code": "TESTCOUPON_1",
    "currency": null,
    "percent_off": 10,
    "amount_off": null
}

Endpoint

GET https://api.paymentwall.com/api/coupon

Sample Response

{
    "name": "Coupon_1",
    "times_redeemed": 1,
    "max_redemptions": 2,
    "expiration_date": "07\/20\/2017",
    "status": "active",
    "code": "TESTCOUPON_1",
    "currency": null,
    "percent_off": 10,
    "amount_off": null
}

Endpoint

GET https://api.paymentwall.com/api/coupon

Sample Response

{
    "name": "Coupon_1",
    "times_redeemed": 1,
    "max_redemptions": 2,
    "expiration_date": "07\/20\/2017",
    "status": "active",
    "code": "TESTCOUPON_1",
    "currency": null,
    "percent_off": 10,
    "amount_off": null
}

Endpoint

GET https://api.paymentwall.com/api/coupon

Sample Response

{
    "name": "Coupon_1",
    "times_redeemed": 1,
    "max_redemptions": 2,
    "expiration_date": "07\/20\/2017",
    "status": "active",
    "code": "TESTCOUPON_1",
    "currency": null,
    "percent_off": 10,
    "amount_off": null
}

Endpoint

GET https://api.paymentwall.com/api/coupon

Sample Response

{
    "name": "Coupon_1",
    "times_redeemed": 1,
    "max_redemptions": 2,
    "expiration_date": "07\/20\/2017",
    "status": "active",
    "code": "TESTCOUPON_1",
    "currency": null,
    "percent_off": 10,
    "amount_off": null
}

Endpoint

GET https://api.paymentwall.com/api/coupon

Sample Response

{
    "name": "Coupon_1",
    "times_redeemed": 1,
    "max_redemptions": 2,
    "expiration_date": "07\/20\/2017",
    "status": "active",
    "code": "TESTCOUPON_1",
    "currency": null,
    "percent_off": 10,
    "amount_off": null
}

Delivery Confirmation

Delivery Confirmation API allows you to notify Paymentwall about successful delivery of the purchased item(s) to the user. This information helps us resolve dispute cases and refund requests in the fastest and the most efficient manner.

The required parameters are different with the type of your products, refer to digital or physical.


This API expects secret key to be sent as custom HTTPS header “X-ApiKey”.

Endpoint

POST https://api.paymentwall.com/api/delivery

Endpoint

POST https://api.paymentwall.com/api/delivery

Endpoint

POST https://api.paymentwall.com/api/delivery

Endpoint

POST https://api.paymentwall.com/api/delivery

Endpoint

POST https://api.paymentwall.com/api/delivery

Endpoint

POST https://api.paymentwall.com/api/delivery

Endpoint

POST https://api.paymentwall.com/api/delivery

Digital

Parameters
Parameter Description
payment_id
required
string
Paymentwall reference ID of the transaction. It can be obtained from parameter ref in pingback request.
merchant_reference_id
required
string
The order ID of the transaction in your system.
type
required
string
Type of delivery, required to be set as digital.
is_test
integer
Can be either 0 or 1. 1 means test API calls.
status
required
string
Refer to Status.
estimated_delivery_datetime
required
date
Estimated delivery date of the order. Format: 2017/01/15 15:04:55 +0500.
estimated_update_datetime
required
date
When the next status is planned to update. Format: 2017/01/16 15:04:55 +0500.
reason
required
string
Additional description for the status updated. It can be set as null if it is not convenient to provide.
refundable
required
string
Either yes or no. Whether the order is refundable at this stage.
attachments
required
array
Array attachments of the proofs of delivery. URL of pictures is expected. Could be set as null if it is not convenient to provide.
details
required
string
Description of order status which is showed to Paymentwall and recipient.
product_description
string
Description of the new product in case of subsitution or change.
shipping_address[email]
required
string
The email address of your customers.

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');
Paymentwall_Config::getInstance()->set(array(
    'private_key' => '[YOUR_SECRET_KEY]'
));

$delivery = new Paymentwall_GenerericApiObject('delivery');

$response = $delivery->post(array(
    'payment_id' => 'b63400368',
    'merchant_reference_id' => 'order_12345',
    'type' => 'digital',
    'status' => 'delivered',
    'estimated_delivery_datetime' => '2015/01/15 15:00:00 +0300',
    'estimated_update_datetime' => '2015/01/15 11:00:00 +0300',
    'refundable' => true,
    'details' => 'Item was delivered to the user account and via email',
    'shipping_address[email]' => 'user@hostname.com',
    'reason' => 'none',
    'attachments[0]' => '@/usr/local/www/content/proof/b63400368/1.png',
    'attachments[1]' => '@/usr/local/www/content/proof/b63400368/2.png',
));
if (isset($response['success'])) {
    // delivery status is successfully saved
} elseif (isset($response['error'])) {
    var_dump($response['error'], $response['notices']);
}
?>

Sample Response

{
    "success": 1
}

Sample Request

'use strict';
var HttpAction = require('paymentwall/lib/HttpAction'),
    util = require('util'),
    querystring = require('querystring'),
    ApiObject = require('paymentwall/lib/ApiObject'),
    Paymentwall = require('paymentwall');

Paymentwall.Configure(
    Paymentwall.Base.API_GOODS,
    'YOUR_PROJECT_KEY ',
    'YOUR_SECRET_KEY '
);

var api = new ApiObject();
api.createDeliveryRequest = function() {
    var url = this.BRICK_BASE_URL;
    var method = 'POST';
    var post_options = this.createPostOptions(url, '/api/delivery', method);
    return post_options;
};

var post_options = api.createDeliveryRequest();

var post_data = {
    "payment_id" : "b63400368",
    "merchant_reference_id" : "order_12345",
    "type" : "digital",
    "status" : "delivered",
    "estimated_delivery_datetime" : "2018/08/23 15:00:00 +0300",
    "estimated_update_datetime" : "2018/08/23 11:00:00 +0300",
    "refundable" : true,
    "details" : "Item was delivered to the user account and via email",
    "shipping_address[email]" : "user@hostname.com",
    "reason" : "none",
    "attachments" : {}
};

post_data = querystring.stringify(post_data);

HttpAction.runAction(post_options, post_data, true, function(response) {
    response = response.JSON_chunk;
    if(response.success) {
        // delivery status is successfully saved
    } else if(response.error) {
        console.log(response.error);
        console.log(response.notices);
    }
});

Sample Response

{
    "success": 1
}

Sample Request

{
private void sendPost() {

        HttpPost post = new HttpPost("https://api.paymentwall.com/api/delivery");
        post.addHeader("X-ApiKey", "<PROJECT_SECRET_KEY>");

        // add request parameter, form parameters
        List<NameValuePair> urlParameters = new ArrayList<NameValuePair>();
        urlParameters.add(new BasicNameValuePair("payment_id", "b199488072"));
        urlParameters.add(new BasicNameValuePair("merchant_reference_id", "w199488072"));
        urlParameters.add(new BasicNameValuePair("type", "digital"));
        urlParameters.add(new BasicNameValuePair("status", "order_placed"));
        urlParameters.add(new BasicNameValuePair("estimated_delivery_datetime", "2015/01/15 15:00:00 +0300"));
        urlParameters.add(new BasicNameValuePair("estimated_update_datetime", "2015/01/15 11:00:00 +0300"));
        urlParameters.add(new BasicNameValuePair("refundable", "true"));
        urlParameters.add(new BasicNameValuePair("details", "Item was delivered to the user account and via email"));
        urlParameters.add(new BasicNameValuePair("shipping_address[email]", "test@paymentwall.com"));
        urlParameters.add(new BasicNameValuePair("reason", "none"));
        urlParameters.add(new BasicNameValuePair("attachments[0]", "@/usr/local/www/content/proof/b63400368/1.png"));
        urlParameters.add(new BasicNameValuePair("attachments[1]", "@/usr/local/www/content/proof/b63400368/2.png"));

        try {
            post.setEntity(new UrlEncodedFormEntity(urlParameters));
            CloseableHttpClient httpClient = HttpClients.createDefault();
            CloseableHttpResponse response = httpClient.execute(post);
            System.out.println(EntityUtils.toString(response.getEntity()));
        } catch(IOException ex) {
            System.out.println(ex.getMessage());
        }

    }
}

Sample Response

{
    "success": 1
}

Sample Response

{
    "success": 1
}

Sample Response

{
    "success": 1
}

Sample Response

{
    "success": 1
}

Sample Request

curl https://api.paymentwall.com/api/delivery \
-H "X-ApiKey: [YOUR_SECRET_KEY]" \
-d "payment_id=b111260108" \
-d "merchant_reference_id=order_12345" \
-d "type=digital" \
-d "status=started" \
-d "is_test=1" \
-d "estimated_delivery_datetime=2017/01/15 15:04:55 +0500" \
-d "estimated_update_datetime=2017/01/16 15:04:55 +0500" \
-d "refundable=false" \
-d "details=Item was delivered to the user account and via email" \
-d "shipping_address[email]=test@paymentwall.com"
-d "reason=none"

Sample Response

{
    "success": 1
}

Physical

Parameters
Parameter Description
payment_id
required
string
Paymentwall reference ID of the transaction. Can be obtained from parameter ref in pingback request.
merchant_reference_id
required
string
The order ID of the transaction in your system.
type
required
string
Type of delivery, required to be set as physical.
is_test
integer
Can be either 0 or 1. 1 means test API calls.
status
required
string
Refer to Status.
carrier_tracking_id
required
string
Tracking ID provided by the shipping carrier, e.g. 999999999999.
carrier_type
required
string
Name of the shipping carrier, e.g. FedEx.
carrier_tracking_url
string
Tracking URL provided by carrier. required for order_shipped status.
estimated_delivery_datetime
required
date
Estimated delivery date of the order. Format: 2017/01/15 15:04:55 +0500.
estimated_update_datetime
required
date
When the next status update is planned. Format: 2017/01/16 15:04:55 +0500.
reason
required
string
Additional description for the status update. Could be set as null if it is not convenient to provide.
refundable
required
string
Can be either true or false. Whether the order is refundable at this stage.
received_by Initials of the person received the delivery. Required for delivered status.
attachments
required
array
Array attachments of the proofs of delivery. URL of pictures is expected. Could be set as null if it is not convenient to provide.
details
required
string
Description of order status update to be showed to Paymentwall and recipient.
product_description
string
Description of the new product in case of substitution or change.
shipping_address[email]
required
string
The email address of your customers.
shipping_address[country]
required
string
Shipping address country, ISO alpha-2 code.
shipping_address[city]
required
string
Shipping address city.
shipping_address[zip]
required
string
Shipping address zip/postal code.
shipping_address[state]
required
string
Shipping address state or province.
shipping_address[street]
required
string
Shipping address street.
shipping_address[phone]
required
string
Phone number of the recipient.
shipping_address[firstname]
required
string
Firstname of the recipient.
shipping_address[lastname]
required
string
Lastname of the recipient.
recipient_feedback Freeform data about user satisfaction.

Status

For physical delivery, Paymentwall requires the following statuses to be communicated via the Delivery Confirmation API:

  • order_placed
  • package_prepared
  • delivering
  • delivered

Merchants are encouraged to send all other applicable statuses. This will keep the end-users and our support and risk teams informed of the actual status of the order and improve the user experience.

Possible values
Name Description
order_placed Order has been placed within merchants system.
This status should be sent immediately after receiving a pingback.
order_preparing Merchant started to look for ordered item in stock, processing the order.
package_prepared Merchant has prepared the package and it’s waiting to be shipped. The tracking ID is known at this point.
order_shipped Item is being delivered, e.g. it has been shipped.(Previously named as delivering)
out_for_delivery The delivery has been started. (Previously named as started)
delivered Item has been delivered to the end-user. Attachment of delivery proof is expected in this case.
consumed Item is consumed by the end-user. Eg: activation keys, in-game virtual currency.
waiting_user_action User’s action is requested to complete the delivery. Eg: check the item or pick it up.
delayed Delay in delivery.
Parameter reason is required to specify the cause.
failed_will_retry Delivery to end user failed. Waiting for retry.
order_cancelled Order has been cancelled, waiting for refund or substitution.
Parameter reason is required to specify the cause. Eg: out of stock
retry_started Attempt to retry on delivery.
refund_requested End user made a refund request on the order.
refund_request_declined Merchant decline request to refund.
Parameter reason is required to specify the cause.
refund_request_accepted Order will be refunded.
Details parameter should include refund information.
refund_issued The original payment has been refunded.
Details parameter should include refund information.
A call to Cancellation API is needed for the refund of original payment.
cancelled_subscription Cancel Subscription.
substitution_requested Changes need to be made to the order after paid.
Parameter reason is required to specify the cause.
substitution_accepted Changes have been accepted by merchant. Subsequent changes in the status - started or order_preparing are expected.
substitution_declined Changes have been declined by the merchant.
Parameter reason is required to specify the cause.

Payment Status

This API allows you to check the status of a payment via payment reference ID.

Parameters
Name Description
key
required
string
The project key which can be found in Merchant Area→ My Projects.
ref
required
string
Payment reference ID.
Can be obtained from parameter ref in pingback request.
uid
string
ID of end-users in your system
ag_external_id
string
It can be obtained from parameter goodsid in pingback request.
sign_version
required
integer
Signature version
Version 2 employs MD5 and version 3 uses SHA256.
sign
required
string
The request signature.
Refer to Signature Calculation for more details

Parameter ref is not required if you have submitted uid and ag_external_id for transactions in live environment.

Endpoint

GET https://api.paymentwall.com/api/rest/payment

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');

$params = array(
    'key' => 'YOUR_PROJECT_KEY',
    'ref' => 'b123456789',
    'uid' => 'user40012',
    'callback' => 'paymentStatusHandler',
    'sign_version' => 2
);

Paymentwall_Config::getInstance()->set(array('private_key' => 'YOUR_SECRET_KEY'));
$params['sign'] = (new Paymentwall_Signature_Widget())->calculate(
    $params,
    $params['sign_version']
);

$url = 'https://api.paymentwall.com/api/rest/payment/?'.http_build_query($params);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
$response = curl_exec($curl); 
echo $response;
?>

Sample Response:

[{
  "object":"payment",
  "id":"b123456",
  "created":1419438832,
  "amount":"9.99",
  "currency":"USD",
  "refunded":false,
  "risk":"approved",
  "uid":"user_200255",
  "product_id":"product_100244",
  "payment_system":"cc",
  "subscription":{
    "object":"subscription",
    "id":"VCBZT392SW",
    "period":"day",
    "period_duration":3,
    "payments_limit":122,
    "is_trial":0,
    "started":1,
    "expired":0, // if user's access to premium features has expired after, e.g. if he cancelled it last month and the next payment is already due, or if subscription total duration limitation is 1 year and the subscription is past 1 year
    "active":1,
    "date_started":1419438832,
    "date_next":1419698032
  }
}]

Endpoint

GET https://api.paymentwall.com/api/rest/payment

Sample Response

[{
  "object":"payment",
  "id":"b123456",
  "created":1419438832,
  "amount":"9.99",
  "currency":"USD",
  "refunded":false,
  "risk":"approved",
  "uid":"user_200255",
  "product_id":"product_100244",
  "payment_system":"cc",
  "subscription":{
    "object":"subscription",
    "id":"VCBZT392SW",
    "period":"day",
    "period_duration":3,
    "payments_limit":122,
    "is_trial":0,
    "started":1,
    "expired":0, // if user's access to premium features has expired after, e.g. if he cancelled it last month and the next payment is already due, or if subscription total duration limitation is 1 year and the subscription is past 1 year
    "active":1,
    "date_started":1419438832,
    "date_next":1419698032
  }
}]

Endpoint

GET https://api.paymentwall.com/api/rest/payment

Sample Response

[{
  "object":"payment",
  "id":"b123456",
  "created":1419438832,
  "amount":"9.99",
  "currency":"USD",
  "refunded":false,
  "risk":"approved",
  "uid":"user_200255",
  "product_id":"product_100244",
  "payment_system":"cc",
  "subscription":{
    "object":"subscription",
    "id":"VCBZT392SW",
    "period":"day",
    "period_duration":3,
    "payments_limit":122,
    "is_trial":0,
    "started":1,
    "expired":0, // if user's access to premium features has expired after, e.g. if he cancelled it last month and the next payment is already due, or if subscription total duration limitation is 1 year and the subscription is past 1 year
    "active":1,
    "date_started":1419438832,
    "date_next":1419698032
  }
}]

Endpoint

GET https://api.paymentwall.com/api/rest/payment

Sample Response

[{
  "object":"payment",
  "id":"b123456",
  "created":1419438832,
  "amount":"9.99",
  "currency":"USD",
  "refunded":false,
  "risk":"approved",
  "uid":"user_200255",
  "product_id":"product_100244",
  "payment_system":"cc",
  "subscription":{
    "object":"subscription",
    "id":"VCBZT392SW",
    "period":"day",
    "period_duration":3,
    "payments_limit":122,
    "is_trial":0,
    "started":1,
    "expired":0, // if user's access to premium features has expired after, e.g. if he cancelled it last month and the next payment is already due, or if subscription total duration limitation is 1 year and the subscription is past 1 year
    "active":1,
    "date_started":1419438832,
    "date_next":1419698032
  }
}]

Endpoint

GET https://api.paymentwall.com/api/rest/payment

Sample Response

[{
  "object":"payment",
  "id":"b123456",
  "created":1419438832,
  "amount":"9.99",
  "currency":"USD",
  "refunded":false,
  "risk":"approved",
  "uid":"user_200255",
  "product_id":"product_100244",
  "payment_system":"cc",
  "subscription":{
    "object":"subscription",
    "id":"VCBZT392SW",
    "period":"day",
    "period_duration":3,
    "payments_limit":122,
    "is_trial":0,
    "started":1,
    "expired":0, // if user's access to premium features has expired after, e.g. if he cancelled it last month and the next payment is already due, or if subscription total duration limitation is 1 year and the subscription is past 1 year
    "active":1,
    "date_started":1419438832,
    "date_next":1419698032
  }
}]

Endpoint

GET https://api.paymentwall.com/api/rest/payment

Sample Response

[{
  "object":"payment",
  "id":"b123456",
  "created":1419438832,
  "amount":"9.99",
  "currency":"USD",
  "refunded":false,
  "risk":"approved",
  "uid":"user_200255",
  "product_id":"product_100244",
  "payment_system":"cc",
  "subscription":{
    "object":"subscription",
    "id":"VCBZT392SW",
    "period":"day",
    "period_duration":3,
    "payments_limit":122,
    "is_trial":0,
    "started":1,
    "expired":0, // if user's access to premium features has expired after, e.g. if he cancelled it last month and the next payment is already due, or if subscription total duration limitation is 1 year and the subscription is past 1 year
    "active":1,
    "date_started":1419438832,
    "date_next":1419698032
  }
}]

Endpoint

GET https://api.paymentwall.com/api/rest/payment

Sample Request

curl https://api.paymentwall.com/api/rest/payment \
-d "key=[YOUR_PROJECT_KEY]" \
-d "ref=t1234" \
-d "sign_version=2" \
-d "sign=[SIGNATURE]" \

Sample Response

[{
  "object":"payment",
  "id":"b123456",
  "created":1419438832,
  "amount":"9.99",
  "currency":"USD",
  "refunded":false,
  "risk":"approved",
  "uid":"user_200255",
  "product_id":"product_100244",
  "payment_system":"cc",
  "subscription":{
    "object":"subscription",
    "id":"VCBZT392SW",
    "period":"day",
    "period_duration":3,
    "payments_limit":122,
    "is_trial":0,
    "started":1,
    "expired":0, // if user's access to premium features has expired after, e.g. if he cancelled it last month and the next payment is already due, or if subscription total duration limitation is 1 year and the subscription is past 1 year
    "active":1,
    "date_started":1419438832,
    "date_next":1419698032
  }
}]

Payment Systems

Payment system API can retrieve the list of payment systems activated for a project in a specific country along with their names, logos and short codes.

Parameters
Name Description
country_code
required
string
Country code.
ISO 3166-1 alpha-2 code of the country.
currency_converted
string
Currency code of your product.
Format by ISO 4217. 3 letters.
include_pricepoints
string
1 or 0 to include pricepoints for Mobiamo.
key
required
string
The project key which can be found in Merchant Area→ My Projects.
sign_version
required
integer
Signature version. Version 2 uses MD5 and version 3 represents SHA256.
sign
required
string
The signature of widget.
Refer to signature calculation for more details.
img_size
string
Size of the logo, if you need a @2x or @3x size. Possible values: @2x, @3x.
img_mode
string
Mode of the logo, dark mode can be used for dark backgrounds. Possible values: dark, light.
amount
double
If amount and currencyCode are passed, the API will only return payment systems that support this price in this country. For example, 500 EUR is not a supported price for Mobiamo in Germany.
currencyCode
string
Currency code of your product. Format by ISO 4217. 3 letters.

Payment system response

Attributes
Name Description
id The payment system short code, ps, could be used as optional parameter.
name Payment system name.
new_window Payment methods require opening a new window or redirecting users to a new url.
img_url URL of the payment system logo.
img_class The class of image. Can be ignored as it doesn’t have any usage.
ps_type_id The payment method category of payment system.
1 - Credit cards. 2 - Bank transfer. 3 - Prepaid cards. 4 - E-wallet. 5 - Mobile payment.

Endpoint

GET https://api.paymentwall.com/api/payment-systems/

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');

$params = array(
    'key' => 'YOUR_PROJECT_KEY',
    'country_code' => 'US',
    'sign_version' => 2
);

Paymentwall_Config::getInstance()->set(array('private_key' => 'YOUR_SECRET_KEY'));
$params['sign'] = (new Paymentwall_Signature_Widget())->calculate(
    $params,
    $params['sign_version']
);

$url = 'https://api.paymentwall.com/api/payment-systems/?'.http_build_query($params);
$curl = curl_init($url);
curl_setopt($curl,CURLOPT_RETURNTRANSFER,TRUE);
$response = curl_exec($curl);
echo $response;
?>

Sample Response:

[
    {
        "id":"paypal",
        "name":"PayPal",
        "new_window":true,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_paypal.png",
        "img_class":"paypal",
        "ps_type_id":4
    },
    {
        "id":"alipay",
        "name":"AliPay",
        "new_window":true,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_alipay.png",
        "img_class":"alipay",
        "ps_type_id":4
    },
    {
        "id":"neosurf",
        "name":"Neosurf",
        "new_window":false,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_neosurf.png",
        "img_class":"neosurf",
        "ps_type_id":3
    },
    {
        "id":"mobiamo",
        "name":"Mobiamo",
        "new_window":false,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_mobiamo.png",
        "img_class":"mobiamo",
        "ps_type_id":5
    },
    {
        "id":"mint",
        "name":"MINT",
        "new_window":false,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_mint.png",
        "img_class":"mint",
        "ps_type_id":3
    }
]

Endpoint

GET https://api.paymentwall.com/api/payment-systems/

Sample Response

[
    {
        "id":"paypal",
        "name":"PayPal",
        "new_window":true,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_paypal.png",
        "img_class":"paypal",
        "ps_type_id":4
    },
    {
        "id":"alipay",
        "name":"AliPay",
        "new_window":true,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_alipay.png",
        "img_class":"alipay",
        "ps_type_id":4
    },
    {
        "id":"neosurf",
        "name":"Neosurf",
        "new_window":false,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_neosurf.png",
        "img_class":"neosurf",
        "ps_type_id":3
    },
    {
        "id":"mobiamo",
        "name":"Mobiamo",
        "new_window":false,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_mobiamo.png",
        "img_class":"mobiamo",
        "ps_type_id":5
    },
    {
        "id":"mint",
        "name":"MINT",
        "new_window":false,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_mint.png",
        "img_class":"mint",
        "ps_type_id":3
    }
]

Endpoint

GET https://api.paymentwall.com/api/payment-systems/

Sample Response

[
    {
        "id":"paypal",
        "name":"PayPal",
        "new_window":true,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_paypal.png",
        "img_class":"paypal",
        "ps_type_id":4
     },
     {
        "id":"alipay",
        "name":"AliPay",
        "new_window":true,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_alipay.png",
        "img_class":"alipay",
        "ps_type_id":4
     },
     {
        "id":"neosurf",
        "name":"Neosurf",
        "new_window":false,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_neosurf.png",
        "img_class":"neosurf",
        "ps_type_id":3
     },
     {
        "id":"mobiamo",
        "name":"Mobiamo",
        "new_window":false,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_mobiamo.png",
        "img_class":"mobiamo",
        "ps_type_id":5
     },
     {
        "id":"mint",
        "name":"MINT",
        "new_window":false,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_mint.png",
        "img_class":"mint",
        "ps_type_id":3
     }
]

Endpoint

GET https://api.paymentwall.com/api/payment-systems/

Sample Response

[
    {
        "id":"paypal",
        "name":"PayPal",
        "new_window":true,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_paypal.png",
        "img_class":"paypal",
        "ps_type_id":4
    },
    {
        "id":"alipay",
        "name":"AliPay",
        "new_window":true,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_alipay.png",
        "img_class":"alipay",
        "ps_type_id":4
    },
    {
        "id":"neosurf",
        "name":"Neosurf",
        "new_window":false,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_neosurf.png",
        "img_class":"neosurf",
        "ps_type_id":3
    },
    {
        "id":"mobiamo",
        "name":"Mobiamo",
        "new_window":false,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_mobiamo.png",
        "img_class":"mobiamo",
        "ps_type_id":5
    },
    {
        "id":"mint",
        "name":"MINT",
        "new_window":false,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_mint.png",
        "img_class":"mint",
        "ps_type_id":3
    }
]

Endpoint

GET https://api.paymentwall.com/api/payment-systems/

Sample Response

[
    {
        "id":"paypal",
        "name":"PayPal",
        "new_window":true,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_paypal.png",
        "img_class":"paypal",
        "ps_type_id":4
    },
    {
        "id":"alipay",
        "name":"AliPay",
        "new_window":true,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_alipay.png",
        "img_class":"alipay",
        "ps_type_id":4
    },
    {
        "id":"neosurf",
        "name":"Neosurf",
        "new_window":false,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_neosurf.png",
        "img_class":"neosurf",
        "ps_type_id":3
    },
    {
        "id":"mobiamo",
        "name":"Mobiamo",
        "new_window":false,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_mobiamo.png",
        "img_class":"mobiamo",
        "ps_type_id":5
    },
    {
        "id":"mint",
        "name":"MINT",
        "new_window":false,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_mint.png",
        "img_class":"mint",
        "ps_type_id":3
    }
]

Endpoint

GET https://api.paymentwall.com/api/payment-systems/

Sample Response

[
    {
        "id":"paypal",
        "name":"PayPal",
        "new_window":true,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_paypal.png",
        "img_class":"paypal",
        "ps_type_id":4
    },
    {
        "id":"alipay",
        "name":"AliPay",
        "new_window":true,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_alipay.png",
        "img_class":"alipay",
        "ps_type_id":4
    },
    {
        "id":"neosurf",
        "name":"Neosurf",
        "new_window":false,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_neosurf.png",
        "img_class":"neosurf",
        "ps_type_id":3
    },
    {
        "id":"mobiamo",
        "name":"Mobiamo",
        "new_window":false,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_mobiamo.png",
        "img_class":"mobiamo",
        "ps_type_id":5
    },
    {
        "id":"mint",
        "name":"MINT",
        "new_window":false,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_mint.png",
        "img_class":"mint",
        "ps_type_id":3
    }
]

Endpoint

GET https://api.paymentwall.com/api/payment-systems/

Sample Request

curl https://api.paymentwall.com/api/payment-systems/ \
-d "key=[YOUR_PROJECT_KEY]" \
-d "country_code=RU" \
-d "sign_version=2" \
-d "sign=[SIGNATURE]" \

Sample Response:

[
    {
        "id":"paypal",
        "name":"PayPal",
        "new_window":true,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_paypal.png",
        "img_class":"paypal",
        "ps_type_id":4
    },
    {
        "id":"alipay",
        "name":"AliPay",
        "new_window":true,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_alipay.png",
        "img_class":"alipay",
        "ps_type_id":4
    },
    {
        "id":"neosurf",
        "name":"Neosurf",
        "new_window":false,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_neosurf.png",
        "img_class":"neosurf",
        "ps_type_id":3
    },
    {
        "id":"mobiamo",
        "name":"Mobiamo",
        "new_window":false,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_mobiamo.png",
        "img_class":"mobiamo",
        "ps_type_id":5
    },
    {
        "id":"mint",
        "name":"MINT",
        "new_window":false,
        "img_url":"https:\/\/api.paymentwall.com\/images\/ps_logos\/pm_mint.png",
        "img_class":"mint",
        "ps_type_id":3
    }
]

Product Details

You can update the information of a product that is stored under Products Section in Paymentwall merchant dashboard by using this API.

Parameters
Name Description
key
required
string
The project key which can be found in Merchant Area→ My Projects.
ag_external_id
required
string
Product SKU ID.
Set up under Products Section in your Merchant Account. It is also passed as goodsid in pingback request.
country_code
string
Country code in ISO 3166-1 alpha-2 format.
It is determined by user IP by default.
sign_version
required
int
eg: 2, 3
Signature version
Version 2 uses MD5 and version 3 uses SHA256.
sign
required
string
The request signature.
Refer to Signature Calculation for more details

Endpoint

GET https://api.paymentwall.com/api/rest/product/

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');

$params = array(
    'key'=>'YOUR_PROJECT_KEY',
    'ag_external_id'=>'product101',
    'country_code'=>'US',
    'callback'=>'productDetailsHandler',
    'sign_version'=>2
);

Paymentwall_Config::getInstance()->set(array('private_key' => 'YOUR_SECRET_KEY'));
$params['sign'] = (new Paymentwall_Signature_Widget())->calculate(
    $params,
    $params['sign_version']
);

$url = 'https://api.paymentwall.com/api/rest/product/?'.http_build_query($params);
$curl = curl_init($url);
curl_setopt($curl,CURLOPT_RETURNTRANSFER,TRUE);
$response = curl_exec($curl);
echo $response;
?>

Sample Response

{
    "object":"product",
    "id":"T20170101",
    "name":"testproduct",
    "amount":"9.99",
    "currency":"USD",
    "order":2,
    "best_value":0,
    "most_popular":0,
    "is_default":0,
    "type":"fixed",
    "show_discount":0,
    "old_price":"19.99",
    "product_description":"",
    "custom_fields":"",
    "slug":"testproduct",
    "product_pic_url":"",
    "promotion":""
}

Endpoint

GET https://api.paymentwall.com/api/rest/product/

Sample Response

{
    "object":"product",
    "id":"T20170101",
    "name":"testproduct",
    "amount":"9.99",
    "currency":"USD",
    "order":2,
    "best_value":0,
    "most_popular":0,
    "is_default":0,
    "type":"fixed",
    "show_discount":0,
    "old_price":"19.99",
    "product_description":"",
    "custom_fields":"",
    "slug":"testproduct",
    "product_pic_url":"",
    "promotion":""
}

Endpoint

GET https://api.paymentwall.com/api/rest/product/

Sample Response

{
    "object":"product",
    "id":"T20170101",
    "name":"testproduct",
    "amount":"9.99",
    "currency":"USD",
    "order":2,
    "best_value":0,
    "most_popular":0,
    "is_default":0,
    "type":"fixed",
    "show_discount":0,
    "old_price":"19.99",
    "product_description":"",
    "custom_fields":"",
    "slug":"testproduct",
    "product_pic_url":"",
    "promotion":""
}

Endpoint

GET https://api.paymentwall.com/api/rest/product/

Sample Response

{
    "object":"product",
    "id":"T20170101",
    "name":"testproduct",
    "amount":"9.99",
    "currency":"USD",
    "order":2,
    "best_value":0,
    "most_popular":0,
    "is_default":0,
    "type":"fixed",
    "show_discount":0,
    "old_price":"19.99",
    "product_description":"",
    "custom_fields":"",
    "slug":"testproduct",
    "product_pic_url":"",
    "promotion":""
}

Endpoint

GET https://api.paymentwall.com/api/rest/product/

Sample Response

{
    "object":"product",
    "id":"T20170101",
    "name":"testproduct",
    "amount":"9.99",
    "currency":"USD",
    "order":2,
    "best_value":0,
    "most_popular":0,
    "is_default":0,
    "type":"fixed",
    "show_discount":0,
    "old_price":"19.99",
    "product_description":"",
    "custom_fields":"",
    "slug":"testproduct",
    "product_pic_url":"",
    "promotion":""
}

Endpoint

GET https://api.paymentwall.com/api/rest/product/

Sample Response

{
    "object":"product",
    "id":"T20170101",
    "name":"testproduct",
    "amount":"9.99",
    "currency":"USD",
    "order":2,
    "best_value":0,
    "most_popular":0,
    "is_default":0,
    "type":"fixed",
    "show_discount":0,
    "old_price":"19.99",
    "product_description":"",
    "custom_fields":"",
    "slug":"testproduct",
    "product_pic_url":"",
    "promotion":""
}

Endpoint

GET https://api.paymentwall.com/api/rest/product/

Sample Request

curl https://api.paymentwall.com/api/rest/product \
-d "key=[YOUR_PROJECT_KEY]" \
-d "ag_external_id=product_100244" \
-d "sign_version=2" \
-d "sign=[SIGNATURE]" \

Sample Response

{
    "object":"product",
    "id":"T20170101",
    "name":"testproduct",
    "amount":"9.99",
    "currency":"USD",
    "order":2,
    "best_value":0,
    "most_popular":0,
    "is_default":0,
    "type":"fixed",
    "show_discount":0,
    "old_price":"19.99",
    "product_description":"",
    "custom_fields":"",
    "slug":"testproduct",
    "product_pic_url":"",
    "promotion":""
}

Geolocation

You can use this API call for client-side or server-side detection of user’s location. This API also works tightly with Paymentwall Risk Scoring.

Parameters
Name Description
key
required
string
The project key which can be found in Merchant Area→ My Projects. Project status should be LIVE to use this API.
uid
required
string
User’s id.
User’s account id used in your system.
user_ip
string
E.g. 255.255.255.255
IP address of the user.
callback
string
Callback function. Can be used for JSON on client side.

Endpoint

GET https://api.paymentwall.com/api/rest/country

Sample Request

require_once('path/to/lib/paymentwall.php');
$params = array(
    'key' => 'YOUR_PROJECT_KEY',
    'uid' => 'user101',
    'user_ip' => '192.168.1.101'
);

$url = 'https://api.paymentwall.com/api/rest/country?' .http_build_query($params);
$curl = curl_init($url);
curl_setopt($curl,CURLOPT_RETURNTRANSFER, TRUE);
$response = curl_exec($curl);
echo $response;
?>

Sample Response

{
    "code":"US",
    "country":"United States"
}

Sample Response when callback parameter is present

callbackFunction({
    "code":"US",
        "country":"United States"
})

Endpoint

GET https://api.paymentwall.com/api/rest/country

Sample Response

{
    "code":"US",
    "country":"United States"
}

Endpoint

GET https://api.paymentwall.com/api/rest/country

Sample Response

{
    "code":"US",
    "country":"United States"
}

Endpoint

GET https://api.paymentwall.com/api/rest/country

Sample Response

{
    "code":"US",
    "country":"United States"
}

Endpoint

GET https://api.paymentwall.com/api/rest/country

Sample Response

{
    "code":"US",
    "country":"United States"
}

Endpoint

GET https://api.paymentwall.com/api/rest/country

Sample Response

{
    "code":"US",
    "country":"United States"
}

Endpoint

GET https://api.paymentwall.com/api/rest/country

Sample Request

curl https://api.paymentwall.com/api/rest/country \
> -d "key=[YOUR_PROJECT_KEY]" \
> -d "uid=[USER_ID]" \

Sample Response

{
    "code":"US",
    "country":"United States"
}

Receipt

This API allows to pull receipt of each click.

Parameters
Parameter Description
key
required
string
The project key which can be found in Merchant Area→ My Projects.
ref
required
string
Payment reference ID.
Can be obtained from parameter ref in pingback request.
type
required
integer
Type of the receipt:
0. Payment
2. Refund
format
required
string
Format of the receipt:
html
pdf
download
integer
When format is pdf, you can choose either download or not by passing 0/1.
string
integer
Accepts 1 when format is pdf and download is 0 to receive content as string.
sign_version
required
integer
Signature version
Version 2 employs MD5 and version 3 uses SHA256.
sign
required
string lowercase
The request signature. Refer to Signature Calculation for more details.

Endpoint

GET https://api.paymentwall.com/api/rest/receipt

Sample Request

<?php
require_once('path/to/lib/paymentwall.php');

$params = array(
    'key' => 'YOUR_PROJECT_KEY',
    'ref' => '123456789',
    'type' => '0',
    'format' => 'html',
    'sign_version' => 2
);

Paymentwall_Config::getInstance()->set(array('private_key' => 'YOUR_SECRET_KEY'));
$params['sign'] = (new Paymentwall_Signature_Widget())->calculate(
    $params,
    $params['sign_version']
);

$url = 'https://api.paymentwall.com/api/rest/receipt/?'.http_build_query($params);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
$response = curl_exec($curl); 
echo $response;

Sample Response

{ "body":"<!DOCTYPE html>.....<\/html>", "type":"html" }

Sample Error Response:

{ "type":"Error", "object": Error", "error": "Request signature is invalid", "code": 4009 }