Secure Trading Web Services API abstraction.
To learn about the different types of requests and the required attributes, refer to the Secure Trading Web Services API documentation.
Service is used to construct Request using existing templates and to pre-populate them with your API credentials.
/**
* @param string $site_reference The Merchant's Site Reference.
* @param string $username
* @param string $password
* @param string $interface_url
*/
$service = new \Gajus\Strading\Service('test_github53934', '[email protected]', '93gbjdMR');Requests templates to process card and PayPal transactions come with the library:
To make a new template, copy over the full request XML from the respective Secure Trading documentation.
/**
* @param string $name Request template name, e.g. "card/order".
* @return Gajus\Strading\Request
*/
$auth = $service->request('card/auth');The above example has initialised Request using the "card/auth" template.
Template is populated from an array, where each array key refers to an existing node.
/**
* Populate XML template using data from an array.
*
* @param array $data ['node name' => 'text node value', 'another node[attribute]' => 'attribute value']
* @param string $namespace XML namespace under which the node resides, e.g. /requestblock/request
* @return null
*/
$auth->populate([
'amount' => 100,
'amount[currencycode]' => 'GBP',
'email' => '[email protected]',
'name' => [
'first' => 'Foo',
'last' => 'Bar'
],
'payment' => [
'pan' => '4111110000000211',
'securitycode' => '123',
'expirydate' => '10/2031'
],
'payment[type]' => 'VISA'
],'/requestblock/request/billing');The above example is using "/requestblock/request/billing" namespace to refer to a specific XML node. Do this to reduce the amount of array nesting.
To preview the request, you can retrive the SimpleXMLElement:
/**
* Request XML stripped of empty tags without attributes.
*
* @return string
*/
$auth->getXML();The above will produce:
<?xml version="1.0"?>
<requestblock version="3.67">
<alias>[email protected]</alias>
<request type="AUTH">
<billing>
<amount currencycode="GBP">100</amount>
<email>[email protected]</email>
<name>
<last>Bar</last>
<first>Foo</first>
</name>
<payment type="VISA">
<expirydate>10/2031</expirydate>
<pan>4111110000000211</pan>
<securitycode>123</securitycode>
</payment>
</billing>
<operation>
<sitereference>test_github53934</sitereference>
<accounttypedescription>ECOM</accounttypedescription>
</operation>
</request>
</requestblock>The XML nodes that were not populated and did not have a default value in the template, were stripped away from the request XML.
You can populate the request over several itterations.
$auth->populate([
'merchant' => [
'orderreference' => 'gajus-0000001'
],
'customer' => [
'name' => [
'first' => 'Foo',
'last' => 'Bar'
],
'email' => '[email protected]'
]
], '/requestblock/request');The above will produce:
<?xml version="1.0"?>
<requestblock version="3.67">
<alias>[email protected]</alias>
<request type="AUTH">
<merchant>
<orderreference>gajus-0000001</orderreference>
</merchant>
<customer>
<email>[email protected]</email>
<name>
<last>Bar</last>
<first>Foo</first>
</name>
</customer>
<billing>
<amount currencycode="GBP">100</amount>
<email>[email protected]</email>
<name>
<last>Bar</last>
<first>Foo</first>
</name>
<payment type="VISA">
<expirydate>10/2031</expirydate>
<pan>4111110000000211</pan>
<securitycode>123</securitycode>
</payment>
</billing>
<operation>
<sitereference>test_github53934</sitereference>
<accounttypedescription>ECOM</accounttypedescription>
</operation>
</request>
</requestblock>Methods to dump XML are for debugging only. You do not need to deal with XML when making the request or handling the response.
The location of your request templates can be changed by calling the setTemplateDirectory() method.
$service->setTemplateDirectory('/my/templates/live/here');
$service->getTemplateDirectory(); // Returns: /my/templates/live/hereMake the request and capture the Response:
/**
* Issue the request.
*
* @return Gajus\Strading\Response
*/
$response = $auth->request();If HTTP response is not 200, then Gajus\Strading\Exception\RuntimeException will be thrown. This will happen if you provide invalid authentication credentials or your credentials do not grant you access to the API endpoint.
Response class abstracts the response XML.
/**
* Transaction abstracts access to the most generic information about the response:
*
* - request_reference
* - transaction_type
* - transaction_reference
* - timestamp
* - parent_transaction_reference
* - authcode
* - amount
* - paypal_token
*
* Presence of this data will depend on the type of the response you receive, e.g.
* only PayPal order request will include "paypal_token" parameter.
*
* @return array
*/
public function getTransaction ();
/**
* This information is available when response type is "ERROR".
*
* @return null|Gajus\Strading\Error
*/
public function getError ();
/**
* This information is available in response to the "paypal/order" request.
*
* @return null|string URL to redirect the client to.
*/
public function getRedirectUrl () {
return $this->redirect_url;
}
/**
* @return string Response type.
*/
public function getType () {
return $this->type;
}
/**
* @return string Raw XML response.
*/
public function getXML () {
return $this->xml->asXML();
}In case Response type is "ERROR", the getError method will return an instance of Gajus\Strading\Error.
/**
* @return string
*/
public function getCode () {
return $this->code;
}
/**
* @return string
*/
public function getMessage () {
return $this->message;
}
/**
* This tag contains one or more child elements. If the error code is "30000" (Field Error)
* then this field will contain the field (or fields) which caused the error.
*
* @todo https://github.com/gajus/strading/issues/1
* @return string
*/
public function getData () {
return $this->data;
}