ePayment Form v2.13.0

The payment form allows a merchant 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.

[TODO: write better intro]

If you need to provide your customers with a link that directs them to our secure ePayment form the customer can click on a direct link, or the merchant's site can redirect the customer to a URL in the following format:

https://www.usaepay.com/interface/epayform/[key]/[command]?UMamount=[amount]&UMinvoice=[invoice]&UMmd5hash=[hash]

Where [key] is the source key copied from the sources screen, [command] is either sale, credit or authonly, [amount] is the total monetary amount of the transaction, [invoice] is the invoice or order number and [hash] is the md5hash pin (See Source Pin Code). Pin and hash are optional.

• Simple sale form with a hard-coded final amount of 100.00
  • https://www.usaepay.com/interface/epayform/aJxT847qH_YOUR_SOURCE_KEY_6GK3QW3/sale?&UMamount=100.00
• Simple authorization only form with a hard-coded final amount of 100.00
  • https://www.usaepay.com/interface/epayform/aJxT847qH_YOUR_SOURCE_KEY_6GK3QW3/authonly?&UMamount=100.00
• Simple authorization only form with a hard-coded final amount of 100.00, a description of “ePaymentForm, and the Order Number 123456
  • https://www.usaepay.com/interface/epayform/aJxT847qH_YOUR_SOURCE_KEY_6GK3QW3/authonly?&UMamount=100.00&UMdescription=ePaymentForm&UMinvoice=123456

The customer can also post data directly to the payment form. The merchant's website would just need to present the customer with an HTML page containing the following form:

<form action="https://www.usaepay.com/interface/epayform/">
<input type="hidden" name="UMkey" value="[key]">
<input type="hidden" name="UMcommand" value="sale">
<input type="hidden" name="UMamount" value="[amount]">
<input type="hidden" name="UMinvoice" value="[invoice]">
<input type="hidden" name="UMmd5hash" value="[hash]">
<input type="submit" value="Continue to Payment Form">
</form>

Any of the form fields, will be managed by the API. If you create a custom payment form, you must make sure to include a hidden form field for any field you wish to pass through to the API.

If the amount will not be fixed, but will instead be entered manually by the merchant, change the input type from “hidden” to “text” as shown below:

<form action="https://www.usaepay.com/interface/epayform/">
<input type="hidden" name="UMkey" value="[key]">
<input type="hidden" name="UMcommand" value="sale">
<input type="text" name="UMamount" value="[amount]">
<input type="hidden" name="UMinvoice" value="[invoice]">
<input type="hidden" name="UMmd5hash" value="[hash]">
<input type="submit" value="Continue to Payment Form">
</form>

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.