CGI Transaction Gateway API v2.13.1

https://www.usaepay.com/gate

https://www.usaepay.com/secure/gate

The gateway API can be accessed in two ways, server-side or client-side, depending on the capabilities of your scripting/cgi platform. The server-side method is safer but requires that your CGI make an SSL connection to the CGI in the background.

The client method is easier to implement but does not offer as strong security as the server method. Most notably it opens your cart to cross-site scripting attacks and could reveal sensitive data via server log files. Before filling any orders placed through a client-side system it is recommended that you double check authorizations against your batch reports.

It is highly recommended that you use the server method if possible. Please check www.usaepay.com/developers.htm, which provides libraries and sample code for further assistance. Even with all of the security features built into the USA ePay gateway, we can only protect a transaction so far. It is essential that web developers take security seriously and check all of their scripts for possible weaknesses.

Client certificate use is also recommended. To require a client certificate use https://www.usaepay.com/secure/gate.php. If you do not want to use client certificates, then you should use https://www.usaepay.com/gate.php.

The server-side method uses the following steps:

1. First, the client's browser submits the check out form securely to https://www.yourcompany.com/yourscript.cgi
2. yourscript.cgi validates the info and preforms any data correction (removing spaces from credit card numbers, etc.)
3. yourscript.cgi opens a connection to https://www.usaepay.com/gate.php and posts the required processing fields (listed below). This connection is created by your server (www.yourcompany.com) not by the client's browser (hence server-side).
4. yourscript.cgi reads the processing result returned by posting to https://www.usaepay.com/gate.php
5. yourscript.cgi then interprets the data and returns the desired result back to the client browser.

The client-side method provides an easy integration into existing forms without the need for extensive CGI programming experience. It does not provide as clean an interface and may cause concern for the end user if they see what appears to be an unfamilliar site handling their credit card information (USA ePay). The following basic steps are used in a client-side transaction:

1. Client browser submits check out form (with required hidden fields) securely to https://www.usaepay.com/gate.php
2. The card is then processed and the results are passed back to your script by redirecting the client browser to http://www.yoursite.com/yourscript.cgi?resultfields
3. yourscript.cgi then interprets the data and returns the desired result back to the client browser.

The following is an example of a client-side method form. (You would have to also write myorderform.cgi.)

<form action="https://www.usaepay.com/gate.php" method="POST">
<input type="hidden" name="UMkey" value="h328dtwj834jhs98d">
<input type="hidden" name="UMredir" value="http://www.mycompany.com/cgi-bin/myorderform.cgi">
<input type="hidden" name="UMinvoice" value="1234">
<input type="hidden" name="UMamount" value="1.00">
First Name: <input type="text" name="fname"><br>
Last Name: <input type="text" name="lname"><br>
Street: <input type="text" name="UMstreet"><br>
City: <input type="text" name="city"><br>
State: <input type="text" name="state"><br>
Zip: <input type="text" name="UMzip"><br>
<br>
<br>
Credit Card Info:<br>
Card Type: <select name=cardtype>
<option>Visa <option>Mastercard <option>Amex</select><br>
Card Number: <input type=text name=UMcard><br>
Expiration: <input type=text name=UMexpir><br>
Name On Card: <input type=text name=UMname><br>
<br>
<br>
<input type=submit value="Place Order">
</form>

If you do not have the programming knowledge needed to write a CGI script, you can use the gateway to manage your results. When a customer's credit card is approved, the gateway will redirect the customer to a specified URL. If the card is declined, the gateway can be set to redirect to the URL of your choice, or display a customizable template. To upload a template, log in at www.usaepay.com, click on Settings, and edit the course for your form. On the source page is a box for “Declined Template.” Paste your HTML into this box.

The following is an example of a client-side method form. This differs from the above example in that you do not need to write a CGI to manage the server response.

<https://www.usaepay.com/gate.php " method="POST">
<input type="hidden" name="UMkey" value="h328dtwj834jhs98d">
<input type="hidden" name="UMredirApproved"
value="http://www.mycompany.com/orderapproved.html">
<input type="hidden" name="UMticket" value="101">
<input type="hidden" name="UMamount" value="1.00">
First Name: <input type="text" name="fname"><br>
Last Name: <input type="text" name="lname"><br>
Street: <input type="text" name="UMstreet"><br>
City: <input type="text" name="city"><br>
State: <input type="text" name="state"><br>
Zip: <input type="text" name="UMzip"><br>
<br>
<br>
Credit Card Info:<br>
Card Type: <select name=cardtype>
<option>Visa
<option>Mastercard
<option>Amex</select><br>
Card Number: <input type=text name=UMcard><br>
Expiration: <input type=text name=UMexpir><br>
Name On Card: <input type=text name=UMname><br>
<br>
<br>
<input type=submit value="Place Order">
</form>

The payment form allows you to send the customer to USAePay for the collection of secure payment information. This eliminates the need for individual merchants to maintain their own SSL certificates. To implement the payment form, the merchant's website needs to redirect the customer to a specially formatted URL or display a form that will post to the USA ePay site. For more information on using the payment form, please see the ePayment Form Manual.

The transaction api is typically used to process credit card sales but it can also accept many other transaction types by changing the UMcommand variable. The following section describes the different commands that are available and the data required for each.

UMcommand=cc:sale

The 'cc:sale' command is the default processing command. If UMcommand is left blank or omitted, the system will use 'cc:sale'. The 'cc:sale' command runs a standard credit card sale. It will charge (debit) the customers credit card for the amount specified. If the charge is successful the transaction will be placed in the merchant's currently open batch for settlement. As long as the merchant has their batch set to autoclose, no further action is required to capture these funds.

UMcommand=cc:authonly

The 'cc:authonly' command runs a credit card authorization. It approved, the funds will be held in the customers account. The funds will remain held until either the transaction is captured and settled, or until the authorization code expires. The length of time before an authorization expires varies from bank to bank but generally it is recommended that the authorization be captured within 24-48 hours. Merchants should consult their merchant service provider for the information specific to their account. If a merchant does not capture the transaction, no funds will be received by the merchant.

UMcommand=cc:capture

The 'cc:capture' command moves previously authorization only transaction into the batch for settlement. The original Transaction ID (refnum) must be passed in UMrefNum field. Additionally, the amount of originally authorized may be adjusted by passing the UMamount field. The tolerences for the settle amount vary depending on the type of Merchant Account and the merchant service provider. The transaction will be placed in the merchant's currently open batch for settlement. As long as the merchant has their batch set to autoclose, no further action is required to capture these funds.

UMcommand=cc:postauth

The 'cc:postauth' command adds a transaction that was authorized outside of the gateway to the current batch. Typically this is used when a merchant obtains a Voice Authorization via the phone. To send a postauth transaction, the merchant must pass in the authorization code that was provided by bank in the UMauthCode field. The transaction will be placed in the merchant's currently open batch for settlement. As long as the merchant has their batch set to autoclose, no further action is required to capture these funds.

UMcommand=cc:credit

The 'cc:credit' command is used to refund money to a credit card. It requires the credit card number and expiration date as well as the amount being refunded. This transaction is also referred to as an “Open Credit”. It does not associate the credit with an existing sale in the system. Some credit card processors do not support open credits. Merchants should verify with their provider before using this command. A safer alternative to the credit command is the “Refund” command. (see below). The credit is placed in the currently open batch. When the batch is closed the credit will be sent to the bank.

UMcommand=check:sale

The 'check:sale' command is used to debit money from a customers checking/savings account via ACH/EFT. To use this feature the merchant must have an account with a support check processor. To process a check:sale, the customer's account number and ABA Routing number must be sent in the UMaccount and UMrouting fields.

UMcommand=Check:Credit

The 'check:credit' command is used to send money to a customers checking/savings account via ACH/EFT. Funds will be transfered from the merchant's account and deposited into the customer's account. To use this feature the merchant must verify with their check processor that they can support this type of transaction. Check:Credit transactions are not designed to be refunds on previous sales but rather to pay a 3rd party. Example uses include paying commissions to resellers or paying vendors/contractors. To refund an existing “Check:Sale” transaction, the “Refund” command (see below) should be used. Due to the risk associated with processing Check:Credit transactions, this command requires the use of a pin on the source key.

UMcommand=void

The 'void' 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 UMrefNum field.

UMcommand=refund

The 'refund' command allows the merchant to refund some or all of a previous sale transaction. It can be used with both credit card and check sales. It requires that the Transaction ID (refnum) of the original sale be submitted in the UMrefNum field along with the amount to be refunded. If the amount is not submitted, then the entire amount of the original sale will be refunded. The refund command will work for both credit card and check transactions. Not all check processors support refunds on checks so Merchants should verify with their provider that they can use this command.

(primarily used in conjunction with client-side method with simple redirection) You can enable automatic emailing of Merchant Receipts for the API gateway by editing your source on www.usaepay.com. Once you have logged into your account, click on “Settings.” Edit the source by clicking on the pencil next to its name and enter the desired email address(es) into the Merchant Receipt field. Separate multiple addresses with commas.

In order to process checks though the API, the merchant must have an account with one of our supported check processors. Please contact technical support if you have any questions about adding check processing capabilities to your account. The fields required for processing checks are: UMkey, UMrouting, UMaccount, UMamount, UMname and identification information. Identification information can either be UMssn (social security number) or UMdlnum and UMdlstate (driver's license number and state of issue).

The API allows you to add customers to a recurring billing cycle through client-side or server-side methods. In order for a customer to be added to a recurring billing cycle the UMrecurring command must be set to yes and the initial charge must be approved. Once the initial charge is approved and the UMrecurring has been set to yes, the customer will automatically be added to a recurring billing cycle. To set the initial amount and the recurring charge to different amounts, use UMamount to the initial charge and UMbillamount to the recurring charge. (If UMbillamount is left empty, UMamount will be the recurring charge.)

The gateway supports VPAS (Verified by Visa) and UCAF (Mastercard Securecode) with both an integrated authentication system and support for third party verification. Using the integrated system provides a quick, easy method for developers to support Verified by Visa and Mastercard Secure Code without requiring complicated XML messaging formats.

To use the integrated solution, the merchant must first have an account with Cardinal Commerce. (If the merchant does not have an account, but requests authentication, the transaction will be handled as if the cardholder is not enrolled in VPAS and/or UCAF.) The following process is required to use the integrated solution:

1. Merchant's site collects cardholder information
2. Merchant's site sends an authorization to gate.php with the UMcardauth flag set to true
3. Gateway checks to see if the cardholder is enrolled in the VPAS and/or UCAF program. If the cardholder has not set a password, the transaction is processed normally (gate.php will return UMstatus=Approved or UMstatus=Declined). If the cardholder does have a password then gate.php will return UMstatus=Verification indicating that the merchant's site needs to prompt the user for a password. In the response, gate.php will also send back UMacsurl and UMpayload.
4. Merchant's site must send the customer's browser to the URL contained in UMacsurl with three get values: PAReq set to the value in UMpayload, TermUrl set to the URL on the merchant's site that will continue the transaction, MD set to some identifying information (such as the order number) that will allow the order to proceed.
5. Customer enters their username and password. If authentication is successful, they will be sent back to TermUrl with the variable PaRes set.
6. Merchant's set sends a second authentication request to the gateway, identical to the one sent in step 2, except that UMpares is set to the value of PaRes.
7. Then gate.php returns Approved or Declined as usual.

If you are using a third party verification system, or implementing the Cardinal Commerce API on the merchant's side, simply pass UMcavv and UMeci with the authentication request. (Please note: UMxid is obsolete and will be ignored.)

To validate transaction authenticity, the merchant can set a pin code for a source. The pin is stored in the merchant's software, or entered manually when the transaction is placed. The pin is not sent to the gateway, but is instead used to create a hash (also known as a fingerprint or message digest) for a transaction. The transaction hash is created by combining the command, the pin, the monetary amount, the invoice, and (optionally) an extra key. This information is separated by colons and run through an md5 algorithm. The algorithm produces a hash, which is then sent to the gateway in the UMmd5hash field where it is matched against the hash from the pin on file. If the two hashes do not match, the transaction is rejected. For example:

  Command: sale
  Pin: sd*s3j002jd
  Amount: 53.21
  Invoice: 34576721

  Data String: sale:sd*s3j002jd:53.21:34576721:
  Hash String: 63e121cc3491f652ad5c6cc31bf10c35 

In this example, the above would be included in the string sent to the gateway:

  UMcommand=sale&UMmd5hash=63e121cc3491f652ad5c6cc31bf10c35&
  UMamount=53.21&UMinvoice=34576721 

Occasionally a merchant may (accidentally or purposefully) send multiple transactions using the same amount and invoice number. To increase the uniqueness of each transaction you can also send a UMmd5key, set to contain some type of random data. The key can be something as simple as a timestamp, or it can contain randomly generated data. The following is a sample implementation in PHP:

<?php
$umcommand = "sale" ;
$umkey = "h328dtwj834jhs98d" ;
$card = "4444111122223337" ;
$expir = "0209" ;
$pin = "hs4rk" ;
$amount = "29.30" ;
$invoice = "45671" ;
 
$hashkey = mktime ();   // mktime returns the current time in seconds since epoch.
$hashdata = $umcommand . ":" . $pin . ":" . $amount . ":" . $invoice . ":" . $hashkey ;
 
$hash = md5 ( $hashdata );   // php includes a built-in md5 function that will create the hash
 
$request = "UMkey=$umkey&UMmd5hash=$hash& UMmd5key=$hashkey&UMamount=$amount&UMinvoice=$invoice" ;
$request .= "&UMcard=$card&UMexpir=$expir" ;
?>

The transaction API can process multiple payments to multiple merchants/source keys in single call. This is useful in cases where a base sale is processed by the merchant and a separate handling fee is processed by another merchant. In the following examples we will use the scenario of a concert where the ticket price is $25 dollars collected by the venue plus a $2 handling fee that is collected by the servicing company. The venue and the servicing company have two separate merchant accounts and two separate source keys.

<form action="https://www.usaepay.com/secure/gate" method="POST">
<!-- Base Information,  Source key for concert venue -->
<input type="hidden" name="UMkey" value="xN05m11zdG2F143mKsanVaFchCLDIib2">
<input type="hidden" name="UMname" value="John Smith">
<input type="hidden" name="UMamount" value="25.00">
<input type="hidden" name="UMdescription" value="Ticket to Concert">
<input type="hidden" name="UMcard" value="4444555566667779">
<input type="hidden" name="UMexpir" value="0909">
<input type="hidden" name="UMstreet" value="1234 Main Street">
<input type="hidden" name="UMzip" value="01029">
 
<!-- Additional Information for Service Fee,  Source key for Service Company -->
<input type="hidden" name="UM02key" value="72FujjW5i1v4DUr75FUiCcSzI039dq4b">
<input type="hidden" name="UM02amount" value="2.00">
<input type="hidden" name="UM02description" value="Servicing Fee">
 
<input type="submit" value="Continue">
</form>

Each additional transaction is defined by adding a numerical index to the base transaction fields. For example, UMkey is the sourcekey for the first transaction and UM02key is the source key for the second transaction. If a third transaction is also going to be run, it can be specified using UM03key. Any fields that are not populated for the second transaction will be copied from the base transaction. For example if UMdescription is set to “Testing” but UM02description is omitted, the system will copy the UMdescription to UM02description. To prevent this from happening, make sure to specify a blank value:

<input type="hidden" name="UMdescription" value="First description">
<input type="hidden" name="UM02description" value="">

While typically this feature will be used to split the payment into just two transactions, it is possible to run up to 100 transactions. Then index number nust always be two digits: UM02key not UM2key.

By default the gateway will stop if it encounters an error in one of the transactions. For example if the ticket fee of $25 is declined, processing stops and the $2 fee is not processed. If you would like to override this behavior, set UMonError=continue. This will cause all transactions to be processed, even if the first one is declined. You may also set UMonError=void, which will void any approvals if subsequent transactions are declined. For example, if the $25 is approved but the $2 service fee is declined, the system would go back and void the $25 approval.

The gateway will return indexed error codes that match the index on the input variables. For example UMauthCode will contain the authcode for the $25 ticket sale and UM02authCode will contain the auth code for the $2 service fee.

<form action="https://www.usaepay.com/gate">
<input type="hidden" name="UMkey" value="LCVG03KGIQ1IexF8cz02ARMN6hWjpYvG"> 
<!-- Enter your source key, above is a dummy key -->
<input type="hidden" name="UMcommand" value="creditvoid"> <!-- Credit / Void command -->
<input type="hidden" name="UMrefNum" value="55001467"> 
<!-- Reference number (transaction ID) of the original transaction -->
<input type="hidden" name="UMinvoice" value="123456">
<input type="hidden" name="UMmd5hash" value="cea9cc2f86f666edda4d855ce523f6ae">
<input type="submit" value="Process CreditVoid">
</form>

Use of a pin is required for this command. In order to complete the process your md5hash value must include the command, the PIN, and the invoice. The data string for this particular example is as follows: creditvoid:1234:123456: resulting in the md5 hash to look like: cea9cc2f86f666edda4d855ce523f6ae

Due to the process referencing an older transaction the UMamount field does not need to be passed or included in the MD5 hash.

Setting UMtestmode to “true” puts the transaction into ”Test Mode”. For more information on what test mode does and credit card numbers to use with test mode, please see the test mode reference page.

These AVS codes are returned in the UMavsResultCode variable, and serve to provide developers with greater control over the AVS system. Many developers may choose to capture and display the UMavsResult variable instead. The UMavsResult variable contains the meaning of the code, rather than the code itself.

The following is a list of result codes for the Address Verification System (AVS) and what each one indicates. The codes listed in the Code column are the most common responses, but depending on the platform being used, codes listed in the Alternates column may be received.

The following is a list of result codes for the CVV2/CVC2/CID verification system and what each one indicates. These codes are returned in the UMcvv2ResultCode variable and provide developers with greater control over the CVV2 system. Many developers choose to capture and display the UMcvv2Result variable instead. The UMcvv2Result variable contains the meaning of the code rather than the code itself.

The card security codes are 3 or 4 digit codes printed or embossed on Visa, Mastercard, American Express and Discover cards. These codes are also referred to as CVV2, CVC, CSC or CCID. Their purpose is to provide additional protection against fraudulent card use. Below is a list of possible result codes.

It is essential that developers pay attention to the version number of the API. The version number is broken up into three positions: compatibility.features.fixes. For example: v2.4.1 The first position (2 in this example) represents the compatibility level. Any application developed with any version 2 of the API will always work with any other revision of version 2. But applications developed with version 3, will not be compatible with version 2.

When a new version of the gateway API is released, the URL will change to keep scripts written on the old version from breaking. The second position (4 in this example) refers to the addition of new fields/features. These features provide additional functionality and are not mandatory. The third position (1 in this example) indicates bug fixes, when nothing structural has changed within the API.

The following is a list of CGI variables that need to be passed to the gateway url. If you are using the client-side method some can be embedded as hidden tags, and others much match your field. An example of a client-side form can be found above.

Note: CC stands for real-time credit card transactions, Checks stands for real-time check processing.

The following fields are only required in participating in the Verified by Visa or Mastercard Secure Code programs:

The following fields are only required in a card present environment such as a retail store, restaurant or hotel.

The following CGI variables are returned to your script along with any other fields you have passed to gate.php. For example, if you pass the variable FavoriteColor, gate.php will echo FavoriteColor back in the response.

  ver. 2.13.0 -> 2.13.1:
  Added support for check:credit transactions
  Reworked the UMcommand variable to make transaction types clearer.
  02/20/08

  ver. 2.12.1 -> 2.13.0:
  Added support for split payments
  Added UMonError for split payments
  01/15/08

  ver. 2.12.0 -> 2.12.1:
  Added UMaccounttype
  Added UMcheckformat
  Fixed storage of initial transaction when customer is created
  01/11/08

  ver. 2.11.2 -> 2.12.0:
  Added UMcustnum
  Added UMcontactless
  Updated UMmagsupport to include contactless option
  05/16/07

  ver. 2.11.1 -> 2.11.2:
  Documented UMchecknum
  05/08/07

  ver. 2.11.0 -> 2.11.1:
  Documented the CAVV=-1 flag for VbV/MC Secure code transactions
  Documented the UMcustom fields
  03/06/07

  ver. 2.10.1 -> 2.11.0:
  Added UMconvertedAmount, UMconvertedAmountCurrency and UMconversionRate
  03/06/07

  ver. 2.10.0 -> 2.10.1:
  Added creditvoid command
  01/29/07

  ver. 2.9.6 -> 2.10.0:
  Added UMcurrency
  01/18/07

  ver. 2.9.5 -> 2.9.6:
  Added UMignoreDuplicate and UMisDuplicate
  11/28/06

  ver. 2.9.4 -> 2.9.5:
  Added custom fields for recurring billing
  Added UMclerk, UMtranterm and UMresttable
  9/12/06

  ver. 2.9.3 -> 2.9.4:
  Copy cardholder from magstrip if not provided in UMname
  5/20/06

  ver. 2.9.2 -> 2.9.3:
  Added UMnontaxable flag for indicating nontaxable instruction
  Added UMvpasResultCode result field with value of vpas aut (platform dependant)
  3/28/05

  ver. 2.9.1 -> 2.9.2:
  UMcustid now saves to the recurring billing customer number field
  12/27/04

  ver. 2.9.0 -> 2.9.1:
  Added next option to UMstart
  Corrected UMversion response variable to return 2.9
  11/23/04

  ver. 2.8.3 -> 2.9.0:
  Added input fields for UMtip, UMshipping, UMdiscount, UMorderid
  Added response field for UMerrorcode
  11/10/04

  ver. 2.8.2 -> 2.8.3:
  Added support for loading check based recurring billing entries
  09/02/04

  ver. 2.8.0 -> 2.8.2:
  Commas are now stripped from amount (ie 4,500.09 will now be handled correctly)
  UMredirDeclined url now gets appended with the result fields.
  04/28/04

  ver. 2.7.1 -> 2.8.0:
  Card present support added with new fields: UMcardpresent, UMmagstripe, 
   UMtermtype, UMmagsupport
  Added UMsoftware field.
  Added UMbatch result field
  03/26/04

  ver. 2.7.0 -> 2.7.1:
  VBV can now be rerun using only UMrefNum
  02/14/04

  ver. 2.6.1 -> 2.7.0:
  Added UMmd5hash and UMmd5key, implementing new source pin feature
  Updated UMversion to 2.7.
  02/07/04

  ver. 2.6.0 -> 2.6.1:
  Fixed api to return RefNum for credits (blank refnum was being returned).
  Fixed void command to void transaction via refnum (this is the recommended 
   way to void a transaction).
  Updated UMversion to 2.6.
  02/07/04

  ver. 2.5.3 -> 2.6.0:
  Fixed API to return AVS and CVV2 results even when error is returned (ie a 
   fraud module block).
  Added new UMavsResultCode and UMcvv2ResultCode fields.
  01/27/04

  ver. 2.5.2 -> 2.5.3:
  Added support for biannually in Recurring Billing schedule method.
  10/22/03

  ver. 2.5.1 -> 2.5.2:
  Added Mastercard UCAF to the Verified by Visa Section. Both are handled identicatlly.
  08/08/03

  ver. 2.5.0 -> 2.5.1:
  Added UMtax and UMponum fields for corporate purchasing cards.
  08/08/03

  ver. 2.4.0 -> 2.5.0:
  Added support for VPAS (Verified by Visa) fields: UMcardauth,UMpares, UMcavv, UMxid and UMeci
  07/26/03

  ver. 2.3.2 -> 2.4.0:
  Added new command "capture" which can be used to settle a transaction that was authorized 
   using the "authonly" command. This differs from the "postauth" command which settles a 
   transaction authorized "offline" (ie telephone authorization). To use capture, the UMrefNum 
   that was obtained from authonly must be passed back.
  The "preauth" command has been rename "authonly" to avoid confusion. "preauth" is still 
   supported for backward compatibility.
  06/25/03

  ver. 2.3.1 -> 2.3.2 :
  UMbillamount added to the Recurring Billing functionality allowing the merchant to separate 
   things like "setup" charge amount from the recurring charge amount.
  03/28/03

  ver. 2.3.0 -> 2.3.1 :
  Recurring Capabilities added via API. Please refer to the Recurring Billing section of the API 
   to the newly added fields.
  11/22/02