Using the Payment Form in Advanced Editing Mode
Customizing the Payment Form
For simple customizations to the payment form, like changing a header or field name, you should not have to use Advanced Editing mode. Click here for more information about simple edits.
To perform advanced edits to your payment form, log into your merchant account and go to Settings -> Payment Forms -> Select the desired form -> Select the 'Template' section -> then select 'Advanced Editing'.
Please Note: Once you choose to use the advanced editor, you will no longer be able to use the template editor for this payment form.
A list of form fields can be found at the bottom of this page. Example templates for common use cases for the form can be found below. Please keep in mind that not all examples will be useful for every merchant. You may need to do further customization once you've added the example code to your form in order to have it function properly. Make sure you've tested your form before you make the link public!
Example code and payment form templates
- Creating a Basic Drop-Down Menu- Add a dropdown menu with numerous options to any field.
- Same As Billing - Add a checkbox which allows customers to copy billing fields over to the shipping fields.
- Duplicate Field - Populates a single text box into two fields.
- Use Billing Names - Fills in card holder Billing first and last name.
- Invoice Number - Generates a random invoice number.
- Radio Button Amount - Amount radio buttons including an optional text box.
- Convenience Fee - Adds convenience fee as flat rate or percentage.
- Discount Code - Use a discount code
- Creating a "Buy Now" Button - Create a "Buy Now" button for your site.
- Relabeling "Pay By Check" Button - Relabeling "Pay By Check" button to "Pay by ACH"
- Add Drop-down Country & State List - Add Dynamic Drop-down Country & State List
- Add ReCaptcha - Add a ReCaptcha to your form to prevent fraud.
- Creating a Swipe Feature - Adds a Swipe button to the form.
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.
|UMcommand||Processing Command. Possible values are: sale, credit, void, creditvoid, authonly, capture, postauth, check and checkcredit. Default is sale.|
|UMkey||x||The source key (assigned by the server when you created a source in your virtual terminal).|
|UMhash||If the source key
|UMignoreDuplicate||Set to yes if you would like to override the duplicate transaction handling.|
|UMauthCode||x||Authorization Code obtained "offline" (ie telephone authorization). Only required for Post Auth.|
|UMcard||CC||Credit Card Number with no spaces or dashes.|
|UMsaveCard||If set to true and the transaction has been approved, the system will issue a token for future use.|
|UMexpir||CC||Expiration Date in the form of MMYY with no spaces or punctuation.|
|UMrouting||Checks||Bank Routing number. Required when
|UMaccount||Checks||Checking Account Number. Required when
|UMaccounttype||The type of account to debit/credit, either “Checking” or “Savings”. If omitted or left blank, it will default to “Checking” Only applies to the Check:Sale and Check:Credit commands.|
|UMamount||x||Charge amount without $. This is the grand total including tax, shipping and any discounts.|
|UMallowPartialAuth||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
|UMtax||Portion of above charge amount
|UMnontaxable||Set to yes if transaction is not taxable. (optional, platform dependant)|
|UMtip||Portion of charge amount
|UMshipping||Portion of above charge amount
|UMduty||Duty charge (Required only for level 3)|
|UMdiscount||The amount of any discounts that were applied.|
|UMsubtotal||The amount of the order before tip, shipping, discount and tax were applied.
|UMcustid||Unique customer id.|
|UMinvoice||Unique Invoice or order number. 10 digits|
|UMorderid||Order identifier. This field can be used to reference the order to which this transaction corresponds. This field can contain up to 64 characters and should be used instead of
|UMponum||Purchase Order number. Only required for corporate purchasing cards.|
|UMticket||Obsolete, included for backward compatibility. Use
|UMdescription||Description of transaction.|
|UMcomments||Optional transaction comments field. Comments are displayed on the transaction details page.|
|UMcvv2||CVV2 data for Visa.|
|UMcustemail||Customer's Email Address.|
|UMcustreceipt||Yes/No. Sends the Customer a Receipt. This overrides the setting for the merchant and source.|
|UMcustreceiptname||Name of the custom receipt template to use. If omitted or if receipt not found, default customer receipt template will be used.|
|UMname||x||Name on card or checking account.|
|UMdlnum||Checks||Driver's license number.|
|UMdlstate||Checks||Driver's license state of issue.|
|UMcheckformat||The ach format of electronic check transaction. Not supported by all check processors. List of ACH formats|
|UMchecknum||Checks||Check number. (optional)|
|UMcheckimagefront||JPG image of front side of check. (optional) If data is encoded, encoding must match
|UMcheckimageback||JPG image of back side of check. (optional) If data is encoded, encoding must match
|UMcheckimageencoding||Encoding method used for check images. (Either base64 or raw). Be careful to avoid double encoding the data! Many check scanners output the image files already in base64 format. No additional encoding is required.|
|UMclerk||Indicates the clerk/person processing transaction, for reporting purposes. (optional)|
|UMtranterm||Indicates the terminal used to process transaction, for reporting purposes. (optional)|
|UMresttable||Indicates the restaurant table, for reporting purposes. (optional)|
|UMip||The IP address of the client requesting the transaction. This is used in many of the fraud modules.|
|UMsoftware||Allows application developers to stamp their application name and version number onto each transaction. Used to assist customers with trouble shooting. (optional)|
|UMredirApproved||Redirection URL - If the card is approved, redirect to this URL. No fields are passed back. Typically merchants should enable merchant receipts with this option. To enable merchant receipts for a source, see Merchant Email Receipts above.|
|UMredirDeclined||Redirection URL - If the card is not approved, redirect to this URL. No fields are passed back. If
|UMechofields||Echo input fields in response. If
|UMonError||Instructs the gateway what to do when a decline is received when multiple transactions are being processed (see "Split Payments" above). Can be set to Stop, Continue or Void. Defaults to "Stop"|
|UMtestmode||If UMtestmode is set to 1 the gateway will simulate a transaction without actually processing the card. All fraud and verification checks are performed.|
|UMcardEncrypted||A solution for supporting both keying in transactions on a payment form and using an encrypted keypad like the sred key device from idtech. The encrypted data can be inserted into the hidden UMcardEncrypted field (with the enc:// prefix) and the masked card can be set in the UMcard field.|
Billing and Shipping Address Fields
|Billing Address||Shipping Address|
Stored Customers and Recurring Billing
UMrecurring is deprecated.
|UMaddcustomer||If set to true, the system will save the customer in the customer database.|
|UMenableRecurring||If set to true, the system will set up a recurring billing schedule entry once the initial transaction has been approved.|
|UMbillamount||Sets the monetary amount to charge on each cycle. If this field is left blank the
|UMschedule||Determines the recurring billing schedule. Possible values are:
|UMnumleft||Number of transactions remaining in recurring billing cycle. If the recurring billing should go on indefinitely, set this to . (defaults to )|
|UMstart||Start date. Default is tomorrow. Must be entered in YYYYMMDD format. If set to
|UMrecurringreceipt||If set to true, the system will turn on the option to email the customer a receipt every time their payment method is charged on recurring.|
|UMcustom[1-20]||Optional fields for storing custom data. This data is stored in customer record not the transaction record.|
Line Item Details
Merchants can pass information about the individual line items that make up an order. This data is visible on the transaction details page. Up to 100 lines may be stored per transaction.
|UMline*sku||32||Product id, code or SKU|
|UMline*name||255||Item name or short description|
|UMline*cost||00000000.00||Cost of item, each|
|UMline*qty||11||Quantity of item, each|
|UMline*taxable||1||Y = Taxable, N = Non-taxable|
Please Note: Replace the * with the line number. For example
CGI Result Variables
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.
|UMstatus||Status of the transaction. The possible values are:
|UMrefNum||Transaction reference number|
|UMbatch||Batch reference number. This will only be returned for sale and auth commands. Please Note: The batch number returned is for the batch that was open when the transaction was initiated. It is possible that the batch was closed while the transaction was processing. In this case the transaction will get queued for the next batch to open.|
|UMavsResult||AVS result in readable format|
|UMavsResultCode||AVS result code.|
|UMcvv2Result||CVV2 result in readable format.|
|UMcvv2ResultCode||CVV2 result code.|
|UMvpasResultCode||Verified by Visa (VPAS) or Mastercard SecureCode (UCAF) result code.|
|UMerror||Error description if
|UMerrorcode||A numerical error code.|
|UMacsurl||Verification URL to send cardholder to. Sent when
|UMpayload||Authentication data to pass to verification url. Sent when
|UMisDuplicate||Indicates whether this transaction is a folded duplicate or not.
|UMconvertedAmount||Amount converted to merchant's currency, when using a a multi-currency processor.|
|UMconvertedAmountCurrency||Merchant's currency, when using a a multi-currency processor.|
|UMconversionRate||Conversion rate used to convert currency, when using a a multi-currency processor.|
|UMcustnum||Customer reference number assigned by gateway. Returned only if
|UMresponseHash||Response verification hash. Only present if response hash was requested in the
Payment Form via POST
The merchant 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 code below. The
form action line should replace the example link
https://secure.usaepay.com/pay/lnkt6jxy9fvkpwx8d/hZbcVNLj Form Link found at the top of the payment form page in the console:
<form action="https://secure.usaepay.com/pay/lnkt6jxy9fvkpwx8d/hZbcVNLj"> <input type="hidden" name="key" value="[key]"> <input type="hidden" name="command" value="sale"> <input type="hidden" name="amount" value="[amount]"> <input type="hidden" name="invoice" value="[invoice]"> <input type="hidden" name="hash" value="[hash]"> <input type="submit" value="Continue to Payment Form"> </form>
Any 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
"text" as shown below:
<code html> <form action="https://secure.usaepay.com/pay/lnkt6jxy9fvkpwx8d/hZbcVNLj"> <input type="hidden" name="key" value="[key]"> <input type="hidden" name="command" value="sale"> <input type="text" name="amount" value="[amount]"> <input type="hidden" name="invoice" value="[invoice]"> <input type="hidden" name="hash" value="[hash]"> <input type="submit" value="Continue to Payment Form"> </form> </code>
Address Verification System
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.
|YYY||Y, YYA, YYD||Address: Match & 5 Digit Zip: Match|
|NYZ||Z||Address: No Match & 5 Digit Zip: Match|
|YNA||A, YNY||Address: Match & 5 Digit Zip: No Match|
|NNN||N, NN||Address: No Match & 5 Digit Zip: No Match|
|YYX||X||Address: Match & 9 Digit Zip: Match|
|NYW||W||Address: No Match & 9 Digit Zip: Match|
|XXW||Card Number Not On File|
|XXU||Address Information not verified for domestic transaction|
|XXR||R, U, E||Retry / System Unavailable|
|XXS||S||Service Not Supported|
|XXE||Address Verification Not Allowed For Card Type|
|XXG||G,C,I||Global Non-AVS participant|
|YYG||B, M||International Address: Match & Zip: Not Compatible|
|GGG||D||International Address: Match & Zip: Match|
|YGG||P||International Address: No Compatible & Zip: Match|
Card ID Result Codes
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.
|S||Should be on card but not so indicated|
|U||Issuer Not Certified|
|X||No response from association|
|(blank)||No CVV2/CVC data available for transaction.|