ePayment Form

Overview

The payment form allows a merchant to send the customer to eBizCharge 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, display a form that will post to the eBizCharge site, or display a button that's connected to the form. You will need the source key to connect to the gateway.

Using the Payment Form

Customized Payment Form

To customize your payment form, log into your merchant account and go to Settings → Source Keys → Edit → Customize Epay Form. You may need to add a source if you haven't already done so. Please do not use your Virtual Terminal (vterm), Sale Form (quicksale), or Recurring Billing (recurring) keys to create a payment form! These keys are already being used by various functions in your merchant console. A list of form fields can be found at the bottom of this page. Example code for the form can be found below. Please keep in mind that not all of these 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!

Payment Form via POST

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>

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 “hidden” to “text” as shown below:

</form>

ePayment Form / Check-Out Form fields used

The form uses the following fields to post to eBizCharge:

-UMkey - This is the source key that connects you as a valid merchant on our gateway (Required)

-UMcommand - This indicates the type of a transaction, sale. (Required)

-UMcustreceipt - This flags eBizCharge to send a customer receipt via email through a value of 'yes'.

-UMaddcustomer (UMrecurring is deprecated) - This flags eBizCharge to add this transaction as a customer record in Customers & Billing area of the Merchant Console.

-UMinvoice - This allows you to pass a numerical invoice number for record keeping. (Required)

-UMamount - A text box displayed for customer to enter a decimal (0.00) amount. (Required)

-UMbillamount - Sets the monetary amount to charge on each cycle. If this field is left blank the UMamount will be used instead. This is NOT the “initial” charge or “setup” charge, this is only the “recurring” charge. UMamount determines the initial charge.

-UMschedule - Determines the recurring billing schedule. Possible values are daily, weekly, biweekly, monthly, bimonthly, quarterly, biannually, or annually. (defaults to monthly)

-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 UMstart=next the date of the next billing cycle will be used. For example if today is 1/10/2009 and UMschedule=monthly then UMstart will be set to 2/10/2009.

-UMdescription - A text box for any comments left by the donor

-UMcomments - Optional transaction comments field. Comments are displayed on the transaction details page.

-UMemail - A place for the donor to enter their email address for a confirmation receipt.

-Billing Fields - All the billing fields that will be transferred over to the secure payment form.

The form is not limited to only these fields - a full list of fields can be seen at the bottom of this page. If you have questions about creating custom fields, please see Custom Fields.

Example code and payment form templates

Creating a "Buy Now" button - Creating a “Buy Now” button

Drop-Down Menu - Creating a Basic Drop-Down Menu

Same As Billing - checkbox for “Same As Billing”

Invoice Number - random invoice generator

Convenience Fee - adds convenience fee as flat rate or percentage

Recurring - example recurring form

One-time Sale - example one-time sale form

Required Field prompts - uses Javascript to validate form fields before submission. Provides alert window if required fields are blank.

Required Fields with Javascript - indicates which fields are required when customer lands on page. Provides inline instructions if required fields are blank.

Quantity - uses Javascript for adding extra field Quantity

Quantity For Multiple Products - uses Javascript and creates extra fields for quantities of multiple products.

Discount Code - Use a discount code

Developer Reference

Test Mode

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.

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.

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.

Code	Alternates	Meaning
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.

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.

Code	Meaning
M	Match
N	No Match
P	Not Processed
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.

Form Fields

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.

Base Fields

Field	Required	Description
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 (UMkey) has a pin assigned a validation hash is required.
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.
UMrefNum	x	The UMrefNum received when a transaction was authorized via either the “sale” or “authonly” commands. Required for void and capture commands.
UMcard	CC	Credit Card Number with no spaces or dashes.
UMexpir	CC	Expiration Date in the form of MMYY with no spaces or punctuation.
UMrouting	Checks	Bank Routing number. Required when UMcommand is set to check or checkcredit.
UMaccount	Checks	Checking Account Number. Required when UMcommand is set to check or checkcredit.
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 UMamount is not available.
UMcurrency	*	Currency of UMamount. Required if using a MCP based account. Must be one of the 3 digit numeric codes found here.
UMtax		Portion of above charge amount (UMamount) that is sales tax.
UMnontaxable		Set to yes if transaction is not taxable. (optional, platform dependant)
UMtip		Portion of charge amount (UMamount) for gratuity (tip).
UMshipping		Portion of above charge amount (UMamount) that is for shipping charges.
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. UMsubtotal+UMtip+UMshipping-UMdiscount+UMtax must equal UMamount. If UMsubtotal is not specified, it will be ignored.
UMcustid		Unique customer id.
UMinvoice	x	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 UMinvoice when orderid is longer that 10 digits.
UMponum		Purchase Order number. Only required for corporate purchasing cards.
UMticket		Obsolete, included for backward compatibility. Use UMinvoice instead
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.
UMstreet	CC	Street Address
UMzip	CC	Zip code
UMdlnum	Checks	Driver's license number.
UMdlstate	Checks	Driver's license state of issue.
UMcheckformat		Record type of electronic check transaction. Not supported by all check processors. List of Check Record Types Also known as SEC code.
UMchecknum	Checks	Check number. (optional)
UMcheckimagefront		JPG image of front side of check. (optional) If data is encoded, encoding must match UMcheckimageencoding.
UMcheckimageback		JPG image of back side of check. (optional) If data is encoded, encoding must match UMcheckimageencoding.
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		Indiactes 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 UMredirApproved is set but UMredirDeclined is not, the gateway will display the template entered in the sources area. This feature overrides the “Declined Template” feature that is available in the Source Key settings screen. If both are set, the declined template will be ignored and the user will be redirect to the UMredirDeclined url.
UMechofields		Echo input fields in response. If UMechofields is set to all then all fields included in the form (except for the credit card number, key, expiration and cvc) will be included in the redirection URL as GET variables. This is only useful with the client-side method. For example if you post a form with the field “comments” to the gateway and set UMredirApproved to “http://mysite.com/handler.cgi” then the gateway will redirect to http://mysite.com/handler.cgi?comments=… Please Note: Use of this feature is not recommended for security reasons. These fields will typically be logged in your web server log files. On many hosting companies these log files are world-readable which means that anyone would be able to read the information.
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.

Billing and Shipping Address Fields

Billing Address	Shipping Address
UMbillfname	UMshipfname
UMbilllname	UMshiplname
UMbillcompany	UMshipcompany
UMbillstreet	UMshipstreet
UMbillstreet2	UMshipsreet2
UMbillcity	UMshipcity
UMbillstate	UMshipstate
UMbillzip	UMshipzip
UMbillcountry	UMshipcountry
UMbillphone	UMshipphone
UMemail
UMfax
UMwebsite

Stored Customers and Recurring Billing

Field	Description
UMaddcustomer	UMrecurring is deprecated. If set to yes, the system will enter the transaction as a recurring billing 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 UMamount will be used instead. This is NOT the “initial” charge or “setup” charge, this is only the “recurring” charge. UMamount determines the initial charge.
UMschedule	Determines the recurring billing schedule. Possible values are disabled, daily, weekly, biweekly, monthly, bimonthly, quarterly, biannually, or annually. (defaults to monthly)
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 UMstart=next the date of the next billing cycle will be used. For example if today is 1/10/2004 and UMschedule=monthly then UMstart will be set to 2/10/2004.
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.

Field	Max Length	Description
UMline*sku	32	Product id, code or SKU
UMline*name	255	Item name or short description
UMline*description	64k	Long description
UMline*cost	00000000.00	Cost of item, each
UMline*qty	11	Quantity of item, each
UMline*taxable	1	Y = Taxable, N = Non-taxable

* replace the '*' with the line number. For example UMline1sku.

Visa VPAS (Verified By Visa) and UCAF (Mastercard Secure Code) Fields

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

Field	Description
UMcardauth	Set UMcardauth=true to enable cardholder authentication using the integrated gateway authentication system.
UMpares	Cardholder authentication payload. (When using integrated authentication system.)
UMxid	This field is obsolete.
UMcavv	CAVV value received from third part authenticator. If you support CAVV but customer did not participate you must send UMcavv=-1. This flags our system that you support VbV/MC Secure Code. (Only needed if not using the gateway authentication system.)
UMeci	ECI value received from third party authenticator. (Only needed if not using the gateway authentication system.)

Card Present Fields

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

Field	Description
UMcardpresent	Set UMcardpresent=true to enable card present mode. If UMmagstripe is sent, UMcardpresent will be automatically set to true.
UMmagstripe	Mag stripe data read from card. Can include Track 1, Track 2 or both.
UMdukpt	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.
UMtermtype	The type of terminal being used: POS (cash register), StandAlone (self service terminal), Unattended (ie gas pump) Unkown (defaults to Unknown)
UMmagsupport	Describes the magstripe reading capabilities of your POS hardware: yes, no, contactless, unknown (default is unknown unless magstripe has been sent).
UMcontactless	UMmagstripe was read via contactless swiper: yes or no (default is no).
UMsignature	Cardholder signature captured by pos device. Base64 encoded.

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.

Field	Description
UMstatus	Status of the transaction. The possible values are: Approved, Declined, Verification and Error.
UMauthCode	Authorization number.
UMrefNum	Transaction reference number
UMbatch	Batch reference number. This will only be returned for sale and auth commands. Warning: 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.
UMresult	Transaction result
UMerror	Error description if UMstatus is Declined or Error.
UMerrorcode	A numerical error code.
UMacsurl	Verification URL to send cardholder to. Sent when UMstatus is verification (cardholder authentication is required).
UMpayload	Authentication data to pass to verification url. Sent when UMstatus is verification (cardholder authentication is required).
UMisDuplicate	Indicates whether this transaction is a folded duplicate or not. 'Y' means that this transaction was flagged as duplicate and has already been processed. The details returned are from the original transaction. Send UMignoreDuplicate to override the duplicate folding.
UMconvertedAmount	Amount converted to merchant's currency, when using a multi-currency processor.
UMconvertedAmountCurrency	Merchant's currency, when using a multi-currency processor.
UMconversionRate	Conversion rate used to convert currency, when using a multi-currency processor.
UMcustnum	Customer reference number assigned by gateway. Returned only if UMaddcustomer=yes.
UMresponseHash	Response verification hash. Only present if response hash was requested in the UMhash. (See Source Pin Code section for further details)