Documentation
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:
- 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.
- On Paymentwall’s website, the user can approve access to their account.
- Once user approves access to their account they will be redirected back to your website (based on redirect_uri param) with code parameter.
- Then, make a request to Paymentwall Oauth 2.0 server with that code.
- You will receive the access_token.
OAuth 2.0 Flow Diagram
- User Authorization Request
- User Authorizes Application
- Authorization Code Grant
- Access Token Request
- 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:
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.
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”}
}