Parameter Name

Opt/Req

Description

UserName

R

User name assigned in the payment server. The user must have an appropriate level of access within the system in order to utilize the web service.

Password

R

Password associated with the user name provided.

TransType

R

Identifies the type of credit card transaction being made. Valid values are:

•      Sale - make a purchase using a credit card

•      Auth – authorize the amount on a credit card

•      Return – credits the card holder’s account

•      Void – undo an unsettled transaction

•      Force – force an Auth transaction in to the current batch (PostAuth) or place a transaction not processed through the payment server into the current batch (ForceAuth).

Note: When using this transaction type for a ForceAuth, you must include an AuthCode under the ExtData parameter.

•      RepeatSale – perform a recurring billing or installment payment transaction

Processors supporting the restaurant adjustment function only:

•      Adjustment – used to modify an existing tip amount for an original sale To call the service

Terminal-based processors only:

•      Capture – settle a single transaction in the current batch

Terminal-based processors and host-based processors supporting batch release feature only:

•      CaptureAll – settle all transactions in the current batch

•      Reversal – perform a manual full reversal on a credit card or repeat sale within 24 hours of the original transaction. See ‘Developer Notes’ for additional details on support for reversals.

CardNum

R^$

Credit card number used to uniquely identify the card owner’s account.

ExpDate

R^$

Credit card date of expiration in MMYY format.

MagData

R^#

Track data encoded in the magnetic stripe of a credit card. The data will follow the following format:

%B5149612222222229^FDCS/TEST CHECK CARD^12041011234567   440?;5149612222222229=12041011234567440?

This parameter must contain the full magnetic read in order to be classified as a ‘card present’ transaction

Note: This input is required for processing swiped/card present transactions.

NameOnCard

O

Card owner’s name as it appears on the card. See ‘Developer Notes’ for invalid character processing.

Note: This parameter may be required depending on the merchant’s processor setup.

Amount

R^$

Total transaction amount in DDDD.CC format.

InvNum

O

The invoice ID is assigned by the merchant. This identifier can be used to locate a specific transaction or multiple transactions grouped under a single invoice. See ‘Developer Notes’ for invalid character processing.

PNRef

R¹

Unique payment reference number used to identify a single transaction within the system. The payment reference number (PNRef) is assigned by the payment server at the time the transaction is created.

Zip

O

Card owner’s billing address five-digit postal/zip code. See ‘Developer Notes’ for invalid character processing.

Note: This parameter may be required depending on the merchant’s setup.

Street

O

Card owner’s billing address street name and number. See ‘Developer Notes’ for invalid character processing.

Note: This parameter may be required depending on the merchant’s setup.

CVNum

O

Card verification number.

Note: This parameter may be required depending on the merchant’s setup.

ExtData

O

The ExtData parameter allows you to pass additional information to the web service that is not covered under the input parameters. ExtData values need not be placed in any particular order; however, they must be properly formatted using XML tags.

The following information may be added via the ExtData parameter:

Authorization Code: (required when TransType = Force) Original authorization/approval code. Valid format is:

•      <AuthCode>AuthorizationCode</AuthCode> where Authorization Code is the original authorization or approval code.

Customer Code: (optional) Customer or purchase order (PO) number used with Level II information for Global Payments only (if using another processor that supports Level II, use the PO Number to pass this information instead). See ‘Developer Notes’ for invalid character processing. Valid format is:

•      <CustCode>CustomerCode</CustCode> where Customer Code is the number assigned to identify the customer or the PO number.

Convenience Amount: (optional) Allows the merchant to add a flat fee to the total transaction to recoup the costs of offering the credit card transaction convenience. This function may be used by utility companies, government agencies, and schools. Valid format is:

•      <ConvenienceAmt>Amount</ConvenienceAmt> where Amount is the value to be added to the total transaction in DDDD.CC format.

Tip Amount: (optional) Allows the customer to specify a dollar amount that is already included in the total amount for the purpose of tipping. Valid format is:

•      <TipAmt>Amount</TipAmt> where Amount is the value of the tip already included in the total transaction in DDDD.CC format.

Tax Amount: (optional) Allows the merchant to add a dollar amount to the total transaction to cover sales tax. Valid format is:

•      <TaxAmt>Amount</TaxAmt> where Amount is the value to be added to the total transaction in DDDD.CC format.

Sequence Number: (optional) Identifies the payment order with a repeat sale or installment transaction. For example, payment 1 of 4. Valid format is:

•      <SequenceNum>SequenceNum</SequenceNum> where SequenceNum is any positive integer less than or equal to the SequenceCount.

Sequence Count: (optional) Identifies the total number of charges that will be made for a repeat sale or installment transaction. For example, 4 payments must be made to complete the payment. Valid format is:

•      <SequenceCount>SequenceCount</SequenceCount> where SequenceCount is any positive integer greater than or equal to the SequenceNum.

Server ID: (optional) Unique server identification number. See ‘Developer Notes’ for invalid character processing. Valid format is:

•      <ServerID>ServerID</ServerID> where ServerID uniquely identifies the payment server used.

Time out: (optional) Processor time out value in seconds. The default value for the parameter is 30 seconds for a transaction and 300 seconds for a settlement transaction. Valid format is:

•      <TimeOut>TimeOut</TimeOut> where TimeOut is the processor time out value in seconds.

Training Mode: (optional) This is an indicator that specifies whether transactions will be processed for local loop back testing or treated normally. Valid formats are:

•      <TrainingMode>T</TrainingMode> where T (true) indicates that training mode is active and transactions are processed for local loop back testing.

•      <TrainingMode>F</TrainingMode> where F (false) indicates that training mode is inactive and transactions should be treated normally.

Transaction ID: (optional) Merchant-assigned numerical string passed along with an original transaction that can be used for identification and voids. Valid format is:

•      <TransactionID>TransactionIdentifierValue</TransactionID> where TransactionIdentifierValue is a numerical string.

Target: (optional) Identifies the target transaction ID for the original transaction you wish to void without the use of a PNRef. Valid format is:

•      <Target>TransactionIdentifierValue</Target> where TransactionIdentifierValue is a numerical string identifying the original transaction.

Force: (optional) This is an indicator that specifies whether or not duplicate transactions will be processed. Valid formats are:

•      <Force>T</Force> where T (true) indicates that duplicate transactions are accepted.

•      <Force>F</Force> where F (false) indicates that duplicate transactions are not accepted.

Note: Some processors, including Concord EFS, will not recognize this tag and delete duplicate transactions.

Register Number: (optional) Unique identifier for a specific register. See ‘Developer Notes’ for invalid character processing. Valid format is:

•      <RegisterNum>RegisterNum</RegisterNum> where RegisterNum is a valid unique identifier assigned to a specific register.

City (Depending on processor used, this may be required) City name for the card owner’s billing address. See ‘Developer Notes’ for invalid character processing. Valid format is:

•      <City>City</City> where City is the card owner’s city name.

Bill-To State: (Depending on processor used, this may be required) Two-character state code for the card owner’s bill-to address. See ‘Developer Notes’ for invalid character processing. Valid format is:

•      <BillToState>BillToState</BillToState> where BillToState is the two-character state code for the card owner’s bill-to address.

Customer ID: (optional) Identification number assigned to the customer by the merchant. Valid Format is:

•      <CustomerID>CustomerID</CustomerID> where CustomerID is the customer’s assigned customer ID.

Purchase Order (PO) Number: (optional) Customer or PO number used with Level II information. See ‘Developer Notes’ for invalid character processing. Valid format is:

•      <PONum>PONum</PONum> where 'PONum' is the number assigned to identify the customer or the PO.

Note: If using Level II with Global Payments, use the CustCode to pass this information instead.

Bill Payment: (optional) This is an indicator that specifies whether or not the transaction is being used to pay a utility bill. It is only supported when TransType = Sale or RepeatSale. Valid formats are:

•      <BillPayment>T</BillPayment> where T (true) indicates that the transaction is being used to pay a utility bill.

•      <BillPayment>F</BillPayment> where F (false) indicates that the transaction is being used for something other than a utility bill.

Note: This tag is only relevant to Retail, MOTO, and ecommerce markets. The information is currently supported by Vital, First Data North, and Global Payments processors. Other processors may be supported in the future.

Card Verification Presence: (optional except for First Data transactions) Indicates whether card verification (CV, CVV2, CVC2, or CID) has been sent along with the request. Valid formats are:

•      <CVPresence>1</CVPresence> where 1 indicates that no CV was provided.

•      <CVPresence>2</CVPresence> where 2 indicates that the CV was not submitted (i.e., the card was key entered).

•      <CVPresence>3</CVPresence> where 3 indicates that the CV was submitted.

•      <CVPresence>4</CVPresence> where 4 indicates that the CV is illegible.

•      <CVPresence>5</CVPresence> where 5 indicates that the CV was not present on the card.

Card Presence: (optional) Indicates whether the card was present for the transaction. Valid formats are:

•      <Presentation><CardPresent>True</CardPresent></Presentation> where True indicates that the card was present at the time of the transaction.

•      <Presentation><CardPresent>False</CardPresent></Presentation> where False indicates that the card was not present at the time of the transaction.

•      <Presentation><CardPresent>Unknown</CardPresent></Presentation> where Unknown indicates that the card may or may not have been present at the time of the transaction.

Entry Mode: (optional) Indicates how the values for payment information were obtained. Valid formats are:

•      <EntryMode>UNKNOWN</EntryMode> where unknown indicates that the mode of entry is unknown.

•      <EntryMode>MANUAL</EntryMode> where manual indicates that the payment values were manually entered.

•      <EntryMode>MagneticStripe</EntryMode> where MagneticStripe indicates that the payment values were entered via magnetic stripe card reader (swiped card).

•      <EntryMode>ICC</EntryMode> where ICC indicates that the mode of entry is Instant Card Clearing.

•      <EntryMode>PROXIMITY</EntryMode> where proximity indicates that the payment values were entered via proximity card reader.

AMEX Batch Phase: When working with AMEX batch settlement, the Phase value can be used to determine the phase of the settlement file. Valid formats are:

•      <Phase>Confirm</Phase> where Confirm indicates that the batch is ready to settle

•      <Phase>Submit</Phase> where Submit indicates that the batch has been submitted to the payment processor

•      <Phase>None</Phase> where None indicates that no action has occurred

Note: Batches must be submitted before they can be settled (Confirm). If you send a “confirm” only, the most recently submitted batch will be settled.

External IP: (optional) When using the Transact web service, the IP address defaults to the calling computer's IP. If the request is coming from an external source, the external IP address can be substituted for the purpose of logging and fraud control.

To implement this IP pass through functionality, the following XML node should be included in the external data field of the web service call

•      <ExternalIP>IP Address Here</ExternalIP>

If the ExternalIP node is not included in the external data field, then the default behavior of using the callers IP address is used.

IIAS Fields specific to First Data North

IIAS Indicator: (optional) Identifies whether the current transaction was authorized for submission by an auto substantiation database. For the indicator to be recognized the merchant must be set up for retail and the card type must be Visa or MasterCard. Valid formats are:

•      <IIAS_Indicator>T</IIAS_Indicator> where T (true) indicates that the transaction was authorized.

•      <IIAS_Indicator>F</IIAS_Indicator> where F (true) indicates that the transaction was not authorized.

•      <IIAS_Indicator></IIAS_Indicator> where a blank value indicates that the transaction not was authorized.

Note: False or blank indicators will disqualify the transaction for IIAS and any other IIAS fields will be ignored.

Partial Indicator: (optional) Indicates whether a transaction is partially approved by the host. Valid formats are:

•      <Partial_Indicator>T</PartialIndicator> where T (true) indicates that the host may process the transaction as a partial authorization for available funds.

•      <Partial_Indicator>F</Partial_Indicator> where F indicates that the transaction does not qualify for partial approval.

•      <Partial_Indicator></Partial_Indicator> where a blank value indicates that the transaction does not qualify for partial approval.

Note: The Partial Indicator will return three fields in the response as received from the host (First Data North):

•      Requested Amount: Decimal dollar amount as requested for authorization

•      Approved  Amount: Decimal dollar amount as approved by the host

•      Balanced Amount: Decimal dollar amount remaining on the balance on the account.

Optional Amounts: All optional amounts should include the decimal. They are all 13 character fields with explicit decimal. The total of the sub amounts must match to the total authorization amount of the transaction. Optional subtotal amount for qualified medical expenses (over-the-counter medical items). This applies to Visa transactions only.

•      <QHP_Amount>Value</QHP_Amount>

•      <RX_Amount>Value</RX_Amount> - where Value is the optional prescription/RX subtotal in DDDD.CC format

•      <Vision_Amount>Value</Vision_Amount> - where Value is the optional Vision/Optical subtotal in DDDD.CC format

•      <Dental_Amount>Value</Dental_Amount> - where Value is the optional dental subtotal in DDDD.CC format

•      <Clinical_Amount>Value</Clinical_Amount> - where Value is the optional clinical subtotal in DDDD.CC format

If a partial reversal is required by an integrator, certain fields must be passed. The TransType passed with this request is the Reversal. You must also pass the PNRef and IIAS_Indicator = T

The response will have the Partial_Reversal_Flag field set to T (true) and a Total_Amount field will show what amount is to be settled after requesting the partial reversal transaction.

Full reversals are also supported. To request a full reversal, the IIAS_Indicator must be set to T (true).

Level 3 fields specific to First Data North

These fields are required to qualify transactions for level 3 processing and must be passed with the LineItem xml in ExtData.  These are used in conjunction with other fields (address, customer number, PO Num, etc.), which are collected elsewhere.  Please consult the following table for required fields per card type.

Here is an example of what the fields would look like included in ExtData:

<LineItemDetail><LineItem><Amount>3.00</Amount><CommodityCode>Commodity</CommodityCode><Description>Description</Description><DiscountAmount>.50</DiscountAmount><DiscountIncluded>True</DiscountIncluded><ProductCode>1234</ProductCode><Quantity>1.00</Quantity><TaxAmount>0</TaxAmount><TaxInvoiceNumber></TaxInvoiceNumber><TaxRate>0</TaxRate><TaxIncluded>False</TaxIncluded><UnitOfMeasure>BushelUS</UnitOfMeasure><UnitPrice>3.5100</UnitPrice><UPC>8675309</UPC></LineItem></LineItemDetail>

Developer note:  Level 3 data is only sent to the processor at time of settlement, so you could send the fields with an authorization, then force the authorization without having to include the fields.

Contactless and Soft Descriptors are currently specific to RapidConnect

Contactless transactions:

You will need to pass in the entry mode of ‘Proximity’ with the EntryMode tag:

•      <EntryMode>Proximity</EntryMode>

Soft Descriptors:

Soft descriptors can be sent in using the following tags:

•      AltMerchName – Alternate name

•      AltMerchAddr – Alternate address

•      AltMerchCity – Alternate city

•      AltMerchState – Alternate state

•      AltMerchZip – Alternate zip code

The completed string would look like the example below:

<AltMerchName>Alternate Name</AltMerchName><AltMerchAddr>123 Different St</AltMerchAddr><AltMerchCity>Seattle</AltMerchCity><AltMerchState>WA</AltMerchState><AltMerchZip>98102</AltMerchZip>