Documentation
Cart API
Paymentwall Widget Call
Default Widget Call
https://api.paymentwall.com/api/cart
GET
HTTP, HTTPS
| Parameter | Description | Example |
|---|---|---|
| key | project key, can be found in Project Settings | key=015d82e056695f030120198742e7a1d5 |
| uid | Unique ID of the end-user in your system (usually it is an email). Please note that uid parameter is case-insensitive (e.g. JohnDoe and johndoe are considered the same user). If your project allows case sensitive usernames, please use a numeric ID for the uid parameter |
uid=SomeUserNameOrEmailOrId |
| widget | widget type code. Currently only p1 (or customized) widget is supported | widget=p1_1 |
| external_ids | array of product IDs which can be set up in Products section, indexed. For multiple products with the same ID just repeat it in call | external_ids[0]=product_1&external_ids[1]=product_1&external_ids[2]=product_1&external_ids[3]=some_other_product |
| end-user's email, where the notification should be sent | email=addr@domain.com |
| Parameter | Description | Example |
|---|---|---|
| prices | prices of goods, indexed, in case you want to redefine prices for current widget call (e.g. in case of some discounts). Should be the same for products with same id | prices[0]=10&prices[1]=12.99 |
| currencies | currencies of prices, required only with prices, indexed. Should be the same for multiple products with the same id | currencies[0]=USD¤cies[1]=EUR |
| evaluation | if equals 1, widget can be loaded even until the project status is Live without being logged into the merchant account in the same browser session. Requires version 2 widget signature to be used | evaluation=1 |
| User Profile API parameters | Parameters for enhanced Risk Scoring, such as lastname, firstname, address, birthday, engagement history. Refer to User Profile API | |
| sign | widget signature. Required if custom prices are used | sign=617aed7f7cdee55f5b55ea226915c18c |
| sign_version | version of signature algorithm used to calculate sign. For this API always equals 2 | sign_version=2 |
| pingback_url | URL of pingback listener script where pingbacks should be sent. Takes effect only if activated for the merchant account per request. Requires widget call to be signed with signature version 2 | pingback_url=http://www.mysite.com/pingback.php |
Example using Paymentwall PHP Library at GitHub.
For more code samples in different programming languages, please visit https://www.paymentwall.com/en/documentation/getting-started/
require_once('/path/to/paymentwall-php/lib/paymentwall.php');
Paymentwall_Base::setApiType(Paymentwall_Base::API_CART);
Paymentwall_Base::setAppKey('YOUR_PROJECT_KEY'); // available in your Paymentwall merchant area
Paymentwall_Base::setSecretKey('YOUR_SECRET_KEY'); // available in your Paymentwall merchant area
$widget = new Paymentwall_Widget(
'user40012', // id of the end-user who's making the payment
'p1_1', // widget code, e.g. p1; can be picked inside of your merchant account,
array(
new Paymentwall_Product('product301', 3.33, 'EUR'), // first product in cart
new Paymentwall_Product('product607', 7.77, 'EUR') // second product in cart
),
array('email' => 'user@hostname.com') // additional params
);
echo $widget->getHtmlCode();
The example above will output an iframe with the following source:
https://api.paymentwall.com/api/cart?key=[PROJECT_KEY]&uid=user40012&widget=p1_1&external_ids%5B0%5D=product301&prices%5B0%5D=3.33&external_ids%5B1%5D=product607&prices%5B1%5D=7.77&sign_version=2&sign=[SIGNATURE_v_2]
Pingback Processing
Whenever a user pays, we send you a pingback, also known as callback, postback, or instant payment notification.
Pingbacks can be sent in one of the two formats:
| Type | Description |
|---|---|
| HTTP Request | HTTP request is sent from our servers to your Pingback listener script where we communicate to your server details about the payment so that your server can process the pingback automatically and deliver the virtual currency to the according user. URL of your script that listens for pingbacks is called Pingback URL. This format is preferable. |
| An email is sent to the address that you configure as your Pingback Email once a user pays or completes an offer. Once you receive the email, you should deliver the product manually to the according user. |
http://www.yourserver.com/anypath?uid=[USER_ID]&sign_version=2&goodsid[]=[GOODS_IDS_ARRAY]&type=[TYPE]&ref=[REF]&sig=[SIGNATURE]
GET
HTTP, HTTPS
| Parameter | Description |
|---|---|
| uid | ID of the end-user in your system who paid. The value of uid parameter from Paymentwall Call is used (e.g. Facebook Third-Party ID) |
| goodsid | array of ids of products set up in the Products section, alphanumeric, e.g. gold_membership, indexed |
| type | type of callback. 0 - when product is bought, 1 - when product is given as a customer service courtesy (write-off), 2 - in case of chargeback (see below) |
| ref | reference id, alphanumeric |
| sig | Signature. For detailed info on signature calculation please refer to Signature Calculation documentation. |
| sign_version | Pingback signature version |
| is_test | value defined as 1 if the payment is done via Test Payment method, or if the pingback is sent via Test Pingback Tool. Otherwise this parameter is not present in the request. |
- uid = 12345123333
- goodsid[0] = item_1
- goodsid[1] = item_2
- goodsid[2] = item_3
- goodsid[3] = item_4
- type = 0
- ref = b3443554
- sign_version = 2
- sig = 4dc33234bd9cccbb700f59be67ce2b68
http://www.yourserver.com/anypath?uid=12345123333&goodsid[0]=item_1&goodsid[1]=item_2&goodsid[2]=item_3&goodsid[3]=item_4&type=0&ref=b3443554&sig=a66842a31bab12e1bf207d8f5641d076
If you are able to process the callback requests, please start your response message with 'OK'. If we don't receive a confirmation message, or if the response status code is different from 200, we'll send pingback again within 30 minutes and the subsequent retries will happen at 30 minute increments after that.
Please add the following IP Addresses as authorized IP addresses to access the script:
- 174.36.92.186
- 174.36.92.187
- 174.36.92.192
- 174.36.96.66
- 174.37.14.28
Please note that certain load balancing services, such as CloudFlare, may alter the originating IP of the request. In such case, the IP address of the request visible on your server may different from original IP address. In this case, using HTTP_X_REAL_IP request header should help getting the original Paymentwall's IP to check if it is whitelisted.
Chargeback Processing
Required. This is used in cases of fraud, correction etc. Paymentwall sends request to the Callback URL and communicates how much virtual currency should be taken back from which userID. Format, Request method and Parameters are the same as for common Callback except for:
- currency - negative whole number (e.g. -2)
- type = 2 in case of chargeback
- reason - code of chargeback reason. Possible reasons are:
| Code | Reason | Recommendation |
|---|---|---|
| 1 | Chargeback | |
| 2 | Credit Card fraud | Ban User |
| 3 | Order fraud | Ban User |
| 4 | Bad data entry | |
| 5 | Fake / Proxy user | |
| 6 | Rejected by advertiser | |
| 7 | Duplicate conversions | |
| 8 | Goodwill credit taken back | |
| 9 | Canceled order, e.g. refund | |
| 10 | Partially reversed transaction |
Sample Pingback Listener Script
Using Paymentwall PHP library available at GitHub.
For more code samples in different programming languages, please visit https://www.paymentwall.com/en/documentation/getting-started/
require_once('/path/to/paymentwall-php/lib/paymentwall.php');
Paymentwall_Base::setApiType(Paymentwall_Base::API_CART);
Paymentwall_Base::setAppKey('YOUR_PROJECT_KEY'); // available in your Paymentwall merchant area
Paymentwall_Base::setSecretKey('YOUR_SECRET_KEY'); // available in your Paymentwall merchant area
$pingback = new Paymentwall_Pingback($_GET, $_SERVER['REMOTE_ADDR']);
if ($pingback->validate()) {
$products = $pingback->getProducts();
if ($pingback->isDeliverable()) {
// deliver products from the cart
} else if ($pingback->isCancelable()) {
// withdraw products from the cart
}
echo 'OK'; // Paymentwall expects response to be OK, otherwise the pingback will be resent
} else {
echo $pingback->getErrorSummary();
}
Signature Calculation
For detailed info on signature calculation please refer to Signature Calculation documentation.
