Page History: Credit Card Merchant Services API Developers Guide

Compare Page Revisions

4 3 2 1 0 Current 4 3 2 1 0

« Older Revision - Back to Page History - Current Revision

Page Revision: 13/05/2010 17:01

Table of Contents [Hide/Show]    Introduction    Getting Started    API Usage       Request Parameters       Example Request       Response Parameters       Example XML Response       Testing Transaction Responses    Warnings & Disclaimers

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

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.


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.

<?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 testing 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. response SummaryCode value of 0). Providing a value for the amount ending with 01 will result in the test payment being declined (ie. response SummaryCode value of 1). You can use these method to successfully test your application with a variety of possible transaction response codes.

Warnings & Disclaimers¶