WePay

OAuth2 Account Creation

What is OAuth2?

OAuth2 is a process by which you can get a merchant's permission to do things on their behalf, like process payments for them, view their account balance, refund payments, etc. The end result of OAuth2 is getting an access_token, which is a secret parameter that lets you act on a specific merchant's behalf.

Using OAuth2, your platform can easily setup a payment account for your users and get them processing payments quickly with only four fields to fill out - with very little interruption of the user experience and light WePay branding.

If you want to be able to process payments for a merchant, getting an access_token is always the first step.

Example

A crowdfunding site wants to enable its fundraiser to collect donations. The crowdfunding site first needs to be able to create a WePay payment account for each fundraiser. This allows the fundraiser to charge credit cards and have the money collected sent to their WePay account, where they will view account balances, refund payments, withdraw money, etc. To do this easily, the crowdfunding site uses OAuth2 to get permission from the fundraiser to do all of this automatically.

At WePay, fundraisers are the merchants and donors are the payers and we'll use those terms below.

Live Example

This is what the user experience for OAuth2 looks like:

Click here to create your WePay account

How does it work?

There are 3 steps to OAuth2:

  1. The merchant clicks on the OAuth2 button on your site and confirms with WePay that they want to grant you permission to process payments for them.
  2. The merchant confirms and you receive a temporary code parameter.
  3. You exchange the temporary code parameter with WePay for a permanent access_token that will let you do things on the merchant's behalf.
  4. Make the /account/create call with the access_token from step 3 to get an account_id.

Step 1:

The first step is to put the OAuth2 button embed code on your site. Below, is an example of the embed code. Make sure you replace the client_id with your own app's client_id!


<a id="start_oauth2">Click here to create your WePay account</a>

<script src="https://static.wepay.com/min/js/wepay.v2.js" type="text/javascript"></script>
<script type="text/javascript">

WePay.set_endpoint("stage"); // stage or production

WePay.OAuth2.button_init(document.getElementById('start_oauth2'), {
    "client_id":"112894",
     "scope":["manage_accounts","collect_payments","view_user","send_money","preapprove_payments"],
    "user_name":"test user",
    "user_email":"test@example.com",
    "redirect_uri":"http://www.example.com/test",
    "top":100, // control the positioning of the popup with the top and left params
    "left":100,
    "state":"robot", // this is an optional parameter that lets you persist some state value through the flow
    "callback":function(data) {
		/** This callback gets fired after the user clicks "grant access" in the popup and the popup closes. The data object will include the code which you can pass to your server to make the /oauth2/token call **/
		if (data.code.length !== 0) {
			// send the data to the server
		} else {
			// an error has occurred and will be in data.error
		}
	}
});

</script>

The user will click on the button and be presented with a co-branded popup where they confirm that they want to give you permission to process payments on their behalf. To do so they will either login (if they already have a WePay account), or register (if they do not have a WePay account already).

Step 2:

After the user clicks "Grant Access" in the OAuth2 popup above, it will call whatever callback function you specified. The 1st parameter passed to the callback function will be a data JSON object which has a code property. You should pass this code parameter to your server where it will be used in step 3 to get an access_token.

Step 3:

Now that you have passed the temporary code parameter to your server, you can use it to get a permanent access_token.

To do so, you will make the /oauth2/token API call. You will pass your client_id, client_secret, the temporary code parameter, and whatever redirect_uri you specified in step 1.

The response to this call will include an access_token. This access_token is a permanent parameter that will let you make API calls on behalf of the merchant. You should store this access_token in your database, and take steps to keep it secure (treat it like you would a hashed password).

  • PHP
  • cURL
  • Ruby
  • Python
<?php
    // WePay PHP SDK - http://git.io/mY7iQQ
    require 'wepay.php';

    // oauth2 parameters
    $code = $_GET['code']; // the code parameter from step 2
    $redirect_uri = "http://www.example.com/oauth2_redirect_uri"; // this is the redirect_uri you used in step 1

    // application settings
    $client_id = 123456789;
    $client_secret = "1a3b5c7d9";

    // change to useProduction for live environments
    Wepay::useStaging($client_id, $client_secret);

    $wepay = new WePay(NULL); // we don't have an access_token yet so we can pass NULL here

    // create an account for a user
    $response = WePay::getToken($code, $redirect_uri);

    // display the response
    print_r($response);
?>
curl https://stage.wepayapi.com/v2/oauth2/token \
	-d "client_id=123456789" \
	-d "client_secret=1a3b5c7d9" \
	-d "code=52sdga231sddd213jj9a" \
	-d "redirect_uri=http://www.example.com/oauth2_redirect_uri"
				
# WePay Ruby SDK - http://git.io/a_c2uQ
require 'WePay_API_v2_Ruby_SDK.rb'

# oauth2 parameters
code = params[:code]; # the code parameter from step 2
redirect_uri = "http://www.example.com/oauth2_redirect_uri"; # this is the redirect_uri you used in step 1

# application settings
client_id = 123456789
client_secret = '1a3b5c7d9'

# set _use_stage to false for live environments
wepay = WePay.new(client_id, client_secret, _use_stage = true)

# create an account for a user
response = wepay.oauth2_token(code, redirect_uri)

# display the response
p response
# WePay Python SDK - http://git.io/v7Y1jA
from wepay import WePay

# oauth2 parameters
code = '52sdga231sddd213jj9a'; # the code parameter from step 2
redirect_uri = "http://www.example.com/oauth2_redirect_uri"; # this is the redirect_uri you used in step 1

# application settings
client_id = 123456789
client_secret = '1a3b5c7d9'
production = False

# set production to True for live environments
wepay = WePay(production, None)

# create an account for a user
response = wepay.get_token(redirect_uri, client_id, client_secret, code)

# display the response
print response

Step 4:

Each merchant requires a payment account in order to start processing payments. A payment account has its own transaction history and account balance. Once you have an access_token for each merchant, you'll want to create a payment account for each merchant.

All you need to do is make the /account/create call with the merchant's access_token. The account name that you specify will be used on receipts and on the credit card statement for payments made to this account.

You will receive back an account_id which you should store in your database. You will use the merchant's account_id and access_token when making payments with the /checkout/create call (for example). You can also use the account_id to look up the account balance and status.

  • PHP
  • cURL
  • Ruby
  • Python
<?php
    // WePay PHP SDK - http://git.io/mY7iQQ
    require 'wepay.php';

    // application settings
    $client_id = 123456789;
    $client_secret = "1a3b5c7d9";
    $access_token = "1a3b5c7d9";

    // change to useProduction for live environments
    Wepay::useStaging($client_id, $client_secret);

    $wepay = new WePay($access_token);

    // create an account for a user
    $response = $wepay->request('account/create/', array(
        'name'          => 'Account Name',
        'description'   => 'A description for your account.'
    ));

    // display the response
    print_r($response);
?>
curl https://stage.wepayapi.com/v2/account/create \
	-H "Authorization: Bearer STAGE_8a19aff55b85a436dad5cd1386db1999437facb5914b494f4da5f206a56a5d20" \
	-d "name=Account name" \
	-d "description=A description for your account."
				
# WePay Ruby SDK - http://git.io/a_c2uQ
require 'WePay_API_v2_Ruby_SDK.rb'

# application settings
client_id = 123456789
client_secret = '1a3b5c7d9'
access_token = '1a3b5c7d9'

# set _use_stage to false for live environments
wepay = WePay.new(client_id, client_secret, _use_stage = true)

# create an account for a user
response = wepay.call('/account/create', access_token, {
    :name          => 'Account Name',
    :description   => 'A description for your account.'
})

# display the response
p response
# WePay Python SDK - http://git.io/v7Y1jA
from wepay import WePay

# application settings
access_token = '1a3b5c7d9'
production = False

# set production to True for live environments
wepay = WePay(production, access_token)

# create an account for a user
response = wepay.call('/account/create', {
    'name': 'Account Name',
    'description': 'A description for your account.'
})

# display the response
print response

Next Steps

Now that you have an account_id and an access_token, you can help the merchant accept payments. Read the process payments overview for information on how to do that.