Downloads

Download Latest Version

Library Overview

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

System Requirements

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.

Trouble Shooting

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.

Shared hosting environments are NOT recommended for this integration unless given full access to install/modify files.

Shared hosting environment requires a proxy server URL

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

:::php
$tran->proxyurl="http://proxy.mycompany.com:3128";

Unable to find SSL certificate path

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:

:::php
$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
`<?php echo date("m/d/y", filemtime($certpath))?>`

You can download a new file from: http://curl.haxx.se/ca/cacert.pem

Specified Source Key Not Found

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 "_U88GQ3F4A64h5QH82x26DhuBfB1aH5C" is a dummy Sandbox key with Pin: "1234" 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 "usesandbox" property.

Examples

Example: Sale

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
<?php

include "./usaepay.php";    // Change this path to the location you have save usaepay.php

$tran=new umTransaction;

$tran->key="_U88GQ3F4A64h5QH82x26DhuBfB1aH5C";      // Your Source Key
$tran->pin="1234";      // Source Key Pin
$tran->usesandbox=true;     // Sandbox true/false
$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="cc:sale";    // Command to run; Possible values are: cc:sale, cc:authonly, cc:capture, cc:credit, cc:postauth, check:sale, check:credit, void, void:release, refund, creditvoid and cc:save. Default is cc:sale.

$tran->card="4000100011112224";     // card number, no dashes, no spaces
$tran->exp="0919";          // 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="123";          // 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>RefNum:</b> " . $tran->refnum . "<br>";
    echo "<b>AVS Result:</b> " . $tran->avs_result . "<br>";
    echo "<b>Cvv2 Result:</b> " . $tran->cvv2_result . "<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>";
}       
?>

Example: Auth Only (Queued Transaction)

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
<?php

include "./usaepay.php";    // Change this path to the location you have save usaepay.php

$tran=new umTransaction;

$tran->key="_U88GQ3F4A64h5QH82x26DhuBfB1aH5C";      // Your Source Key
$tran->pin="1234";      // Source Key Pin
$tran->usesandbox=true;     // Sandbox true/false
$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="authonly";    // Command to run; Possible values are: cc:sale, cc:authonly, cc:capture, cc:credit, cc:postauth, check:sale, check:credit, void, void:release, refund, creditvoid and cc:save. Default is cc:sale.

$tran->card="4000100011112224";     // card number, no dashes, no spaces
$tran->exp="0919";          // 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="123";          // 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>RefNum:</b> " . $tran->refnum . "<br>";
    echo "<b>AVS Result:</b> " . $tran->avs_result . "<br>";
    echo "<b>Cvv2 Result:</b> " . $tran->cvv2_result . "<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>";
}       
?>

Example: Capture (Queued Transaction)

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
<?php

include "./usaepay.php";    // Change this path to the location you have save usaepay.php

$tran=new umTransaction;

$tran->key="_U88GQ3F4A64h5QH82x26DhuBfB1aH5C";      // Your Source Key
$tran->pin="1234";      // Source Key Pin
$tran->usesandbox=true;     // Sandbox true/false
$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="capture";    // Command to run; Possible values are: cc:sale, cc:authonly, cc:capture, cc:credit, cc:postauth, check:sale, check:credit, void, void:release, refund, creditvoid and cc:save. Default is cc:sale.

$tran->refnum="60557362";   // Specify refnum of the transaction that you would like to capture.


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>RefNum:</b> " . $tran->refnum . "<br>";
    echo "<b>AVS Result:</b> " . $tran->avs_result . "<br>";
    echo "<b>Cvv2 Result:</b> " . $tran->cvv2_result . "<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>";
}       
?>

Example: Void/Void:Release

The void:release command cancels a pending transaction. For credit card transactions, this command removes the transaction from the current batch. For ACH check transactions, the transaction is removed from the file that is sent to the bank. In both cases, there is a limited amount of time that a void may be run. For credit cards, a transaction can no longer be voided once the batch has been closed. For checks, a transaction can no longer be voided once the file has been sent to bank. This typically happens at the end of each business day. The void requires that the original transaction reference number be passed in the refnum field. Difference between Void and void:release is that void:release speeds up the process of releasing customer's funds.

:::php
<?php

include "./usaepay.php";    // Change this path to the location you have save usaepay.php

$tran=new umTransaction;

$tran->key="_U88GQ3F4A64h5QH82x26DhuBfB1aH5C";      // Your Source Key
$tran->pin="1234";      // Source Key Pin
$tran->usesandbox=true;     // Sandbox true/false
$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="void"; * void command cancels a pending transaction. $tran->command="void:release"; // void:release speeds up the process of releasing customer's funds.

$tran->refnum="60557436";       // Specify refnum of the transaction that you would like to capture.


echo "`<h1>`Please wait one moment while we process your request...`<br>`\n";
flush();

if($tran->Process())
{
    echo "<b>Request Approved</b><br>";
    echo "<b>Authcode:</b> " . $tran->authcode . "<br>";
    echo "<b>RefNum:</b> " . $tran->refnum . "<br>";
    echo "<b>AVS Result:</b> " . $tran->avs_result . "<br>";
    echo "<b>Cvv2 Result:</b> " . $tran->cvv2_result . "<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>";
}       
?>

Example: CreditVoid

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
<?php

include "./usaepay.php";    // Change this path to the location you have save usaepay.php

$tran=new umTransaction;

$tran->key="_U88GQ3F4A64h5QH82x26DhuBfB1aH5C";      // Your Source Key
$tran->pin="1234";      // Source Key Pin
$tran->usesandbox=true;     // Sandbox true/false
$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";    // Command to run; Possible values are: cc:sale, cc:authonly, cc:capture, cc:credit, cc:postauth, check:sale, check:credit, void, void:release, refund, creditvoid and cc:save. Default is cc:sale.

$tran->refnum="60557362";   // Specify refnum of the transaction that you would like to capture.


echo "`<h1>`Please wait one moment while we process your request...`<br>`\n";
flush();

if($tran->Process())
{
    echo "<b>Request Approved</b><br>";
    echo "<b>Authcode:</b> " . $tran->authcode . "<br>";
    echo "<b>RefNum:</b> " . $tran->refnum . "<br>";
    echo "<b>AVS Result:</b> " . $tran->avs_result . "<br>";
    echo "<b>Cvv2 Result:</b> " . $tran->cvv2_result . "<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>";
}       
?>

Example: Multi-Currency Sale

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
<?php

include "./usaepay.php";    // Change this path to the location you have save usaepay.php

$tran=new umTransaction;

$tran->key="_U88GQ3F4A64h5QH82x26DhuBfB1aH5C";      // Your Source Key
$tran->pin="1234";      // Source Key Pin
$tran->usesandbox=true;     // Sandbox true/false
$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="cc:sale";    // Command to run; Possible values are: cc:sale, cc:authonly, cc:capture, cc:credit, cc:postauth, check:sale, check:credit, void, void:release, refund, creditvoid and cc:save. Default is cc:sale.

$tran->card="4000100011112224";     // card number, no dashes, no spaces
$tran->exp="0919";          // expiration date 4 digits no /
$tran->amount="1.00";           // charge amount in dollars
$tran->currency = "840";        // international currency, full list of codes: https://help.usaepay.info/developer/reference/currencycodes/
$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="123";          // 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>";
}       
?>

Example: QuickSale

:::php
<?php

include "./usaepay.php";    // Change this path to the location you have save usaepay.php

$tran=new umTransaction;

$tran->key="_U88GQ3F4A64h5QH82x26DhuBfB1aH5C";      // Your Source Key
$tran->pin="1234";      // Source Key Pin
$tran->usesandbox=true;     // Sandbox true/false
$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->amount="10.00";          // charge amount in dollars
$tran->invoice="1234";          // invoice number.  must be unique.
$tran->description="Online Order";  // description of charge
$tran->refnum="60557422"; //refnum


echo "`<h1>`Please wait one moment while we process your card...`<br>`\n";
flush();

if($tran->ProcessQuickSale())
{
    echo "<b>Card Approved</b><br>";
    echo "<b>Authcode:</b> " . $tran->authcode . "<br>";
    echo "<b>RefNum:</b> " . $tran->refnum . "<br>";
    echo "<b>AVS Result:</b> " . $tran->avs_result . "<br>";
    echo "<b>Cvv2 Result:</b> " . $tran->cvv2_result . "<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>";
}       
?>

Example: cc:save

:::php
<?php

include "./usaepay.php";    // Change this path to the location you have save usaepay.php

$tran=new umTransaction;

$tran->key="_U88GQ3F4A64h5QH82x26DhuBfB1aH5C";      // Your Source Key
$tran->pin="1234";      // Source Key Pin
$tran->usesandbox=true;     // Sandbox true/false

$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="cc:save";    // Command to run; Possible values are: cc:sale, cc:authonly, cc:capture, cc:credit, cc:postauth, check:sale, check:credit, void, refund, creditvoid and cc:save. Default is cc:sale.

$tran->card="4000100011112224";     // card number, no dashes, no spaces
$tran->exp="0919";          // 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="123";          // 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>CardRef:</b> " . $tran->cardref . "<br>";
    echo "<b>AVS Result:</b> " . $tran->avs_result . "<br>";
    echo "<b>Cvv2 Result:</b> " . $tran->cvv2_result . "<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>";
}       
?>

Reference Tables

Read/Write Properties
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-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, void:release, refund, creditvoid and cc:save. Default is cc:sale.
allowpartialauth Yes/No. Indicates whether to allow a partial authorization if the full UMamount is not available (for debit, prepaid and gift cards). If left blank or set to No, the transaction will be automatically canceled and reversed if full UMamount is not available
ifauthexpired controls what happens when capturing an authorization that has expired. Options are 'ignore','error','reauth'.
authexpiredays Set the number of days an authorization is valid for. Defaults to merchant account settings.
inventorylocation Set the warehouse to pull inventory from. defaults to source key setting.
card Credit Card Number with no spaces or dashes.
savecard If set to true and the transaction has been approved, the system will issue a token for future use.
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.
nontaxable Set to yes if transaction is not taxable. (optional, platform dependent)
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)
custreceiptname Use a custom email receipt template
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.
clerk Indicates the clerk/person processing transaction, for reporting purposes. (optional)
terminal Indictes the terminal used to process transaction, for reporting purposes. (optional)
restaurant_table Indicates the restaurant table, for reporting purposes. (optional)
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)
checkimage_front JPG image of front side of check. (optional). Use raw image data, do not encode using base64
checkimage_back JPG image of back side of check. (optional)
auxonus Aux On US for check 21
epccode EPC Code for check 21
Customer Database and Recurring Billing
addcustomer If set to yes and the transaction has been approved, the system will create a new customer record and store the payment information for future use. (Yes/No)
schedule How often to run the transaction. Possible values are: daily, weekly, biweekly, monthly, bimonthly, quarterly, biannually, annually. Default is monthly. If you do not want to enable recurring billing for this customer, set schedule="disabled"
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
Custom Data Fields (optional)
custom1
custom2
custom3
custom4
custom5
custom6
custom7
custom8
custom9
custom10
custom11
custom12
custom13
custom14
custom15
custom16
custom17
custom18
custom19
custom20
Functions
Functions Description
Process Runs the transaction. Return true on Approved and false on Declined or Error.
addLine Add lineitem data to transaction
getLineTotal Method for calculating the total amount of the lines.
clearLines Remove all lineitem data
clearData Clear all transaction properties but retain the key, pin, software and gatewayurl
ProcessQuickSale Run a sale by referencing a previous sale (refnum must be set). No credit card or check data is required.
ProcessQuickCredit Run a refund by referencing a previous sale (refnum must be set). No credit card or check data is required.
CheckData Check data for errors. (runs automatically during the Process function)
Test Tests PHP installation. If errors are detected, suggested solutions will be displayed.
Read Properties
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
cardref Card reference token. 16-19 digit alphanumeric string. It is returned with dashes but it is not required that these be stored.
batch Batch Number
avs_result The result of the AVS check.
cvv2_result The result of the CVV2 check.
cardlevelresult [developer:cardlevelcodes
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.
procrefnum Transaction Reference number provided by backend processor (platform), blank if not available
balance The balance remaining on some prepaid and stored value cards
authamount Amount authorized. May be less than amount requested if allowpartialauth was set true
Line Items
Line Items Description
refnum (optional) Gateway assigned product RefNum, used for inventory control.
sku Product id, code or SKU
name item name or short description
description Long description
cost Cost of item per unit of measure(before tax and discount)
qty Quantity
taxable Y = Taxable, N = Non-taxable
taxrate Tax rate for line Required for level 3 processing
taxamount Amount of tax charge for line (if left blank will be calculated from taxrate) Required for level 3 processing
um Unit of measure. If left blank or an invalid code is sent, EA (Each) will be used Required for level 3 processing
commoditycode Commodity code Required for level 3 processing
discountrate Discount percentage for line Required for level 3 processing
discountamount Discount amount for line(if left blank will be calculated from discountrate) Required for level 3 processing
taxclass Required for level 3 processing
# Changelog
ver. 1.6.13 -> 1.7.0:
Pass the timeout parameter to gateway for automatic reversal support
Add geolocation parameter for transaction location information
1/25/15

ver. 1.6.12 -> 1.6.13:
Add duty and shipfromzip for level 3 processing
Add savecard parameter for card tokenization,  cardref is result variable
Add void:release command
06/25/13

ver. 1.6.11 -> 1.6.12:
Add ifauthexpired, authexpiredays and inventorylocation
Add level3 data to lineitems
Support cash:refund, external:cc:sale, external:check:sale and external:gift:sale commands
02/26/13

ver. 1.6.10 -> 1.6.11:
Aded clerk, terminal and restaurant_table variables.
Add support for event ticket sales (ticketedevent variable).
Updated addLine() method to support passing line item data as array rather than arg list.
Added getLineTotal() method for calculating the total amount of the lines.
Drop storing the avs and cvv2 results in the avs and cvv2 properties (conflicts with the data being submitted).
Add support for passing the refnum of the product line items (for inventory control).
11/29/11

ver. 1.6.6 -> 1.6.8:
Rewrite ProcessQuickCredit and ProcessQuickSale methods
01/05/11

ver. 1.6.5 -> 1.6.6:
Rewrite transport to only send fields that are set
Add ProcessQuickCredit and ProcessQuickSale methods
Add clearData method to reset all fields
Add response vars authamount, balance, cardlevelresult, procrefnum
Add allowpartialauth property
Add addcustomer property (recurring is still supported, but depreciated)
Add custreceiptname property
Add auxonus and epccode fields for check 21
06/01/10

ver. 1.6.4 -> 1.6.5:
Fix arg_separator.output bug
Added support for lineitem detail
Added custom fields
Added nontaxable property
Added checkimage_front, checkimage_back properties
11/11/08

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