phorge-phorge/externals/wepay/README.md

WePay PHP SDK

WePay's API allows you to easily add payments into your application.

For full documentation, see WePay's developer documentation

Usage

In addition to the samples below, we have included a very basic demo application in the demoapp directory. See its README file for additional information.

Configuration

For all requests, you must initialize the SDK with your Client ID and Client Secret, into either Staging or Production mode. All API calls made against WePay's staging environment mirror production in functionality, but do not actually move money. This allows you to develop your application and test the checkout experience from the perspective of your users without spending any money on payments. Our full documentation contains additional information on test account numbers you can use in addition to "magic" amounts you can use to trigger payment failures and reversals (helpful for testing IPNs).

Note: Staging and Production are two completely independent environments and share NO data with each other. This means that in order to use staging, you must register at stage.wepay.com and get a set of API keys for your Staging application, and must do the same on Production when you are ready to go live. API keys and access tokens granted on stage can not be used on Production, and vice-versa.

<?php
require './wepay.php';
WePay::useProduction('YOUR CLIENT ID', 'YOUR CLIENT SECRET'); // To initialize staging, use WePay::useStaging('ID','SECRET'); instead.

Authentication

To obtain an access token for your user, you must redirect the user to WePay for authentication. WePay uses OAuth2 for authorization, which is detailed in our documentation. To generate the URI to which you must redirect your user, the SDK contains WePay::getAuthorizationUri($scope, $redirect_uri). $scope should be an array of scope strings detailed in the documentation. To request full access (most useful for testing, since users may be weary of granting permission to your application if it wants to do too much), you pay pass in WePay::getAllScopes(). $redirect_uri must be a fully qualified URI where we will send the user after permission is granted (or not granted), and the domain must match your application settings.

If the user grants permission, he or she will be redirected to your $redirect_uri with code=XXXX appended to the query string. If permission is not granted, we will instead put error=XXXX in the query string. If code is present, the following will exchange it for an access token. Note that codes are only valid for several minutes, so you should do this immediately after the user is redirected back to your website or application.

<?php
if (!empty($_GET['error'])) {
	// user did not grant permissions
}
elseif (empty($_GET['code'])) {
	// set $scope and $redirect_uri before doing this
	// this will send the user to WePay to authenticate
	$uri = WePay::getAuthorizationUri($scope, $redirect_uri);
	header("Location: $uri");
	exit;
}
else {
	$info = WePay::getToken($_GET['code'], $redirect_uri);
	if ($info) {
		// YOUR ACCESS TOKEN IS HERE
		$access_token = $info->access_token;
	}
	else {
		// Unable to obtain access token
	}
}

Full details on the access token response are here.

Note: If you only need access for yourself (e.g., for a personal storefront), the application settings page automatically creates an access token for you. Simply copy and paste it into your code rather than manually going through the authentication flow.

Making API Calls

With the $access_token from above, get a new SDK object:

<?php
$wepay = new WePay($access_token);

Then you can make a simple API call. This will list the user's accounts available to your application:

// (continued from above)
try {
	$accounts = $wepay->request('account/find');
	foreach ($accounts as $account) {
		echo "<a href=\"$account->account_uri\">$account->name</a>: $account->description <br />";
	}
}
catch (WePayException $e) {
	// Something went wrong - normally you would log
	// this and give your user a more informative message
	echo $e->getMessage();
}

And that's it! For more detail on what API calls are available, their parameters and responses, and what permissions they require, please see our documentation. For some more detailed examples, look in the demoapp directory and check the README. Dropping the entire directory in a web-accessible location and adding your API keys should allow you to be up and running in just a few seconds.

SSL Certificate

If making an API call causes the following problem:

Uncaught exception 'Exception' with message 'cURL error while making API call to WePay: SSL certificate problem, verify that the CA cert is OK. Details: error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed'

You can read the solution here: https://support.wepay.com/entries/21095813-problem-with-ssl-certificate-verification