Service Location:
For SOAP connections:
https://<assigned domain>/ws/transact.asmx?op=ProcessDebitCard
For standard HTTPS connections:
https://<assigned domain>/ws/transact.asmx/ProcessDebitCard?
Description:
This web service is used whenever a transaction is completed via customer debit card. The processes supported by this web service include:
• Sale - make a purchase using a debit card
• Return – credits the card holder’s account
BuyPass fuel transactions only:
• Auth – authorize the amount on a debit card
• Force – force an Auth transaction in to the current batch (PostAuth)
Terminal-based processors only:
• Capture – settle a single transaction in the current batch
Terminal-based processors and host-based processors supporting the batch release feature only:
• CaptureAll – settle all transactions in the current batch
Global Canadian Debit only:
• AddReversal - used when the host sends a response and the information is validated through the pin pad, if the information is found to be invalid. This transaction type can reverse the transaction sent to the host. The PNREF number of the original transaction can be sent along with the AddReversal transaction type to perform the reversal of that transaction.
Global, TSYS, and First Data North only:
• Reversal – perform a manual full reversal on a debit card sale within 24 hours of the original transaction. The expected behavior of this transaction type is defined by the type of the payment processor the merchant account is configured for. See ‘Developer Notes’ for additional information.
Developer Notes:
Invalid Characters: Some parameters and XML tags contain data that will automatically remove invalid characters from the user-entered data. These parameters and tags include:
• MagData
• NameOnCard
• InvNum
• RegisterNum
Reversal Transactions: Reversal is only for the following payment processors: TSYS, GlobalEast and First Data North (CES). All reversals must be processed as card-present transactions.
• For TSYS: The supported issuers for all debit card issuers. The supported industries are only retail and restaurant. Reversals must be processed within 2 hours of the original debit card transaction. TIP: TSYS requires the debit card number and expiration date along with the original sale PNREF number to process reversals.
• For First Data North: The supported industries are retail and restaurant. This is also supported for retail and restaurant and reversals must be processed within 24 hours of the original credit card transaction.
• For Global East: This is supported for all debit card issuers. It is supported retail and restaurant industries. It is required that the reversal be processed within the open batch time period. It restores debit bank account funds immediately.
PIN-less Debit Transactions: In some cases, debit transactions can be processed without the customer’s entering a PIN number (a “PIN-less” debit transaction). Essentially, the same information is sent as in a typical PIN-based debit transaction, with the exception of the encrypted PIN-block and key serial number. This transaction type is currently only available with BuyPass and Global Payments processors.
If the
designated processor is BuyPass or Global, the transaction will be accepted
either with both the PIN-block and key serial number (interpreted as a PIN-based
debit transaction) or accepted with neither piece of data (interpreted as a
PIN-less debit transaction).
If the above requirements are met for a
transaction, PIN-less debit transactions will be allowed through the Payment
Server. However, when working with BuyPass, additional setup is required to
ensure that the transaction is accepted by the processor:
Application ID Setup: To process PIN-less debit through BuyPass, the application ID sent must identify the application in use. Contact your administrator for additional details.
Register Number and Terminal ID Setup: When processing transactions with BuyPass, the Payment Server will attempt to match the RegisterNum passed from the client-side with the register number set up in the merchant account. Once it has made the match, it will send the corresponding terminal ID assigned to that register number to BuyPass. When no terminal ID is sent to BuyPass, the default value is sent (usually terminal ID “01”).
If you are also doing VRU (phone-originated) transactions, a separate terminal ID must be set up in the registers on the merchant account and submitted in your request through the web service.
If the merchant will be doing both internet and VRU transactions at the same time, the terminal ID value will be required to differentiate between the two. For example, you may set up “01” for Internet and “02” for VRU. The request sent through the ProcessDebitCard operation must then send the appropriate register number to reflect the appropriate transaction type.
Fuel Purchases: Debit Card Use: Debit card processing for fuel purchases is now available through BuyPass only. This functionality allows for fuel purchases with standard debit cards (Visa, MasterCard, etc.). Debit fuel purchases (TransTypes Sale and Force) require item-level purchase information. If all the required information for a certain purchase is not provided, the transaction will be rejected and an error message generated. The main implication for the developer is that additional data must be passed to the gateway in order for fuel purchases to process correctly.
Item-level debit fuel purchase information is passed inside the <Items> tag in ExtData. Fuel purchases are differentiated at the gateway from other purchases by the Fuel designation placed within the <Category> tag in item. 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.
Input Parameters:
O = Optional, R = Required, R* = Required except in Capture and CaptureAll transactions, R# = Required except for CaptureAll transactions, R1 = Required on Force and Capture transactions, R$ = Required on all swiped card transactions
|
Parameter Name |
Opt/Req |
Description | ||||||||||||||||||||||||
|
UserName |
R |
User name assigned in the payment server. The user must have an appropriate level of access in order to utilize the web service. | ||||||||||||||||||||||||
|
Password |
R |
Password associated with the user name provided. | ||||||||||||||||||||||||
|
TransType |
R |
Identifies the type of debit card transaction being made. Valid values are: • Sale - make a purchase using a debit card • Return – credits the card holder’s account BuyPass fuel transactions only: • Auth – authorize the amount on a debit card • Force – force an Auth transaction in to the current batch (PostAuth) Terminal-based processors only: • Capture – settle a single transaction in the current batch Terminal-based processors and host-based processors supporting the batch release feature only: • CaptureAll – settle all transactions in the current batch Global Canadian Debit only: • AddReversal - used when the host sends a response and the information is validated through the pin pad, if the information is found to be invalid. This transaction type can reverse the transaction sent to the host. The PNREF number of the original transaction can be sent along with the AddReversal transaction type to perform the reversal of that transaction. Global, TSYS, and First Data North only: • Reversal – perform a manual full reversal on a debit card sale within 24 hours of the original transaction. The expected behavior of this transaction type is defined by the type of the payment processor the merchant account is configured for. See ‘Developer Notes’ for additional information. | ||||||||||||||||||||||||
|
CardNum |
R* |
Debit card number used to uniquely identify the owner’s account. | ||||||||||||||||||||||||
|
ExpDate |
R* |
Debit card date of expiration in MMYY format. | ||||||||||||||||||||||||
|
MagData |
R$ |
Data located the magnetic strip on the back of the card. The format of the MagData is CardNum=ExpDate followed by the service date and checksum. For example: 36438999960016=05121015432112345678 | ||||||||||||||||||||||||
|
NameOnCard |
O |
Card owner’s name as it appears on the card | ||||||||||||||||||||||||
|
Amount |
R# |
Total transaction amount in DDDD.CC format. Note: This amount includes the CashBackAmt and SureChargeAmt. | ||||||||||||||||||||||||
|
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. | ||||||||||||||||||||||||
|
PNRef |
R1 |
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. | ||||||||||||||||||||||||
|
Pin |
R* |
The encrypted PIN-block returned by the PIN pad. Note: The transaction will fail if an unencrypted PIN is used. Note: This information is not required for PIN-less debit transactions. See ‘Developer Notes’ for additional information on pin-less debit transactions. | ||||||||||||||||||||||||
|
RegisterNum |
O |
A string that uniquely identifies the register, terminal, or computer on which the transaction was performed. | ||||||||||||||||||||||||
|
SureChargeAmt |
O |
The amount, in DDDD.CC format, charged by a merchant in exchange for processing a debit card transaction. | ||||||||||||||||||||||||
|
CashBackAmt |
O |
The amount, in DDDD.CC format, requested by the card holder in cash back from the debit transaction. | ||||||||||||||||||||||||
|
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: 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. Key Serial Number: (required for all non-PIN-less debit transactions) PIN pad serial number. Valid format is: • <KeySerialNumber>KeySerialNumber</KeySerialNumber> where KeySerialNumber is the PIN pad serial number used in managing DUKPT PIN pads. 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 BuyPass, will not recognize this tag and reject duplicate transactions. GLOBAL Interac Specific Tags The Global Canadian platform and does not require the US standard KeySerialNumber tag. In its place, this platform uses the Canadian MAC specific tags listed below. All of the tags within the <MAC></MAC> tags are required to process Canadian debit transactions.
Continued, next page.
Account Type: (required for submission with the MAC related values for Canadian Debit) This value identifies the type of account being debited. Valid format is:
• <AccountType>Checking</AccountType> where Checking indicates that a checking account is being used for the debit transaction. • <AccountType>Saving</AccountType> where Saving indicates that a savings account is being used for the debit transaction.
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.
|