Bristol Pound

Developer Area

Web Shop

Note: SOAP web services, including Webshop, are being deprecated in readiness for Cyclos 4.x early 2016

Our Web Shop service is a simple SOAP web service for generating payments and is useful for adding a £B payment facility into an online shop.

It is designed to be easy to implement with only two methods, one to generate the payment and the other to get the result for processing.

Any language can be used to access this Web Service as long as they are able to support the SOAP protocol, we generally use clients written in Java or PHP which work well. The example below is in PHP and you can download the source code files here.

We use Cyclos server software, http://www.cyclos.org/, as our online payment system so you will see it referred to below. Note you will need to contact our Technical Team at support@bristolpound.org to get set up on this system before you can use it.

How it works

1. Generate a payment request

Firstly you need to prepare payment parameters to generate a payment and redirect the client to the payment server (Cyclos). For this you only need an amount, a recipient user name and a description.

prepare_payment.php
<?php
// Get the web service proxy
require_once 'cyclos.php';
$cyclos = new Cyclos();
$webShopService = $cyclos->service('webshop'); // Setup the payment parameters
$params = new stdclass();
$params->amount = [YOUR_AMOUNT];
$params->description = "Test Payment";
$params->clientAddress = $_SERVER['REMOTE_ADDR'];
$params->toUsername = '[YOUR_USERNAME]';

// This should be the absolute url for the page which will process the payment
$params->returnUrl = [YOUR_URL]."/complete_payment.php";

// Generate the ticket
try {
//Ensure the input parameter is named 'params' and the output, 'return'
$ticket = $webShopService->generate(array('params' => $params))->return;
} catch (SoapFault $e) {
die("Error generating a payment ticket: $e");
}

// With the ticket ok, redirect the client to perform the payment
header( "Location: ".Cyclos::$server_root."/do/webshop/payment?ticket=".$ticket ) ;
?>

 

2. User gets redirected to the payment server (Cyclos)

Similar to how PayPal sometimes works, the user then gets redirected directly to a secure payment page on our server, and is asked for their username and password to make the payment.

3. User confirms the payment

Still on the secure payment server, the user is asked to confirm the payment.

4. Payment is made and user can print receipt

Still on the secure payment server, the user is able to see the result of their transaction and print the receipt if required, they then need to hit close otherwise the next step will not happen!.

5. Payment is processed further on the website

The user is then returned to the "returnurl" and the website can check the payment has been made correctly and can then process the order as appropriate. An example of this file is below.

complete_payment.php
<?php
// Get the web service proxy
require_once 'cyclos.php';
$cyclos = new Cyclos();
$webShopService = $cyclos->service('webshop');

// Get the ticket details
try {
//Ensure the input parameter is named 'params' and the output, 'return'
$ticket = $webShopService->get(array('ticket' => $_GET['ticket']))->return;
} catch (SoapFault $e) {
die("Error retrieving payment ticket: $e");
}

// Validate the ticket data
$expected_amount = [YOUR_AMOUNT];

if ($ticket->awaitingAuthorization) {
die("The payment is awaiting authorization in Cyclos");
} else if (!$ticket->ok) {
die("The ticket was not validated");
} else if ($ticket->amount != $expected_amount) {
die("Wrong ticket: invalid amount");
} else if ($ticket->clientAddress != $_SERVER['REMOTE_ADDR']) {
die("Wrong ticket: unexpected client address");
} else {
echo("The payment has been successfully processed");
}
?>

 

Joomla

Cyclos have developed a module for Joomla which uses this web service, which you can read about and download here: http://www.cyclos.org/joomla/index.php?option=com_content&view=article&id=46&Itemid=2

Further reading

The best way to start your integration is to have a look at the test files referenced above which you can download here. We can set you up on the server and give you any further help and support you need.

There is a some further docmentation on this web service (and others) on the Cyclos site here:

Web service specification: https://bristol-staging-monea.isotoma.com/monea/services/webshop?wsdl
Cyclos Web Shop documentation: http://www.cyclos.org/wiki/index.php/Web_services/WebShop_payment
General Cyclos Web Service Documentation: http://www.cyclos.org/wiki/index.php/Web_services