Redirect API

The redirect API is used to make a very specific kind of application. It is almost exactly like a webhook, only your payer’s browser will be redirected to your hook location. The redirect API has new improvements over it’s old version, which was part of the Checkout guide.

The redirect API is enabled on a SchoolPay payee by our customer service team. Once enabled, you can open your checkout item and configure the redirect. Each item can be configured with a different redirect.

You can configure a redirect URL, comma-separated list of query parameters, and a signature password. We supply enough parameters to make basic decisions, but you will need to use the SchoolPay API to pull more details about a transaction if needed. The parameters we support are:

Your parameters will be sent as query parameters, along with a signature parameter. You will receive a signature whether or not you provide a password, however, you should enter a dummy password even if you’re not going to use one in SchoolPay.

You can use the signature parameter to confirm the validity of a request. To confirm the signature a request, you need to:

1. Create a JSON-object with keys in alphabetic order, with no whitespace, and all data types are strings.
2. SHA-256 HMAC that string with the password configured on the item Base64-encode the resulting string.

For example, if you are given the following query (valid) string:

?amount=20.00&id=4&[email protected]&signature=xNCNgF/3NMhB/hbJuNfdPFTNuckf6pu46JqAWWYGyxA=

You would want to use equivalent code to this PHP (the first line is added for clarity):

$_GET = ["amount" => "20.00", "email" => "[email protected]", "id" => "4"];
$request = [
	'amount' => (string) filter_input(INPUT_GET, 'amount', FILTER_VALIDATE_REGEXP, ['options' => ['regexp' => '/^\d+\.\d\d$/']]),
	'email' => (string) filter_input(INPUT_GET, 'email', FILTER_VALIDATE_EMAIL),
	'id' => (string) filter_input(INPUT_GET, 'id', FILTER_VALIDATE_INT),
];
$json = json_encode($request);
$expected_signature = hash_hmac('sha256', $json, $password, $raw = true);
$expected_signature = base64_encode($expected_signature);
if ( @$_GET['signature'] === $expected_signature ) {
	// At this point, $request is verified and can be trusted input
	// For example, you can send a "verify and associate" task to Amazon SQS
}