XML specification and field definitions - describes the eWAY real time Payments
(with CVN) XML document required and the resulting eWAY XML document returned, including
field definitions and sample XML documents.
- Test gateway - https://www.eway.com.au/gateway_cvn/xmltest/testpage.asp - FREE!
- Live gateway - https://www.eway.com.au/gateway_cvn/xmlpayment.asp - CHARGED PER
TRANS
Linking to eWAY
Below are the specifications for using the eWAY XML solution, including linking
requirements and field descriptions.
The following table outlines the maximum string lengths that can be passed to the
eWAY XML payment page.
If data of greater length is passed then it is truncated.
|
ewayCustomerID |
8 |
|
|
ewayTotalAmount |
12 |
|
|
ewayCustomerFirstName |
50 |
|
|
ewayCustomerLastName |
50 |
|
|
ewayCustomerEmail |
50 |
|
|
ewayCustomerAddress |
255 |
|
|
ewayCustomerPostcode |
6 |
|
|
ewayCustomerInvoiceDescription |
10000 |
|
|
ewayCustomerInvoiceRef |
50 |
|
|
ewayCardHoldersName |
50 |
|
|
ewayCardNumber |
20 |
|
|
ewayCardExpiryMonth |
2 |
|
|
ewayCardExpiryYear |
2 |
|
|
ewayTrxnNumber |
16 |
|
|
ewayOption1 |
255 |
|
|
ewayOption2 |
255 |
|
|
ewayOption3 |
255 |
|
|
ewayCVN |
3 or 4 |
|
|
ewayTrxnStatus |
6 |
|
|
ewayTrxnNumber |
16 |
|
|
ewayTrxnReference |
50 |
|
|
ewayTrxnOption1 |
255 |
|
|
ewayTrxnOption2 |
255 |
|
|
ewayTrxnOption3 |
255 |
|
|
ewayAuthCode |
6 |
|
|
ewayReturnAmount |
12 |
|
|
ewayTrxnError |
100 |
|
|
ewayCustomerID |
Your unique eWAY customer ID assigned to you when you join eWAY. eg 11438715 |
|
ewayTotalAmount |
The total amount in cents for the transaction, eg $1.00 = 100 |
|
ewayCustomerFirstName |
The first name of your customer making a purchase at your site. |
|
ewayCustomerLastName |
The last name of your customer making a purchase at your site. |
|
ewayCustomerEmail |
The email address of your customer making a purchase at your site. |
|
ewayCustomerAddress |
The address of your customer making a purchase at your site including state, city
and country. |
|
ewayCustomerPostcode |
The postcode of your customer making a purchase at your site. |
|
ewayCustomerInvoiceDescription |
A description of the products or services purchased. |
|
ewayCustomerInvoiceRef |
A reference to your own invoice system for the purchase. |
|
ewayTrxnReference |
See 'eWAYTrxnNumber'. |
|
ewayOption1 |
This value is returned to your website. An additional field for you to pass and
receive information from eWAY. |
|
ewayOption2 |
This value is returned to your website. An additional field for you to pass and
receive information from eWAY. |
|
ewayOption3 |
This value is returned to your website. An additional field for you to pass and
receive information from eWAY. |
|
ewayCVN |
This is the 3 digit security code found on the back of VISA and MasterCard credit
cards, or 4 digit security code found on the fronf or AMEX cards. |
|
ewayTrxnStatus |
This value is returned to your website. For a successful transaction "True"
is passed and for a failed transaction "False" is passed. This allows you
to make your own logging on your website for transaction status. |
|
ewayTrxnNumber |
This value is returned to your website. You can pass a unique transaction number
from your site. You can update and track the status of a transaction when eWAY returns
to your site.
NB. This number is returned as 'ewayTrxnReference'. The number returned as
'ewayTrxnNumber', is actually the unique eWAY Transaction number, created
by eWAY itself. |
|
ewayAuthCode |
If the transaction is successful, this is the bank authorisation number. This is
also sent in the email receipt. |
|
eWAYReturnAmount |
Can be used a check that the transaction is processed for the same amount as you
request from your website. |
|
ewayTxnError |
This is the response returned by the bank, and can be related to both successful
and failed transactions. |
Example XML Layout.
Please do not copy/paste the code behind the following XML example for your code.
This will result in malformed code, as it is presented here for display purposes
only. Please refer to our sample code for more information.
The following is an example of the XML sent to the eWAY XML payment page.
<ewaygateway>
<ewayCustomerID> 12345678 </ewayCustomerID>
<ewayTotalAmount> 10 </ewayTotalAmount>
<ewayCustomerFirstName> Jackie </ewayCustomerFirstName>
<ewayCustomerLastName> Chan </ewayCustomerLastName>
<ewayCustomerEmail> chan@webactive.com.au </ewayCustomerEmail>
<ewayCustomerAddress> 123 Sesame St </ewayCustomerAddress>
<ewayCustomerPostcode> 2345 </ewayCustomerPostcode>
<ewayCustomerInvoiceDescription> Red socks </ewayCustomerInvoiceDescription>
<ewayCustomerInvoiceRef> 0123 - abc </ewayCustomerInvoiceRef>
<ewayCardHoldersName> Jackie Chan </ewayCardHoldersName>
<ewayCardNumber> 424212132325454 </ewayCardNumber>
<ewayCardExpiryMonth> 04 </ewayCardExpiryMonth>
<ewayCardExpiryYear> 09 </ewayCardExpiryYear>
<ewayTrxnNumber> 987654321 </ewayTrxnNumber>
<ewayCVN> 123 </ewayCVN>
<ewayOption1></ewayOption1>
<ewayOption2></ewayOption2>
<ewayOption3></ewayOption3>
</ewaygateway>
The following is an example of the XML returned after a successful test transaction.
<ewayResponse>
<ewayTrxnError></ewayTrxnError>
<ewayTrxnStatus> True </ewayTrxnStatus>
<ewayTrxnNumber> 10002 </ewayTrxnNumber>
<ewayTrxnOption1></ewayTrxnOption1>
<ewayTrxnOption2></ewayTrxnOption2>
<ewayTrxnOption3></ewayTrxnOption3>
<ewayReturnAmount> 10 </ewayReturnAmount>
<ewayAuthCode> 123456 </ewayAuthCode>
<ewayTrxnReference> 987654321 </ewayTrxnReference>
</ewayResponse>
We have provided sample code for ASP, PHP, ASP.NET (C#) and VB.NET programming languages.
Basically, all you need to do, per transaction, is:
- Send the XML document via HTTPS, using SSL.
- Parse the XML document returned
from eWAY.
- ASP Code
This ZIP file contains the following 3 Active Server Pages:
- ePayment.asa - Creates and sends the XML document to eWAY.
- paymentForm.htm - An example of a form to send to the process.asp page. Be
sure to include a valid eWAYCustomerID when you go live, this will be issued to
you after you join eWAY.
- process.asp - This includes the ePayment.asa file and displays the transaction
results.
For more information on passing XML, please see the Field specifications tab.
»
Download the XML ASP sample code (with CVN support)
- PHP Code
This ZIP file contains the following files:
- WebForm.php - An example of a form to send to the eWAY gateway.
- EwayConfig.inc.php - This file contains all configuration information, remember
to change this to your own customerID when you are ready to go live.
- EwayPaymentLive.php - This takes the fields from the WebForm.php page and
converts it to an XML string and sends it to the gateway.
- testewaylive.php - Test page to test the functionality.
- Please Read - - If you are attempting to
execute the PHP Code from a Windows environment, and are receiving an SSL Certificate
error, you may need to add the line:
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
when calling the eWAY Gateway, after the line:
$ch = curl_init( $this->myGatewayURL );
For more information on passing XML, please the Field specifications tab.
»
Download the XML PHP sample code - version 4.x and 5.x
- C++ Code
Target platform: OS Portable (Source code to work with many OS platforms)
Required libraries:
Library documentation index page: doc\html\index.html
This ZIP file contains the following files:
- \bin - binary files
- \doc - project documentation (doxygen+html)
- \example - example of library usage
- \include - library include
- \src - library sources
- \test - automatic tests
- \tmp - all temporary output files
- readme.txt - Short help
- Eway_Gateway.sln - Solution for MS Visual Studio 2003
- Eway_Gateway.vcproj - Project for build eWAY gateway static library
- Eway_Gateway_Example_App.vcproj - Project for build example of library usage
- Eway_Gateway_Test.vcproj - Project for build automatic tests of library
For more information on passing XML, please see the Field specifications tab.
»
Download the C++ source code
- JAVA Code
This ZIP file contains the following folders:
In the folder \connection_classes_with_demo
- /src - Source files of the connection clases of the com.eway package and
source of demo application
- /bin - Binary versions of the above. The 3 connection classes are also made
available in a single jar
- /doc - Documentation of connection classes in javadoc format. Start with
index.html in the /doc folder
- Readme - More detailed information
For more information on passing XML, please see the Field specifications tab.
»
Download the JAVA source code
- C# Code
This ZIP file contains the following files:
- WebForm1.aspx (2003) / Default.aspx (2005) - An example of a form to send
to the eWAY gateway. Be sure to include a valid eWAYCustomerID when you go live.
This ID will be issued to you once you've joined eWAY.
- WebForm1.aspx.cs (2003) / Default.aspx (2005) - C# Server-side code for the
WebForm1.aspx page.
- GatewayConnector.cs - This page connects to the eWAY gateway, sends an XML
request and receives the XML response.
- GatewayRequest.cs - This takes the fields from the WebForm1.aspx page and
converts it to an XML string to pass to the GatewayConnector.cs page.
- GatewayResponse.cs - This passes the eWAY gateway response back to the WebForm1.aspx
page.
- Web.config - This holds the configuration settings for the live and test
gateway URLs, as well as your eWAY Customer ID and the ID used for testing.
For more information on passing XML, please see the Field specifications tab.
»
Download the C# source code (with CVN support) (Microsoft Visual Studio 2003)
»
Download the C# source code (with CVN support) (Microsoft Visual Studio 2005)
- VB.NET Code
This ZIP file contains the following files:
- WebForm1.aspx (2003) / Default.aspx (2005) - An example of a form to send
to the eWAY gateway. Be sure to include a valid eWAYCustomerID when you go live.
This ID will be issued to you once you've joined eWAY.
- WebForm1.aspx.cs (2003) / Default.aspx (2005) - C# Server-side code for the
WebForm1.aspx page.
- GatewayConnector.cs - This page connects to the eWAY gateway, sends an XML
request and receives the XML response.
- GatewayRequest.cs - This takes the fields from the WebForm1.aspx page and
converts it to an XML string to pass to the GatewayConnector.cs page.
- GatewayResponse.cs - This passes the eWAY gateway response back to the WebForm1.aspx
page.
- Web.config - This holds the configuration settings for the live and test
gateway URLs, as well as your eWAY Customer ID and the ID used for testing.
- readme.txt - Additional notes on the the VB.NET Sample Code.
For more information on passing XML, please see the Field specifications tab.
»
Download the VB.NET source code (with CVN support)
You can build and test your website payment solution before joining eWAY.
To test your solution with eWAY, all you need to do is pass the
required test-account information. This test facility uses the real payment functionality,
so there are very few changes required once you join eWAY.
These testing instructions make use of the same sample code we provide
for connection to eWAY.
|
IMPORTANT!
Please make sure you use the following values when testing:
- The test gateway URL is https://www.eway.com.au/gateway_cvn/xmltest/testpage.asp
- The test Customer ID is 87654321 - this is the only ID that will
work on the test gateway.
- The test Credit Card number is 4444333322221111 - this is the only
credit card number that will work on the test gateway.
- The test Total Amount should end in 00 or 08 to
get a successful response (e.g. $10.00 or $10.08) - all other amounts will return
a failed response.
|
- Instructions for Testing - ASP
1. Download our ASP XML Sample Code.
2. Ensure the URL in process.asp and Epayment.asa
are:
'https://www.eway.com.au/gateway_cvn/xmltest/testpage.asp'
3. Open PaymentForm.htm in Internet Explorer
and set the field values to the following:
|
ewayCustomerID |
87654321 |
Test eWAYcustomerID, you will be issued with your own Live eWAYCusomterID ID once
you . |
"Error: Invalid eWAY TEST Gateway account. Your credit card has not been billed
for this transaction.(Test Gateway)" |
|
ewayCardNumber |
4444333322221111 |
Credit card number |
"Error: Invalid credit card provided. Your credit card has not been billed for this
transaction.(Test Gateway)" |
|
ewayCardExpiryMonth |
Greater than or equal to today's month ie 06 for the 04/06/08 |
Credit card expiry month |
"Error: Expiry Month invalid. Your credit card has not been billed for this
transaction.(Test Gateway)"
OR
"eWAY Error: Invalid Expiry Date. Your credit card has not been billed
for this transaction.(Test Gateway)" |
|
ewayCardExpiryYear |
Greater than or equal to today's year ie 08 for the 05/05/08 |
Credit card expiry year |
"Error: Expiry Year invalid. Your credit card has not been billed for this transaction.(Test
Gateway)"
OR
"eWAY Error: Invalid Expiry Date. Your credit card has not been billed for this
transaction.(Test Gateway)" |
|
ewayTotalAmount |
Any integer value, e.g. 1000 (This is $10.00) |
Total amount for the transaction.
All values are to be passed in cents (ie 1000 = $10.00) with no
decimal points, dollar signs, etc. N.B. The cents value passed will correspond to
the response code returned in the XML response, e.g. for 1000 the Response Code
will be 00, for 1050 the Response Code will be 50.
|
"Error: Invalid Amount. Your credit card has not been billed for this transaction.
TotalAmount= 1050 "(Test Gateway)"
|
|
ewayCVN |
Any 3 or 4 digit number |
3 digit security code found on the back of Visa and Mastercard credit cards.
4 digit code for American Express Cards.
* Only require if using the CVN Gateway. |
"Error: Invalid CVN. Your credit card has not been billed for this transaction.(Test
Gateway)" |
4. If you pass anything other than the values in the "Value to pass to eWAY" column
(above), you will receive the respective error message in the "Error Messages" column
(above, right).
If the exact values outined above are passed to the test gateway, the CENTS value
passed in the ewayTotalAmount field will be the Response Code returned,
e.g. if "100" is passed ($1.00), the Response Code will be "00", or if "1015" is
passed ($10.15), the Resonse Code will be "15". These Response Codes also generate
the Response Text, and thus the value returned in ewayTrxnError.
View All Response Codes, and associated Response Text
The other fields returned in the XML will have the following values:
|
ewayTrxnStatus |
True |
False |
|
ewayTrxnNumber |
10000 + |
10000 + |
|
ewayTrxnReference |
value sent in <ewayTrxnNumber> returned |
value sent in <ewayTrxnNumber> returned |
|
ewayAuthCode |
123456 |
empty |
|
ewayReturnAmount |
value sent returned |
value sent returned |
|
ewayTrxnError |
"Response Code,Response Text" (e.g. 00, Transaction Approved(Test Gateway))
View Possible Response Codes and Response Text |
"Response Code, Response Text" (e.g. 01, Do Not Honour(Test Gateway))
OR
See above - "Possible error messages"
View Possible Response Codes and Response Text |
|
ewayTrxnOption1 |
value sent returned |
value sent returned |
|
ewayTrxnOption2 |
value sent returned |
value sent returned |
|
ewayTrxnOption3 |
value sent returned |
value sent returned |
- Instructions for Testing - PHP
1. Download our PHP XML Sample Code.
2. Ensure the variable $eWAY_UseLive = false in EwayConfig.inc.php.
And that $eWAY_Paymentmethod = REAL_TIME_CVN. When you are ready to test with the
live gateway you simple change this to $eWAY_UseLive = true.
3. Open WebForm.php in a browser and set
the fields to the following values:
|
ewayCustomerID |
87654321 |
Test eWAYcustomerID, you will be issued with your own Live eWAYCusomterID ID once
you . |
"Error: Invalid eWAY TEST Gateway account. Your credit card has not been billed
for this transaction.(Test Gateway)" |
|
ewayCardNumber |
4444333322221111 |
Credit card number |
"Error: Invalid credit card provided. Your credit card has not been billed for this
transaction.(Test Gateway)" |
|
ewayCardExpiryMonth |
Greater than or equal to today's month ie 06 for the 04/06/08 |
Credit card expiry month |
"Error: Expiry Month invalid. Your credit card has not been billed for this
transaction.(Test Gateway)"
OR
"eWAY Error: Invalid Expiry Date. Your credit card has not been billed
for this transaction.(Test Gateway)" |
|
ewayCardExpiryYear |
Greater than or equal to today's year ie 08 for the 05/05/08 |
Credit card expiry year |
"Error: Expiry Year invalid. Your credit card has not been billed for this transaction.(Test
Gateway)"
OR
"eWAY Error: Invalid Expiry Date. Your credit card has not been billed for this
transaction.(Test Gateway)" |
|
ewayTotalAmount |
Any integer value, e.g. 1000 (This is $10.00) |
Total amount for the transaction.
All values are to be passed in cents (ie 1000 = $10.00) with no
decimal points, dollar signs, etc. N.B. The cents value passed will correspond to
the response code returned in the XML response, e.g. for 1000 the Response Code
will be 00, for 1050 the Response Code will be 50.
|
"Error: Invalid Amount. Your credit card has not been billed for this transaction.
TotalAmount= 1050 "(Test Gateway)"
|
|
ewayCVN |
Any 3 or 4 digit number |
3 digit security code found on the back of Visa and Mastercard credit cards.
4 digit code for American Express Cards.
* Only require if using the CVN Gateway. |
"Error: Invalid CVN. Your credit card has not been billed for this transaction.(Test
Gateway)" |
4. If you pass anything other than the values in the "Value to pass to eWAY" column
(above), you will receive the respective error message in the "Error Messages" column
(above, right).
If the exact values outlined above are passed to the test gateway, the CENTS value
passed in the ewayTotalAmount field will be the Response Code returned,
e.g. if "100" is passed ($1.00), the Response Code will be "00", or if "1015" is
passed ($10.15), the Resonse Code will be "15". These Response Codes also generate
the Response Text, and thus the value returned in ewayTrxnError.
View All Response Codes, and associated Response Text
The other fields returned in the XML will have the following values:
|
ewayTrxnStatus |
True |
False |
|
ewayTrxnNumber |
10000 + |
10000 + |
|
ewayTrxnReference |
value sent in <ewayTrxnNumber> returned |
value sent in <ewayTrxnNumber> returned |
|
ewayAuthCode |
123456 |
empty |
|
ewayReturnAmount |
value sent returned |
value sent returned |
|
ewayTrxnError |
"Response Code,Response Text" (e.g. 00, Transaction Approved(Test Gateway))
View Possible Response Codes and Response Text |
"Response Code, Response Text" (e.g. 01, Do Not Honour(Test Gateway))
OR
See above - "Possible error messages"
View Possible Response Codes and Response Text |
|
ewayTrxnOption1 |
value sent returned |
value sent returned |
|
ewayTrxnOption2 |
value sent returned |
value sent returned |
|
ewayTrxnOption3 |
value sent returned |
value sent returned |
- Instructions for Testing - C# (ASP.NET)
1. Download our C# XML Sample Code
2. Ensure the URL and eWAYCustomerID in Web.config are
set to the following:
|
<!--
Test Account -->
<add key="ewayCustomerID"
value="87654321"/>
|
|
AND
|
|
<!--
Test gateway -->
<add
key="ewayGateway" value="https://www.eway.com.au/gateway_cvn/xmltest/TestPage.asp"/>
|
3. Once your files are added to an ASP.NET Web Application Project, run WebForm1.aspx
in Internet Explorer and set the fields to the following vales:
|
ewayCustomerID |
87654321 |
Test eWAYcustomerID, you will be issued with your own Live eWAYCusomterID ID once
you . |
"Error: Invalid eWAY TEST Gateway account. Your credit card has not been billed
for this transaction.(Test Gateway)" |
|
ewayCardNumber |
4444333322221111 |
Credit card number |
"Error: Invalid credit card provided. Your credit card has not been billed for this
transaction.(Test Gateway)" |
|
ewayCardExpiryMonth |
Greater than or equal to today's month ie 06 for the 04/06/08 |
Credit card expiry month |
"Error: Expiry Month invalid. Your credit card has not been billed for this
transaction.(Test Gateway)"
OR
"eWAY Error: Invalid Expiry Date. Your credit card has not been billed
for this transaction.(Test Gateway)" |
|
ewayCardExpiryYear |
Greater than or equal to today's year ie 08 for the 05/05/08 |
Credit card expiry year |
"Error: Expiry Year invalid. Your credit card has not been billed for this transaction.(Test
Gateway)"
OR
"eWAY Error: Invalid Expiry Date. Your credit card has not been billed for this
transaction.(Test Gateway)" |
|
ewayTotalAmount |
Any integer value, e.g. 1000 (This is $10.00) |
Total amount for the transaction.
All values are to be passed in cents (ie 1000 = $10.00) with no
decimal points, dollar signs, etc. N.B. The cents value passed will correspond to
the response code returned in the XML response, e.g. for 1000 the Response Code
will be 00, for 1050 the Response Code will be 50.
|
"Error: Invalid Amount. Your credit card has not been billed for this transaction.
TotalAmount= 1050 "(Test Gateway)"
|
|
ewayCVN |
Any 3 or 4 digit number |
3 digit security code found on the back of Visa and Mastercard credit cards.
4 digit code for American Express Cards.
* Only require if using the CVN Gateway. |
"Error: Invalid CVN. Your credit card has not been billed for this transaction.(Test
Gateway)" |
4. If you pass anything other than the values in the "Value to pass to eWAY" column
(above), you will receive the respective error message in the "Error Messages" column
(above, right).