Transaction_Integration_Service


Valutec Card Solutions
Transaction Integration Web Service

About

The Transaction_Integration_Service is a standard web service as defined by the World Wide Web Consortium (W3C, http://www.w3.org/).

It provides several web methods that your programs can use to process transactions on Valutec gift and loyalty cards.

If you are not familiar with web services, you might want to examine these resources:

Automatic Discovery and Code Generation

The Transaction_Integration_Service documents itself in a form that is machine readable, using WSDL. You can obtain the WSDL definition of this web service here.

Many Java and .NET development environments include or have available tools that can read this WSDL and automatically generate a set of classes that encapsulate all the details of interacting with the web service. You can then use the web service via these wrapper classes without needing to deal with any of the WSDL, SOAP, HTTP, or network communications details. After the wrapper classes have been generated, the only code you will have to write is to instantiate the wrapper and call the appropriate transaction method on it. You can be up and running after writing as few as 1 or 2 lines of code (thanks to the hundreds of lines that were automatically generated for you).

If you have such web services tools available to you, then there only two things you need to know in order to start using this web service:

  1. How to use your web service tools
  2. The WSDL URL for this web service is https://www.valutec.net/customers/transactions/valutec.asmx?WSDL

NOTE that the names of some web methods may be modified by your tools in order to follow naming conventions or avoid the illegal use of keywords in your programming language. For example, in Java and other languages the void(...) web method may be renamed to _void(...) or some other variation because void is a language keyword.

If you do not have such tools available to you, then you have a couple of options:


If you are not using tool-generated wrappers, you will need to be familiar and comfortable with your libraries for raw TCP/IP and/or HTTPS communication.

Response Format

Most of the web methods listed in Transaction Methods return an XML element of the type TransactionResponse. Several newer methods require an additional field in the response that is not present in TransactionResponse; these return a TransactionResponse2 element. Information about each field in these elements is provided here, and the XML schema for both these elements can be found in the WSDL.

NOTE that each web method may populate only a subset of the response fields. Fields it does not need may be empty, or they may be omitted entirely. If you process the response directly (i.e. rather than obtaining and accessing it through generated wrapper code), your code will need to allow for either case.



TransactionResponse Element

The TransactionResponse element contains these fields:

RawOutput (maximum length: 100 Characters)

This field contains the actual URL-encoded string that represents the raw output of our transactional systems. This field will always contain the raw string--provided that the transaction process completed successfully--and can be decoded and parsed by using our Terminal Application Specifications document (v7.1).

However, there is no need for you to decode this field if you don't want to, because each data item that it contains will also be present individually in the appropriate response field.

If this field is empty or missing, it is likely that the transaction process did not complete successfully. In this case, you may find a helpful error message in the ErrorMsg field.

TerminalID (maximum length: 15 Characters)

This is the Terminal ID that you provided to the web method from which you obtained this response. Using this field will allow you to verify that the proper terminal ID was passed in your request.

If this field is empty or missing, it is likely that the transaction process did not complete successfully. In this case, you may find a helpful error message in the ErrorMsg field.

IPaddress (maximum length: 15 Characters)
This will show the IP address of the client that requested the transaction. The actual address here is determined by the client's network structure, firewalls, internet service provider, etc. It probably will not be the IP address of the machine that originated the request, but will be the public IP address through which that machine connects to the internet.

Authorized (maximum length: 5 Characters)
If a valid transaction request has been successfully processed this will return a true value. Any errors that may have occurred in the processing of the transaction will return false and the reason for the error will be in the ErrorMsg field.

AuthorizationCode (maximum length: 9 Characters)
Any successful transaction that will cause a card’s value to change will result in an authorization code. This is an important value to hold for your records. If there is a transaction that needs to be voided, this value has to be passed to roll back the transaction. The rules for voiding transactions can be referenced in the Terminal Application Specifications document (v7.1).

TransactionType (maximum length: 7 Characters)
This field represents the type of transaction that was requested. It will be either "Gift" or "Loyalty".

Balance (maximum length: 9 Characters)
Most transactions will produce a Balance. If a transaction changes the card’s value, this field will provide a value.

PointBalance (maximum length: 9 Characters)
Cards that utilize any kind of Point balance, this field will provide a value depending on the type of transaction.

RewardLevel (maximum length: 1 Characters)
Cards that utilize any kind of Level of reward, this field will provide a value depending on the type of transaction.

Refund (maximum length: 9 Characters)
On a deactivation of a card, this field will provide the refund amount of a card that still has stored value.

CardAmountUsed (maximum length: 9 Characters)
In a sale or a restaurant sale, if split tender is used by the merchant, this field will show the amount that was taken off of the card. If there is a remaining balance owed by the customer, that amount is shown in the AmountDue field.

AmountDue (maximum length: 9 Characters)
Please see CardAmountUsed.

TotalSales (maximum length: 5 Characters)
This Field is reserved for host total reports (Previous Day and Current Day totals). It represents the total number of Sales for the period request.

TotalSales_Amount (maximum length: 9 Characters)
This Field is reserved for host total reports (Previous Day and Current Day totals). It represents the total amount of Sales for the period request.

TotalActivations (maximum length: 5 Characters)
This Field is reserved for host total reports (Previous Day and Current Day totals). It represents the total number of Activations for the period request.

TotalActivations_Amount (maximum length: 9 Characters)
This Field is reserved for host total reports (Previous Day and Current Day totals). It represents the total amount of Activations for the period request.

TotalAddValues (maximum length: 5 Characters)
This Field is reserved for host total reports (Previous Day and Current Day totals). It represents the total number of Add Values for the period request.

TotalAddValues_Amount (maximum length: 9 Characters)
This Field is reserved for host total reports (Previous Day and Current Day totals). It represents the total amount of Add Values for the period request.

TotalVoids (maximum length: 5 Characters)
This Field is reserved for host total reports (Previous Day and Current Day totals). It represents the total number of Voids for the period request.

TotalVoids_Amount (maximum length: 9 Characters)
This Field is reserved for host total reports (Previous Day and Current Day totals). It represents the total amount of Voids for the period request.

TotalDeactivations (maximum length: 5 Characters)
This Field is reserved for host total reports (Previous Day and Current Day totals). It represents the total number of Deactivations for the period request.

TotalDeactivations_Amount (maximum length: 9 Characters)
This Field is reserved for host total reports (Previous Day and Current Day totals). It represents the total amount of Deactivations for the period request.

Identifier (maximum length: 10 Characters)
The identifier that was specified in the the call to the transaction method that generated this response. If the identifier was specified with a length of less than 10 characters, it will be echoed here left-padded with zeros to make it 10 characters long.

ErrorMsg (maximum length: 100 Characters)
On any transaction that the Authorized field is false, this will give you the host error message. For a complete list of messages, please refer to the Terminal Application Specifications document (v7.1).

CardNumber (maximum length: 19 Characters)


TransactionResponse2 Element


The TransactionResponse2 element is identical to the TransactionResponse except that it contains one additional field:
CardNumber (maximum length: 19 Characters)
For the eCommerce transaction, this is the card number of the card that was created and activated. It is not used for other transaction types. When present, this number will always begin with an 8 and will always be 19 digits long.


Transaction Methods

The following operations are supported. For a formal definition, please review the Service Description.