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

New 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

Paymentwall Bridge OAuth API

Paymentwall Bridge OAuth 2.0 allows platforms and modules to easily connect (create) accounts of your customers and accept payments in just 5 minutes. This tutorial is for platform application. For registration as platform please write: devsupport@paymentwall.com

How Paymentwall Bridge Works

Paymentwall Bridge is based on OAuth 2.0. For additional information please read the official OAuth 2.0 tutorial here: https://tools.ietf.org/html/rfc6749

A few steps:

  1. On a page at your website you include Paymentwall’s “Authorize via PW Account” button with your custom client_id which tracks the user’s click.
  2. On Paymentwall’s website, the user can approve access to their account.
  3. Once user approves access to their account they will be redirected back to your website (based on redirect_uri param) with code parameter.
  4. Then, make a request to Paymentwall Oauth 2.0 server with that code.
  5. You will receive the access_token.

OAuth 2.0 Flow Diagram

  1. User Authorization Request
  2. User Authorizes Application
  3. Authorization Code Grant
  4. Access Token Request
  5. Access Token Grant

auth_code_flow.png

1. Authorization URL

Generate this link for initialize OAuth 2.0 process: End point:

https://api.paymentwall.com/pwaccount/oauth/authorize

Sample Link

https://api.paymentwall.com/pwaccount/oauth/authorize?response_type=code&client_id=246921bdb35e8de871c206f8710b6c4d&redirect_uri=https://example.com/oauth/paymentwall&scope=pwaccount.email.get,merchant.application.get,merchant.application.update,merchant.application.create&state=206c80413b9a96c1312cc346b7d2517b84463edd

Response Parameters:

Parameter Example Description
response_type code https://tools.ietf.org/html/rfc6749#section-3.1.1
client_id 246921bdb35e8de871c206f8710b6c4d Your platform identification. Generated by Paymentwall. You can get it after registration as Platform.
redirect_uri https://example.com/oauth/paymentwall Your Oauth landing page.
scope pwaccount.email.get,merchant.application.get,merchant.application.update,merchant.application.create Your requested scope.
state 206c80413b9a96c1312cc346b7d2517b84463edd Some random string for prevent CSRF attacks. Will be returned back with code to your Oauth landing page.

Sample PHP code: The example below uses PHP League's OAuth2 Client

// Construct the OAuth Client provider
$provider = new \League\OAuth2\Client\Provider\GenericProvider([
    'clientId'                => 'YOUR_PUBLIC_KEY', // project key
    'redirectUri'             => 'YOUR_REDIRECT_URL', // the URL where the user will be redirected after logging in
    'urlAuthorize'            => 'https://api.paymentwall.com/pwaccount/oauth/authorize',
    'urlAccessToken'          => 'https://api.paymentwall.com/pwaccount/oauth/token',
    'urlResourceOwnerDetails' => 'https://api.paymentwall.com/pwapi/pwaccount/',
    'scopes'                  => 'default,pwaccount.email.get,merchant.application.get,merchant.application.update,merchant.application.create'
]);

$authorizationUrl = $provider->getAuthorizationUrl();

// Get the state generated for you and store it to the session.
$_SESSION['oauth2state'] = $provider->getState();

Showing the button. This will redirect the user to Paymentwall's authorization page.

<a href="<?php echo $authorizationUrl; ?>"><button>Login with PW Account</button></a>

2. Approval Page

Once user clicks on Paymentwall’s “Authorize via PW Account” Button. They will be redirected to Paymentwall approval page or alternatively to a login page.

Approval Page

3. Authorization Code

Once the user approves access to their account, we redirect them back to your site with authorize code based on your redirect_uri which was in first step.

Example URL:

https://example.com/oauth/paymentwall?code=0b422057958e163c8e9b00569b05982548d44157&state=206c80413b9a96c1312cc346b7d2517b84463edd

In this case, params:

Parameter Short name Description
https://example.com/oauth/paymentwall redirect URL URL, which was declared at first step.
code=0b422057958e163c8e9b00569b05982548d44157 authorize code Random generated by Paymentwall code, which allow get access_token (fourth step).
state=206c80413b9a96c1312cc346b7d2517b84463edd state CSRF prevention parameter. For more information we suggest read this article: https://www.owasp.org/index.php/Cross-Site_Request_Forgery_%28CSRF%29

*All parameters are required.

4. Access Token Request

Once you receive code parameter you ready to request access_token.

Parameter Description
code Code, that you receive, at third step.
client_id Your platform identification. Generated by Paymentwall. You can get it after registration as Platform.
client_secret You secret key. Generated by Paymentwall. You can get it after registration as Platform.
redirect_uri Same uri, as it was at first step.

All parameters are required.

Sample Request:

curl https://api.paymentwall.com/pwaccount/oauth/token \
-d "code=0b422057958e163c8e9b00569b05982548d44157" \
-d "client_id=246921bdb35e8de871c206f8710b6c4d" \
-d "client_secret=d7732ffeca64be8e67628e35240357b1" \
-d "redirect_uri=https://example.com/oauth/paymentwall"

Sample PHP code: The example below uses PHP League's OAuth2 Client


// Construct the OAuth Client provider
$provider = new \League\OAuth2\Client\Provider\GenericProvider([
    'clientId'                => 'YOUR_PUBLIC_KEY', // project key
    'redirectUri'             => 'YOUR_REDIRECT_URL', // the URL where the user will be redirected after logging in
    'urlAuthorize'            => 'https://api.paymentwall.com/pwaccount/oauth/authorize',
    'urlAccessToken'          => 'https://api.paymentwall.com/pwaccount/oauth/token',
    'urlResourceOwnerDetails' => 'https://api.paymentwall.com/pwapi/pwaccount/',
    'scopes'                  => 'default,pwaccount.email.get,merchant.application.get,merchant.application.update,merchant.application.create'
]);

// Generate the token
$accessToken = $provider->getAccessToken('authorization_code', [
    'code'              => $_GET['code'],
    'resource_owner_id' => 'YOUR_PUBLIC_KEY',
    'client_secret'     => 'YOUR_SECRET_KEY',
    'redirect_uri'      => 'YOUR_REDIRECT_URL'
]);

// Store the token, in this case, it is stored in the session
$_SESSION['token'] = $accessToken->getToken();

// You can refresh the token like so:
$accessToken->getRefreshToken();

5. Access Token Grant

If everything is correct, you’ll receive a response like this:

{
"access_token" : "0e9d02499fe06762ecaafb9cfbb506676631dcfd",
"expires_in" : 3600,
"token_type" : "bearer",
"scope" :  "pwaccount.email.get,merchant.application.get,merchant.application.update,merchant.application.create" 
}
Parameter Description
access_token Your "key" to API requests.
expires_in Count of seconds to token expire.
token_type https://tools.ietf.org/html/rfc6750#section-6.1.1
scope Your access scope.

API Basics

Once you get access_token you are ready to use Paymentwall API and manipulate with end-user accounts.

API - PWAccount

PWAccount is a like main hub. Merchant, user, advertiser and other types of accounts based on PWAccount (Paymentwall Account).

Scope

  • default — allows you to get pwaccount id, this ID is static user identificator
  • pwaccount.email.get — allows to get PWAccount email
  • pwaccount.personal_data.get — allows to get PWAccount personal data (first_name, last_name, phone)

Get PWAccount

API Endpoint: https://api.paymentwall.com/pwapi/pwaccount

Method: GET

Sample Request:

curl https://api.paymentwall.com/pwapi/pwaccount \
-d "access_token=0b422057958e163c8e9b00569b05982548d44157" \
-d "version=1"

Sample Response (default scope):

{
  "pwaccount_id" : 123
}

Sample Response (default + pwaccount.email.get scope):

{
"pwaccount_id" : 123,
"email" : "john@doe.com"
}

Sample Response (default + pwaccount.email.get + pwaccount.personal_data.get scope):

{
"pwaccount_id" : 123,
"email" : "john@doe.com",
"first_name" : "John", 
"last_name" : "Doe"
}

API - Merchant

Scope

  • merchant.application.get — read only merchant applications
  • merchant.application.create — allows creation of merchant applications
  • merchant.application.update — allows updating of current merchant applications

Get list of Projects

API Endpoint: https://api.paymentwall.com/pwapi/merchant/application

Method: GET

Sample Request:

curl https://api.paymentwall.com/pwapi/merchant/application \
-d "access_token=0b422057958e163c8e9b00569b05982548d44157" \
-d "version=1"

Sample Response:

[
{
  "name":"ACME Store 1",
  "id":12345,
  "key":"d74682ee47c3fffd5dcd749f840fcdd4",
  "secret":"c1987fbb25dd5dc305ab2f00fe465eeb",
  "url":"https://www.example.com",
  "signature_version":2,
  "pingaback_status_pattern":"OK",
  "compliance_status":{"cc":"pending","alternative":"pending”}
},
{
  "name":"ACME Store 2",
  "id":123456,
  "key":"4ae022074f3a4e9b78711fc0030be962",
  "secret":"a30076faa0fc220ff85ed21b458a54c9",
  "url":"https://www.example.com/2",
  "signature_version":2,
  "pingaback_status_pattern":"OK",
  "compliance_status":{"cc":"pending","alternative":"pending”}
}
]

Get Project

API Endpoint: https://api.paymentwall.com/pwapi/merchant/application/:ID

Method: GET

Sample Request:

curl https://api.paymentwall.com/pwapi/merchant/application/12345 \
-d "access_token=0b422057958e163c8e9b00569b05982548d44157" \
-d "version=1"

Sample Response:

{

"name":"ACME Store",
"id":12345,
"key":"d74682ee47c3fffd5dcd749f840fcdd4",
"secret":"c1987fbb25dd5dc305ab2f00fe465eeb",
"url":"example.com",
"signature_version":2, 
"pingaback_status_pattern":"OK",
"compliance_status":{"cc":"pending","alternative":"pending”}
}

Sample PHP code:

// Using Guzzle PHP HTTP client

$client = new GuzzleHttp\Client();

$res = $client->get('https://api.paymentwall.com/pwapi/merchant/application/12345', [
    'query' => [
        'access_token' => $_SESSION['token'], //the token that was stored previously
        'version' => '1'
    ]
]);

Create Project

API Endpoint: https://api.paymentwall.com/pwapi/merchant/application/

Method: POST

Parameters:

Green fields — required

Name Example Description
name My Favorite Project String, name of merchant project
url https://example.com/ URL to merchant project
pinback_url https://example.com/paymentwall/pingback To learn more about integrating Pingbacks, refer to the Getting Started page.
source custom-source Create application based on Paymentwall pre-defined source settings (contact integration@paymentwall.com)
evaluation_mode https://www.paymentwall.com/en/documentation/Test-Payment-Method/1083

Sample Request:

curl https://api.paymentwall.com/pwapi/merchant/application/ \
-d "access_token=0b422057958e163c8e9b00569b05982548d44157" \
-d "version=1" \
-d "name=My Favorite Project" \
-d "url=https://example.com/" \
-d "pinback_url=https://example.com/paymentwall/pingback"
// Using Guzzle PHP HTTP client

$client = new GuzzleHttp\Client();

$res = $client->post('https://api.paymentwall.com/pwapi/merchant/application/', [
    'form_params' => [
        'access_token' => $_SESSION['token'], // the token that was stored in step 2
        'version' => 1, 
        'name' => 'Name of My Project', //the name of your new project
        'url' => 'http://www.example.com', //URL of your new project
        'pingback_url' => 'http://www.example.com' // Pingback URL of your new project
    ]
]);

//Store the Project key and Secret Key
$body = json_decode($res->getBody());
$projectKey = $body->key;
$secretKey  = $body->secret;

Sample Response:

{
  "name":"ACME Store",
  "id":12345,
  "key":"d74682ee47c3fffd5dcd749f840fcdd4",
  "secret":"c1987fbb25dd5dc305ab2f00fe465eeb",
  "url":"example.com",
  "signature_version":2,
  "pingaback_status_pattern":"OK"
}

Update Project

API Endpoint: https://api.paymentwall.com/pwapi/merchant/application/

Method: PUT

Parameters:

Name Example Description
name My Favorite Project String, name of merchant project
url https://example.com/ URL to merchant project
pinback_url https://example.com/paymentwall/pingback To learn more about integrating Pingbacks, refer to the Getting Started page.
source custom-source Create application based on Paymentwall pre-defined source settings (contact integration@paymentwall.com)
evaluation_mode https://www.paymentwall.com/en/documentation/Test-Payment-Method/1083
api_type 2 Type of API: digital goods, virtual currency, cart. Same as in https://github.com/paymentwall/paymentwall-php/blob/master/lib/Paymentwall/Config.php#L9
notify_email john@doe.com Email for notification

Sample Request:

curl https://api.paymentwall.com/pwapi/merchant/application/12345 \
-d "access_token=0b422057958e163c8e9b00569b05982548d44157" \
-d "version=1" \
-d "name=ACME store"

Sample Response:

{
  "name":"ACME Store",
  "id":12345,
  "key":"d74682ee47c3fffd5dcd749f840fcdd4",
  "secret":"c1987fbb25dd5dc305ab2f00fe465eeb",
  "url":"example.com",
  "signature_version":2,
  "pingaback_status_pattern":"OK"
}

How to create Vendor project and assign it to global Marketplace account:

API Endpoint: https://api.paymentwall.com/pwapi/merchant/application

Method: POST

Parameters: Name Example Description
is_vendor true
application_key $applicationKey The key of application to which Vendor project will be mapped
vendor_settings[commission_percentage] 95 Vendor’s commission. In example Vendor gets 95% of commission, and Marketplace gets 5%
vendor_settings[commission_fixed] 0 Fixed commission you want to charge your Vendor per product sold
vendor_settings[currency_code] USD Choose currency, when ‘commission_fixed’ is not ‘0'
vendor_settings[commission_base] net ‘net’ is by default for now. Take your commission after payment system fees are deducted.
vendor_settings[commission_scope] all ‘all’ is by default for now
vendor_settings[payout_handler] pw ‘pw’ is by default for now

Sample Request:

curl -X POST \
https://api.paymentwall.com/pwapi/merchant/application/ \
    -F access_token=0b422057958e163c8e9b00569b05982548d44157 \
    -F version=1 \
    -F name=  Vendor Project \
    -F url= https://example.com/ \
    -F pingback_url= https://example.com/paymentwall/pingback \
    -F is_vendore=true \
    -F application_key=9313ea769dffcbbc60f4665820c6a5b9 \
    -F 'vendor_settings[commission_percentage]=95' \
    -F 'vendor_settings[commission_fixed]=0' \
    -F 'vendor_settings[currency_code]=USD' \
    -F 'vendor_settings[commission_base]=net' \
    -F 'vendor_settings[commission_scope]=all' \
    -F 'vendor_settings[payout_handler]=pw'

Sample Response:

{
"name":"Vendor Project”,
"id":100173,
"key":"2184ed40d71605bca3eb03409c1d3cd1”,
"secret":"6548579ca01d52bb38ac7df6dc3aeef3”,
"url":”",
"signature_version":1,
"pingback_status_pattern":"OK”,
"api_type":"Digital Goods \/ Subscriptions \/ One-Time Payments”,
"status":"Set up is not finished”,
"integration_status":"setup_not_finished”,
"pingback_url":”",
"pingback_email":0,
"compliance_status":{"cc":"pending","alternative":"pending”}
}
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.
We use cookies on this website to make your browsing experience better. By using the Paymentwall website you agree to our Cookies Policy.