Official eWAY Documentation
Version 0.82
Published on 8/08/2013
Contents
Welcome from eWAY CEO ... 5
Overview ... 6
Payment types included ... 7
Individual payments ... 7
Beagle Alerts (powered by ReD) ... 7
Beagle (free) ... 7
3-D Secure ... 7
Token ... 8
Global Endpoint ... 8
Beagle Alerts ... 9
Rule sets ... 9
Customised protection ... 9
Beagle Alert types ... 9
Beagle Alert Actions ... 10
Review ... 10
PreAuth ... 10
Allow... 10
Block ... 10
Integration and cost ... 10
Beagle (free) vs Beagle Alerts ... 11
Beagle (free) ... 11
Beagle Alerts ... 11
Who is ReD? ... 11
Summary for the process of a challenged transaction ... 11
Supported technologies ... 15
SOAP ... 15
REST (POST) ... 15
HTTP POST ... 15
RPC ... 15
JSONP ... 15
Supported countries ... 16
Infrastructure ... 16
PCI DSS Compliance ... 17
Available Methods ... 18
ProcessPayment ... 18
TokenPayment ... 18
CreateTokenCustomer ... 18
UpdateTokenCustomer ... 18
Authentication ... 19
Implementation ... 20
Step 1: Create an Access Code ... 20
Live Endpoints ... 20
Sandbox Endpoints ... 21
Sample request – XML ... 21
Request field descriptions ... 22
Response ... 26
Sample response - XML ... 26
Response field descriptions ... 27
Step 2: Customer submits card details direct to eWAY ... 30
Sample HTML form ... 31
JSONP ... 31
Step 3: Request the results ... 32
Live Endpoints ... 32
Sandbox Endpoints ... 32
Sample request - XML ... 33
Request field descriptions ... 33
Sample response ... 33
Response field descriptions ... 34
Options ... 34
Verification ... 35
Testing ... 35
Sandbox... 35
Creating an API Key ... 35
Appendix A – Process Payment Examples ... 36
SOAP 1.1 ... 36
Create Access Code ... 36
Get Access Code Result ... 38
XML ... 39
Create Access Code ... 39
Get Access Code Result ... 41
JSON ... 42
Create Access Code ... 42
Get Access Code Result ... 44
Appendix B –Token Payment Examples ... 46
SOAP 1.1 ... 46
Create Access Code ... 46
Get Access Code Result ... 47
XML ... 48
Create Access Code ... 48
Get Access Code Result ... 50
JSON ... 51
Create Access Code ... 51
Get Access Code Result ... 53
Appendix C – Create Token Customer Examples ... 55
SOAP 1.1 ... 55
Create Access Code ... 55
Get Access Code Result ... 56
XML ... 57
Create Access Code ... 57
Get Access Code Result ... 58
JSON ... 59
Create Access Code ... 59
Get Access Code Result ... 61
Appendix D – Update Token Customer Examples ... 63
SOAP 1.1 ... 63
Create Access Code ... 63
Get Access Code Result ... 64
XML ... 65
Create Access Code ... 65
Get Access Code Result ... 66
JSON ... 67
Create Access Code ... 67
Get Access Code Result ... 69
Appendix E – JSONP Script Example ... 71
Available Options ... 71
Sample Script ... 71
Appendix F – Supporting Diagram ... 73
Rapid 3.0 transparent redirect API Transaction Flow ... 73
Appendix G – Response Messages ... 74
Transaction Response Messages ... 74
Beagle (Free) and Beagle Alerts Fraud Response Messages ... 76
System Response Codes ... 77
Validation Response Codes ... 78
Appendix H – PCI DSS Compliance ... 81
Disclaimer... 82
Welcome from eWAY CEO
I’m Matt Bullock, CEO of eWAY, and it’s my pleasure to introduce you to the new way to take online payments: Rapid 3.0 transparent redirect API. This global solution provides streamlined integration and enhanced security to our clients and partners all over the world, taking eWAY’s functionality to new heights.
For the first time, merchants in Australia, New Zealand and the United Kingdom can connect their websites to a single, global gateway. This means that our development partners need only integrate with eWAY once before they can start selling their carts and applications to international clients.
The announcement of Rapid 3.0 transparent redirect API also marks the launch of Beagle Alerts, which harnesses the power of ReD’s industry-leading fraud recognition. No additional integration is required; merchants simply login to MYeWAY and fill in a short questionnaire to set up real-time protection which is tailored to their businesses. Beagle Alerts denies, challenges or accepts transactions based on data garnered by monitoring card activity all around the globe.
It’s with great pride that I provide this documentation to you – I hope you enjoy using Rapid 3.0 transparent redirect API to save time, save money and win more clients. My team is here to help, so please don’t hesitate to call them if you have any more questions.
Kind regards,
Matt Bullock eWAY
CEO and Founder
Overview
Rapid 3.0 transparent redirect API is a payment product that allows merchants to post credit card data from their customer’s browser directly to eWAY without it passing through the merchant’s server.
Each Rapid 3.0 transparent redirect API payment consists of three steps.
1. The merchant requests an access code by sending a request to eWAY containing details of the transaction, including the amount, the invoice number and the customer details.
2. The merchant displays a secure HTML form to the customer for credit card entry. The form is submitted directly to eWAY for processing. This is achieved via a HTTPS POST from the client’s browser.
3. eWAY redirects the customer to a Return URL specified by the merchant. The merchant then requests the results of the transaction from eWAY.
Please see Appendix F for a larger version of this diagram.
Payment types included
Individual payments
Rapid 3.0 transparent redirect API allows merchants to take payments seamlessly through their websites without having to handle credit card data. The merchant hosts the payment page, but transaction information is transmitted directly from the customer’s web browser to eWAY without passing through the merchant’s server. eWAY then sends confirmation of the transaction back to the merchant’s website and email account.
This reduces the merchant’s scope for PCI DSS compliance and enhances security while giving developers maximum control over the look and feel of their payment processing.
Beagle Alerts (powered by ReD)
Beagle Alerts is our most advanced fraud prevention product. Once enabled on an account, each transaction is checked against a global database of credit card transaction activity, providing the merchant with real-time recommendations to accept, challenge or deny each payment.
A short questionnaire helps us create a rule profile which is tailored to the needs of the business. This service is provided by the world leaders in online payment risk management, ReD, which protected 17 billion transactions in 2011.
No additional integration is required to use Beagle Alerts; the merchant simply activates it using MYeWAY.
Beagle (free)
Beagle (free) uses numerous external services to give you control over the payments made through your website, blocking or flagging high-risk transactions based on factors such as the location of the customers computer, country associated with the credit card, and their billing address.
Note that Beagle (free) requires two specific fields to be passed;
IPAddress and the Country field within the Customer element.
3-D Secure
3-D Secure provides an additional layer of security by redirecting customers to a bank-hosted page which requests a PIN before
processing a payment. This reduces the likelihood of fraud and reduces the liability of the merchant. If 3-D Secure is not enabled on the
customer’s card, the transaction will be processed normally. No
additional integration is required to use this solution, but it does need to be compatible with your Internet Merchant Facility.
Token
Token Payments creates a unique Token ID for each customer when eWAY receives the billing details. This token refers to the customer and card data stored on eWAY,s PCI DSS compliant platform, and whenever you subsequently need to charge the customer, you can use this token instead of asking the cardholder to enter their details a second time. This solution is particularly useful when a repeat purchase is required or expected from the customer, such as with a subscription or payment plan.
Global Endpoint
Rapid 3.0 transparent redirect API is a truly global solution, allowing merchants all over the world to process transactions through a single gateway. With an expanded number of data interchange standards supported including REST, JSON and RPC, integrating this hostname is now even easier.
Connecting through a single hostname allows eWAY’s global network to determine the closest data centre connection through which to process the transaction, ensuring the fastest possible processing time.
By integrating this into their shopping carts and applications, our development partners will have an unparallelled capacity to win clients in all eWAY’s territories.
Beagle Alerts
Beagle Alerts is powered by ReD (Retail Decisions), the industry-leading fraud recognition service, which uses hundreds of complex rules to identify potentially fraudulent transactions in real time.
Rule sets
The factors analysed may include:
•
How recently the credit card number has been used•
How often the credit card number is used•
How many different billing, shipping, or email addresses have been used for a single credit card•
How many different email addresses or credit cards have been used for a single billing addressCustomised protection
This solution is tailored to suit each merchant based on their answers to a short questionnaire which effectively determines their level of risk. This questionnaire covers the merchant’s industry type, their fraud history, their risk expectations for the future and the location of their customer base.
Beagle Alert types
Based on what, if any, rules are tripped for your transaction, the following Beagle Alert responses may be returned:,
Icon Type Description
Allow When a transaction is accepted, this means that the risk level has been assessed as low.
Deny A transaction which has been denied by Beagle alerts has been judged to be high risk. Merchants are able to request email or text message notifications so as they are aware of the Denied transactions.
Challenge When a transaction has been challenged, this means that it has been assessed as having moderate risk, and should be reviewed. Merchants are able to request email or text message notifications so as they are aware of the Challenged transactions.
Beagle Alert Actions
eWAY merchants have a number of options for handling all of the above types of Beagle Alerts:
Review
Selecting Review in the settings for Beagle Alerts will ensure that the transaction is not processed until the merchant logs in to MYeWAY and manually Allows or Denies it. Only when the payment has been allowed, will it be sent to the bank for processing
PreAuth
Choosing PreAuth reserves the funds, but the card is not charged until the merchant completes the transaction within MYeWAY. Using this method, merchants need not worry about logging in and approving a payment only to have the card be declined.
Allow
The Allow option ensures that challenged transactions are processed automatically. The merchant can still login to MYeWAY and Deny the transaction, which will trigger a refund to be processed.
Block
Choosing Block will automatically block the transaction from being sent to merchants bank for processing. It is recommended that this option be selected for all Denied transactions.
The above can be configured in MYeWAY at Settings > Anti-fraud / Beagle
Integration and cost
If Rapid 3.0 transparent redirect API has been integrated correctly, Beagle Alerts requires no additional development and it can be activated from within MYeWAY.
Pricing for Beagle Alerts is available on the eWAY website.
Beagle (free) vs Beagle Alerts
Beagle (free)
Beagle (free) is a powerful anti-fraud engine to analyse your transactions using additional external services to analyse various details passed to the eWAY gateway. This is a customisable service which eWAY offers to protect our merchants from high-risk transactions.
Beagle Alerts
Beagle Alerts is our premium fraud prevention solution, which harnesses the power of ReD to detect suspicious transactions with industry-leading accuracy. In addition to checking customer IP
addresses, billing details and email addresses, Beagle Alerts uses live data from more than 190 countries around the world to ensure that merchants have the best protection available.
If a customer’s billing details have been used elsewhere in suspicious circumstances, Beagle Alerts can deny or challenge the transaction in real time. Merchants have the option to approve challenged transactions manually, automatically or by completing a Pre Auth, which reserves the funds until the merchant is ready to charge the card. Note: Pre-Auth is only supported in Australia
Who is ReD?
ReD (Retail Decisions) is a specialist provider of fraud prevention and payment services, with offices and staff across Europe and the Asia Pacific region, as well as America, the Middle East and Africa.
They work closely with global, regional and local partners.
ReD provides fraud solutions for all payment transaction types. The company is present in every part of the payments value chain, protecting merchants, issuers, acquirers, PSPs, processors and switches through products such as ReD Shield®, ReD PRISM® and ReD1 Gateway™. These solutions are supported by a team of industry leading fraud and risk experts, standing ready to help protect merchants in the global battle against payment fraud.
ReD’s constant investment in technology keeps their merchant clients ahead of fraudsters. They protected more than 17 billion transactions in 2011 and gathered data from more than 190 countries in six continents. ReD protects trusted brands in the travel, retail, banking and telecommunications sectors.
Thanks to our partnership with ReD, all eWAY merchants can access this world leading technology.
You don’t need an account with ReD, and no additional integration is required!
Summary for the process of a challenged transaction
What is a challenged transaction and how is it different from a normal transaction?
A transaction is challenged when Beagle Alerts determines that it has a moderate risk of fraud. This may happen when multiple billing addresses have been used with the credit card, the email
addresses is from a high-risk domain, the IP address is from a high risk country, or for a variety of other reasons.
Beagle Alerts uses data from ReD (Retail Decisions), a worldwide fraud-prevention service to determine the risk level of each transaction. Low risk transactions are accepted, moderate risk transactions are challenged and high risk transactions are denied.
Will all my transactions be powered by Beagle Alerts?
Once Beagle Alerts has been activated on your account, it will check all your transactions. You can activate Beagle Alerts in MYeWAY under Settings > Beagle Alert Settings.
For best results, please ensure that your site sends through all the available fields for Beagle Alerts to check.
What happens if my transaction is Accepted by Beagle Alerts?
The transaction will be processed by eWAY, and your merchant provider will attempt to charge the credit card.
What happens if my transaction is Denied by Beagle Alerts?
Your settings in MYeWAY will determine how a denied transaction is handled. These settings can be found in Settings > Anti-Fraud / Beagle. We recommend choosing “Block Transaction” so that denied transactions are not processed.
Block:
The transaction will not be processed. No further action is required on your part.
Allow:
The transaction will be processed (unless one of your Beagle [free] rules blocks it).
What happens if my transaction is Challenged by Beagle Alerts?
Your settings in MYeWAY will determine how a challenged transaction is handled. These settings can be found in Settings > Anti-Fraud > Beagle.
You have four options for challenged transactions:
Block:
The transaction will not be processed. No further action is required on your part.
Allow:
The transaction will be processed (unless one of your Beagle [free] rules blocks it).
Review:
The transaction will be stored until you login to MYeWAY and allow or deny it.
If you select Allow, eWAY will process the transaction and your merchant provider will attempt to
charge the credit card. You will need to contact the client for their CVN (Card Verification Number).
If you select Deny the transaction will not be sent to the bank. You will no longer be able to process it.
PreAuth:
eWAY will process the transaction, but the customer will not be charged. Instead, funds will be reserved on their card until you login to MYeWAY and allow or deny the transaction.
If you select Allow the reserved funds will be charged.
If you select Deny the reserved funds will be released.
What happens if the transaction is challenged, sent to the bank, and then declined from the bank?
If this happens, you will not have the option to Allow or Deny the transaction. Instead, you will be prompted to Acknowledge. This is because the bank is unable to charge your client in the first place.
How will I know if a transaction was challenged?
Manual Check:
Challenged transactions will be marked with the following icon in MYeWAY:
Under Settings / Anti-Fraud / Beagle you can choose to be notified of challenged transactions via email and set your email address.
You can search for challenged transactions in MYeWAY under Reporting / Transaction report.
On the rightmost filter you can select “Challenged” in the drop-down menu. This will show only challenged transactions.
Programmatically:
A successful transaction through Rapid 3.0 transparent redirect API will render the response A2000.
A transaction which is allowed by Beagle Alerts but declined by the bank will return D44XY F7001, where XY is the bank’s two-digit response code. A transaction which is allowed by Beagle Alerts and approved by the bank will return A2000, F7001 followed by a comma separated list of Beagle Alert rules that were broken. The A2000 will always be the first code to appear in the response.
This process happens because you want your client to see a successful transaction, then you can allow or deny behind the scenes. This stops clients from trying to pay multiple times, as well as protecting you from fraudulent transactions.
If the client is fraudulent, we don’t want to share your anti-fraud processes with them.
Supported technologies
The following data interchange standards are supported by Rapid 3.0 transparent redirect API:
SOAP
Simple Object Access Protocol is a protocol for invoking web service methods. It uses HTTP as its transfer layer and XML as its markup language. SOAP is an established protocol and most
programming languages already have SOAP client classes available, which means that requests and responses do not have to be manually created or parsed.
REST (POST)
Representational State Transfer is a model for invoking web services based solely on HTTP. It can access any information available using just a URL. REST’s simple structure makes application interoperability easier.
REST is supported with both JSON and XML.
HTTP POST
POST is a request method supported by the HTTP protocol and is specifically used when a client needs to send data to a server as part of a request. POST is supported for sending both JSON and XML in the message body.
RPC
Remote Procedure Call is a specification that enables calling methods on remote machines over HTTP. RPC is supported by both the XML-RPC and JSON-RPC specifications.
JSONP
JavaScript Object Notation with Padding allows dynamically including external JavaScript sources in your website for supporting asynchronous calls. Both pre and post payment callbacks are provided.
JSONP is supported only in Step 2.
Supported countries
Rapid 3.0 transparent redirect API offers one integration to support payment processing in Australia, New Zealand and the UK, with support for payments in other countries coming soon.
Rapid 3.0 transparent redirect API also supports multi-currency processing provided the merchant account includes this functionality.
Infrastructure
Uptime and security are of paramount importance to eWAY. We use data centres in multiple cities to ensure the continuity of our service, and we have partnered with industry leaders such as Macquarie Telecom and Datapipe to maintain our reputation as the reliable choice in online payment processing.
PCI DSS Compliance
With respect to the PCI DSS 2.0 standard, to remove the eCommerce element of your website from the scope of a PCI DSS audit you must ensure that card data is sent directly from the customer’s browser. At no time should it be captured or processed by the merchant’s server or any other server not compliant with the PCI DSS.
For a security review by our QSA, Stratsec, please see Appendix H.
Available Methods
Rapid 3.0 transparent redirect API supports both regular one-off payments, token payments, Beagle
Rapid 3.0 transparent redirect API supports both regular one-off payments, token payments, Beagle