Credit Card Merchant Services API Developers Guide


Introduction

The Webvault Merchant Services API is a secure web based (HTTPS) application programming interface enabling software developers to conduct credit card payments and other associated transactions online in real-time from a website, shopping card system or any other internet connected application. Utilising the HTTPS protocol and XML the merchant services API is compatible with any software development platform. Transaction requests are secured by RSA 1024 Bit SSL encryption. The Webvault merchant services API allows you to design customised credit card payment solutions that can fully integrate with your own software systems.

Getting Started

To begin using the Webvault merchant services API you must request a FREE test merchant services account by contacting Webvault Customer Support. A test merchant account will allow you to conduct test payments and transactions against our certification gateway system so that you can design your software to interact with our payments gateway. When you are finished testing, you can apply for a live merchant services account, pay the annual licensing fee and setup a compatible credit card processing facility with your Australian bank or financial institution. Please see our Getting Started With Credit Card Merchant Services for more information.

API Usage

To conduct a credit card transaction request simply initiate a standard HTTPS request from your chosen software framework using the following URL. The request string will also contain the associated transaction data as regular querystring parameters. Because the API responds to a standard HTTPS request you can also conduct test transactions from your web browser.

https://merchantservices.webvault.com.au/transaction.aspx

NOTE: You must use the https:// secure SSL protocol when conduction transactions with the merchant services API, otherwise you will receive the response error "Please use a secure SSL connection". You CANNOT conduct unsecure payment or transaction requests when using the merchant services API.

Request Parameters

The following credit card payment and transaction request parameters are supplied when conducting a HTTPS request through to the payment gateway.

MerchantID (Required, Max 32 Characters)
This is your merchant services account identifier. This parameter must be supplied with every request so that you can authenticate and conduct a transaction.

Password (Required, Max 20 Characters)
This is your merchant services account password. This parameter must be supplied with every request so that you can authenticate and conduct a transaction.

RequestType (Required)
This indicates the type of transaction request you wish to process. You must supply this parameter with a valid transaction request type string. Below is a list of types of transaction requests you can perform and the corresponding RequestType string. Most of the time for regular credit card payment requests you will use the capture RequestType.

capture - Authorise and transfer funds from the cardholder
refund - Authorise and transfer funds to the cardholder
auth - Request authorisation for the transfer of funds from cardholder
settlementAdvice - Request settlement and transfer funds from a previous authorisation
void - Request cancellation of a settlement advice
authReversal - Reverses a previously processed authorisation
queryStatus - Returns the current status of a previously processed transaction
settleAll - Settles all outstanding authorisations

OrderID (Required, Unique, Max 32 Characters)
This property must be set with a unique order ID string for each transaction or request that you make. If you use the same OrderID string as a previous transaction, the payment gateway will reject your request. It is suggested that you generate the orderID from an auto increment field or primary key from a table in your database to ensure that the ID will be unique each time. This property can contain alpha as well as numerical characters. This is the value you will use to track your transaction requests with the payment gateway. You may also wish to provide this number to your payee as a transaction reference number.

Reference (Optional, Max 50 Characters)
This property is optional, and allows you to assign your own reference number to each transaction request. This property does not have to be unique. You might assign your customer order number or a brief note. This value may be useful for reconciliation and reporting.

CardNumber (Conditional, Numeric, Max 19 Characters)
This property is required for particular transactions (capture, refund & auth). It is the number of the credit card or cardholder’s credit account. This property should be set with a string of numeric characters only, however if the string contains alpha characters or spaces these will be removed automatically.

ExpiryMonth(Conditional, Numeric, Max 2 Characters)
This property is required for particular transactions (capture, refund & auth). This property should be set with the 2 digit number of the month in which the cardholder’s credit card expires.

ExpiryYear(Conditional, Numeric, Max 2 or 4 Characters)
This property is required for particular transactions (capture, refund, & auth). This property should be set with the 2 or 4 digit year in which the cardholder’s credit card expires.

Amount (Conditional, Numeric, Max 16 Characters)
This property is required for particular transactions (capture, refund, auth, settlementadvice & authreversal). This property is the numerical value of the amount you wish to transact to or from the cardholder’s credit card account. This value should be specified in the transacting currencies lowest denomination. For example, $100 AUD would be presented as 10000. You must not include any decimal points within this value.

Currency (Conditional,Max 3 Characters)
This property is required for particular transactions (capture, refund, auth, settlementadvice & authreversal). If you do not supply a value the system will charge the amount in Australian Dollars (AUD). This property should be set to the 3 character ISO 4217 currency code of your choice. The currencies you can process will depend on your financial institution. The character code for Australian dollars is AUD. For additional currencies please refer to the List of ISO 4217 Currency Codes.

IPAddress (Conditional, Max 50 Characters)
This property must be supplied for particular transactions (capture, refund, auth, settlementadvice & authreversal). This value should contain the internet IP address of the host or client making the transaction request. In most circumstances this will be the IP address of the customer making the payment. This information helpful for tracking payment requests and for deterring credit card fraud. If you do not supply a value the system will use the IP address of the host connecting to the API by default.

CVC (Optional, Max 6 Characters)
This parameter is optional for some transaction requests (capture, refund, auth, settlementadvice & authreversal). This data can be set with the card verification data which is printed on the cardholder’s credit card. This data is usually between 3 and 6 characters long and will vary depending on the type of credit card. For VISA and Mastercard the CVC is often a 3 digit code printed on the reverse side of the card. American express often print a 4 digit code on the front side of the card. You can process a credit card payment without supplying the CVC security digits, however if CVC data is supplied in a transaction request and is found to be incorrect, then the payment gateway will deny the transaction. CVC is an optional additional security method for merchants to validate cardholder information.

ECI (Conditional, Max 3 Characters)
This property is conditional for some transactions (capture, refund, & auth), and optional for others (settlementadvice & authreversal). The ECI value may be required by your financial institution for security reporting purposes. The following table lists the currently available ECI values. In most circumstances, transaction requests made over the web should employ SSL security and therefore the ECI Value should be set to “SSL”. A list of available ECI codes is below.

CCT - Call Centre Transaction
IVR - IVR Transaction
MTO - MOTO Transaction
SSL - SSL Channel Encrypted Transaction
UEC - Non-Secured Electronic Commerce Transaction
WAP - Non-Secured Wireless Transaction
SWP - Secure Wireless Transaction with Encryption


AuthID (Optional, Max 6 Characters)
This parameter can be optionally provided for some transaction requests (capture, refund, auth, settlementadvice & authreversal). The value should be the Authorisation response string previously provided by your financial institution in a prior auth transaction request. This value is by your financial institution to identify a previous authorisation request so that the transaction can be settled and the cardholders funds transferred.

RPI (Optional, Boolean)
This property can be optionally set for some transaction requests (capture, refund, auth, settlementadvice & authreversal). This value stands for recurring participant indicator and should be set to true if the transaction complies with recurring billing requirements.

Address (Optional, Max 20 Characters)
This property can be optionally set for some transaction requests (capture, refund, auth, settlementadvice & authreversal). This value can be set to the current billing address of the cardholder for AVS verification and is an optional security feature available to merchants for verification of the cardholder. AVS verification is not available to all merchants, so please enquire with your bank before processing AVS data in your credit card transaction requests. It is important not to set the Address property with any more than 20 characters otherwise an error will be generated and the transaction will fail. Longer address data should be truncated to a 20 character string.

ZipCode(Optional, Max 9 Characters)
This property can be optionally set for some transaction requests (capture, refund, auth, settlementadvice & authreversal). This value can be set to the current zip or postal code of the cardholder’s billing address for AVS verification. Please enquire with your bank before processing AVS data in your credit card transaction requests as this feature may not be available to you.

Example Request

An example of regular properly formatted credit card payment request will look like the following.


https://merchantservices.webvault.com.au/transaction.aspx?MerchantID=YourAccountID&Password=YourPassword&RequestType=capture&OrderID=REF0001020&CardNumber=4444444444444444&ExpiryMonth=02&ExpiryYear=13&Amount=10000&Currency=AUD&IPAddress=203.156.45.91&ECI=SSL

Response Parameters

Reply's to transaction requests will be provided by our API by way of secure HTTP response. Response data will be in a standard XML 1.0 format which allows for compatibility with all major development frameworks. The following is a list of XML elements which make up the response parameters to a transaction request. These response parameters allow you to determine if the transaction was successful and/or whether a payment was approved. You can then take appropriate action within your own software.

Condition (OK OR ERROR)
This value indicates whether the transaction request was successfully received and interpreted by our system, or whether there was some kind of error. There are two possible values which are OK or ERROR. You should check this response element to determine whether there is some kind of error with your request. If the merchant services system is currently unavailable you will also receive an ERROR value response for this parameter.

NOTE: the Condition value DOES NOT indicate wether the payment was succesfully approved or declined, only whether your request was correctly received and interpreted by our system. Please refer to the SummaryCode value to determine the approval outcome of a transaction request.

Error (Max 500 Characters)
This value will contain a description any transaction errors that occurred while processing your request. This response parameter will only be returned if the Condition element contains a value of ERROR.

SummaryCode (Numeric, 1 Character)
This value indicates the outcome of a payment or transaction and whether it was approved or declined by your financial institution and/or the third party card issuer. You should check SummaryCode to determine whether or not a payment (capture), refund or pre-authorisation was successful. The list of possible SummaryCode values are below.

0 - Transaction Approved (The transaction request has been approved by the acquiring banking network)
1 - Transaction Declined (The transaction has been declined by the acquiring banking network)
2 - Transaction Error (The transaction request encountered an unexpected error while communicating with the acquiring banking network)
3 - Transaction Rejected (The transaction request was rejected for processing by the payment gateway)

ResponseCode (Numeric, Max 3 Characters)
This value will be set to the corresponding response code that matches the ResponseText value (see below). This property can assist in providing greater detail as to the outcome of a transaction request as indicated by the acquiring banking network.

ResponseText (Alphanumeric, Max 256 Characters)
This value will be set to a text description explaining the outcome of the transaction request. This value will correspond to the appropriate ResponseCode value.

RRN (Alphanumeric, Max 40 Characters)
This value will be set to the retrieval reference number supplied by the acquiring financial institution and should be recorded. This number can be provided to the cardholder as a receipt reference number for a successful transaction or you may wish to provide your unique OrderID or another reference number of your choosing.

XID (Alphanumeric, Max 40 Characters)
This value is the transaction identifier supplied by the financial acquirer to assist in the tracking of requests. You should store and record this value along with the RRN for reconciliation purposes.

ResponseAmount (Numeric, Max 16 Characters)
This value will be set to the amount of the transaction processed in the currencies lowest denominational value. In most cases this value will be the same as the value specified in the Amount property, however in some instances the transaction amount may differ. You can refer to this property to confirm the total amount processed after a transaction request.

Authorisation (AlphaNumeric, Max 6 Characters)
This value is the pre-authorisation identifier supplied by the financial acquirer. This value can be specified as the AuthID on a future request for settlement of this transaction.

AVS (AlphaNumeric, Max 1 Character)
The value returned will indicate the verification result of the cardholder’s Address and ZipCode if supplied in the transaction request. The AVS code can help a merchant to determine the validity of the cardholder's payment information and their right to authorise a transaction. AVS verification is not available with all financial institutions and cardholders. A list of potential AVS values are below.

X - Address and 9 digit ZipCode was verified successfully
Y - Address and ZipCode was verified successfully
A - Address was verified successfully, but ZipCode is invalid
Z - Address is Invalid, but 9 digit ZipCode was verified successfully
W - Address is Invalid but ZipCode was verified successfully
N - Address and ZipCode are invalid
U - AVS is currently unavailable
S - AVS is invalid or not supported
Other - Unknown response provided by financial institution

Certification(AlphaNumeric, Max 4 Character)
The value returned indicates the current certification status of your MerchantID account and whether the transaction was conducted on the Test or Live payment gateway. The two possible values are LIVE or TEST.

CvcCode (AlphaNumeric, Max 1 Characters)
This value indicates the outcome of the card verification data process provided in the CVC request parameter. CVC is an optional additional security method for merchants to validate cardholder information. The list of potential return values are below.

M - Card verification data was authenticated successfully
N - Card verification data was not authenticated
P - CVC not able to be processed at this time
S - CVC data is printed on the cardholders card, though not supplied
U - Card issuer not certified for CVC processing

SettleDate (AlphaNumeric, Max 8 Characters)
This value indicates the settlement date of a transaction indicated by your acquiring bank or financial institution. Please note that this date may differ from the local date and time on which the transaction request was processed by our systems. The SettleDate will be returned in the date format of mmddyyyy. For example, ‘03282012’ would represent the 28th March 2012.

Status (AlphaNumeric, Max 13 Characters)
This response value is used in conjunction with the querystatus transaction request type. The value returned indicates the current status of a previous transaction request. The list of possible return values are below.

Advised - The settlement advice has been accepted by the payment gateway
Auth - The acquirer has indicated that the Authorisation was successful
Authreversed - The authorisation has been reversed
Cancelled - The transaction has been successfully cancelled
Declined - The transaction has been declined by the acquiring network
Rejected - The transaction has been rejected by the payment gateway
Settled - The transaction has been successfully settled
Statusunknown - The status of the transaction is unknown

Example XML Response

An example response for a capture credit card payment request transaction is below.

NOTE: The XML response parameters returned will vary depending on the type of transaction request, as well as the outcome of the transaction. Your application should test for XML parameter nodes that may not exist as part of the transaction response.


<?xml version="1.0" encoding="utf-8" ?> 
<TransactionResponse>
  <Condition>OK</Condition> 
  <SummaryCode>0</SummaryCode> 
  <ResponseCode>00</ResponseCode> 
  <ResponseText>Approved</ResponseText> 
  <RRN>55VOM2</RRN> 
  <XID>7296395</XID> 
  <ResponseAmount>1000</ResponseAmount> 
  <Authorisation>L6Hm</Authorisation> 
  <CvcCode>S</CvcCode> 
  <SettleDate>13/05/2010</SettleDate> 
  <Certification>TEST</Certification> 
</TransactionResponse>

Testing Transaction Responses

While your MerchantID account is linked to the test payments gateway, you can manipulate the outcome of a transaction response based on the value of the Amount request parameter. Providing a value for the transaction amount ending with 00 (eg. 1000) will result in a successful payment (ie. SummaryCode value of 0). Providing a value for the amount parameter ending with 01 will result in the test payment being declined (ie. SummaryCode value of 1). You can use this method to test how your application responds to the outcome of successful and unsuccessful payment transactions.

Warnings & Disclaimers

SECURITY

For security reasons the Webvault merchant services system does NOT store or record any sensitive credit card payment details at any stage during the transaction. The ensures the privacy of the cardholder information.

We therefore remind all merchant services customers that it is your responsibility to ensure the security of your own software applications. SSL or other appropriate encyrption algorithms should be used at all times when retrieving payment information from cardholders. Whilst you as a merchant may be able are able to store customer payment information in your own software systems you do so at your own risk. Webvault will not take responsibility, nor guarantee the security of payment data stored on their servers or network by any client. Webvault recommends the use of encryption when storing sensitive payment information.

CREDIT CARD FRAUD

Merchants should also be aware of credit card fraud. Processing a credit card transaction through the Webvault merchant services API carries the exact same risks as processing a transaction using another method provided by your financial institution. Webvault is NOT a financial institution, and all transactions are approved or declined by the appropriate third party card issuer. Merchants are still bound by all terms and conditions specified by their bank or financial institution in relation to conducting credit card payment transactions online. Webvault does NOT take responsibility for fraudulent use of credit cards by any individual processing a credit card through software accessing our software interface.

NO SERVICE GUARANTEE

Due to the fact that the Internet consists of many interconnected networks, Webvault does not guarantee that’s its merchant services interface will not suffer full or partial downtime from time to time. Whilst Webvault will take every reasonable effort to ensure quality of service, merchants should have applications and procedures in place that act as a backup measure for the processing of credit card payments with their financial institution in the event of an unexpected outage. Webvault takes no responsibility for the loss of income resulting from a service outage.

YOUR OWN RISK

Whilst every effort has been made to ensure the reliability and security of this applications software, Webvault offers no guarantee of it being “"bug-free"”. Merchants account holders use this application programming interface at their own risk.