| Platform | File | Download |
| UNIX (Linux, BSD, Mac OS X, etc) | usaepay-php-1.6.0.tgz | Download |
| Windows | usaepay-php-160.zip | Download |
| PHP Library file only (usaepay.php) | usaepay-php-160.txt | Download |
The USAePay PHP Library provides an easy to use PHP interface for running server to server processing. If you are developing your site using PHP it is highly recommended that you use this script rather than the client side method. Not only will it provide a more consistent interface for your customers, but it will also prevent manipulation of order data.
When using this script, the basic flow will go something like:
Customer enters creditcard data on merchant's server
Script on merchant's server takes customer data and populates USAePay transaction ($transaciton=new umTransaction)
Merchant's server tells USAePay transaction to process ($transaction→Process)
USAePay library sends transaction via SSL encrypted HTTP connection to USAePay for authorization
USAePay library reads response from USAePay
Library returns response to merchant's script
Merchant's script interprets the result and displays the corresponding response to the customer
This library has been tested on Linux (RedHat, Mandrake and Debian), FreeBSD, Mac OS X (Darwin) and Windows 2000 but it should work on any platform that can support PHP 4.x, libcURL and OpenSSL. Most Linux distributions have the required packages available in the operating system. Mac OS X users can download an excellent PHP Apache module with CURL/ssl support from http://www.entropy.ch/software/macosx/php/.
The required pieces for compiling your own PHP to support USAePay are: PHP 4.3.3 or higher, libcURL and OpenSSL. PHP is self-described as “a widely-used general-purpose scripting language that is especially suited for Web development.” It is freely available for download at http://www.php.net. libcURL is a library that simplifies server to server communication, the latest version can be downloaded from http://curl.haxx.se/download.html. OpenSSL has become the most popular library for implementing SSL encryption. The latest version can be downloaded from http://www.openssl.org/. If you are compiling PHP yourself, make sure to include –with-curl and –with-openssl in your configuration line.
A “verify_install.php” script has been included that will help you check that your server is properly configured to use the php library. To use this script you must first edit it, filling in the correct path to usaepay.php. If you upload both usaepay.php and verify_install.php to the same directory, you can usaually set the include to: include ”./usaepay.php”; Once you have modified the script, upload both usaepay.php and verify_install.php to your webserver. Finally, go to the verify_install.php script in your webbrowser. The script will check your installation and recommend solutions to any problems it encounters.
If your server must send outgoing traffic through a proxy, set the property proxyurl to the url of your proxy server. Make sure to include port if not on port 80. Example: http://proxy.mycompany.com:3128
$tran->proxyurl="http://proxy.mycompany.com:3128";
If the SSL certificate path test failed, its possible that curl is not correctly configured to use this bundle. You can correct the problem by add the following code to your script:
$tran->cabundle='<?php echo $certpath?>';
It is also possible that your root CA bundle is out dated. You can find out when the root CA bundle was last updated by adding the following code to your script:
<?php echo date("m/d/y", filemtime($certpath))?>
You can download a new file from: curl-ca-bundle.zip
I reviewed the usaepay documentation and downloaded the test files to make sure everything will run on our web server. The file: “verify_install.php” runs with no problem and shows an “OK” in each category. However, I cannot successfully run the file “example.php”. It returns the following:
Please Wait One Moment While We process your card.
Card Declined (Error)
Reason: Specified source key not found.
The source key “897asdfjha98ds6f76324hbmnBZc9769374ybndfs876” is a dummy key used for the example. Please generate your key at usaepay.com when you log into your USAePay Merchant Console. You can also generate keys from the test server however remember to change the gatewayurl property.
This is a modified Sale example to process a Multi-Currency (MCP) Transaction. The customer's creditcard will be authorized for the amount specified and placed in the batch for settlement. Once the batch is settled, the funds will be transferred to the merchant's account. Please note: unless merchants have configured their batch to auto close, they will need to log into usaepay.com to close their batch.
<?php
include "/usr/local/lib/php/usaepay.php";
$tran=new umTransaction;
$tran->key="897asdfjha98ds6f76324hbmnBZc9769374ybndfs876"; //Place your source key here
$tran->ip=$REMOTE_ADDR; // This allows fraud blocking on the customers ip address
$tran->testmode=1; // Change this to 0 for the transaction to process
$tran->card="5100019780009781"; // card number, no dashes, no spaces
$tran->exp="0109"; // expiration date 4 digits no /
$tran->currency = "392"; // international currency, full list of codes: http://wiki.usaepay.com/developer/currencycode
$tran->amount="1.00"; // charge amount in dollars
$tran->invoice="1234"; // invoice number. must be unique.
$tran->cardholder="Mr. Multi Currency"; // name of card holder
$tran->street="1234 Main Street"; // street address
$tran->zip="05673"; // zip code
$tran->description="Online Order"; // description of charge
$tran->cvv2="435"; // cvv2 code
echo "<h1>Please wait one moment while we process your card...<br>\n";
flush();
if($tran->Process())
{
echo "<b>Card Approved</b><br>";
echo "<b>Authcode:</b> " . $tran->authcode . "<br>";
echo "<b>AVS Result:</b> " . $tran->avs . "<br>";
echo "<b>Cvv2 Result:</b> " . $tran->cvv2 . "<br>";
echo "<b>Converted Amount:</b> ". $tran->convertedamount . "<br>";
echo "<b>Converted Amount Currency:</b> ". $tran->convertedamountcurrency . "<br>";
echo "<b>Conversion Rate:</b> ". $tran->conversionrate . "<br>";
} else {
echo "<b>Card Declined</b> (" . $tran->result . ")<br>";
echo "<b>Reason:</b> " . $tran->error . "<br>";
if($tran->curlerror) echo "<b>Curl Error:</b> " . $tran->curlerror . "<br>";
}
?>
The most common transaction is a Sale. The customer's creditcard will be authorized for the amount specified and placed in the batch for settlement. Once the batch is settled, the funds will be transferred to the merchant's account. Please note: unless merchants have configured their batch to auto close, they will need to log into usaepay.com to close their batch.
<?php
include "/usr/local/lib/php/usaepay.php";
$tran=new umTransaction;
$tran->key="897asdfjha98ds6f76324hbmnBZc9769374ybndfs876";
$tran->ip=$REMOTE_ADDR; // This allows fraud blocking on the customers ip address
$tran->testmode=1; // Change this to 0 for the transaction to process
$tran->card="4005562233445564"; // card number, no dashes, no spaces
$tran->exp="0102"; // expiration date 4 digits no /
$tran->amount="1.00"; // charge amount in dollars
$tran->invoice="1234"; // invoice number. must be unique.
$tran->cardholder="Test T Jones"; // name of card holder
$tran->street="1234 Main Street"; // street address
$tran->zip="05673"; // zip code
$tran->description="Online Order"; // description of charge
$tran->cvv2="435"; // cvv2 code
echo "<h1>Please wait one moment while we process your card...<br>\n";
flush();
if($tran->Process())
{
echo "<b>Card Approved</b><br>";
echo "<b>Authcode:</b> " . $tran->authcode . "<br>";
echo "<b>AVS Result:</b> " . $tran->avs . "<br>";
echo "<b>Cvv2 Result:</b> " . $tran->cvv2 . "<br>";
} else {
echo "<b>Card Declined</b> (" . $tran->result . ")<br>";
echo "<b>Reason:</b> " . $tran->error . "<br>";
if($tran->curlerror) echo "<b>Curl Error:</b> " . $tran->curlerror . "<br>";
}
?>
The Auth Only transaction is extremely useful for companies that do not ship products right away. The gateway will authorize the charge but instead of putting the charge into the merchant's batch, the charge is placed on the Queued Transactions screen. This allows a merchant to verify that the customer's card is good and that they have the funds available. The merchant then has up to 30 days (depending on their bank) to “capture” the transaction once they are ready to ship the merchandise. There are two ways in which the transaction can be moved from the queued transactions screen to the current batch: 1) the merchant can log into www.usaepay.com and go to the queued transactions screen and select capture; 2) the transaction can be captured via the PHP API. If you are planning on capturing transactions via the PHP API, make sure to record the value of the refnum field. (See Capture Example)
<?php
include "/usr/local/lib/php/usaepay.php";
$tran=new umTransaction;
$tran->key="897asdfjha98ds6f76324hbmnBZc9769374ybndfs876";
$tran->ip=$REMOTE_ADDR; // This allows fraud blocking on the customers ip address
$tran->testmode=1; // Change this to 0 for the transaction to process
$tran->command="authonly"; // This tells the server to queue the transaction after authorizing it.
$tran->card="4005562233445564"; // card number, no dashes, no spaces
$tran->exp="1212"; // expiration date 4 digits no /
$tran->amount="1.00"; // charge amount in dollars
$tran->invoice="1234"; // invoice number. must be unique.
$tran->cardholder="Test T Jones"; // name of card holder
$tran->street="1234 Main Street"; // street address
$tran->zip="05673"; // zip code
$tran->description="Online Order"; // description of charge
$tran->cvv2="435"; // cvv2 code
echo "<h1>Please wait one moment while we process your card...<br>\n";
flush();
if($tran->Process())
{
echo "<b>Card Approved</b><br>";
echo "<b>Authcode:</b> " . $tran->authcode . "<br>";
echo "<b>AVS Result:</b> " . $tran->avs . "<br>";
echo "<b>Cvv2 Result:</b> " . $tran->cvv2 . "<br>";
} else {
echo "<b>Card Declined</b> (" . $tran->result . ")<br>";
echo "<b>Reason:</b> " . $tran->error . "<br>";
if($tran->curlerror) echo "<b>Curl Error:</b> " . $tran->curlerror . "<br>";
}
?>
This command allows you to capture a previously authorized charge. An example of this would be a shopping cart that uses an order management system. When a customer places an order, the transaction is authorized and then queued. The merchant then logs into the shopping cart and marks the order as “Shipped.” The shopping cart then tells USAePay to capture that transaction. To capture the transaction via the API, you must have the refnum returned during the original authorization. This value should be stored on the merchant's server.
<?php
include "/usr/local/lib/php/usaepay.php";
$tran=new umTransaction;
$tran->key="897asdfjha98ds6f76324hbmnBZc9769374ybndfs876";
$tran->ip=$REMOTE_ADDR; // This allows fraud blocking on the customers ip address
$tran->testmode=1; // Change this to 0 for the transaction to process
$tran->command="capture"; // This tells the server to move the transaction from the queued status to the currently open batch
$tran->refnum="$refnum"; // the original ref number received during the authonly
echo "<h1>Please wait one moment while we capture the charge...<br>\n";
flush();
if($tran->Process())
{
echo "<b>Transaction Captured</b><br>";
echo "<b>Authcode:</b> " . $tran->authcode . "<br>";
echo "<b>AVS Result:</b> " . $tran->avs . "<br>";
echo "<b>Cvv2 Result:</b> " . $tran->cvv2 . "<br>";
} else {
echo "<b>Unable to capture transaction</b> (" . $tran->result . ")<br>";
echo "<b>Reason:</b> " . $tran->error . "<br>";
if($tran->curlerror) echo "<b>Curl Error:</b> " . $tran->curlerror . "<br>";
}
?>
The CreditVoid command allows you to “credit back” or “void out” a transaction based on the original transaction reference number. The command automatically checks the status of the transaction, if the transaction has been settled then a credit (for all or part of the initial transaction) is entered into the current batch. If the transaction has not been settled then it will be voided (removed from the current settlement batch). The only required property for this command is the refnum property. The amount specified must be equal to or less than the original transaction. If no amount is specified, the full amount will be refunded. Note: for security reasons, this command requires that a pin be configured on the source key.
<?php
include "/usr/local/lib/php/usaepay.php";
$tran=new umTransaction;
$tran->key="897asdfjha98ds6f76324hbmnBZc9769374ybndfs876";
$tran->pin="1234";
$tran->ip=$REMOTE_ADDR; // This allows fraud blocking on the customers ip address
$tran->testmode=0; // Change this to 0 for the transaction to process
$tran->command="creditvoid";
$tran->refnum="$refnum"; // the original ref number received during the authorization
echo "<h1>Please wait one moment while we refund/void the charge...<br>\n";
flush();
if($tran->Process())
{
echo "<b>Transaction Refunded</b><br>";
} else {
echo "<b>Unable to refund transaction</b> (" . $tran->result . ")<br>";
echo "<b>Reason:</b> " . $tran->error . "<br>";
if($tran->curlerror) echo "<b>Curl Error:</b> " . $tran->curlerror . "<br>";
}
?>
| Property | Description |
| cabundle | Override the default location of the SSL root CA bundle. |
| proxyurl | If your server must send outgoing traffic through a proxy, set this property to the url of your proxy server. Make sure to include port if not on port 80. Example: http://proxy.mycompany.com:3128 |
| gatewayurl | Optional. Allows you to override the default gateway url of https://www.usaepay.com/gate. To use the secondary server pools set the url to https://www-11.usaepay.com/gate or https://www-03.usaepay.com/gate or or https://www-02.usaepay.com/gate |
| ignoresslcerterrors | Optional. Set true to ignore any errors encountered while verifying the gateway's ssl certificate. Only use this setting as a temporary work around for servers that do not have a proper ca bundle file installed. |
| General Properties |
| key | Source Key generated by the Merchant Console at www.usaepay.com. |
| pin | Pin for Source Key. This field is required only if the merchant has set a Pin in the merchant console. |
| command | Command to run; Possible values are: cc:sale, cc:authonly, cc:capture, cc:credit, cc:postauth, check:sale, check:credit, void, refund and creditvoid Default is cc:sale. |
| card | Credit Card Number with no spaces or dashes. |
| exp | Expiration Date in the form of MMYY with no spaces or punctuation. |
| amount | Charge amount without $. The amount field should include the total amount to be charged, including sales tax. |
| currency | Currency of “amount.” Required if using a MCP based account. Must be one of the 3 digit numeric codes found here. |
| tax | The portion of amount that is sales tax. |
| tip | The portion of amount that is tip. |
| shipping | Shipping charges. |
| discount | Discount amount (ie gift certificate or coupon). |
| subtotal | Order subtotal. If set, then subtotal + tip + shipping - discount + tax must equal amount or the transaction will be declined. If subtotal is left blank, it will be ignored. |
| invoice | Unique ticket, invoice or order number. 10 digits. |
| orderid | Unique order identifier. Used to reference the order to which the transaction corresponds. This field can contain up to 64 characters and should be used instead of invoice when orderids longer that 10 digits are needed. |
| ponum | Customer purchase order number. Only required for commercial cards. |
| origauthcode | Originating Auth Code, required when running the postauth command. Typically used when a voice authorization is obtained. |
| custid | Alpha-numeric code that uniquely identifies the customer. |
| cardholder | Name as it appears on the creditcard. |
| street | Street Address for use in AVS check |
| zip | Zipcode for AVS check |
| description | Charge description (optional). |
| cvv2 | CVC/CVV2 code (optional). |
| custemail | Customer Email address (optional). |
| custreceipt | Send a customer receipt. Note, this will override the source setting. (defaults to no) |
| ignoreduplicate | Suppresses the duplicate folding feature. |
| ip | IP Address of client browser, used for fraud checks. (optional) |
| timeout | Sets how long to wait, in seconds, for a reply from the gateway before returning an error. (optional, defaults to 45 seconds) |
| software | Allows developers to send the name and version of their application in to the gateway. |
| testmode | Use testmode. If set to yes then the transaction will be simulated but not actually processed. (optional, defaults to no) |
| usesandbox | If set to true will use the sandbox server. Overrides the gatewayurl parameter |
| transport | Override the connection library used. Either 'curl' or 'stream'. By default the library will be selected automatically. |
| Card Present Transactions |
| cardpresent | Marks transaction as a card present transaction. true or false |
| magstripe | Track 1, Track 2 or both Tracks read from credit card. |
| dukpt | DUK/PT key for Pin-Debit transactions. The first 16 characters are the encrypted pin block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the Pin Pad serial number and transaction counter. |
| termtype | The type of terminal being used: Optons are POS (cash register), StandAlone (self service terminal), Unattended (ie gas pump), Unkown. (defaults to Unknown) |
| magsupport | Support for mag stripe reader: yes, no, contactless or unknown (default is unknown unless magstripe has been sent) |
| contactless | Magstripe was read via contactless swiper: yes or no (default is no) |
| signature | Raw cardholder signature captured by pos device. (does not need to be encoded) |
| Electronic Check Transactions |
| routing | Bank routing number. Required for check transactions. |
| account | Bank account number. Required for check transactions. |
| dlnum | Driver's License Number. Required for check transactions if not using SSN. |
| dlstate | Driver's License Issuing State. Required for check transactions if not using SSN. |
| checknum | The checknumber. (optional) |
| Recurring Billing |
| recurring | Save as a recurring transaction. (Yes/No) |
| schedule | How often to run the transaction. Possible values are: daily, weekly, biweekly, monthly, bimonthly, quarterly, biannually, annually. Default is monthly. |
| numleft | The number of times to left in billing cycle. Either a number or * for unlimited. (default is *) |
| start | When to start the schedule. Must be in YYYYMMDD format. To begin one billing period from today, set to “next.” (For example, if today is 5/1/2007 and schedule is “monthly” the recurring billing will start on 6/1/2007.) If left blank, default is “tomorrow.” |
| end | When to stop running transactions. Default is to run forever. If both end and numleft are specified, transaction will stop when the earliest condition is met. |
| billamount | Optional recurring billing amount. If not specified, the amount field will be used for future recurring billing charges. |
| billtax | Optional recurring billing tax. If not specified, the tax field will be used for future recurring billing charges. |
| billsourcekey | If set to true, for future recurring billing charges will be run using the same source key as the original transaction. By default recurring charges run using a source key labeled “Recurring”. |
| Cardholder Authorization (Verified By Visa and Mastercard SecureCode) |
| cardauth | Enables Cardholder Authentication. The merchant must have a Cardinal Commerce account enabled in the gateway. If they don't have an account, this field will be ignored and the transaction will be processed normally (without authentication). Set cardauth=1 to enable cardholder authentication, set cardauth=0 to disable authentication. (defaults to disabled) |
| pares | The authentication response received from an independent authentication site. |
| Billing Address Fields |
| billfname |
| billlname |
| billcompany |
| billstreet |
| billstreet2 |
| billcity |
| billstate |
| billzip |
| billcountry |
| billphone |
| email |
| fax |
| website |
| Shipping Address Fields (optional) |
| shipfname |
| shiplname |
| shipcompany |
| shipstreet |
| shipstreet2 |
| shipcity |
| shipstate |
| shipzip |
| shipcountry |
| shipphone |
| Function | Description |
| CheckData | Check data for errors. (runs automatically during the Process function) |
| Process | Runs the transaction. Return true on Approved and false on Declined or Error. |
| Test | Tests PHP installation. If errors are detected, suggested solutions will be displayed. |
| Property | Description |
| result | Full result: Approved, Declined, Error or Verification |
| resultcode | Single character result code: A,D,E or V |
| authcode | Authorization Code |
| refnum | Reference Number |
| batch | Batch Number |
| avs_result | The result of the AVS check. |
| cvv2_result | The result of the CVV2 check. |
| vpas_result_code | The result of the cardholder authentication (CAVV) |
| isduplicate | When the duplicate folding feature is enabled, this will indicate when a transaction has been marked as a duplicate. All transaction data returned (authcode, refnum, etc), is from the original transaction. |
| error | Error if transaction is not approved. |
| errorcode | Numerical error code. |
| transporterror | This will contain any underlying connection errors received (useful for debugging curl/ssl installation). |
| acsurl | If the result was Verification, this field will contain the url that the customer must be sent to for authentication. |
| pareq | Contains the encrypted authentication request. This must be posted to the above url as the field “PaReq”. |
| convertedamount | Amount converted to merchant's currency, when using a multi-currency processor. |
| convertedamountcurrency | Merchant's currency, when using a multi-currency processor. |
| conversionrate | Conversion rate used to convert currency, when using a multi-currency processor. |
| custnum | Customer reference number assigned by gateway for recurring transactions only. |
ver. 1.5.5 -> 1.6.0:
Added dukpt property for Pin Debit transacitons
Added comments property
Added signature property
Added sandbox property
Added transport property
Renamed curlerror to transporterror
8/28/08
ver. 1.5.4 -> 1.5.5:
Added billtax
Added billsourcekey
Added proxyurl
08/27/07
ver. 1.5.3 -> 1.5.4:
Added custnum
Added contactless
Updated magsupport to include contactless option
05/15/07
ver. 1.5.1 -> 1.5.3:
Added checknum property
05/06/07
ver. 1.5.0 -> 1.5.1:
Added currency conversion response properties
Fix ignoreduplicates property
01/19/07
ver. 1.4.3 -> 1.5.0:
Added currency property
Added ignoreduplicates property and isduplicate result property
Added support for creditvoid command
01/17/07
ver. 1.4.2 -> 1.4.3:
Added cabundle property
Added Test() function to diagnose installation issues
11/11/05
