VeriFone Universal API Concepts

Helpdesk Training

VeriFone Universal API Concepts

What are advantages of VeriFone having a unified standard?What is the VeriFone Universal API?Which VeriFone products use the VeriFone Universal API?What is the structure of the VeriFone Universal API?What does the Response XML Element typically contain?What does the Request XML Element typically contain?

What is the VeriFone Universal API?

The VeriFone Universal API is a standardized format to send and receive information from VeriFone products. One of the earliest products to employ this structure was the Rapid Internet Transit Authority (RiTa), a product VeriFone gained from the GOSoftware acquisition. That product is now known officially as PAYware Transact.

Today, several of VeriFone's most popular software based card acceptance products are built on top of PAYware Transact. These products have inherited the VeriFone Universal API as their method of organizing data.

What are advantages to VeriFone having a unified standard?

Ease of Troubleshooting – Helpdesk/First-Line Support can debug field issues on multiple products with little difference in training between products.

Ease of Migration – integrators and partners can easily migrate from one VeriFone product to another making few, if any, code changes.

Ease of Development – VeriFone can reuse their code base across several platforms with confidence that it will function in the expected manner. This saves VeriFone time and money.

Ease of Quality Assurance – Quality Assurance can test multiple platforms using the same tests and tools

Products that utilize the VeriFone Universal API

Softpay Connect PAYware Connect PAYware Merchant PAYware Mobile PAYware PC PAYware Report Viewer

PAYware Settlement Manager PAYware SIM PAYware STS PAYware TIM PAYware Transact

Structure of the VeriFone Universal API

The VeriFone Universal API uses XML 1.0 as its document structure. Each request has TRANSACTION as the Document Element, whereas, each response has RESPONSE as the Document Element.

The request uses TRANSACTION as its tag because a “transaction” is occurring between the sending application and the VeriFone product. This “transaction” is not necessarily going to be an actual monetary transaction. Strictly speaking, the word transaction does not mean a monetary transaction. It can also refer to an exchange of data. In other words, a request can contain an administrative command or a reporting command, and the tag will still be TRANSACTION.

The response should contain less information than the request, and the returned fields will be more predictable.

Structure of the VeriFone Universal API (Continued)

Each RESPONSE or TRANSACTION should contain an element for each field that is being passed or returned.

Typically, the XML Element name is the parameter or field being passed; whereas, the XML Text Content between the starting and ending tags is the value being passed for that field or parameter.

In some cases, mostly with reporting, some elements have nested children elements. This is typically used for specifying search fields and fields that you would like to be returned in the report.

The other exception to the VeriFone Universal API is also in reporting. Some responses for instance a PDF formatted report, are returned in the format specified and don't return as XML.

Structure Example 1 (PAYware Connect Settlement)

Request:

<TRANSACTION><FUNCTION_TYPE>BATCH</FUNCTION_TYPE><COMMAND>SETTLE</COMMAND><USER_ID>APITest1</USER_ID><USER_PW>*******</USER_PW><CLIENT_ID>19500030001</CLIENT_ID><MERCHANTKEY>**********</MERCHANTKEY>

</TRANSACTION>

Response:

<RESPONSE> <RESPONSE_TEXT>Settlement Scheduled</RESPONSE_TEXT> <RESULT_CODE>21</RESULT_CODE> <TERMINATION_STATUS>SUCCESS</TERMINATION_STATUS></RESPONSE>

Structure Example 2 (Reporting API Exception in Request)Request:<TRANSACTION> <COMMAND>TRANSEARCH</COMMAND> <CLIENT_ID>19500030001</CLIENT_ID> <MERCHANTKEY>***********</MERCHANTKEY> <FUNCTION_TYPE>REPORT</FUNCTION_TYPE> <MAX_NUM_RECORDS_RETURNED>8000</MAX_NUM_RECORDS_RETURNED> <FORMAT>delimited</FORMAT> <DELIMITER>,</DELIMITER> <RETURN_FLD_HDRS>1</RETURN_FLD_HDRS> <RESPONSEFIELDS> <TRANS_DATE /> <TRANS_TIME /> <BATCH_SEQ_NUM /> <ACCT_NUM /> <INVOICE /> <TROUTD /> <COMMAND /> <TIP_AMOUNT /> <TRANS_AMOUNT /> <R_AUTH_CODE /> </RESPONSEFIELDS> <SEARCHFIELDS> <START_TRANS_DATE>2010.11.01</START_TRANS_DATE> <END_TRANS_DATE>2010.12.10</END_TRANS_DATE> </SEARCHFIELDS></TRANSACTION>

Structure Example 3 (Reporting API Exception in Response)Response:

2010.11.05,14:44:56,6,400555******0019, ,95141417,SALE,0.00,1.00,TAS3572010.11.09,14:03:50,7,545454******5454, ,96003581,SALE,0.00,1.00,TAS7212010.11.15,13:18:39,8,400555******0019,123456,97412801,SALE,0.00,1.00,TAS2312010.11.15,13:19:02,8,400555******0019,123456,97412910,SALE,0.00,1.00, 2010.11.15,13:20:15,8,371449******8431,123456,97413257,SALE,0.00,1.00, 2010.11.15,13:21:03,-10003,371449******8431,123456,97413475,SALE,0.00,1.00,AXS3572010.11.15,13:21:20,8,371449******8431,123456,97413547,SALE,0.00,1.00, 2010.11.15,15:54:53,8,545454******5454, ,97455835,SALE,0.00,1.00,TAS8142010.11.22,14:23:02,9,401200******0026, ,99075762,SALE,0.00,1.00,TAS9872010.11.22,15:05:44,9,401200******0026, ,99089025,SALE,0.00,1.00, 2010.11.22,15:06:21,9,401200******0026, ,99089243,CREDIT,0.00,1.00,

Typical Types of Data contained in a TRANSACTION element

Required Functional Data – elements that are necessary for every transaction type in order for the VeriFone product to understand what type of function is being accessed

Required Account Data – elements used to locate a specific account, site, or terminal in the VeriFone product, as well as, the information required to authenticate to the product.

Conditionally Required Data – elements specific to each command that are required in order to process the transaction

Conditionally Optional Data – elements that are specific to each command but not necessary at minimum to execute the command requested

Types of TRANSACTION Data Example 1

Types of TRANSACTION Data Example 2

Elements you should almost always see in a RESPONSE

TERMINATION_STATUS – If this is SUCCESS, the operation requested has been completed successfully. This does not denote that the transaction had a positive response

RESULT – The VeriFone product's interpretation of the response being sent out. An example is APPROVED for a payment transaction.

RESULT_TEXT – normally this is unabridged from whatever application or operation succeeded or failed during the course of processing the request

RESULT_CODE – a numeric code that represents the state of the response. Normally, the number matches a specific RESULT

Example of a RESPONSE 1

Quick Quiz (to make sure you were paying attention)

What are 3 products that use the VeriFone Universal API?

True or False? All requests that have TRANSACTION as the Document element are payment transactions.

Where would you most likely find an exception to the VeriFone Universal API in VeriFone Products?

What are 3 of the elements that you typically see in a RESPONSE tag?

End of Presentation

Created by: Christopher Wallis