This Web service operation processes credit card transactions for a merchant. The URL to access this Web service is:
Descriptions of the parameters are listed below. Response Codes are listed here.
||Required. User name assigned in the payment server
||Required. Password for the user name assigned in the payment server
Required. Type of the credit card transaction. Valid values are:
- Sale to make a purchase with a credit card
- Adjustment is used to modify an existing tip amount for an original sale.This applies to the processors that support restaurant adjustment transactions
- Auth to authorize an amount on a credit card
- Return to credit the cardholder’s account
- Void to undo an unsettled transaction. Note: pass the Card Number and ExpDate with null values on voids
- Force to place an Auth transaction into the current batch (PostAuth) or to place a transaction not processed through the payment server into the current batch (ForceAuth)
- Capture to settle a single transaction in the current batch; only for terminal-based processors
- CaptureAll to settle all transactions in the current batch; only for terminal-based processors or host-based processors that support a batch release feature
- RepeatSale to perform a recurring billing or installment payment transaction
- Reversal to undo an unsettled transaction. Note: pass the Card Number and ExpDate with null values on Reversals. After a Reversal, the Amount of the original transaction does *not* remain on hold.
||Optional except for these TransTypes: Sale, Auth, Return, Force (ForceAuth). Credit card number to process the transaction. For all other transaction types the parameter needs to be included
||Optional except for these TransTypes: Sale, Auth, Return, Force (ForceAuth). Credit card’s expiration date in MMYY format. For all other transaction types the parameter needs to be included
||Optional except when processing swiped card transactions. Data located on the track 2 of the magnetic strip of the card. Once this field is populated, the transaction will be indicated as Card-Present transaction and usually result in a more favorable retail discount rate. Invalid characters will be removed. The format of the MagData (or Track 2 data) is CardNum=ExpDate followed by the service code and checksum. For example, 36438999960016=05121015432112345678
||Optional, depending on different merchant processor setups. The cardholder’s name as it appears on the card. Invalid characters will be removed.
||Optional except for these TransTypes: Auth, Sale, Return, Force (both PostAuth and ForceAuth). The total transaction amount in DDDD.CC format
||Optional. Invoice tracking number. Invalid characters will be removed.
||Optional except for these TransTypes: Void, Force (PostAuth), Capture. Reference number assigned by the payment server
||Optional depending on different merchant processor setups. Cardholder’s billing address zip code used in address verification. Invalid characters will be removed.
||Optional depending on different merchant processor setup. Cardholder’s billing street address used in address verification. Invalid characters will be removed.
||Optional. Card verification number
Extended data in XML format. ExtData is where you pass values about the current transaction which can’t be passed in the parameters above. Optional except in the cases of: AuthCode (required for a Force (ForceAuth) transaction); City and BillToState (required by certain processors); Invoice and associated nested data elements (required for Concord EFS Purchase Card Level 3 and Fuel purchases- see section below). Valid values are:
<CC_Info_Key>CCInfoKey</CC_Info_Key> for processing a payment to a previously tokenized card
- <AuthCode>ApprovalCode</AuthCode> for original authorization code
- <CustCode>CustomerCode</CustCode> for customer code or PO number of the customer. Invalid characters within this XML tag will be removed. (Note* This is the tag to be passed for Level II information for Global Payments only, please use PONUM for the other processors that support level II.)
- <ConvenienceAmt>ConvenienceAmt</ConvenienceAmt> Allows for passing a convenience amount along with the transaction request. The format is DDDD.CC.
- <TipAmt>TipAmount</TipAmt> for tip amount in DDDD.CC format
- <TaxAmt>TaxAmount</TaxAmt> for tax amount in DDDD.CC format
- <SequenceNum>SequenceNum</SequenceNum> for sequence number used with RepeatSale installment transactions; this designates which number in the sequence the transaction is; it must be a positive integer smaller than or equal to the SequenceCount
- <SequenceCount>SequenceCount</SequenceCount> for sequence count used with RepeatSale installment transactions; this designates the total number of charges that will be made; it must be a positive integer greater than or equal to the SequenceNum
- <ServerID>ServerID</ServerID> for a unique server identification number. Invalid characters within this XML tag will be removed.
- <TimeOut>TimeOut</TimeOut> for timeout value in seconds (default =40)
- <TrainingMode>TrainingMode</TrainingMode> to process transaction in Training Mode; either T or F
- <Force>Force</Force> for forcing duplicate transactions to be processed; either T or F. Note that some processors, including Concord EFS, will not utilize this tag and may still reject a duplicate transaction
- <RegisterNum>RegisterNum</RegisterNum> for register number. Invalid characters within this XML tag will be removed.
- <City>City</City> for the city name of the cardholder’s billing address. Invalid characters within this XML tag will be removed.
- <BillToState>State</BillToState> for the two character state code of the cardholder’s billing address. Invalid characters within this XML tag will be removed.
- <CustomerID>CustomerID</CustomerID> for customer ID
- <PONum>PONum</PONum> for purchase order number. Invalid characters within this XML tag will be removed. (Note* This is to be used for Level II information except Global Payments)
- <BillPayment>BillPayment</BillPayment> to indicate that a transaction is a utility bill payment; either T or F; only supported for TransTypes Sale and RepeatSale; This tag is only relevant to Retail, MOTO, and eCommerce markets. Currently, this information is only supported for Vital, First Data North, and Global Payments processors; other processors may be supported in the future
- <Authentication><XID>AuthenticationID</XID> Verified By VISA<CAVV>CAVV</CAVV> CAVV response value<UCAF>UCAF</UCAF> Universal Card Holder Authentication FieldVerified by Visa and Universal Cardholder Authentication Field are programs implemented by Visa and MasterCard respectively to verify that an account number is being submitted by the cardholder. These programs are for the Ecommerce market exclusively and only MasterCard and Visa cards support this feature.The data for Visa and MasterCard is different.There is a possible CAVV response for Visa cards that will be returned via ExtData * Please see sample in the section Examples for Verified by VISA and UCAF for Mastercard.<TrustAttempt>T</TrustAttempt>The trust attempt tag will indicate VBV or MS was attempted but no XID, CAVV, or UCAFF is available for the transaction.</Authentication>
- <CVPresence>CVPresence Value</CVPresence> CVV2 / CVC2 / CID Presence, indicates whether a CVV2 or CID has been sent along with the request.The valid values for this tag are: None, NotSubmitted, Submitted Illegible, NotPresent (Not present on card). *Please see sample request and response for this CVPresence tag field.
- <EntryMode>EntryModeValue</EntryMode> this was added to indicate how the values for the payment information were obtained. The Valid values for this tag are: UNKNOWN, MANUAL,MAGNETICSTRIPE,ICC, and PROXIMITY
- <API_IP>IP Address</API_AP> to indicate the IP address of the client machine. If merchant has configured Fraud Prevention Options which can include blocking transactions from certain IP addresses, the contents of this tag are used to determine whether this transaction should be blocked as possibly fraudulent.
- <Invoice>Invoice</Invoice> to indicate invoice details will be included. Required for Concord EFS Purchase Card Level 3 but optional for fuel purchases. However, fuel purchases must contain the <Items> element for transactions of type Sale and Force. See below for hierarchy of required and optional elements nested within. Please note that all elements included inside <Invoice> must be in the specific order listed below
- <InvNum>InvNum</InvNum> Purchase invoice number
- <Date>Date</Date> Date of invoice in YYMMDD format for Concord
- <CustomerId>CustomerId</CustomerId> Customer ID number
- <Name>Name</Name> Customer name
- <Address> Customer address
- <Street>Street</Street> Customer address street
- <City>City</City> Customer address city
- <State>State</State> Customer address state
- <Zip>Zip</Zip> Customer address zip code
- <Country>Country</Country> Customer address country
- <Email>Email</Email> Customer email
- <Phone>Phone</Phone> Customer phone number
- <Fax>Fax</Fax> Customer fax number
- <CustCode>CustCode</CustCode> Customer code
- <PONum>PONum</PONum> Purchase order number from customer
- <TaxExempt>TaxExempt</TaxExempt> Customer tax exempt status
- <Description>Description</Description> Description of purchase
- <Item> Required for Concord EFS Purchase Card Level 3 and fuel card purchases. One item in invoice (item details nested within). There may be multiple <Item> nested within <Items> tag
- <SKU>SKU</SKU> SKU number of item
- <UPC>UPC</UPC> Required for Concord EFS Purchase Card Level 3 and fuel purchases. UPC number of item for Purchase Card Level 3 or the NACS (National Association of Convenience Stores) product code for fuel purchases. The NACS is an industry standard list that Concord is utilizing. For a list of NACS product codes, please contact EFSnet? customer support at firstname.lastname@example.org or 1-877-852-2637.
- <Description>Description</Description> Item description
- <Quantity>Quantity</Quantity> Required for Concord EFS Purchase Card Level 3 and fuel purchases. Quantity purchased of item
- <UnitOfMeasurement>UnitOfMeasure</UnitOfMeasurement > Unit of measurement for item
- <UnitPrice>UnitPrice</UnitPrice> Required for Concord EFS Purchase Card Level 3 and fuel purchases. Unit price of item
- <DiscountAmt>DiscountAmount</DiscountAmt> Possible discount amount on item
- <TaxAmt>TaxAmt</TaxAmt> Possible tax amount on item
- <TotalAmt>TotalAmt</TotalAmt> Total amount of item
- <Category>Category</Category> Required for Concord EFS Purchase Card Level 3 and fuel purchases. Item category for Purchase Card Level 3 or the specific value Fuel to designate a fuel purchase item
- <TaxRate>TaxRate</TaxRate> Possible tax rate applied to item
- <DiscountAmt>DiscountAmount</DiscountAmt> Possible total discount for invoice
- <ShippingAmt>ShippingAmt</ShippingAmt> Possible shipping amount for invoice
- <DutyAmt>DutyAmt</DutyAmt> Possible duty amount for invoice
- <TaxAmt>TaxAmt</TaxAmt> Possible tax amount for invoice
- <NationalTaxInc>NationalTaxInc</NationalTaxInc> Possible additional tax amount included in invoice total
- <TotalAmt>TotalAmt</TotalAmt> Total amount of the transaction on the invoice
- <Fleet>Fleet</Fleet> Required for Concord EFS Fleet card purchases. Information on fleet member making purchase. See below for hierarchy of elements nested within. Please note that all elements included inside must be in the specific order listed below
- <VehicleNum>VehicleNum</VehicleNum> May be required for specific Concord EFS Fleet card purchases. The vehicle number
- <DriverNum>DriverNum</DriverNum> May be required for specific Concord EFS Fleet card purchases. The vehicle driver’s number
- <OdometerReading>OdometerReading</OdometerReading> May be required for specific Concord EFS Fleet card purchases. The current odometer reading of the fleet vehicle
- When TransType does not equal Capture or CaptureAll: Required for manually-entered fleet card transactions that have the ISO prefix of the fleet card present only in the track data and not in the embossed data on the front of the card. Valid values are WEX and Voyager. Concord currently does not support manually entered Voyager cards
- When TransType equals CaptureAll: Optional valid values can be: ALL to specify all payment methods assigned to the merchant account should be settled, or a combination of the specific payment methods separated by a colon (i.e. CREDIT:DEBIT:EBT:EGC) in order to specify which individual payment methods assigned to the merchant account should be settled. Please note that if the processor requires all payment methods to settle at the same time, it is required to use the ALL value or the appropriate combination of the specific payment methods in order to settle the account correctly. Currently, only host-based processors that support a manual batch settlement (or batch release) require all payment methods to be settled at the same time
- When TransType equals Capture: This element does not apply since only 1 transaction will be settled
Purchase Card Level 3 Data Use
Level 3 data on Purchase Card transactions is now available, but currently only through the Concord EFS processor. This sends invoice information with line-item detail provided to the processor for validation. The data is all sent through the ExtData parameter nested within the <Invoice> element (see chart above). Note that if you use the <Invoice> element it will ignore any data of the same purpose specified elsewhere by way of a parameter or other ExtData parameter tag, i.e. it will use one or the other but not both. For example, if you supply the <TaxAmt> element within the <Invoice> element and as a separate element in the ExtData parameter, the separate <TaxAmt> element outside the <Invoice> element will be ignored (duplicate information will not cause a problem). See Example 10 below for a sample transaction sending Purchase Card Level 3 data.
Fuel Purchases: Standard and Fleet Card Use
Credit card processing for fuel purchases with both Standard and Fleet type cards are now available, currently through Concord EFS only. This functionality allows for fuel purchases with standard credit cards (Visa, Mastercard, etc) and with Fleet type cards (Wex, Voyager, and MasterCard Fleet are currently supported). Fuel purchases are differentiated at the gateway from other purchases by the Fuel designation placed within the <Category> tag in item descriptions (see Examples 11 through 13 below). In effect, a transaction will only be treated as a fuel transaction if at least one of the items within <Items> is designated as category Fuel.
Both Standard and Fleet cards require item-level purchase information for fuel purchases (for TransType’s Sale and Force), and Fleet cards may additionally require vehicle number, driver number, and/or odometer information on such purchases. If all the required information for a certain purchase is not provided, the transaction will be rejected and an error message generated. Note that Fleet cards in some cases can be used to purchase non-fuel items on a transaction designated as fuel, but item-level information must be present for all items in the transaction, otherwise the transaction may be declined. The main implication for the developer is that additional data must be passed to the gateway in order for fuel purchases to process correctly.
For standard credit card processing on Sale and Force fuel transactions, item-level purchase information must be provided. It can be passed inside the Items> tag alone or nestled within <Invoice> information in ExtData. See above chart for details on these and other required XML tags for standard card processing on fuel transactions, and see Example 11 below.
For Fleet card processing on fuel purchases, additional information on the fleet member such as vehicle number, driver number, and/or odometer information may also need to be provided (according to the requirements for the particular Fleet card; for example, Wex typically requires the <DriverNum> tag). See the <Fleet> tag as described in the table above, and Examples 12 and 13 below. Fleet data must be provided on Sale, Auth, Force, and Return transactions. This information will be saved and, if not obtained a second time for a Force (PostAuth), will be automatically sent to the processor.
The Fleet data can generally come directly from the card’s magnetic data or the POS system can acquire the data by examining information found on the card’s magnetic data and then prompting the cardholder for the required data. When transactions are submitted, the card’s requirements will be validated by the payment processor and an error will be generated if the proper Fleet data is not submitted. Exceptions: If a MasterCard Fleet card is used and Fleet information is not provided, the transaction will be processed as a standard fuel transaction, rather than generating an error. Also, MasterCard Fleet allows the user to exclude fleet data on manually-entered transactions.
Manual Fleet transactions present a special case. Fleet cards are different in that the account data embossed on a card is often not the same as the track (magnetic) data. This is true for both Wex and Voyager Fleet cards. The result of this is that in a manuallyentered (non-swiped) card submission, the card type cannot be identified by the account number data displayed on the card. For a Wex card, the user must identify the card manually, and this information must be passed in <CardType> tag in the ExtData parameter (see Example 13). However, a Voyager card cannot be processed manually through Concord EFS at this time.
- Manually Entered Sale
- Manually Entered Auth (Commercial Card)
- Forced Transaction
- Manually Entered Force
- Auth Capture
- Capture All
- Repeat Sale
- Level 3 Sale
- Fuel Sale
- Sale (Fleet Card)
- Manually Entered Fleet Card
- Tip Adjustment
- Verified By Visa
- Mastercard Secure Code