This guide provides information on using PHP with the USAePay SOAP API. The SOAP API provides an advanced interface to USAePay that allows merchants and resellers to access a wide range of functionality. This API requires a little more expertise than our simpler PHP Library for the Transaction API. If you are only looking to process transactions it is recommended that you use the PHP Library instead.
When using PHP there are several SOAP libraries available that can be used to make the integration with USAePay easier. While using a library is not required, it typically makes the development process much quicker. We've listed the two libraries that we recommend and actively support. There are several other libraries that should work well but we have not had the time to throughly test all of them.
PHP 5 and above comes with a Soap extension included. USAePay recommends that all developers use this class if possible. This guide includes examples for the PHP 5 SoapClient and assumes that you have it installed correctly. To verify that you have the soap client installed run a script with <?php phpinfo() ?>. The output should include “Soap Client: enabled” If you do not have it installed and are using a Linux server, you will need to install the php-soap package. For example, on Red Hat EL or CentOS:
yum install php-soap
If you compile your own PHP server, include –enable-soap in the ./configure command.
If you do not have the ability to install software or recompile php, use the PEAR Soap library instead (see below).
The official Pear repository includes a fairly full-featured Soap library written in PHP. Since it is written in PHP, it does not require any special privileges on the server. See PEAR::Soap for more information.
The information in this guide is for the PHP SoapClient extension. For information on using the PEAR::Soap library with USAePay, please see the PEAR Soap Guide.
The first step is to instantiate the SoapClient object. In the soap example provided on this site, we use $client for this object.
<?php //for live server use 'www' for test server use 'sandbox' $wsdl='https://www.usaepay.com/soap/gate/3213EA2A/usaepay.wsdl'; // instantiate SoapClient object as $client $client = new SoapClient($wsdl); ?>
If this fails with the error:
Fatal error: Cannot instantiate non-existent class: soapclient
then you do not have the SoapClient extension installed. See the directions above for more info on installing the extension.
If this fails with the error:
Unable to retrieve WSDL https://www.usaepay.com/soap/gate/xxxxxxxx/usaepay.wsdl
then remove 'usaepay.wsdl' from the link leaving only 'https://www.usaepay.com/soap/gate/xxxxxxxx/' and try again.
The ueSecurityToken object is used to securely identify the merchant to the gateway. To build a token, you will need the merchant's Source Key and Pin. The source key is created by the merchant in the Merchant Console under the Settings - Sources screen. Many of the methods in the SOAP API require the use of a PIN, and it is recommended that you always use a PIN. The merchant assigns the PIN when creating the source key.
<?php $sourcekey = 'yQbOFkmykeygoeshere3Lc9PH1l14'; $pin = '1234'; // generate random seed value $seed=mktime() . rand(); // make hash value using sha1 function $clear= $sourcekey . $seed . $pin; $hash=sha1($clear); // assembly ueSecurityToken as an array $token=array( 'SourceKey'=>$sourcekey, 'PinHash'=>array( 'Type'=>'sha1', 'Seed'=>$seed, 'HashValue'=>$hash ), 'ClientIP'=>$_SERVER['REMOTE_ADDR'], ); ?>
For questions please email firstname.lastname@example.org