developer:transactionapi

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
developer:transactionapi [2012/07/09 09:04]
tem
developer:transactionapi [2015/07/16 21:11] (current)
tem
Line 127: Line 127:
 | cc:authonly | preauth, authonly | | | cc:authonly | preauth, authonly | |
 | cc:capture | capture |  | | cc:capture | capture |  |
-| cc:adjust | adjust |  |+| cc:adjust | adjust | Yes |
 | cc:credit | credit | | | cc:credit | credit | |
 | cc:postauth | postauth | | | cc:postauth | postauth | |
Line 135: Line 135:
 | refund | cc:refund, check:​refund | | | refund | cc:refund, check:​refund | |
 | creditvoid | | Yes | | creditvoid | | Yes |
 +| giftcard:​sale | sale |
 +| giftcard:​refund | refund | Yes |
 +| giftcard:​activate | activate | Yes |
 +| giftcard:​addvalue | addvalue | Yes |
 +| giftcard:​balance | balance | Yes |
 +| giftcard:​void | void | Yes |
 +| giftcard:​transfer | transfer | Yes |
 +
  
  
Line 165: Line 173:
 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. 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.
  
 +  *Developers can capture transactions using the "​cc:​capture:​reauth" ​ command. If the authorization has not expired, it will place the transaction in the batch for settlement. If the authorization has expired, it will attempt to reauthorize the same card. The developer does not need to know the state of the transaction ahead of time. They only need to post the original transaction reference number.
 +  *We do not allow setting the expiration time to longer that 30 days. We do however, have a "​cc:​capture:​override"​ command that will force a capture, even if the authorization has exceeded the maximum 30 days.  We would not recommend capturing transactions over 60 days due to the charge back risk.
  
 ==== cc:adjust- Adjust a Credit Card Transaction ==== ==== cc:adjust- Adjust a Credit Card Transaction ====
Line 173: Line 183:
  
 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. 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.
 +
 +  * Refunds can be performed via the "​cc:​refund:​adjust"​ command.If the authorization has not settled yet, it will adjust the authorization amount down to the new amount (releasing funds back to the card holder in realtime). If the authorization has settled,a credit transaction will be submitted.The developer does not need to know what state the transaction is in ahead of time.They only need to post the original transaction reference number and amount being refunded.
  
  
Line 235: Line 247:
 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. 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.
  
 +==== giftcard:​sale ====
  
 +<​code>​
 +UMcommand=giftcard:​sale
 +</​code>​
 +
 +giftcard sale reduces the available balance associated with the gift card account and returns the remaining balance back to the terminal.
 +
 +==== giftcard:​refund ====
 +<​code>​
 +UMcommand=giftcard:​refund
 +</​code>​
 +
 +giftcard refund allows you to refund/​credit the card back. 
 +==== giftcard:​activate ====
 +
 +<​code>​
 +UMcommand=giftcard:​activate
 +</​code>​
 +
 +For giftcard activate the cards are required to be activated before use and then you can pass in a starting balance. ​
 +
 +==== giftcard:​addvalue ====
 +<​code>​
 +UMcommand=giftcard:​addvalue
 +</​code>​
 +
 +giftcard addvalue increases the available balance on the associated gift card account (issuer maximums may apply)
 +
 +==== giftcard:​balance ====
 +
 +<​code>​
 +UMcommand=giftcardbalance
 +</​code>​
 +
 +giftcard balance returns the available balance on the gift card account
 +
 +
 +==== giftcard:​transfer ====
 +
 +<​code>​
 +UMcommand=giftcard:​transfer ​
 +</​code>​
 +
 +giftcard transfer moves the entire balance off of one giftcard to another. You would put two card numbers, separated by a comma and it transfers from the first to the second. ​
 ===== Optional Features ===== ===== Optional Features =====
  
Line 245: Line 301:
 ==== Electronic Checks ==== ==== 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). 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).
 +
 +==== Gift Cards ====
 +Visa, Mastercard and Amex branded giftcards can be processed in the same way as normal credit cards using the commands above that start with "​cc:"​. ​ For private branded, closed loop giftcards, ​ merchants can be configured to support a variety of popular giftcard processors. ​  These types of cards are processed using the above commands that start with "​giftcard:"​. ​  For more information on giftcard processing please see the [[developer:​giftcards|gift card documentation]]. ​
 +
  
 ==== Recurring Billing ==== ==== Recurring Billing ====
Line 303: Line 363:
 ^Data String|sale:​sd*s3j002jd:​53.21:​34576721:​1234 | ^Data String|sale:​sd*s3j002jd:​53.21:​34576721:​1234 |
 ^MD5 Hash String|52d534dd45388432ac0a44c9174ffb3f ​ | ^MD5 Hash String|52d534dd45388432ac0a44c9174ffb3f ​ |
-^UMhash Value|m/1223/​52d534dd45388432ac0a44c9174ffb3f/​ |+^UMhash Value|m/1234/​52d534dd45388432ac0a44c9174ffb3f/​ |
  
  
Line 323: Line 383:
 $hash = md5 ( $hashdata );   // php includes a built-in md5 function that will create the hash $hash = md5 ( $hashdata );   // php includes a built-in md5 function that will create the hash
  
-$request = "​UMkey=$umkey&​UMhash=m/​$hashseed/​$hash/​y&​UMamount=$amount&​UMinvoice=$invoice"​ ;+$request = "​UMkey=$umkey&​UMhash=m/​$hashseed/​$hash/​y&​UMamount=$amount&​UMinvoice=$invoice&​UMcommand=$umcommand" ;
 $request .= "&​UMcard=$card&​UMexpir=$expir"​ ; $request .= "&​UMcard=$card&​UMexpir=$expir"​ ;
 ?> ?>
Line 383: Line 443:
   * The cardholder sees two or more separate charges with the DBA names of the respective merchants on the statement.   * 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.   * At least 2 MIDs (Merchant IDs) are required, with a source key generated in each account.
 +
 +NOTE: If you set "​UMaddcustomer=yes",​ it will create customer record on both merchant accounts. ​
  
  
Line 493: Line 555:
  
 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. 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 ==== ==== CGI Post Variables ====
Line 513: Line 565:
  
 ^Field ^ Required ^ Description ^ ^Field ^ Required ^ Description ^
-| UMcommand |      | 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. |+| UMcommand |      | Processing Command. ​ Possible values are: cc:sale, cc:​authonly,​ cc:capture, cc:credit, cc:​postauth,​ check:sale, check:​credit,​ void, refundcreditvoid,  giftcard:​sale,​ giftcard:​refund,​ giftcard:​activate, ​ giftcard:​addvalue,​ giftcard:​balance,​ giftcard:​generate,​ giftcard:​void and giftcard:​transfer  ​Default is sale. |
 | UMkey | ALL | The source key (assigned by the server when you created a source in your virtual terminal). | | UMkey | ALL | The source key (assigned by the server when you created a source in your virtual terminal). |
 | UMhash | Check:​Credit,​ CreditVoid | If the source key (UMkey) ​ has a pin assigned a validation hash is required (See Source Pin Code section). | | UMhash | Check:​Credit,​ CreditVoid | If the source key (UMkey) ​ has a pin assigned a validation hash is required (See Source Pin Code section). |
Line 519: Line 571:
 | UMauthCode | CC:PostAuth | Authorization Code obtained "​offline"​ (ie telephone authorization). Only required for Post Auth. | | UMauthCode | CC:PostAuth | Authorization Code obtained "​offline"​ (ie telephone authorization). Only required for Post Auth. |
 | UMrefNum | CC:​Capture,​Void,​Refund,​ CreditVoid | The UMrefNum received when a transaction was authorized via either the "​sale"​ or "​authonly"​ commands. Required for void and capture commands. ​ | | UMrefNum | CC:​Capture,​Void,​Refund,​ CreditVoid | The UMrefNum received when a transaction was authorized via either the "​sale"​ or "​authonly"​ commands. Required for void and capture commands. ​ |
-| UMcard | CC:Sale, CC:​AuthOnly,​ CC:Credit, CC:PostAuth | Credit Card Number with no spaces or dashes. |+| UMcard | CC:Sale, CC:​AuthOnly,​ CC:Credit, CC:PostAuth | Credit Card Number with no spaces or dashes
 +| UMsaveCard ​   |               | If set to true and the transaction has been approved, the system will issue a token for future use. |
 | UMexpir | CC:Sale, CC:​AuthOnly,​ CC:Credit, CC:PostAuth | Expiration Date in the form of MMYY with no spaces or punctuation. | | UMexpir | CC:Sale, CC:​AuthOnly,​ CC:Credit, CC:PostAuth | Expiration Date in the form of MMYY with no spaces or punctuation. |
 | UMrouting | Check:Sale, Check:​Credit | Bank Routing number. Required when UMcommand is set to check or checkcredit. | | UMrouting | Check:Sale, Check:​Credit | Bank Routing number. Required when UMcommand is set to check or checkcredit. |
Line 526: Line 579:
 | UMcheckformat | | Record type of electronic check transaction. Not supported by all check processors. ​ [[merchant:​checkformat|List of Check Record Types]] Also known as SEC code. | | UMcheckformat | | Record type of electronic check transaction. Not supported by all check processors. ​ [[merchant:​checkformat|List of Check Record Types]] Also known as SEC code. |
 | UMamount | CC:Sale, CC:​AuthOnly,​ CC:​PostAuth,​ CC:Credit, Check:Sale, Check:​Credit | Charge amount without $. This is the grand total including tax, shipping and any discounts. | | UMamount | CC:Sale, CC:​AuthOnly,​ CC:​PostAuth,​ CC:Credit, Check:Sale, Check:​Credit | Charge amount without $. This is the grand total including tax, shipping and any discounts. |
-UMallowPartialAuth ​|  | Yes/No. Indicates whether to allow a partial authorization if the full UMamount is not available ​(for debit, prepaid and gift cards).  If left blank or set to No,  ​the transaction ​will be automatically canceled ​and reversed if full UMamount is not available ​|+UMenablePartialAuth ​|  | Yes/No. Indicates whether to allow a partial authorization ​of funds if the full UMamount is not available. ​ If a lower amount is authorized,  ​UMresult ​will be and UMauthAmount will indicate the lower amount authorized. ​|
 | UMcurrency | * | Currency of UMamount. **Required if using a [[Developer:​multicurrency|MCP]] based account.** ​ Must be one of the 3 digit numeric codes found [[developer:​currencycode|here]]. | | UMcurrency | * | Currency of UMamount. **Required if using a [[Developer:​multicurrency|MCP]] based account.** ​ Must be one of the 3 digit numeric codes found [[developer:​currencycode|here]]. |
 | UMtax |      | Portion of above charge amount (UMamount) that is sales tax. | | UMtax |      | Portion of above charge amount (UMamount) that is sales tax. |
Line 563: Line 616:
 | UMredirApproved |     | Redirection URL - If the card is approved, redirect to this URL. No fields are passed back. Typically merchants should enable merchant receipts with this option. To enable merchant receipts for a source, see Merchant Email Receipts above. | | UMredirApproved |     | Redirection URL - If the card is approved, redirect to this URL. No fields are passed back. Typically merchants should enable merchant receipts with this option. To enable merchant receipts for a source, see Merchant Email Receipts above. |
 | UMredirDeclined |    | Redirection URL - If the card is not approved, redirect to this URL. No fields are passed back. If UMredirApproved is set but UMredirDeclined is not, the gateway will display the template entered in the sources area. This feature overrides the "​Declined Template" ​ feature that is available in the Source Key settings screen. ​  If both are set,  the declined template will be ignored and the user will be redirect to the UMredirDeclined url. | | UMredirDeclined |    | Redirection URL - If the card is not approved, redirect to this URL. No fields are passed back. If UMredirApproved is set but UMredirDeclined is not, the gateway will display the template entered in the sources area. This feature overrides the "​Declined Template" ​ feature that is available in the Source Key settings screen. ​  If both are set,  the declined template will be ignored and the user will be redirect to the UMredirDeclined url. |
-| UMechofields |     ​  ​  | Echo input fields in response. If UMechofields is set to yes 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. |+| UMechofields |     ​  ​  | Echo input fields in response. If UMechofields is set to all then all fields included in the form (except for the credit card number, key, expiration and cvc) will be included in the redirection URL as GET variables. This is only useful with the client-side method. For example if you post a form with the field "​comments"​ to the gateway and set 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. |
 | UMonError ​    ​| ​         | Instructs the gateway what to do when a decline is received when multiple transactions are being processed (see "Split Payments"​ above). ​ Can be set to Stop, Continue or Void.  Defaults to "​Stop"​ | | UMonError ​    ​| ​         | Instructs the gateway what to do when a decline is received when multiple transactions are being processed (see "Split Payments"​ above). ​ Can be set to Stop, Continue or Void.  Defaults to "​Stop"​ |
 | UMtestmode |     ​  ​  | If UMtestmode is set to 1 the gateway will simulate a transaction without actually processing the card.  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 [[developer:​sandbox|Sandbox]]. | | UMtestmode |     ​  ​  | 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 [[developer:​sandbox|Sandbox]]. |
 +| UMtimeout ​   |          | Sets the maximum time in seconds to allow for an approval. ​  If the timeout is exceeded, ​ the transaction will be cancelled and an error will be returned. ​ See [[developer::​timeouts]] for more information about timeouts. |
  
 === Billing and Shipping Address Fields === === Billing and Shipping Address Fields ===
Line 646: Line 700:
 ^ Field ^ Description ^ ^ Field ^ Description ^
 | UMcardpresent ​    | Set UMcardpresent=true to enable card present mode. If UMmagstripe is sent, UMcardpresent will be automatically set to true. | | UMcardpresent ​    | Set UMcardpresent=true to enable card present mode. If UMmagstripe is sent, UMcardpresent will be automatically set to true. |
-| UMmagstripe     | Mag stripe data read from card. Can include Track 1, Track 2 or both. For encrypted track data,  base64 encode the entire block (including masked track data) and then prepend with "enc : / /"​. ​ See [[developer:endtoencryption|end to end encryption]] |+| UMmagstripe     | 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 [[http://​wiki.usaepay.com/​developer/​endtoendencryption|End To End Encryption]] |
 | UMdukpt ​          | DUK/PT key for Pin-Debit transactions. The first 16 characters are the encrypted pin block, followed by the 6 character long Key Set Identifier (KSID). ​ The remaining characters are the Pin Pad serial number and transaction counter. ​ | | UMdukpt ​          | DUK/PT key for Pin-Debit transactions. The first 16 characters are the encrypted pin block, followed by the 6 character long Key Set Identifier (KSID). ​ The remaining characters are the Pin Pad serial number and transaction counter. ​ |
-| UMtermtype     | The type of terminal being used: POS (cash register), StandAlone (self service terminal), Unattended (ie gas pump) Unkown (defaults to Unknown) |+| UMtermtype     | The type of terminal being used: POS (cash register), contactless, StandAlone (self service terminal), Unattended (ie gas pump) Unkown (defaults to Unknown) |
 | UMmagsupport     | Describes the magstripe reading capabilities of your POS hardware: yes, no, contactless,​ unknown (default is unknown unless magstripe has been sent). | | UMmagsupport     | Describes the magstripe reading capabilities of your POS hardware: yes, no, contactless,​ unknown (default is unknown unless magstripe has been sent). |
 | UMcontactless ​    | UMmagstripe was read via contactless swiper: yes or no (default is no).  | | UMcontactless ​    | UMmagstripe was read via contactless swiper: yes or no (default is no).  |
Line 679: Line 733:
  
 ^ Field ^ Description ^ ^ Field ^ Description ^
-| UMstatus | Status of the transaction. ​ The possible values are: Approved, Declined, Verification and Error. |+| UMstatus | Status of the transaction. ​ The possible values are: Approved, Partially ​Approved, Declined, Verification and Error. |
 | UMauthCode | Authorization number. | | UMauthCode | Authorization number. |
-| UMauthAmount ​ | Amount authorized. ​ May be less than amount requested if UMallowPartialAuth=true |+| UMauthAmount ​ | Amount authorized. ​ May be less than amount requested if UMenablePartialAuth=yes |
 | UMrefNum | Transaction reference number | | UMrefNum | Transaction reference number |
 | UMbatch | Batch reference number. This will only be returned for sale and auth commands. Warning: The batch number returned is for the batch that was open when the transaction was initiated. It is possible that the batch was closed while the transaction was processing. In this case the transaction will get queued for the next batch to open. | | UMbatch | Batch reference number. This will only be returned for sale and auth commands. Warning: The batch number returned is for the batch that was open when the transaction was initiated. It is possible that the batch was closed while the transaction was processing. In this case the transaction will get queued for the next batch to open. |
Line 690: Line 744:
 | UMcvv2ResultCode | [[developer:​cvv2resultcodes|CVV2 result code]]. |  | UMcvv2ResultCode | [[developer:​cvv2resultcodes|CVV2 result code]]. | 
 | UMvpasResultCode | Verified by Visa (VPAS) or Mastercard SecureCode (UCAF) result code. |  | UMvpasResultCode | Verified by Visa (VPAS) or Mastercard SecureCode (UCAF) result code. | 
-| UMresult | Transaction result - A, D, E, or V (for Verification)| ​+| UMresult | Transaction result - A, P, D, E, or V (for Verification)| ​
 | UMerror | Error [[developer:​errorcodes|description]] if UMstatus is Declined or Error. |  | UMerror | Error [[developer:​errorcodes|description]] if UMstatus is Declined or Error. | 
 | UMerrorcode | A [[developer:​errorcodes|numerical]] error code. |  | UMerrorcode | A [[developer:​errorcodes|numerical]] error code. | 
Line 703: Line 757:
 | UMprocRefNum | Transaction Reference number provided by backend processor (platform), blank if not available) | | UMprocRefNum | Transaction Reference number provided by backend processor (platform), blank if not available) |
 | UMcardLevelResult | [[developer:​cardlevelcodes|Card level results]] (for Visa cards only), blank if no results provided| | UMcardLevelResult | [[developer:​cardlevelcodes|Card level results]] (for Visa cards only), blank if no results provided|
 +|UMcardRef |Card reference token. 16-19 digit alphanumeric string. It is returned with dashes but it is not required that these be stored. |
 +|UMcardType |The type of card that was submitted, ie “Visa” |
 +|UMmaskedCardNum |The masked out card number including the last 4 digits |
  
  
developer/transactionapi.1341849874.txt.gz · Last modified: 2012/07/09 09:04 by tem

Page Tools