Downloads
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 | |
| 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