Documentation
Coupons API
API Description
Coupon API allows merchants to create coupons for discounts / promotions / special offers.
This API is activated by request. To activate it please email us at devsupport@paymentwall.com
API URL
https://api.paymentwall.com/api/coupon
Creating a Coupon
Request Method
POST
Protocols supported
HTTP, HTTPS
Request Parameters
| Parameter | Required | Possible values | Description |
|---|---|---|---|
| key | yes | hexadecimal, 32 characters long | Project key, located in your Merchant Account - Project Settings |
| history[registration_date] | yes | numeric, Unix timestamp | Time when request was initiated, represented as Unix timestamp. If more than 60 minutes pass after a request, user sees an error message. Recommended for preventing widget from being shared. |
| sign | yes | hexadecimal, 32 characters long, lowercase | Request signature. All parameters need to be signed. Please refer to the Signature Calculation section below. |
| percent_off | yes* | 1-99 | Discount percentage. |
| amount_off | yes* | numeric | Discount amount. |
| currency_code | yes* | ISO 4217 | Discount currency. |
| name | no | alphanumeric, up to 256 characters long | Coupon name, default value is 'null'. |
| number_of_coupons | no | numeric | Number of coupons to be created with the same properties (if 'code' parameter is provided, the next 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). Default value: 1. |
| code | no | alphanumeric, up to 256 characters long | If 'number_of_coupons' equals 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 | no | alphanumeric, up to 256 characters long | Activating coupon after creating. |
| available_applications | no | any | If this parameter is not included, the coupon will only be created for the specified project key. If 'available_projects' parameter is included, the coupon will be created for all projects under your Merchant Account. |
| max_redemptions | no | numeric | How many times the coupon can be redeemed. |
| expiration_date | no | numeric, Unix timestamp | Coupon expiration date. |
*Either 'percent_off' or 'amount_off' should be included in the request ('currency_code' parameter is required if you are using 'amount_off').
Retrieving information about a coupon
Request Method
GET
Protocols supported
HTTP, HTTPS
Parameters
| Parameter | Required | Possible values | Description |
|---|---|---|---|
| key | yes | hexadecimal, 32 characters long | Project key, located in your Merchant Account - Project Settings |
| code | yes | alphanumeric, up to 256 characters long | Coupon code(s). |
| history[registration_date] | yes | numeric, Unix timestamp | Time when request was initiated, represented as Unix timestamp. If more than 60 minutes pass after a request, user sees an error message. Recommended for preventing widget from being shared. |
| sign | yes | hexadecimal, 32 characters long, lowercase | Request signature. All parameters need to be signed. Please refer to the Signature Calculation section below. |
Sample Response
Response format is similar both when you create a new coupon and when you retreive information about an existing one.
{
"name" :["test_coupon1", "test_coupon2"]
"times_redeemed" : "2",
"max_redemptions" : "3",
"expiration_date" : "1395075196",
"status" : "active",
"code" : ["test_12", "test23"]
"currency" : "EUR",
"amount_off" : "1",
}Signature Calculation
sign = SHA256([PARAM_NAME_1]=[PARAM_VALUE_1][PARAM_NAME_2]=[PARAM_VALUE_2][PARAM_NAME_3]=[PARAM_VALUE_3]...[SECRET_KEY])
SHA256 (Secure Hash Algorithm 2) lowercase hash in form of 62 digit hexadecimal number.
Hint for flash developers: if you have a flash project, don't store SECRET_KEY in it, since flash can be decompiled and your SECRET_KEY might become available to fraudsters. Instead, we kindly reccommend you to calculate signature in server script and pass it to flash via parameter.
[SECRET_KEY] - The secret key of your project.
Please note that additional parameters (e.g. [PARAM_NAME_1]=[PARAM_VALUE_1][PARAM_NAME_2]=[PARAM_VALUE_2]) are supposed to be sorted alphabetically by parameter name.
Example (calculating signature using PHP):
function calculateWidgetSignature($params, $secret) {
// work with sorted data
ksort($params);
// generate the base string
$baseString = '';
foreach($params as $key => $value) {
$baseString .= $key . '=' . $value;
}
$baseString .= $secret;
return hash('sha256',$baseString);
}
$params = array(
'key' => 'test_f9088da998ff21613dc7db38b67',
'uid' => '123456',
'widget' => 'p1',
'sign_version' => 3
);
$secret = 'b3842906095a44c6b538e8571dacc990';
$signature = calculateWidgetSignature($params, $secret);
