PHP Guide

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.

Choosing a SOAP Library

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 SoapClient extension

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).

PEAR::Soap

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.

Using SoapClient

Step 1: Instantiating $client

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://sandbox.usaepay.com/soap/resellerapi/1412E031/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://sandbox.usaepay.com/soap/resellerapi/xxxxxxxxx/usaepay.wsdl

then remove usaepay.wsdl from the link leaving only https://sandbox.usaepay.com/soap/resellerapi/1412E031/xxxxxxxx/ and try again.

Step 2: Building Security $token

The ueSecurityToken object is used to securely identify the reseller to the gateway. To build a token, you will need the reseller's Source Key and Pin. The source key is created by the reseller in the Reseller Console under the Settings - Keys Management 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 reseller assigns the PIN when creating the source key.

    <?php
      $sourcekey = 'R:b***********************************1';
      $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'],
      );
    ?>

Additional Help

For questions please email devsupport@usaepay.com