{"_id":"5632b1a4b904a10d0032f757","project":"55b933b3146ef121002158d3","user":"55b932ba8fd1a02b00f496c8","category":{"_id":"5632b179df556c0d00cd095b","__v":2,"pages":["5632b1a4b904a10d0032f757","5632b1c862c48a0d00334db2"],"project":"55b933b3146ef121002158d3","version":"5632a5e549e16d0d00122443","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-10-29T23:53:29.317Z","from_sync":false,"order":2,"slug":"transaction-api","title":"Transaction API"},"githubsync":"","version":{"_id":"5632a5e549e16d0d00122443","__v":6,"project":"55b933b3146ef121002158d3","createdAt":"2015-10-29T23:04:05.701Z","releaseDate":"2015-10-29T23:04:05.701Z","categories":["5632a5e749e16d0d00122444","5632a5e749e16d0d00122445","5632a5e749e16d0d00122446","5632a5e749e16d0d00122447","5632a5e749e16d0d00122448","5632a5e749e16d0d00122449","5632a5e749e16d0d0012244a","5632a5e749e16d0d0012244b","5632a5e749e16d0d0012244c","5632a5e749e16d0d0012244d","5632a5e749e16d0d0012244e","5632a5e749e16d0d0012244f","5632a5e749e16d0d00122450","5632b179df556c0d00cd095b","564e13053b2b4a19000cd69b","59caa9df65accc001a489c95","59cab50965accc001a489d28","59cadd464ab7b70024378e74"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.1.0","version":"1.1"},"__v":35,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-10-29T23:54:12.620Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"##**CGI Transaction Gateway API v2.18.0**\n \nProduction / Live URLs to connect to:\nhttps://secure.eBizCharge.com/gate\nhttps://secure.eBizCharge.com/secure/gate\n \nPort: 443 - HTTPS\n\n##API Overview\nThe 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.\nThe 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.\nEven with all of the security features built into the eBizCharge 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.\nClient certificate use is also recommended. To require a client certificate use https://secure.eBizCharge.com/secure/gate.php. If you do not want to use client certificates, then you should use https://secure.eBizCharge.com/gate.php.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Integration Methods\"\n}\n[/block]\n##Server-Side Method\n \nThe server-side method uses the following steps and requires programming and web development knowledge:\n1. First, the client's browser submits the check out form securely to https://www.yourcompany.com/makeApayment.xxx\n2. makeApayment.xxx validates the info and preforms any data correction (removing spaces from credit card numbers, etc.)\n3. makeApayment.xxx opens a connection to https://secure.eBizCharge.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). You can do this 1. 4. with our web services SOAP API.\nyourscript.cgi reads the processing result returned by posting to https://secure.eBizCharge.com/gate.php\n5. yourscript.cgi then interprets the data and returns the desired result back to the client browser.\n\n\n## Client-Side Method\n \nThe 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 (eBizCharge). The following basic steps are used in a client-side transaction:\n  * Client browser submits check out form (with required hidden fields) securely to https://secure.eBizCharge.com/gate.php.\n  * 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.\n  * yourscript.cgi then interprets the data and returns the desired result back to the client browser.\n\nThe following is an example of a client-side method form. (You would have to also write myorderform.cgi.)\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<form action=\\\"https://secure.eBizCharge.com/gate.php\\\" method=\\\"POST\\\">\\n<input type=\\\"hidden\\\" name=\\\"UMkey\\\" value=\\\"Your_source_key_here\\\">\\n<input type=\\\"hidden\\\" name=\\\"UMredir\\\" value=\\\"http://www.mycompany.com/cgi-bin/myorderform.cgi\\\">\\n<input type=\\\"hidden\\\" name=\\\"UMinvoice\\\" value=\\\"1234\\\">\\n<input type=\\\"hidden\\\" name=\\\"UMamount\\\" value=\\\"1.00\\\">\\nFull Name: <input type=\\\"text\\\" name=\\\"UMname\\\"><br>\\nStreet: <input type=\\\"text\\\" name=\\\"UMstreet\\\"><br>\\nCity: <input type=\\\"text\\\" name=\\\"city\\\"><br>\\nState: <input type=\\\"text\\\" name=\\\"state\\\"><br>\\nZip: <input type=\\\"text\\\" name=\\\"UMzip\\\"><br>\\n<br>\\n<br>\\nCredit Card Info:<br>\\nCard Type: <select name=cardtype>\\n<option>Visa <option>Mastercard <option>Amex</select><br>\\nCard Number: <input type=text name=UMcard><br>\\nExpiration: <input type=text name=UMexpir><br>\\nName On Card: <input type=text name=UMname><br>\\n<br>\\n<br>\\n<input type=submit value=\\\"Place Order\\\">\\n</form>\",\n      \"language\": \"haml\"\n    }\n  ]\n}\n[/block]\n## Client-Side Method With Simple Redirection\n \nAlso known as “Direct Post Method”. 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 [secure.eBizCharge.com](http://secure.eBizCharge.com), click on Settings, and edit the source key for your form. On the source page is a box for “Declined Template.” Paste your HTML into this box.\nThe 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.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<form action=\\\"https://secure.eBizCharge.com/gate.php \\\" method=\\\"POST\\\">\\n<input type=\\\"hidden\\\" name=\\\"UMkey\\\" value=\\\"Your_source_key_here\\\">\\n<input type=\\\"hidden\\\" name=\\\"UMredirApproved\\\"\\nvalue=\\\"http://www.mycompany.com/orderapproved.html\\\">\\n<input type=\\\"hidden\\\" name=\\\"UMinvoice\\\" value=\\\"123456\\\">\\n<input type=\\\"hidden\\\" name=\\\"UMamount\\\" value=\\\"1.00\\\">\\nFull Name: <input type=\\\"text\\\" name=\\\"UMname\\\"><br>\\nStreet: <input type=\\\"text\\\" name=\\\"UMstreet\\\"><br>\\nCity: <input type=\\\"text\\\" name=\\\"city\\\"><br>\\nState: <input type=\\\"text\\\" name=\\\"state\\\"><br>\\nZip: <input type=\\\"text\\\" name=\\\"UMzip\\\"><br>\\n<br>\\n<br>\\nCredit Card Info:<br>\\nCard Type: <select name=cardtype>\\n<option>Visa\\n<option>Mastercard\\n<option>Amex</select><br>\\nCard Number: <input type=\\\"text\\\" name=\\\"UMcard\\\"><br>\\nExpiration: <input type=\\\"text\\\" name=\\\"UMexpir\\\"><br>\\nName On Card: <input type=\\\"text\\\" name=\\\"UMname\\\"><br>\\n<br>\\n<br>\\n<input type=\\\"submit\\\" value=\\\"Place Order\\\">\\n</form>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n##ePayment Form / Check-Out Form\nThe [payment](/docs/overview) form allows you 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](/docs/overview), the merchant's website needs to redirect the customer to a specially formatted URL or display a form that will post to the eBizCharge site. For more information on using the payment form, please see the [ePayment Form Manual](/docs/overview).\n\n##Processing Commands\nThe 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.\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"cc:sale\",\n    \"h-0\": \"Command\",\n    \"h-1\": \"Alternate/Legacy Equivalents\",\n    \"h-2\": \"Pin Required\",\n    \"0-1\": \"sale\",\n    \"1-0\": \"cc:authonly\",\n    \"1-1\": \"preauth, authonly\",\n    \"2-0\": \"cc:capture\",\n    \"2-1\": \"capture\",\n    \"3-0\": \"cc:adjust\",\n    \"3-1\": \"adjust\",\n    \"4-0\": \"cc:credit\",\n    \"4-1\": \"credit\",\n    \"5-0\": \"cc:postauth\",\n    \"5-1\": \"postauth\",\n    \"6-0\": \"check:sale\",\n    \"6-1\": \"check\",\n    \"7-0\": \"check:credit\",\n    \"7-1\": \"checkcredit, reverseach\",\n    \"7-2\": \"Yes\",\n    \"8-0\": \"void\",\n    \"8-1\": \"cc:void, check:void\",\n    \"9-0\": \"refund\",\n    \"9-1\": \"cc:refund, check:refund\",\n    \"10-0\": \"creditvoid\",\n    \"10-2\": \"Yes\"\n  },\n  \"cols\": 3,\n  \"rows\": 11\n}\n[/block]\n##cc:sale - Credit Card Sale\n*UMcommand=cc:sale*\nThe '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.\n\n##cc:authonly - Credit Card Authorization\n*UMcommand=cc:authonly*\nThe '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.\n \n##cc:capture- Capture an AuthOnly Transaction\n*UMcommand=cc:capture*\nThe '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 tolerances 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.\n \n##cc:adjust- Adjust a Credit Card Transaction\n*UMcommand=cc:adjust*\nThe 'cc:adjust' command allows you to make changes to an existing (unsettled) sale. The authorization amount can be increased (incremental authorization) or decreased (partial reversal) or not changed. Additional data elements such as tax amount and po number can be added. The original Transaction ID (refnum) must be passed in UMrefNum field. The tolerances for the settle amount vary depending on the type of Merchant Account and the merchant service provider. The adjust and capture commands function identically except that the adjust command does not place the transaction in the batch.\n \n##cc:postauth - Offline Credit Card Transaction\n*UMcommand=cc:postauth*\nThe '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.\n \n##cc:credit - Credit Card Refund\n*UMcommand=cc:credit*\nThe '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.\n \n##Check:Sale - ACH/EFT Check Sale\n*UMcommand=check:sale*\nThe '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.\n \n##Check:Credit - ACH/EFT Check Credit\n*UMcommand=Check:Credit*\nThe '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.\n \n##void: Cancel Previous Transaction\n*UMcommand=void*\nThe '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.\n \n##refund: Refund Previous sale\n*UMcommand=refund*\nThe '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.\n \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Optional Features\"\n}\n[/block]\n## Merchant Email Receipts\n(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 [secure.eBizCharge.com](http://secure.eBizCharge.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.\n \n## Electronic Checks\nIn 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).\n \n## Recurring Billing\nThe 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 UMaddcustomer command must be set to yes and the initial charge must be approved. Once the initial charge is approved and the UMaddcustomer 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.)If you do not want to enable recurring billing for this customer, set UMschedule=disabled.\n \n## VPAS (Verified by Visa) and UCAF (Mastercard Secure Code)\nThe 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.\nTo 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:\n1.Merchant's site collects cardholder information\n2.Merchant's site sends an authorization to gate.php with the UMcardauth flag set to true\n3.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.\n4.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.\n5.Customer enters their username and password. If authentication is successful, they will be sent back to TermUrl with the variable PaRes set.\n6.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.\n7.Then gate.php returns Approved or Declined as usual.\n\nIf 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.)\n\n##Source Pin Code\nTo 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 transaction amount, the invoice, and an optional random seed value. This information is separated by colons and run through an md5 or sha1 algorithm. The algorithm produces a hash, which is then sent to the gateway in the UMhash field where it is matched against the hash from the pin on file. If the two hashes do not match, the transaction is rejected.\n\n**Format of UMhash** \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Value\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"Algorithm\",\n    \"0-1\": \"'m' or 's'\",\n    \"0-2\": \"A one character code indicating the algorithm used. 'm' = MD5 and 's' = SHA1\",\n    \"1-0\": \"(separator)\",\n    \"1-1\": \"'/'\",\n    \"2-0\": \"Seed\",\n    \"2-1\": \"(up to 256 chars)\",\n    \"2-2\": \"Optional random seed value. Must match seed value used inside hash value. Also must be upper case letter and/or numbers.\",\n    \"3-0\": \"(separator)\",\n    \"3-1\": \"'/'\",\n    \"4-0\": \"Hash\",\n    \"4-1\": \"(32 or 40 Char Hex)\",\n    \"4-2\": \"MD5 or Sha1 Hash value in hex format.\",\n    \"5-0\": \"(separator)\",\n    \"5-1\": \"'/'\",\n    \"6-0\": \"Response\",\n    \"6-1\": \"'y' or 'n'\",\n    \"6-2\": \"Request a response hash. If omitted, defaults to 'n'\"\n  },\n  \"cols\": 3,\n  \"rows\": 7\n}\n[/block]\nExample UMhash value:\n*UMhash=m/2123123/8827380daee8c6f935d3eaecf63e646c/y*\n\n**Calculating Hash Value**\nThe data used to calculate the hash value are the command, the source key pin, the transaction amount, the invoice and the random seed value separated by colons. The resulting data is sent to MD5 or SHA1 function which will produce the hash value.\nFor example:\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Command\",\n    \"0-1\": \"sale\",\n    \"1-0\": \"Pin\",\n    \"1-1\": \"sd*s3j002jd\",\n    \"2-0\": \"Amount\",\n    \"2-1\": \"53.21\",\n    \"3-0\": \"Invoice\",\n    \"3-1\": \"34576721\",\n    \"4-0\": \"Seed\",\n    \"4-1\": \"1234\"\n  },\n  \"cols\": 2,\n  \"rows\": 5\n}\n[/block]\nWould result in the following data:\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Data String\",\n    \"0-1\": \"sale:sd*s3j002jd:53.21:34576721:1234\",\n    \"1-0\": \"MD5 Hash String\",\n    \"1-1\": \"52d534dd45388432ac0a44c9174ffb3f\",\n    \"2-0\": \"UMhash Value\",\n    \"2-1\": \"m/1223/52d534dd45388432ac0a44c9174ffb3f/\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\nThe following is a sample implementation in PHP:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?php\\n$umcommand = \\\"sale\\\" ;\\n$umkey = \\\"Your_source_key_here\\\" ;\\n$card = \\\"4444111122223337\\\" ;\\n$expir = \\\"0209\\\";\\n$pin = \\\"hs4rk\\\";\\n$amount = \\\"29.30\\\" ;\\n$invoice = \\\"45671\\\" ;\\n$hashseed = mktime ();   // mktime returns the current time in seconds since epoch.\\n$hashdata = $umcommand . \\\":\\\" . $pin . \\\":\\\" . $amount . \\\":\\\" . $invoice . \\\":\\\" . $hashseed ;\\n$hash = md5 ( $hashdata );   // php includes a built-in md5 function that will create the hash\\n$request = \\\"UMkey=$umkey&UMhash=m/$hashseed/$hash/y&UMamount=$amount&UMinvoice=$invoice\\\" ;\\n$request .= \\\"&UMcard=$card&UMexpir=$expir\\\" ;\\n?>\\n \",\n      \"language\": \"php\"\n    }\n  ]\n}\n[/block]\n**Verify Response Hash Value**\nIf requested in the UMhash, the server will generate a response hash value. This response hash value can be used to verify that the response value was generated by the gateway. This is useful when using a response landing page with the client side or payment form integrations.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Value\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"Algorithm\",\n    \"0-1\": \"'m' or 's'\",\n    \"0-2\": \"A one character code indicating the algorithm used. 'm' = MD5 and 's' = SHA1\",\n    \"1-0\": \"(separator)\",\n    \"1-1\": \"'/'\",\n    \"2-0\": \"Seed\",\n    \"2-1\": \"(up to 256 chars)\",\n    \"2-2\": \"Seed value used to create\",\n    \"3-0\": \"(separator)\",\n    \"3-1\": \"'/'\",\n    \"4-0\": \"Hash\",\n    \"4-1\": \"(32 or 40 Char Hex)\",\n    \"4-2\": \"MD5 or Sha1 Hash value in hex format.\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]\nThe hash value is the combination of the Pin, UMresult, UMrefNum and the Seed, separated by colons.\nThe following is a sample implementation in PHP:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?php\\n// Pin assigned to source key\\n$pin='1234';\\n// break apart response hash\\nif(!$_REQUEST['UMresponseHash']) die('Gateway did not return a response hash');\\n$tmp = explode('/', $_REQUEST['UMresponseHash']);\\n$gatewaymethod = $tmp[0];\\n$gatewayseed = $tmp[1];\\n$gatewayhash = $tmp[2];\\n// assembly prehash data\\n$prehash = $pin . ':' . $_REQUEST[\\\"UMresult\\\"] . ':' . $_REQUEST[\\\"UMrefNum\\\"] . ':' . $gatewayseed;\\n// calculate what we think the hash should be\\nif($gatewaymethod=='m') $myhash=md5($prehash);\\nelse if($gatewaymethod=='s') $myhash=sha1($prehash);\\nelse die('Unknown hash method');\\n// Compare our hash to gateway's hash\\nif($myhash == $gatewayhash)\\n{\\n  echo \\\"Transaction response validated\\\";\\n} else {\\n  echo \\\"Invalid transaction response\\\";\\n}\\n?>\",\n      \"language\": \"php\"\n    }\n  ]\n}\n[/block]\n## Split Payments\n \n**Requirements**\n  * There will be 2 or more authorizations obtained, depending on how many “splits”\n  * Each merchant will have their respective split accessible in the reports section\n  * The cardholder sees two or more separate charges with the DBA names of the respective merchants on the statement.\n  * At least 2 MIDs (Merchant IDs) are required, with a source key generated in each account. \n\n**Usage**\nThe 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.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<form action=\\\"https://secure.eBizCharge.com/secure/gate\\\" method=\\\"POST\\\">\\n<!-- Base Information,  Source key for concert venue -->\\n<input type=\\\"hidden\\\" name=\\\"UMkey\\\" value=\\\"Your_source_key_here\\\">\\n<input type=\\\"hidden\\\" name=\\\"UMname\\\" value=\\\"John Smith\\\">\\n<input type=\\\"hidden\\\" name=\\\"UMamount\\\" value=\\\"25.00\\\">\\n<input type=\\\"hidden\\\" name=\\\"UMdescription\\\" value=\\\"Ticket to Concert\\\">\\n<input type=\\\"hidden\\\" name=\\\"UMcard\\\" value=\\\"4444555566667779\\\">\\n<input type=\\\"hidden\\\" name=\\\"UMexpir\\\" value=\\\"0909\\\">\\n<input type=\\\"hidden\\\" name=\\\"UMstreet\\\" value=\\\"1234 Main Street\\\">\\n<input type=\\\"hidden\\\" name=\\\"UMzip\\\" value=\\\"01029\\\">\\n<!-- Additional Information for Service Fee,  Source key for Service Company -->\\n<input type=\\\"hidden\\\" name=\\\"UM02key\\\" value=\\\"Your_source_key_here\\\">\\n<input type=\\\"hidden\\\" name=\\\"UM02amount\\\" value=\\\"2.00\\\">\\n<input type=\\\"hidden\\\" name=\\\"UM02description\\\" value=\\\"Servicing Fee\\\">\\n<input type=\\\"submit\\\" value=\\\"Continue\\\">\\n</form>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nEach 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:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<input type=\\\"hidden\\\" name=\\\"UMdescription\\\" value=\\\"First description\\\">\\n<input type=\\\"hidden\\\" name=\\\"UM02description\\\" value=\\\"\\\">\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nWhile 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 must always be two digits: UM02key not UM2key.\n\n**Handling errors**\nBy 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.\n \n**Result Codes**\nThe 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.\n \n**## Examples**\n \n## CreditVoid\nThe 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.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<form action=\\\"https://secure.eBizCharge.com/gate\\\">\\n<input type=\\\"hidden\\\" name=\\\"UMkey\\\" value=\\\"Your_source_key_here\\\">\\n<!-- Enter your source key, above is a dummy key -->\\n<input type=\\\"hidden\\\" name=\\\"UMcommand\\\" value=\\\"creditvoid\\\"> <!-- Credit / Void command -->\\n<input type=\\\"hidden\\\" name=\\\"UMrefNum\\\" value=\\\"55001467\\\">\\n<!-- Reference number (transaction ID) of the original transaction -->\\n<input type=\\\"hidden\\\" name=\\\"UMinvoice\\\" value=\\\"123456\\\">\\n<input type=\\\"hidden\\\" name=\\\"UMhash\\\" value=\\\"cea9cc2f86f666edda4d855ce523f6ae\\\">\\n<input type=\\\"submit\\\" value=\\\"Process CreditVoid\\\">\\n</form>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nUse 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\nDue to the process referencing an older transaction the UMamount field does not need to be passed or included in the MD5 hash.\n \n##** Developer Reference**\n \n## Test Mode\nSetting 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 NOTE: It is recommended that developers use the sandbox server instead of test mode. Test mode is a simple echo test and is only useful for checking that you are send and receiving data correctly. Transaction data is not stored when in test mode which will prevent you from: viewing transaction data in the console, testing customer/merchant receipts, capturing/voiding transactions.\n \n## Sandbox Server\nThe sandbox server provides a full simulation of the production environment. It allows developers to test all aspects of processing before putting their project into production. The system is self contained and credit cards will not actually be charged. To use the transaction api on the sandbox server change the url from https://secure.eBizCharge.com/gate to https://sandbox.eBizCharge.com/gate. You will also need to use a UMkey generated on the sandbox server. Keys created in production will not work on the sandbox server and vice versa.\n \n## Address Verification System\nThese 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.\nThe 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.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Code\",\n    \"h-1\": \"Alternates\",\n    \"h-2\": \"Meaning\",\n    \"0-0\": \"YYY\",\n    \"0-1\": \"Y, YYA, YYD\",\n    \"0-2\": \"Address: Match & 5 Digit Zip: Match\",\n    \"1-0\": \"NYZ\",\n    \"1-1\": \"Z\",\n    \"1-2\": \"Address: No Match & 5 Digit Zip: Match\",\n    \"2-0\": \"YNA\",\n    \"2-1\": \"A, YNY\",\n    \"2-2\": \"Address: Match & 5 Digit Zip: No Match\",\n    \"3-0\": \"NNN\",\n    \"3-1\": \"N, NN\",\n    \"3-2\": \"Address: No Match & 5 Digit Zip: No Match\",\n    \"4-0\": \"YYX\",\n    \"4-1\": \"X\",\n    \"4-2\": \"Address: Match & 9 Digit Zip: Match\",\n    \"5-0\": \"NYW\",\n    \"5-1\": \"W\",\n    \"5-2\": \"Address: No Match & 9 Digit Zip: Match\",\n    \"6-0\": \"XXW\",\n    \"6-2\": \"Card Number Not On File\",\n    \"7-0\": \"XXU\",\n    \"7-2\": \"Address Information not verified for domestic transaction\",\n    \"8-0\": \"XXR\",\n    \"8-1\": \"R, U, E\",\n    \"8-2\": \"Retry / System Unavailable\",\n    \"9-0\": \"XXS\",\n    \"9-1\": \"S\",\n    \"9-2\": \"Service Not Supported\",\n    \"10-0\": \"XXE\",\n    \"10-2\": \"Address Verification Not Allowed For Card Type\",\n    \"11-0\": \"XXG\",\n    \"11-1\": \"G,C,I\",\n    \"11-2\": \"Global Non-AVS participant\",\n    \"12-0\": \"YYG\",\n    \"12-1\": \"B, M\",\n    \"12-2\": \"International Address: Match & Zip: Not Compatible\",\n    \"13-0\": \"GGG\",\n    \"13-1\": \"D\",\n    \"13-2\": \"International Address: Match & Zip: Match\",\n    \"14-0\": \"YGG\",\n    \"14-1\": \"P\",\n    \"14-2\": \"International Address: No Compatible & Zip: Match\"\n  },\n  \"cols\": 3,\n  \"rows\": 15\n}\n[/block]\n##Card ID Result Codes\nThe 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.\nThe 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.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Code\",\n    \"h-1\": \"Meaning\",\n    \"0-0\": \"M\",\n    \"0-1\": \"Match\",\n    \"1-0\": \"N\",\n    \"1-1\": \"No Match\",\n    \"2-0\": \"P\",\n    \"2-1\": \"Not Processed\",\n    \"3-0\": \"S\",\n    \"3-1\": \"Should be on card but not so indicated\",\n    \"4-0\": \"U\",\n    \"4-1\": \"Issuer Not Certified\",\n    \"5-0\": \"X\",\n    \"5-1\": \"No response from association\",\n    \"6-0\": \"(blank)\",\n    \"6-1\": \"No CVV2/CVC data available for transaction.\"\n  },\n  \"cols\": 2,\n  \"rows\": 7\n}\n[/block]\n##Card Level Result Codes\nThe following is a list of result codes for the card level results and what each one indicates. These codes are returned in the UMcardLevelResult variable and provide developers with extended information about the type of Visa Card that is being processed.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Code\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"A\",\n    \"0-1\": \"Visa Traditional\",\n    \"1-0\": \"B\",\n    \"1-1\": \"Visa Traditional Rewards\",\n    \"2-0\": \"C\",\n    \"2-1\": \"Visa Signature\",\n    \"3-0\": \"D\",\n    \"3-1\": \"Visa Signature Preferred\",\n    \"4-0\": \"G\",\n    \"4-1\": \"Visa Business\",\n    \"5-0\": \"H\",\n    \"5-1\": \"Visa Consumer Check Card\",\n    \"6-0\": \"I\",\n    \"6-1\": \"Visa Commerce\",\n    \"7-0\": \"K\",\n    \"7-1\": \"Visa Corporate\",\n    \"8-0\": \"M\",\n    \"8-1\": \"MasterCard/EuroCard and Diners\",\n    \"9-0\": \"S\",\n    \"9-1\": \"Visa Purchasing\",\n    \"10-0\": \"U\",\n    \"10-1\": \"Visa TravelMoney\",\n    \"11-0\": \"G1\",\n    \"11-1\": \"Visa Signature Business\",\n    \"12-0\": \"G2\",\n    \"12-1\": \"Visa Business Check Card\",\n    \"13-0\": \"J1\",\n    \"13-1\": \"Visa General Prepaid\",\n    \"14-0\": \"J2\",\n    \"14-1\": \"Visa Prepaid Gift Card\",\n    \"15-0\": \"J3\",\n    \"15-1\": \"Visa Prepaid Healthcare\",\n    \"16-0\": \"J4\",\n    \"16-1\": \"Visa Prepaid Commercial\",\n    \"17-0\": \"K1\",\n    \"17-1\": \"Visa GSA Corporate T&E\",\n    \"18-0\": \"S1\",\n    \"18-1\": \"Visa Purchasing with Fleet\",\n    \"19-0\": \"S2\",\n    \"19-1\": \"Visa GSA Purchasing\",\n    \"20-0\": \"S3\",\n    \"20-1\": \"Visa GSA Purchasing with Fleet\",\n    \"21-0\": \"DI\",\n    \"21-1\": \"Discover\",\n    \"22-0\": \"AX\",\n    \"22-1\": \"American Express\"\n  },\n  \"cols\": 2,\n  \"rows\": 23\n}\n[/block]\n## API Version Number\nIt 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.\nWhen 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.\n\n## CGI Post Variables\nThe 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.\nNote: CC stands for real-time credit card transactions, Checks stands for real-time check processing.\n\n**Base Fields** \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Required\",\n    \"h-2\": \"Description\",\n    \"3-0\": \"UMignoreDuplicate\",\n    \"3-2\": \"Set to yes if you would like to override the duplicate transaction handling.\",\n    \"0-0\": \"UMcommand\",\n    \"0-2\": \"Processing Command. Possible values are: cc:sale, cc:authonly, cc:capture, cc:credit, cc:postauth, check:sale, check:credit, void, refund and creditvoid. Default is sale.\",\n    \"1-0\": \"UMkey\",\n    \"1-1\": \"ALL\",\n    \"1-2\": \"The source key (assigned by the server when you created a source in your virtual terminal).\",\n    \"2-0\": \"UMhash\",\n    \"2-1\": \"Check:Credit, CreditVoid\",\n    \"2-2\": \"If the source key (UMkey) has a pin assigned a validation hash is required (See Source Pin Code section).\",\n    \"4-0\": \"UMauthCode\",\n    \"4-1\": \"CC:PostAuth\",\n    \"4-2\": \"Authorization Code obtained “offline” (ie telephone authorization). Only required for Post Auth.\",\n    \"5-0\": \"UMrefNum\",\n    \"5-1\": \"CC:Capture,Void,Refund, CreditVoid\",\n    \"5-2\": \"The UMrefNum received when a transaction was authorized via either the “sale” or “authonly” commands. Required for void and capture commands.\",\n    \"6-0\": \"UMcard\",\n    \"6-1\": \"CC:Sale, CC:AuthOnly, CC:Credit, CC:PostAuth\",\n    \"7-0\": \"UMsaveCard\",\n    \"7-2\": \"If set to true and the transaction has been approved, the system will issue a token for future use.\",\n    \"8-0\": \"UMexpir\",\n    \"8-1\": \"CC:Sale, CC:AuthOnly, CC:Credit, CC:PostAuth\",\n    \"8-2\": \"Expiration Date in the form of MMYY with no spaces or punctuation.\",\n    \"9-0\": \"UMrouting\",\n    \"9-1\": \"Check:Sale, Check:Credit\",\n    \"9-2\": \"Bank Routing number. Required when UMcommand is set to check or checkcredit.\",\n    \"10-0\": \"UMaccount\",\n    \"10-1\": \"Check:Sale, Check:Credit\",\n    \"10-2\": \"Checking Account Number. Required when UMcommand is set to check or checkcredit.\",\n    \"11-0\": \"UMaccounttype\",\n    \"11-2\": \"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.\",\n    \"12-0\": \"UMcheckformat\",\n    \"12-2\": \"Record type of electronic check transaction. Not supported by all check processors. [List of Check Record Types](/docs/ach-check-file-formats) Also known as SEC code.\",\n    \"13-0\": \"UMamount\",\n    \"13-2\": \"CC:Sale, CC:AuthOnly, CC:PostAuth, CC:Credit, Check:Sale, Check:Credit\\nCharge amount without $. This is the grand total including tax, shipping and any discounts.\",\n    \"14-0\": \"UMallowPartialAuth\",\n    \"14-2\": \"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\",\n    \"15-0\": \"UMcurrency\",\n    \"15-1\": \"*\",\n    \"15-2\": \"Currency of UMamount. Required if using a [MCP](/docs/multi-currency-processing) based account. Must be one of the 3 digit numeric codes found [here](/docs/currency-codes-1).\",\n    \"16-0\": \"UMtax\",\n    \"16-2\": \"Portion of above charge amount (UMamount) that is sales tax.\",\n    \"17-0\": \"UMnontaxable\",\n    \"17-2\": \"Set to yes if transaction is not taxable. (optional, platform dependant)\",\n    \"18-0\": \"UMtip\",\n    \"18-2\": \"Portion of charge amount (UMamount) for gratuity (tip).\",\n    \"19-0\": \"UMshipping\",\n    \"19-2\": \"Portion of above charge amount (UMamount) that is for shipping charges.\",\n    \"20-0\": \"UMduty\",\n    \"20-2\": \"Duty charge (Required only for level 3)\",\n    \"21-0\": \"UMdiscount\",\n    \"21-2\": \"The amount of any discounts that were applied.\",\n    \"22-0\": \"UMsubtotal\",\n    \"22-2\": \"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.\",\n    \"23-0\": \"UMcustid\",\n    \"23-2\": \"Unique customer id.\",\n    \"24-0\": \"UMinvoice\",\n    \"24-1\": \"*\",\n    \"24-2\": \"Unique Invoice or order number. 10 digits. While not required, it is strongly recommended that this field be populated for CC:Sale, CC:AuthOnly, CC:PostAuth, CC:Credit, Check:Sale and Check:Credit\",\n    \"25-0\": \"UMorderid\",\n    \"25-2\": \"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.\",\n    \"26-0\": \"UMponum\",\n    \"26-2\": \"Purchase Order number. Only required for corporate purchasing cards.\",\n    \"27-0\": \"UMticket\",\n    \"27-2\": \"Obsolete, included for backward compatibility. Use UMinvoice instead\",\n    \"28-0\": \"UMdescription\",\n    \"28-2\": \"Description of transaction.\",\n    \"29-0\": \"UMcomments\",\n    \"29-2\": \"Optional transaction comments field. Comments are displayed on the transaction details page.\",\n    \"30-0\": \"UMname\",\n    \"30-1\": \"*\",\n    \"30-2\": \"Name on card or checking account. While not required, it is strongly recommended that this field be populated for CC:Sale, CC:AuthOnly, CC:PostAuth, CC:Credit, Check:Sale and Check:Credit\",\n    \"31-0\": \"UMstreet\",\n    \"31-1\": \"*\",\n    \"31-2\": \"Billing Street Address for credit cards. Used for Address Verification System. While not required, this field should be populated for Fraud Prevention and to obtain the best rate for Ecommerce credit card transactions. It should be populated for CC:Sale and CC:AuthOnly\",\n    \"32-0\": \"UMzip\",\n    \"32-1\": \"*\",\n    \"32-2\": \"Billing Zip Code for credit cards. Used for Address Verification System. While not required, this field should be populated for Fraud Prevention and to obtain the best rate for Ecommerce credit card transactions. It should be populated for CC:Sale and CC:AuthOnly\",\n    \"33-0\": \"UMcvv2\",\n    \"33-1\": \"*\",\n    \"33-2\": \"CVV2 data for Visa. Set to -2 if the code is not legible, -9 if the code is not on the card. While not required, this field should be populated for Fraud Prevention and to obtain the best rate for Ecommerce credit card transactions. It should be populated for CC:Sale and CC:AuthOnly\",\n    \"34-0\": \"UMcustemail\",\n    \"34-2\": \"Customer's Email Address.\",\n    \"35-0\": \"UMcustreceipt\",\n    \"35-2\": \"Yes/No. Sends the Customer a Receipt. This overrides the setting for the merchant and source.\",\n    \"36-0\": \"UMcustreceiptname\",\n    \"36-2\": \"Name of the custom receipt template to use. If omitted or if receipt not found, default customer receipt template will be used\",\n    \"37-0\": \"UMdlnum\",\n    \"37-2\": \"Driver's license number.\",\n    \"38-0\": \"UMdlstate\",\n    \"38-2\": \"Driver's license state of issue.\",\n    \"39-0\": \"UMchecknum\",\n    \"39-2\": \"Check number.\",\n    \"40-0\": \"UMcheckimagefront\",\n    \"40-2\": \"JPG image of front side of check. (optional) If data is encoded, encoding must match UMcheckimageencoding\",\n    \"41-0\": \"UMcheckimageback\",\n    \"41-2\": \"JPG image of back side of check. (optional) If data is encoded, encoding must match UMcheckimageencoding\",\n    \"42-0\": \"UMcheckimageencoding\",\n    \"42-2\": \"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.\",\n    \"43-0\": \"UMclerk\",\n    \"43-2\": \"Indicates the clerk/person processing transaction, for reporting purposes. (optional)\",\n    \"44-0\": \"UMtranterm\",\n    \"44-2\": \"Indiactes the terminal used to process transaction, for reporting purposes. (optional)\",\n    \"45-0\": \"UMresttable\",\n    \"45-2\": \"Indicates the restaurant table, for reporting purposes. (optional)\",\n    \"46-0\": \"UMip\",\n    \"46-2\": \"The IP address of the client requesting the transaction. This is used in many of the fraud modules.\",\n    \"47-0\": \"UMsoftware\",\n    \"47-2\": \"Allows application developers to stamp their application name and version number onto each transaction. Used to assist customers with trouble shooting. (optional)\",\n    \"48-0\": \"UMredir\",\n    \"49-0\": \"UMredirApproved\",\n    \"49-2\": \"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.\",\n    \"50-0\": \"UMredirDeclined\",\n    \"50-2\": \"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.\",\n    \"51-0\": \"UMechofields\",\n    \"51-2\": \"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 UMredir 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.\",\n    \"52-0\": \"UMonError\",\n    \"52-2\": \"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”\",\n    \"53-0\": \"UMtestmode\",\n    \"53-2\": \"If UMtestmode is set to 1 the gateway will simulate a transaction without actually processing the card. No transaction data is stored when testmode is enabled. You will not see the transaction on reports or in the batch. Use of testmode is discouraged for anything more than rudimentary integration testing. For a better simulation of a transaction, it is recommended that you use the Sandbox.\"\n  },\n  \"cols\": 3,\n  \"rows\": 54\n}\n[/block]\n**Billing and Shipping Address Fields** \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Billing Address\",\n    \"h-1\": \"Shipping Address\",\n    \"0-0\": \"UMbillfname\",\n    \"0-1\": \"UMshipfname\",\n    \"1-0\": \"UMbilllname\",\n    \"1-1\": \"UMshiplname\",\n    \"2-0\": \"UMbillcompany\",\n    \"2-1\": \"UMshipcompany\",\n    \"3-0\": \"UMbillstreet\",\n    \"3-1\": \"UMshipstreet\",\n    \"4-0\": \"UMbillstreet2\",\n    \"4-1\": \"UMshipsreet2\",\n    \"5-0\": \"UMbillcity\",\n    \"5-1\": \"UMshipcity\",\n    \"6-0\": \"UMbillstate\",\n    \"6-1\": \"UMshipstate\",\n    \"7-0\": \"UMbillzip\",\n    \"7-1\": \"UMshipzip\",\n    \"8-0\": \"UMbillcountry\",\n    \"8-1\": \"UMshipcountry\",\n    \"9-0\": \"UMbillphone\",\n    \"9-1\": \"UMshipphone\",\n    \"10-0\": \"UMemail\",\n    \"10-1\": \"UMemail\",\n    \"11-0\": \"UMfax\",\n    \"11-1\": \"UMfax\",\n    \"12-0\": \"UMwebsite\",\n    \"12-1\": \"UMwebsite\"\n  },\n  \"cols\": 2,\n  \"rows\": 13\n}\n[/block]\n**Stored Customers and Recurring Billing** \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"UMaddcustomer\",\n    \"0-1\": \"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.\",\n    \"1-0\": \"UMschedule\",\n    \"1-1\": \"Determines the recurring billing schedule. Possible values are daily, weekly, biweekly, monthly, bimonthly, quarterly, biannually, or annually. (defaults to monthly) If you do not want to enable recurring billing for this customer, set UMschedule=disabled\",\n    \"2-0\": \"UMbillsourcekey\",\n    \"2-1\": \"If set to yes, the customer will be stored under the source key specified by UMkey. Otherwise the customer will be stored under the default 'Recurring' key.\",\n    \"3-0\": \"UMbillamount\",\n    \"3-1\": \"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.\",\n    \"4-0\": \"UMnumleft\",\n    \"4-1\": \"Number of transactions remaining in recurring billing cycle. If the recurring billing should go on indefinitely, set this to *. (defaults to *)\",\n    \"5-0\": \"UMstart\",\n    \"5-1\": \"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.\",\n    \"6-0\": \"UMrecurringreceipt\",\n    \"6-1\": \"Yes/No. Sends the Customer a Recurring Billing Receipt.\"\n  },\n  \"cols\": 2,\n  \"rows\": 7\n}\n[/block]\n**Merchant Defined Custom Fields**\nThe merchant can create up to 20 fields for storing custom data. This data is stored for both transactions and customers. For a transaction this data is visible on the transaction details screen. For customers the data can be viewed by editing a customer in the customer database.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Max Length\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"UMcustom1\",\n    \"0-1\": \"255\",\n    \"0-2\": \"Optional fields for storing custom data.\",\n    \"1-0\": \"UMcustom2\",\n    \"1-1\": \"255\",\n    \"2-0\": \"UMcustom3\",\n    \"2-1\": \"255\",\n    \"3-0\": \"…\",\n    \"4-0\": \"UMcustom19\",\n    \"4-1\": \"255\",\n    \"5-0\": \"UMcustom20\",\n    \"5-1\": \"255\"\n  },\n  \"cols\": 3,\n  \"rows\": 6\n}\n[/block]\n**Line Item Details**\nMerchants 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.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Max Length\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"UMline*productrefnum\",\n    \"0-1\": \"12\",\n    \"0-2\": \"(optional) Gateway assigned product RefNum, used for inventory control.\",\n    \"1-0\": \"UMline*sku\",\n    \"1-1\": \"32\",\n    \"1-2\": \"Product id, code or SKU\",\n    \"2-0\": \"UMline*name\",\n    \"2-1\": \"255\",\n    \"2-2\": \"Item name or short description\",\n    \"3-0\": \"UMline*description\",\n    \"3-1\": \"64k\",\n    \"3-2\": \"Long description\",\n    \"4-0\": \"UMline*cost\",\n    \"4-1\": \"00000000.00\",\n    \"4-2\": \"Cost of item per unit of measure (before tax or discount)\",\n    \"5-0\": \"UMline*qty\",\n    \"5-1\": \"00000000.0000\",\n    \"5-2\": \"Quantity\",\n    \"6-0\": \"UMline*taxable\",\n    \"6-1\": \"1\",\n    \"6-2\": \"Y = Taxable, N = Non-taxable\",\n    \"7-0\": \"UMline*taxrate\",\n    \"7-1\": \"00.000\",\n    \"7-2\": \"Tax rate for line (only required for level 3 processing)\",\n    \"8-0\": \"UMline*taxamount\",\n    \"8-1\": \"00000000.00\",\n    \"8-2\": \"Amount of tax charge for line (if left blank will be calculated from taxrate)\",\n    \"9-0\": \"UMline*um\",\n    \"9-1\": \"12\",\n    \"9-2\": \"Unit of measure. If left blank or an invalid code is sent, EA (Each) will be used. See list of valid [unit of measure codes](/docs/unit-of-measure-codes)\",\n    \"10-0\": \"UMline*commoditycode\",\n    \"10-1\": \"12\",\n    \"10-2\": \"Commodity code (only required for level 3 processing). See http://www.unspsc.org/ for valid list of codes.\",\n    \"11-0\": \"UMline*discountrate\",\n    \"11-1\": \"000.000\",\n    \"11-2\": \"Discount percentage for line (only required for level 3 processing)\",\n    \"12-0\": \"UMline*discountamount\",\n    \"12-1\": \"00000000.00\",\n    \"12-2\": \"Discount amount for line (if left blank will be calculated from discountrate)\"\n  },\n  \"cols\": 3,\n  \"rows\": 13\n}\n[/block]\n* replace the '*' with the line number. For example UMline1sku.\n\n**Visa VPAS (Verified By Visa) and UCAF (Mastercard Secure Code) Fields**\nThe following fields are only required in participating in the Verified by Visa or Mastercard Secure Code programs:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"UMcardauth\",\n    \"0-1\": \"Set UMcardauth=true to enable cardholder authentication using the integrated gateway authentication system.\",\n    \"1-0\": \"UMpares\",\n    \"1-1\": \"Cardholder authentication payload. (When using integrated authentication system.)\",\n    \"2-0\": \"UMxid\",\n    \"2-1\": \"This field is obsolete.\",\n    \"3-0\": \"UMcavv\",\n    \"3-1\": \"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.)\",\n    \"4-0\": \"UMeci\",\n    \"4-1\": \"ECI value received from third party authenticator. (Only needed if not using the gateway authentication system.)\"\n  },\n  \"cols\": 2,\n  \"rows\": 5\n}\n[/block]\n**Card Present Fields**\nThe following fields are only required in a card present environment such as a retail store, restaurant or hotel.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"UMcardpresent\",\n    \"0-1\": \"Set UMcardpresent=true to enable card present mode. If UMmagstripe is sent, UMcardpresent will be automatically set to true.\",\n    \"1-0\": \"UMmagstripe\",\n    \"1-1\": \"Mag stripe data read from card. Can include Track 1, Track 2 or both. For encrypted track data, base64 encode the entire block (including masked track data) and then prepend with “enc : / /”. See [End To End Encryption](/docs/end-to-end-encryption)\",\n    \"2-0\": \"UMdukpt\",\n    \"2-1\": \"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.\",\n    \"3-0\": \"UMtermtype\",\n    \"3-1\": \"The type of terminal being used: POS (cash register), StandAlone (self service terminal), Unattended (ie gas pump) Unkown (defaults to Unknown)\",\n    \"4-0\": \"UMmagsupport\",\n    \"4-1\": \"Describes the magstripe reading capabilities of your POS hardware: yes, no, contactless, unknown (default is unknown unless magstripe has been sent).\",\n    \"5-0\": \"UMcontactless\",\n    \"5-1\": \"UMmagstripe was read via contactless swiper: yes or no (default is no).\",\n    \"6-0\": \"UMsignature\",\n    \"6-1\": \"Cardholder signature captured by pos device. Base64 encoded.\"\n  },\n  \"cols\": 2,\n  \"rows\": 7\n}\n[/block]\n**Lodging Industry**\nThe following fields are only applicable in the hotel/lodging environment. The fields will be ignored if the merchant is not configured for this industry. Not all fields are applicable for all platforms but may be provided for reporting purposes. Contact integration support for specific platform requirements.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"UMfolio\",\n    \"0-1\": \"Folio Number\",\n    \"1-0\": \"UMroomRate\",\n    \"1-1\": \"Nightly Room Rate\",\n    \"2-0\": \"UMnights\",\n    \"2-1\": \"Number of nights\",\n    \"3-0\": \"UMcheckInDate\",\n    \"3-1\": \"Guest Check In Date\",\n    \"4-0\": \"UMcheckOutDate\",\n    \"4-1\": \"Guest Check Out Date\",\n    \"5-0\": \"UMextraChargeReasons\",\n    \"6-0\": \"UMroomNumber\",\n    \"7-0\": \"UMcustomerCode\",\n    \"8-0\": \"UMlengthOfStay\",\n    \"9-0\": \"UMroomTaxRate\",\n    \"10-0\": \"UMnonRoomCharges\",\n    \"11-0\": \"UMroomTaxAmount\",\n    \"12-0\": \"UMpreferredCustomer\",\n    \"13-0\": \"UMchargeType\",\n    \"14-0\": \"UMdepartureTime\",\n    \"15-0\": \"UMarrivalTime\"\n  },\n  \"cols\": 2,\n  \"rows\": 16\n}\n[/block]\n## CGI Result Variables\nThe 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. To pass other fields, make sure to pass UMechofields=yes and to not use names that start with “UM”.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"UMstatus\",\n    \"0-1\": \"Status of the transaction. The possible values are: Approved, Declined, Verification and Error.\",\n    \"1-0\": \"UMauthCode\",\n    \"1-1\": \"Authorization number.\",\n    \"2-0\": \"UMauthAmount\",\n    \"2-1\": \"Amount authorized. May be less than amount requested if UMallowPartialAuth=true\",\n    \"3-0\": \"UMrefNum\",\n    \"3-1\": \"Transaction reference number\",\n    \"4-0\": \"UMbatch\",\n    \"4-1\": \"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.\",\n    \"5-0\": \"UMremainingBalance\",\n    \"5-1\": \"Returns the balance remaining on some prepaid and stored value cards\",\n    \"6-0\": \"UMavsResult\",\n    \"6-1\": \"AVS result in readable format\",\n    \"7-0\": \"UMavsResultCode\",\n    \"7-1\": \"[AVS result code](/docs/avs-result-codes-1).\",\n    \"8-0\": \"UMcvv2Result\",\n    \"8-1\": \"CVV2 result in readable format.\",\n    \"9-0\": \"UMcvv2ResultCode\",\n    \"9-1\": \"[CVV2 result code.](/docs/cvv2-response-codes)\",\n    \"10-0\": \"UMvpasResultCode\",\n    \"10-1\": \"Verified by Visa (VPAS) or Mastercard SecureCode (UCAF) result code.\",\n    \"11-0\": \"UMresult\",\n    \"11-1\": \"Transaction result - A, D, E, or V (for Verification)\",\n    \"12-0\": \"UMerror\",\n    \"12-1\": \"Error [description ](/docs/description)if UMstatus is Declined or Error.\",\n    \"13-0\": \"UMerrorcode\",\n    \"13-1\": \"A [numerical ](/docs/description)error code.\",\n    \"14-0\": \"UMacsurl\",\n    \"14-1\": \"Verification URL to send cardholder to. Sent when UMstatus is verification (cardholder authentication is required).\",\n    \"15-0\": \"UMpayload\",\n    \"15-1\": \"Authentication data to pass to verification url. Sent when UMstatus is verification (cardholder authentication is required).\",\n    \"16-0\": \"UMisDuplicate\",\n    \"16-1\": \"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.\",\n    \"17-0\": \"UMconvertedAmount\",\n    \"17-1\": \"Amount converted to merchant's currency, when using a [multi-currency processor](/docs/multi-currency-processing).\",\n    \"18-0\": \"UMconvertedAmountCurrency\",\n    \"18-1\": \"Merchant's currency, when using a [multi-currency processor](/docs/multi-currency-processing).\",\n    \"19-0\": \"UMconversionRate\",\n    \"19-1\": \"Conversion rate used to convert currency, when using a [multi-currency processor](/docs/multi-currency-processing).\",\n    \"20-0\": \"UMcustnum\",\n    \"20-1\": \"Customer reference number assigned by gateway. Returned only if UMaddcustomer=yes.\",\n    \"21-0\": \"UMresponseHash\",\n    \"21-1\": \"Response verification hash. Only present if response hash was requested in the UMhash. (See Source Pin Code section for further details)\",\n    \"22-0\": \"UMprocRefNum\",\n    \"22-1\": \"Transaction Reference number provided by backend processor (platform), blank if not available)\",\n    \"23-0\": \"UMcardLevelResult\",\n    \"23-1\": \"[Card level results](/docs/card-level-codes-1) (for Visa cards only), blank if no results provided\",\n    \"24-0\": \"UMcardRef\",\n    \"24-1\": \"Card reference token. 16-19 digit alphanumeric string. It is returned with dashes but it is not required that these be stored.\",\n    \"25-0\": \"UMcardType\",\n    \"25-1\": \"The type of card that was submitted, ie “Visa”\",\n    \"26-0\": \"UMmaskedCardNum\",\n    \"26-1\": \"The masked out card number including the last 4 digits\"\n  },\n  \"cols\": 2,\n  \"rows\": 27\n}\n[/block]","excerpt":"","slug":"api-overview","type":"basic","title":"Overview"}
##**CGI Transaction Gateway API v2.18.0** Production / Live URLs to connect to: https://secure.eBizCharge.com/gate https://secure.eBizCharge.com/secure/gate Port: 443 - HTTPS ##API Overview 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. Even with all of the security features built into the eBizCharge 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://secure.eBizCharge.com/secure/gate.php. If you do not want to use client certificates, then you should use https://secure.eBizCharge.com/gate.php. [block:api-header] { "type": "basic", "title": "Integration Methods" } [/block] ##Server-Side Method The server-side method uses the following steps and requires programming and web development knowledge: 1. First, the client's browser submits the check out form securely to https://www.yourcompany.com/makeApayment.xxx 2. makeApayment.xxx validates the info and preforms any data correction (removing spaces from credit card numbers, etc.) 3. makeApayment.xxx opens a connection to https://secure.eBizCharge.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). You can do this 1. 4. with our web services SOAP API. yourscript.cgi reads the processing result returned by posting to https://secure.eBizCharge.com/gate.php 5. yourscript.cgi then interprets the data and returns the desired result back to the client browser. ## Client-Side Method 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 (eBizCharge). The following basic steps are used in a client-side transaction: * Client browser submits check out form (with required hidden fields) securely to https://secure.eBizCharge.com/gate.php. * 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. * 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.) [block:code] { "codes": [ { "code": "<form action=\"https://secure.eBizCharge.com/gate.php\" method=\"POST\">\n<input type=\"hidden\" name=\"UMkey\" value=\"Your_source_key_here\">\n<input type=\"hidden\" name=\"UMredir\" value=\"http://www.mycompany.com/cgi-bin/myorderform.cgi\">\n<input type=\"hidden\" name=\"UMinvoice\" value=\"1234\">\n<input type=\"hidden\" name=\"UMamount\" value=\"1.00\">\nFull Name: <input type=\"text\" name=\"UMname\"><br>\nStreet: <input type=\"text\" name=\"UMstreet\"><br>\nCity: <input type=\"text\" name=\"city\"><br>\nState: <input type=\"text\" name=\"state\"><br>\nZip: <input type=\"text\" name=\"UMzip\"><br>\n<br>\n<br>\nCredit Card Info:<br>\nCard Type: <select name=cardtype>\n<option>Visa <option>Mastercard <option>Amex</select><br>\nCard Number: <input type=text name=UMcard><br>\nExpiration: <input type=text name=UMexpir><br>\nName On Card: <input type=text name=UMname><br>\n<br>\n<br>\n<input type=submit value=\"Place Order\">\n</form>", "language": "haml" } ] } [/block] ## Client-Side Method With Simple Redirection Also known as “Direct Post Method”. 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 [secure.eBizCharge.com](http://secure.eBizCharge.com), click on Settings, and edit the source key 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. [block:code] { "codes": [ { "code": "<form action=\"https://secure.eBizCharge.com/gate.php \" method=\"POST\">\n<input type=\"hidden\" name=\"UMkey\" value=\"Your_source_key_here\">\n<input type=\"hidden\" name=\"UMredirApproved\"\nvalue=\"http://www.mycompany.com/orderapproved.html\">\n<input type=\"hidden\" name=\"UMinvoice\" value=\"123456\">\n<input type=\"hidden\" name=\"UMamount\" value=\"1.00\">\nFull Name: <input type=\"text\" name=\"UMname\"><br>\nStreet: <input type=\"text\" name=\"UMstreet\"><br>\nCity: <input type=\"text\" name=\"city\"><br>\nState: <input type=\"text\" name=\"state\"><br>\nZip: <input type=\"text\" name=\"UMzip\"><br>\n<br>\n<br>\nCredit Card Info:<br>\nCard Type: <select name=cardtype>\n<option>Visa\n<option>Mastercard\n<option>Amex</select><br>\nCard Number: <input type=\"text\" name=\"UMcard\"><br>\nExpiration: <input type=\"text\" name=\"UMexpir\"><br>\nName On Card: <input type=\"text\" name=\"UMname\"><br>\n<br>\n<br>\n<input type=\"submit\" value=\"Place Order\">\n</form>", "language": "html" } ] } [/block] ##ePayment Form / Check-Out Form The [payment](/docs/overview) form allows you 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](/docs/overview), the merchant's website needs to redirect the customer to a specially formatted URL or display a form that will post to the eBizCharge site. For more information on using the payment form, please see the [ePayment Form Manual](/docs/overview). ##Processing Commands 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. [block:parameters] { "data": { "0-0": "cc:sale", "h-0": "Command", "h-1": "Alternate/Legacy Equivalents", "h-2": "Pin Required", "0-1": "sale", "1-0": "cc:authonly", "1-1": "preauth, authonly", "2-0": "cc:capture", "2-1": "capture", "3-0": "cc:adjust", "3-1": "adjust", "4-0": "cc:credit", "4-1": "credit", "5-0": "cc:postauth", "5-1": "postauth", "6-0": "check:sale", "6-1": "check", "7-0": "check:credit", "7-1": "checkcredit, reverseach", "7-2": "Yes", "8-0": "void", "8-1": "cc:void, check:void", "9-0": "refund", "9-1": "cc:refund, check:refund", "10-0": "creditvoid", "10-2": "Yes" }, "cols": 3, "rows": 11 } [/block] ##cc:sale - Credit Card Sale *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. ##cc:authonly - Credit Card Authorization *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. ##cc:capture- Capture an AuthOnly Transaction *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 tolerances 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. ##cc:adjust- Adjust a Credit Card Transaction *UMcommand=cc:adjust* The 'cc:adjust' command allows you to make changes to an existing (unsettled) sale. The authorization amount can be increased (incremental authorization) or decreased (partial reversal) or not changed. Additional data elements such as tax amount and po number can be added. The original Transaction ID (refnum) must be passed in UMrefNum field. The tolerances for the settle amount vary depending on the type of Merchant Account and the merchant service provider. The adjust and capture commands function identically except that the adjust command does not place the transaction in the batch. ##cc:postauth - Offline Credit Card Transaction *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. ##cc:credit - Credit Card Refund *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. ##Check:Sale - ACH/EFT Check Sale *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. ##Check:Credit - ACH/EFT Check Credit *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. ##void: Cancel Previous Transaction *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. ##refund: Refund Previous sale *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. [block:api-header] { "type": "basic", "title": "Optional Features" } [/block] ## Merchant Email Receipts (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 [secure.eBizCharge.com](http://secure.eBizCharge.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. ## Electronic Checks 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). ## Recurring Billing 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 UMaddcustomer command must be set to yes and the initial charge must be approved. Once the initial charge is approved and the UMaddcustomer 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.)If you do not want to enable recurring billing for this customer, set UMschedule=disabled. ## VPAS (Verified by Visa) and UCAF (Mastercard Secure Code) 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.) ##Source Pin Code 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 transaction amount, the invoice, and an optional random seed value. This information is separated by colons and run through an md5 or sha1 algorithm. The algorithm produces a hash, which is then sent to the gateway in the UMhash field where it is matched against the hash from the pin on file. If the two hashes do not match, the transaction is rejected. **Format of UMhash** [block:parameters] { "data": { "h-0": "Field", "h-1": "Value", "h-2": "Description", "0-0": "Algorithm", "0-1": "'m' or 's'", "0-2": "A one character code indicating the algorithm used. 'm' = MD5 and 's' = SHA1", "1-0": "(separator)", "1-1": "'/'", "2-0": "Seed", "2-1": "(up to 256 chars)", "2-2": "Optional random seed value. Must match seed value used inside hash value. Also must be upper case letter and/or numbers.", "3-0": "(separator)", "3-1": "'/'", "4-0": "Hash", "4-1": "(32 or 40 Char Hex)", "4-2": "MD5 or Sha1 Hash value in hex format.", "5-0": "(separator)", "5-1": "'/'", "6-0": "Response", "6-1": "'y' or 'n'", "6-2": "Request a response hash. If omitted, defaults to 'n'" }, "cols": 3, "rows": 7 } [/block] Example UMhash value: *UMhash=m/2123123/8827380daee8c6f935d3eaecf63e646c/y* **Calculating Hash Value** The data used to calculate the hash value are the command, the source key pin, the transaction amount, the invoice and the random seed value separated by colons. The resulting data is sent to MD5 or SHA1 function which will produce the hash value. For example: [block:parameters] { "data": { "0-0": "Command", "0-1": "sale", "1-0": "Pin", "1-1": "sd*s3j002jd", "2-0": "Amount", "2-1": "53.21", "3-0": "Invoice", "3-1": "34576721", "4-0": "Seed", "4-1": "1234" }, "cols": 2, "rows": 5 } [/block] Would result in the following data: [block:parameters] { "data": { "0-0": "Data String", "0-1": "sale:sd*s3j002jd:53.21:34576721:1234", "1-0": "MD5 Hash String", "1-1": "52d534dd45388432ac0a44c9174ffb3f", "2-0": "UMhash Value", "2-1": "m/1223/52d534dd45388432ac0a44c9174ffb3f/" }, "cols": 2, "rows": 3 } [/block] The following is a sample implementation in PHP: [block:code] { "codes": [ { "code": "<?php\n$umcommand = \"sale\" ;\n$umkey = \"Your_source_key_here\" ;\n$card = \"4444111122223337\" ;\n$expir = \"0209\";\n$pin = \"hs4rk\";\n$amount = \"29.30\" ;\n$invoice = \"45671\" ;\n$hashseed = mktime (); // mktime returns the current time in seconds since epoch.\n$hashdata = $umcommand . \":\" . $pin . \":\" . $amount . \":\" . $invoice . \":\" . $hashseed ;\n$hash = md5 ( $hashdata ); // php includes a built-in md5 function that will create the hash\n$request = \"UMkey=$umkey&UMhash=m/$hashseed/$hash/y&UMamount=$amount&UMinvoice=$invoice\" ;\n$request .= \"&UMcard=$card&UMexpir=$expir\" ;\n?>\n ", "language": "php" } ] } [/block] **Verify Response Hash Value** If requested in the UMhash, the server will generate a response hash value. This response hash value can be used to verify that the response value was generated by the gateway. This is useful when using a response landing page with the client side or payment form integrations. [block:parameters] { "data": { "h-0": "Field", "h-1": "Value", "h-2": "Description", "0-0": "Algorithm", "0-1": "'m' or 's'", "0-2": "A one character code indicating the algorithm used. 'm' = MD5 and 's' = SHA1", "1-0": "(separator)", "1-1": "'/'", "2-0": "Seed", "2-1": "(up to 256 chars)", "2-2": "Seed value used to create", "3-0": "(separator)", "3-1": "'/'", "4-0": "Hash", "4-1": "(32 or 40 Char Hex)", "4-2": "MD5 or Sha1 Hash value in hex format." }, "cols": 3, "rows": 5 } [/block] The hash value is the combination of the Pin, UMresult, UMrefNum and the Seed, separated by colons. The following is a sample implementation in PHP: [block:code] { "codes": [ { "code": "<?php\n// Pin assigned to source key\n$pin='1234';\n// break apart response hash\nif(!$_REQUEST['UMresponseHash']) die('Gateway did not return a response hash');\n$tmp = explode('/', $_REQUEST['UMresponseHash']);\n$gatewaymethod = $tmp[0];\n$gatewayseed = $tmp[1];\n$gatewayhash = $tmp[2];\n// assembly prehash data\n$prehash = $pin . ':' . $_REQUEST[\"UMresult\"] . ':' . $_REQUEST[\"UMrefNum\"] . ':' . $gatewayseed;\n// calculate what we think the hash should be\nif($gatewaymethod=='m') $myhash=md5($prehash);\nelse if($gatewaymethod=='s') $myhash=sha1($prehash);\nelse die('Unknown hash method');\n// Compare our hash to gateway's hash\nif($myhash == $gatewayhash)\n{\n echo \"Transaction response validated\";\n} else {\n echo \"Invalid transaction response\";\n}\n?>", "language": "php" } ] } [/block] ## Split Payments **Requirements** * There will be 2 or more authorizations obtained, depending on how many “splits” * Each merchant will have their respective split accessible in the reports section * The cardholder sees two or more separate charges with the DBA names of the respective merchants on the statement. * At least 2 MIDs (Merchant IDs) are required, with a source key generated in each account. **Usage** 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. [block:code] { "codes": [ { "code": "<form action=\"https://secure.eBizCharge.com/secure/gate\" method=\"POST\">\n<!-- Base Information, Source key for concert venue -->\n<input type=\"hidden\" name=\"UMkey\" value=\"Your_source_key_here\">\n<input type=\"hidden\" name=\"UMname\" value=\"John Smith\">\n<input type=\"hidden\" name=\"UMamount\" value=\"25.00\">\n<input type=\"hidden\" name=\"UMdescription\" value=\"Ticket to Concert\">\n<input type=\"hidden\" name=\"UMcard\" value=\"4444555566667779\">\n<input type=\"hidden\" name=\"UMexpir\" value=\"0909\">\n<input type=\"hidden\" name=\"UMstreet\" value=\"1234 Main Street\">\n<input type=\"hidden\" name=\"UMzip\" value=\"01029\">\n<!-- Additional Information for Service Fee, Source key for Service Company -->\n<input type=\"hidden\" name=\"UM02key\" value=\"Your_source_key_here\">\n<input type=\"hidden\" name=\"UM02amount\" value=\"2.00\">\n<input type=\"hidden\" name=\"UM02description\" value=\"Servicing Fee\">\n<input type=\"submit\" value=\"Continue\">\n</form>", "language": "html" } ] } [/block] 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: [block:code] { "codes": [ { "code": "<input type=\"hidden\" name=\"UMdescription\" value=\"First description\">\n<input type=\"hidden\" name=\"UM02description\" value=\"\">", "language": "html" } ] } [/block] 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 must always be two digits: UM02key not UM2key. **Handling errors** 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. **Result Codes** 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. **## Examples** ## 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. [block:code] { "codes": [ { "code": "<form action=\"https://secure.eBizCharge.com/gate\">\n<input type=\"hidden\" name=\"UMkey\" value=\"Your_source_key_here\">\n<!-- Enter your source key, above is a dummy key -->\n<input type=\"hidden\" name=\"UMcommand\" value=\"creditvoid\"> <!-- Credit / Void command -->\n<input type=\"hidden\" name=\"UMrefNum\" value=\"55001467\">\n<!-- Reference number (transaction ID) of the original transaction -->\n<input type=\"hidden\" name=\"UMinvoice\" value=\"123456\">\n<input type=\"hidden\" name=\"UMhash\" value=\"cea9cc2f86f666edda4d855ce523f6ae\">\n<input type=\"submit\" value=\"Process CreditVoid\">\n</form>", "language": "html" } ] } [/block] 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. ##** 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 NOTE: It is recommended that developers use the sandbox server instead of test mode. Test mode is a simple echo test and is only useful for checking that you are send and receiving data correctly. Transaction data is not stored when in test mode which will prevent you from: viewing transaction data in the console, testing customer/merchant receipts, capturing/voiding transactions. ## Sandbox Server The sandbox server provides a full simulation of the production environment. It allows developers to test all aspects of processing before putting their project into production. The system is self contained and credit cards will not actually be charged. To use the transaction api on the sandbox server change the url from https://secure.eBizCharge.com/gate to https://sandbox.eBizCharge.com/gate. You will also need to use a UMkey generated on the sandbox server. Keys created in production will not work on the sandbox server and vice versa. ## 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. [block:parameters] { "data": { "h-0": "Code", "h-1": "Alternates", "h-2": "Meaning", "0-0": "YYY", "0-1": "Y, YYA, YYD", "0-2": "Address: Match & 5 Digit Zip: Match", "1-0": "NYZ", "1-1": "Z", "1-2": "Address: No Match & 5 Digit Zip: Match", "2-0": "YNA", "2-1": "A, YNY", "2-2": "Address: Match & 5 Digit Zip: No Match", "3-0": "NNN", "3-1": "N, NN", "3-2": "Address: No Match & 5 Digit Zip: No Match", "4-0": "YYX", "4-1": "X", "4-2": "Address: Match & 9 Digit Zip: Match", "5-0": "NYW", "5-1": "W", "5-2": "Address: No Match & 9 Digit Zip: Match", "6-0": "XXW", "6-2": "Card Number Not On File", "7-0": "XXU", "7-2": "Address Information not verified for domestic transaction", "8-0": "XXR", "8-1": "R, U, E", "8-2": "Retry / System Unavailable", "9-0": "XXS", "9-1": "S", "9-2": "Service Not Supported", "10-0": "XXE", "10-2": "Address Verification Not Allowed For Card Type", "11-0": "XXG", "11-1": "G,C,I", "11-2": "Global Non-AVS participant", "12-0": "YYG", "12-1": "B, M", "12-2": "International Address: Match & Zip: Not Compatible", "13-0": "GGG", "13-1": "D", "13-2": "International Address: Match & Zip: Match", "14-0": "YGG", "14-1": "P", "14-2": "International Address: No Compatible & Zip: Match" }, "cols": 3, "rows": 15 } [/block] ##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. [block:parameters] { "data": { "h-0": "Code", "h-1": "Meaning", "0-0": "M", "0-1": "Match", "1-0": "N", "1-1": "No Match", "2-0": "P", "2-1": "Not Processed", "3-0": "S", "3-1": "Should be on card but not so indicated", "4-0": "U", "4-1": "Issuer Not Certified", "5-0": "X", "5-1": "No response from association", "6-0": "(blank)", "6-1": "No CVV2/CVC data available for transaction." }, "cols": 2, "rows": 7 } [/block] ##Card Level Result Codes The following is a list of result codes for the card level results and what each one indicates. These codes are returned in the UMcardLevelResult variable and provide developers with extended information about the type of Visa Card that is being processed. [block:parameters] { "data": { "h-0": "Code", "h-1": "Description", "0-0": "A", "0-1": "Visa Traditional", "1-0": "B", "1-1": "Visa Traditional Rewards", "2-0": "C", "2-1": "Visa Signature", "3-0": "D", "3-1": "Visa Signature Preferred", "4-0": "G", "4-1": "Visa Business", "5-0": "H", "5-1": "Visa Consumer Check Card", "6-0": "I", "6-1": "Visa Commerce", "7-0": "K", "7-1": "Visa Corporate", "8-0": "M", "8-1": "MasterCard/EuroCard and Diners", "9-0": "S", "9-1": "Visa Purchasing", "10-0": "U", "10-1": "Visa TravelMoney", "11-0": "G1", "11-1": "Visa Signature Business", "12-0": "G2", "12-1": "Visa Business Check Card", "13-0": "J1", "13-1": "Visa General Prepaid", "14-0": "J2", "14-1": "Visa Prepaid Gift Card", "15-0": "J3", "15-1": "Visa Prepaid Healthcare", "16-0": "J4", "16-1": "Visa Prepaid Commercial", "17-0": "K1", "17-1": "Visa GSA Corporate T&E", "18-0": "S1", "18-1": "Visa Purchasing with Fleet", "19-0": "S2", "19-1": "Visa GSA Purchasing", "20-0": "S3", "20-1": "Visa GSA Purchasing with Fleet", "21-0": "DI", "21-1": "Discover", "22-0": "AX", "22-1": "American Express" }, "cols": 2, "rows": 23 } [/block] ## API Version Number 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. ## CGI Post Variables 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** [block:parameters] { "data": { "h-0": "Field", "h-1": "Required", "h-2": "Description", "3-0": "UMignoreDuplicate", "3-2": "Set to yes if you would like to override the duplicate transaction handling.", "0-0": "UMcommand", "0-2": "Processing Command. Possible values are: cc:sale, cc:authonly, cc:capture, cc:credit, cc:postauth, check:sale, check:credit, void, refund and creditvoid. Default is sale.", "1-0": "UMkey", "1-1": "ALL", "1-2": "The source key (assigned by the server when you created a source in your virtual terminal).", "2-0": "UMhash", "2-1": "Check:Credit, CreditVoid", "2-2": "If the source key (UMkey) has a pin assigned a validation hash is required (See Source Pin Code section).", "4-0": "UMauthCode", "4-1": "CC:PostAuth", "4-2": "Authorization Code obtained “offline” (ie telephone authorization). Only required for Post Auth.", "5-0": "UMrefNum", "5-1": "CC:Capture,Void,Refund, CreditVoid", "5-2": "The UMrefNum received when a transaction was authorized via either the “sale” or “authonly” commands. Required for void and capture commands.", "6-0": "UMcard", "6-1": "CC:Sale, CC:AuthOnly, CC:Credit, CC:PostAuth", "7-0": "UMsaveCard", "7-2": "If set to true and the transaction has been approved, the system will issue a token for future use.", "8-0": "UMexpir", "8-1": "CC:Sale, CC:AuthOnly, CC:Credit, CC:PostAuth", "8-2": "Expiration Date in the form of MMYY with no spaces or punctuation.", "9-0": "UMrouting", "9-1": "Check:Sale, Check:Credit", "9-2": "Bank Routing number. Required when UMcommand is set to check or checkcredit.", "10-0": "UMaccount", "10-1": "Check:Sale, Check:Credit", "10-2": "Checking Account Number. Required when UMcommand is set to check or checkcredit.", "11-0": "UMaccounttype", "11-2": "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.", "12-0": "UMcheckformat", "12-2": "Record type of electronic check transaction. Not supported by all check processors. [List of Check Record Types](/docs/ach-check-file-formats) Also known as SEC code.", "13-0": "UMamount", "13-2": "CC:Sale, CC:AuthOnly, CC:PostAuth, CC:Credit, Check:Sale, Check:Credit\nCharge amount without $. This is the grand total including tax, shipping and any discounts.", "14-0": "UMallowPartialAuth", "14-2": "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", "15-0": "UMcurrency", "15-1": "*", "15-2": "Currency of UMamount. Required if using a [MCP](/docs/multi-currency-processing) based account. Must be one of the 3 digit numeric codes found [here](/docs/currency-codes-1).", "16-0": "UMtax", "16-2": "Portion of above charge amount (UMamount) that is sales tax.", "17-0": "UMnontaxable", "17-2": "Set to yes if transaction is not taxable. (optional, platform dependant)", "18-0": "UMtip", "18-2": "Portion of charge amount (UMamount) for gratuity (tip).", "19-0": "UMshipping", "19-2": "Portion of above charge amount (UMamount) that is for shipping charges.", "20-0": "UMduty", "20-2": "Duty charge (Required only for level 3)", "21-0": "UMdiscount", "21-2": "The amount of any discounts that were applied.", "22-0": "UMsubtotal", "22-2": "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.", "23-0": "UMcustid", "23-2": "Unique customer id.", "24-0": "UMinvoice", "24-1": "*", "24-2": "Unique Invoice or order number. 10 digits. While not required, it is strongly recommended that this field be populated for CC:Sale, CC:AuthOnly, CC:PostAuth, CC:Credit, Check:Sale and Check:Credit", "25-0": "UMorderid", "25-2": "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.", "26-0": "UMponum", "26-2": "Purchase Order number. Only required for corporate purchasing cards.", "27-0": "UMticket", "27-2": "Obsolete, included for backward compatibility. Use UMinvoice instead", "28-0": "UMdescription", "28-2": "Description of transaction.", "29-0": "UMcomments", "29-2": "Optional transaction comments field. Comments are displayed on the transaction details page.", "30-0": "UMname", "30-1": "*", "30-2": "Name on card or checking account. While not required, it is strongly recommended that this field be populated for CC:Sale, CC:AuthOnly, CC:PostAuth, CC:Credit, Check:Sale and Check:Credit", "31-0": "UMstreet", "31-1": "*", "31-2": "Billing Street Address for credit cards. Used for Address Verification System. While not required, this field should be populated for Fraud Prevention and to obtain the best rate for Ecommerce credit card transactions. It should be populated for CC:Sale and CC:AuthOnly", "32-0": "UMzip", "32-1": "*", "32-2": "Billing Zip Code for credit cards. Used for Address Verification System. While not required, this field should be populated for Fraud Prevention and to obtain the best rate for Ecommerce credit card transactions. It should be populated for CC:Sale and CC:AuthOnly", "33-0": "UMcvv2", "33-1": "*", "33-2": "CVV2 data for Visa. Set to -2 if the code is not legible, -9 if the code is not on the card. While not required, this field should be populated for Fraud Prevention and to obtain the best rate for Ecommerce credit card transactions. It should be populated for CC:Sale and CC:AuthOnly", "34-0": "UMcustemail", "34-2": "Customer's Email Address.", "35-0": "UMcustreceipt", "35-2": "Yes/No. Sends the Customer a Receipt. This overrides the setting for the merchant and source.", "36-0": "UMcustreceiptname", "36-2": "Name of the custom receipt template to use. If omitted or if receipt not found, default customer receipt template will be used", "37-0": "UMdlnum", "37-2": "Driver's license number.", "38-0": "UMdlstate", "38-2": "Driver's license state of issue.", "39-0": "UMchecknum", "39-2": "Check number.", "40-0": "UMcheckimagefront", "40-2": "JPG image of front side of check. (optional) If data is encoded, encoding must match UMcheckimageencoding", "41-0": "UMcheckimageback", "41-2": "JPG image of back side of check. (optional) If data is encoded, encoding must match UMcheckimageencoding", "42-0": "UMcheckimageencoding", "42-2": "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.", "43-0": "UMclerk", "43-2": "Indicates the clerk/person processing transaction, for reporting purposes. (optional)", "44-0": "UMtranterm", "44-2": "Indiactes the terminal used to process transaction, for reporting purposes. (optional)", "45-0": "UMresttable", "45-2": "Indicates the restaurant table, for reporting purposes. (optional)", "46-0": "UMip", "46-2": "The IP address of the client requesting the transaction. This is used in many of the fraud modules.", "47-0": "UMsoftware", "47-2": "Allows application developers to stamp their application name and version number onto each transaction. Used to assist customers with trouble shooting. (optional)", "48-0": "UMredir", "49-0": "UMredirApproved", "49-2": "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.", "50-0": "UMredirDeclined", "50-2": "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.", "51-0": "UMechofields", "51-2": "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 UMredir 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.", "52-0": "UMonError", "52-2": "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”", "53-0": "UMtestmode", "53-2": "If UMtestmode is set to 1 the gateway will simulate a transaction without actually processing the card. No transaction data is stored when testmode is enabled. You will not see the transaction on reports or in the batch. Use of testmode is discouraged for anything more than rudimentary integration testing. For a better simulation of a transaction, it is recommended that you use the Sandbox." }, "cols": 3, "rows": 54 } [/block] **Billing and Shipping Address Fields** [block:parameters] { "data": { "h-0": "Billing Address", "h-1": "Shipping Address", "0-0": "UMbillfname", "0-1": "UMshipfname", "1-0": "UMbilllname", "1-1": "UMshiplname", "2-0": "UMbillcompany", "2-1": "UMshipcompany", "3-0": "UMbillstreet", "3-1": "UMshipstreet", "4-0": "UMbillstreet2", "4-1": "UMshipsreet2", "5-0": "UMbillcity", "5-1": "UMshipcity", "6-0": "UMbillstate", "6-1": "UMshipstate", "7-0": "UMbillzip", "7-1": "UMshipzip", "8-0": "UMbillcountry", "8-1": "UMshipcountry", "9-0": "UMbillphone", "9-1": "UMshipphone", "10-0": "UMemail", "10-1": "UMemail", "11-0": "UMfax", "11-1": "UMfax", "12-0": "UMwebsite", "12-1": "UMwebsite" }, "cols": 2, "rows": 13 } [/block] **Stored Customers and Recurring Billing** [block:parameters] { "data": { "h-0": "Field", "h-1": "Description", "0-0": "UMaddcustomer", "0-1": "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.", "1-0": "UMschedule", "1-1": "Determines the recurring billing schedule. Possible values are daily, weekly, biweekly, monthly, bimonthly, quarterly, biannually, or annually. (defaults to monthly) If you do not want to enable recurring billing for this customer, set UMschedule=disabled", "2-0": "UMbillsourcekey", "2-1": "If set to yes, the customer will be stored under the source key specified by UMkey. Otherwise the customer will be stored under the default 'Recurring' key.", "3-0": "UMbillamount", "3-1": "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.", "4-0": "UMnumleft", "4-1": "Number of transactions remaining in recurring billing cycle. If the recurring billing should go on indefinitely, set this to *. (defaults to *)", "5-0": "UMstart", "5-1": "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.", "6-0": "UMrecurringreceipt", "6-1": "Yes/No. Sends the Customer a Recurring Billing Receipt." }, "cols": 2, "rows": 7 } [/block] **Merchant Defined Custom Fields** The merchant can create up to 20 fields for storing custom data. This data is stored for both transactions and customers. For a transaction this data is visible on the transaction details screen. For customers the data can be viewed by editing a customer in the customer database. [block:parameters] { "data": { "h-0": "Field", "h-1": "Max Length", "h-2": "Description", "0-0": "UMcustom1", "0-1": "255", "0-2": "Optional fields for storing custom data.", "1-0": "UMcustom2", "1-1": "255", "2-0": "UMcustom3", "2-1": "255", "3-0": "…", "4-0": "UMcustom19", "4-1": "255", "5-0": "UMcustom20", "5-1": "255" }, "cols": 3, "rows": 6 } [/block] **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. [block:parameters] { "data": { "h-0": "Field", "h-1": "Max Length", "h-2": "Description", "0-0": "UMline*productrefnum", "0-1": "12", "0-2": "(optional) Gateway assigned product RefNum, used for inventory control.", "1-0": "UMline*sku", "1-1": "32", "1-2": "Product id, code or SKU", "2-0": "UMline*name", "2-1": "255", "2-2": "Item name or short description", "3-0": "UMline*description", "3-1": "64k", "3-2": "Long description", "4-0": "UMline*cost", "4-1": "00000000.00", "4-2": "Cost of item per unit of measure (before tax or discount)", "5-0": "UMline*qty", "5-1": "00000000.0000", "5-2": "Quantity", "6-0": "UMline*taxable", "6-1": "1", "6-2": "Y = Taxable, N = Non-taxable", "7-0": "UMline*taxrate", "7-1": "00.000", "7-2": "Tax rate for line (only required for level 3 processing)", "8-0": "UMline*taxamount", "8-1": "00000000.00", "8-2": "Amount of tax charge for line (if left blank will be calculated from taxrate)", "9-0": "UMline*um", "9-1": "12", "9-2": "Unit of measure. If left blank or an invalid code is sent, EA (Each) will be used. See list of valid [unit of measure codes](/docs/unit-of-measure-codes)", "10-0": "UMline*commoditycode", "10-1": "12", "10-2": "Commodity code (only required for level 3 processing). See http://www.unspsc.org/ for valid list of codes.", "11-0": "UMline*discountrate", "11-1": "000.000", "11-2": "Discount percentage for line (only required for level 3 processing)", "12-0": "UMline*discountamount", "12-1": "00000000.00", "12-2": "Discount amount for line (if left blank will be calculated from discountrate)" }, "cols": 3, "rows": 13 } [/block] * 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: [block:parameters] { "data": { "h-0": "Field", "h-1": "Description", "0-0": "UMcardauth", "0-1": "Set UMcardauth=true to enable cardholder authentication using the integrated gateway authentication system.", "1-0": "UMpares", "1-1": "Cardholder authentication payload. (When using integrated authentication system.)", "2-0": "UMxid", "2-1": "This field is obsolete.", "3-0": "UMcavv", "3-1": "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.)", "4-0": "UMeci", "4-1": "ECI value received from third party authenticator. (Only needed if not using the gateway authentication system.)" }, "cols": 2, "rows": 5 } [/block] **Card Present Fields** The following fields are only required in a card present environment such as a retail store, restaurant or hotel. [block:parameters] { "data": { "h-0": "Field", "h-1": "Description", "0-0": "UMcardpresent", "0-1": "Set UMcardpresent=true to enable card present mode. If UMmagstripe is sent, UMcardpresent will be automatically set to true.", "1-0": "UMmagstripe", "1-1": "Mag stripe data read from card. Can include Track 1, Track 2 or both. For encrypted track data, base64 encode the entire block (including masked track data) and then prepend with “enc : / /”. See [End To End Encryption](/docs/end-to-end-encryption)", "2-0": "UMdukpt", "2-1": "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.", "3-0": "UMtermtype", "3-1": "The type of terminal being used: POS (cash register), StandAlone (self service terminal), Unattended (ie gas pump) Unkown (defaults to Unknown)", "4-0": "UMmagsupport", "4-1": "Describes the magstripe reading capabilities of your POS hardware: yes, no, contactless, unknown (default is unknown unless magstripe has been sent).", "5-0": "UMcontactless", "5-1": "UMmagstripe was read via contactless swiper: yes or no (default is no).", "6-0": "UMsignature", "6-1": "Cardholder signature captured by pos device. Base64 encoded." }, "cols": 2, "rows": 7 } [/block] **Lodging Industry** The following fields are only applicable in the hotel/lodging environment. The fields will be ignored if the merchant is not configured for this industry. Not all fields are applicable for all platforms but may be provided for reporting purposes. Contact integration support for specific platform requirements. [block:parameters] { "data": { "h-0": "Field", "h-1": "Description", "0-0": "UMfolio", "0-1": "Folio Number", "1-0": "UMroomRate", "1-1": "Nightly Room Rate", "2-0": "UMnights", "2-1": "Number of nights", "3-0": "UMcheckInDate", "3-1": "Guest Check In Date", "4-0": "UMcheckOutDate", "4-1": "Guest Check Out Date", "5-0": "UMextraChargeReasons", "6-0": "UMroomNumber", "7-0": "UMcustomerCode", "8-0": "UMlengthOfStay", "9-0": "UMroomTaxRate", "10-0": "UMnonRoomCharges", "11-0": "UMroomTaxAmount", "12-0": "UMpreferredCustomer", "13-0": "UMchargeType", "14-0": "UMdepartureTime", "15-0": "UMarrivalTime" }, "cols": 2, "rows": 16 } [/block] ## 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. To pass other fields, make sure to pass UMechofields=yes and to not use names that start with “UM”. [block:parameters] { "data": { "h-0": "Field", "h-1": "Description", "0-0": "UMstatus", "0-1": "Status of the transaction. The possible values are: Approved, Declined, Verification and Error.", "1-0": "UMauthCode", "1-1": "Authorization number.", "2-0": "UMauthAmount", "2-1": "Amount authorized. May be less than amount requested if UMallowPartialAuth=true", "3-0": "UMrefNum", "3-1": "Transaction reference number", "4-0": "UMbatch", "4-1": "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.", "5-0": "UMremainingBalance", "5-1": "Returns the balance remaining on some prepaid and stored value cards", "6-0": "UMavsResult", "6-1": "AVS result in readable format", "7-0": "UMavsResultCode", "7-1": "[AVS result code](/docs/avs-result-codes-1).", "8-0": "UMcvv2Result", "8-1": "CVV2 result in readable format.", "9-0": "UMcvv2ResultCode", "9-1": "[CVV2 result code.](/docs/cvv2-response-codes)", "10-0": "UMvpasResultCode", "10-1": "Verified by Visa (VPAS) or Mastercard SecureCode (UCAF) result code.", "11-0": "UMresult", "11-1": "Transaction result - A, D, E, or V (for Verification)", "12-0": "UMerror", "12-1": "Error [description ](/docs/description)if UMstatus is Declined or Error.", "13-0": "UMerrorcode", "13-1": "A [numerical ](/docs/description)error code.", "14-0": "UMacsurl", "14-1": "Verification URL to send cardholder to. Sent when UMstatus is verification (cardholder authentication is required).", "15-0": "UMpayload", "15-1": "Authentication data to pass to verification url. Sent when UMstatus is verification (cardholder authentication is required).", "16-0": "UMisDuplicate", "16-1": "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.", "17-0": "UMconvertedAmount", "17-1": "Amount converted to merchant's currency, when using a [multi-currency processor](/docs/multi-currency-processing).", "18-0": "UMconvertedAmountCurrency", "18-1": "Merchant's currency, when using a [multi-currency processor](/docs/multi-currency-processing).", "19-0": "UMconversionRate", "19-1": "Conversion rate used to convert currency, when using a [multi-currency processor](/docs/multi-currency-processing).", "20-0": "UMcustnum", "20-1": "Customer reference number assigned by gateway. Returned only if UMaddcustomer=yes.", "21-0": "UMresponseHash", "21-1": "Response verification hash. Only present if response hash was requested in the UMhash. (See Source Pin Code section for further details)", "22-0": "UMprocRefNum", "22-1": "Transaction Reference number provided by backend processor (platform), blank if not available)", "23-0": "UMcardLevelResult", "23-1": "[Card level results](/docs/card-level-codes-1) (for Visa cards only), blank if no results provided", "24-0": "UMcardRef", "24-1": "Card reference token. 16-19 digit alphanumeric string. It is returned with dashes but it is not required that these be stored.", "25-0": "UMcardType", "25-1": "The type of card that was submitted, ie “Visa”", "26-0": "UMmaskedCardNum", "26-1": "The masked out card number including the last 4 digits" }, "cols": 2, "rows": 27 } [/block]