Paymentwall website uses cookies to store your browsing preferences on your device. However, cookies do not collect personal information.

For more information about how we use cookies, check our cookie policy

Close

Documentation

Getting Started API Libraries APIs Checklists Flows Integrations Mobile SDKs Reference Smart TV SDK SpiderPipe Testing Payments
Contacts
If you still have questions regarding integration, please email us at devsupport@paymentwall.com

Cart API

Paymentwall Widget Call

Default Widget Call

API URL

https://api.paymentwall.com/api/cart

Request Method

GET

Protocols Supported

HTTP, HTTPS

Required Parameters

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
email end-user's email, where the notification should be sent email=addr@domain.com

Optional Parameters

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&currencies[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

Building Widget URL

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.
Email 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 Pingback

Format

http://www.yourserver.com/anypath?uid=[USER_ID]&sign_version=2&goodsid[]=[GOODS_IDS_ARRAY]&type=[TYPE]&ref=[REF]&sig=[SIGNATURE]

Request Method

GET

Protocols Supported

HTTP, HTTPS

Parameters

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.

Parameters Sample

  • 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

Pingback URL Sample

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

Return Value

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.

Security

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.

More details:

This page needs JavaScript
Your browser is
not supported anymore.
Please update to the more recent one.
This page needs JavaScript
This page needs JavaScript.
Please enable it in your browser settings and try again.