Documentation

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

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:

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.

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:

*All parameters are required.

4. Access Token Request

Once you receive code parameter you ready to request access_token.

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" 
}

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

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:

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

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”}
}