Rapid 3.0 Transparent Redirect API. Official eway Documentation. Version 0.82

(1)

Rapid 3.0 Transparent

Redirect API

Official eWAY Documentation

Version 0.82

(2)

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

(7)

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.

(8)

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.

(9)

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.

(10)

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 address

Customised 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.

(11)

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.

(12)

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.

(13)

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.

(14)

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.

(15)

(16)

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.

(17)

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.

(18)

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.

(19)

Available Methods

Rapid 3.0 transparent redirect API supports both regular one-off payments, token payments, Beagle and Beagle Alerts. Additionally, merchants can create or update their token customers through Rapid 3.0 transparent redirect API by sending the appropriate value in the initial request.

ProcessPayment

This method allows merchants to process payments in such a way that the customer remains on the merchant’s website at all times while processing occurs behind the scenes.

TokenPayment

This method allows merchants to process payments using token customers they have stored with eWAY. Merchants can either load an existing token customer by passing in their TokenCustomerID in the initial request, or create a new token customer by leaving the TokenCustomerID field blank. Any values passed in the Customer part of the initial request will be used to either create or update the token customer, depending on the TokenCustomerID value.

When loading an existing token customer, the customer’s details will be returned by eWAY, including the masked credit card details. The masked card can be sent back to eWAY when the payment is processed if the customer wants to process the payment using the card on file.

CreateTokenCustomer

This method allows merchants to create token customers without processing a payment. This is a two-step process, requiring the customer’s details in the initial request, and then the card details in the form POST.

This allows merchants to create new token customers without having to process card data themselves.

UpdateTokenCustomer

This method allows merchants to update existing token customers without processing a payment. Similar to the CreateTokenCustomer method, this is a two-step process with the customer’s details in the initial request, and then the card details in the form POST.

(20)

Authentication

All requests, other than form POSTs (see Step 2: Customer submits card details direct to eWAY), should be sent using basic authentication. This requires passing the “Authorization” HTTP header in the following format:

Authorization: Basic BDOM0dF1WeYYjUQ5TZzMQEE74Y5Ef2x55YtlOp0ES1yMzQ=

In the above example, the string BDOM0dF1WeYYjUQ5TZzMQEE74Y5Ef2x55YtlOp0ES1yMzQ= represents the API Key and password separated by the colon character and then Base64-encoded. User API Keys can be found in MYeWAY.

(21)

Implementation

Card data must be submitted directly from the customer’s browser to eWAY. At no stage should it be captured or processed by the merchant’s web server or any other third party server that is not PCI DSS compliant.

There are a number of different endpoints available for each step in the process. Which one to use depends on the technology being used to call Rapid 3.0 transparent redirect API.

Step 1: Create an Access Code

To request an access code, the merchant will make a server-side call to the CreateAccessCode method of Rapid 3.0 transparent redirect API. The service will respond with an access code and return the customer data.

If the request involves an existing Token customer, their details will be returned in the response including the masked credit card number.

If Token Payments are not in use for this transaction, the returned customer data will be an echo of the data in the request.

Live Endpoints

SOAP

https://api.ewaypayments.com/soap.asmx

REST (POST)

https://api.ewaypayments.com/AccessCodes

HTTP POST XML

https://api.ewaypayments.com/CreateAccessCode.xml

JSON

https://api.ewaypayments.com/CreateAccessCode.json

RPC

XML

https://api.ewaypayments.com/xml-rpc

(22)

Sandbox Endpoints

SOAP

https://api.sandbox.ewaypayments.com/soap.asmx

REST (POST)

https://api.sandbox.ewaypayments.com/AccessCodes

HTTP POST XML

https://api.sandbox.ewaypayments.com/CreateAccessCode.xml

JSON

https://api.sandbox.ewaypayments.com/CreateAccessCode.json

RPC

XML

https://api.sandbox.ewaypayments.com/xml-rpc

JSON

https://api.sandbox.ewaypayments.com/json-rpc

Sample request – XML

HTTP/1.1 OK

Authorization: Basic BDOM0dF1WeYYjUQ5TZzMQEE74Y5Ef2x55YtlOp0ES1yMzQ= Content-Type: text/xml

<?xml version="1.0" encoding="utf-8"?> <CreateAccessCodeRequest>

<RedirectUrl>http://www.mysite.com/returnURL</RedirectUrl> <CustomerIP>202.18.50.1</CustomerIP>

<DeviceID>1234</DeviceID> <Method>ProcessPayment</Method> <Payment>

<InvoiceDescription>Online Purchase</InvoiceDescription> <InvoiceReference>19832261-AA12/1</InvoiceReference> <CurrencyCode>AUD</CurrencyCode>

</Payment> <Customer>

<FirstName>John</FirstName> <LastName>Smith</LastName>

<Street2>15 Smith St</Street2> <City>Sydney</City>

<Email>[email protected]</Email> <Phone>1800106565</Phone>

<Comments>Customer comments</Comments> <Fax>1800106565</Fax>

<Url>http://www.dummyshop123.com</Url> </Customer>

<ShippingMethod>NextDay</ShippingMethod> <FirstName>John</FirstName>

(23)

<Street1>Unit 4</Street1> <Street2>15 Smith St</Street2> <City>Sydney</City>

<Email>[email protected]</Email> <Phone>1800106565</Phone> <Fax>1800106565</Fax> </ShippingAddress> <Items> <LineItem> <SKU>123456-99</SKU>

<Description>Red Socks</Description> <Quantity>1</Quantity> <UnitCost>909</UnitCost> <Tax>91</Tax> <Total>1000</Total> </LineItem> </Items> <Options> <Option>

Request field descriptions

Field Name Field Type Max Length Data Type Description

RedirectUrl1 R 512 string The web address the customer is redirected to with the result of the action.

CustomerIP** O 50 string The customer’s IP address.

Method R 20 string The action to perform with this request (see Available Methods for more information)

Values: ProcessPayment, CreateTokenCustomer, UpdateTokenCustomer, TokenPayment

DeviceID O 50 string The identification name/number for the device or application used to process the transaction. Field types: R – Required, O – Optional

1 Note that the eWAY AccessCode is appended as a querystring parameter to the RedirectURL – existing querystring parameters are preserved.

(24)

Payment

This set of fields contains the details of the payment being processed. This section is required when the Method field is set to ProcessPayment or TokenPayment

TotalAmount^ R 10 int The amount of the transaction in the lowest denomination for the currency (e.g. a $27.00 transaction would have a TotalAmount value of ‘2700’).

The value of this field must be 0 for the CreateTokenCustomer and

UpdateTokenCustomer methods

InvoiceNumber O 16 string The merchant’s invoice number for this transaction. InvoiceDescription O 64 string A description of the purchase that the customer is

making.

InvoiceReference O 50 string The merchant’s reference number for this transaction.

CurrencyCode O 3 string The 3 character code that represents the currency that this transaction is to be processed in. If no value for this field is provided, the merchant’s default currency is used. This should be in uppercase. Field types: R – Required, C – Conditionally Required, O – Optional

^ This field is required when the Action is ProcessPayment or TokenPayment

Customer

This set of fields contains the details of the merchant’s customer. These are used when creating and updating token customers.

TokenCustomerID1 C 16 long An eWAY-issued ID that represents the Token customer to be loaded for this action.

Reference O 50 string The merchant’s reference for this customer. Title† C 5 string The customer’s title. Empty string allowed.

Values: Mr., Ms., Mrs., Miss, Dr., Sir., Prof. FirstName† C 50 string The customer’s first name.

LastName† C 50 string The customer’s last name. CompanyName O 50 string The customer’s company name. JobDescription O 50 string The customer’s job description / title. Street1 O 50 string The customer’s street address.

(25)

Street2 O 50 string The customer’s street address. City O 50 string The customer’s city / town / suburb. State O 50 string The customer’s state / county PostalCode O 30 string The customer’s post / zip code.

Country†** C 2 string The customer’s country. This should be the two letter ISO 3166-1 alpha-2 code as defined in the ISO 3166 standard. This field must be lower case. For more information see: http://www.iso.org/ iso/country_names_and_code_elements Example: au for Australia

Email O 50 string The customer’s email address, which must be correctly formatted if present.

Phone2 O 32 string The customer’s phone number. Mobile2 O 32 string The customer’s mobile phone number.

Comments O 255 string Any comments the merchant wishes to add about the customer.

Fax2 O 32 string The customer’s fax number.

Url O 512 string The customer’s website, which must be correctly formatted if present.

Field Types: O – Optional, C – Conditionally Required 1 Required for UpdateTokenCustomer method 2 Accepts 0-9, +, * “, (, )

† When creating a new token customer, all conditional fields(†)are required

** When this field is present, along with the customer’s IP address, any transaction will be processed using Beagle

Shipping Address

The ShippingAddress section is optional. It is used by Beagle Alerts to calculate a risk score for this transaction

ShippingMethod O 30 string The method used to ship the customer’s order.

Values: Unknown, LowCost,

DesignatedByCustomer, International, Military, NextDay, StorePickup,

TwoDayService, ThreeDayService, Other FirstName O 50 string The first name of the person the order is shipped to. LastName O 50 string The last name of the person the order is shipped to.

(26)

Street1 O 50 string The street address the order is shipped to. Street2 O 50 string The street address of the shipping location. City O 50 string The city / suburb of the shipping location. State O 50 string The state of the shipping location. PostalCode O 30 string The post code of the shipping location.

Country C 2 string The country of the shipping location. This should be the two letter ISO 3166-1 alpha-2 code as defined in the ISO 3166 standard. This field must be lower case. For more information see: http://www.iso.org/ iso/country_names_and_code_elements

Example: au for Australia

Email O 50 string The email address of the person the order is shipped to, which must be correctly formatted if present.

Phone2 O 32 string The phone number of the person the order is shipped to

Fax2 O 32 string The fax number of the shipping location Field types: O – Optional

2 Accepts 0-9, +, * “, (, )

Items

The Items section is optional. If provided, it should contain a list of line items purchased by the customer, up to a maximum of 99 items. It is used by Beagle Alerts to calculate a risk score for this transaction. LineItems have the following fields:

SKU O 12 string The SKU used to identify this line item Description O 26 string A brief description of the product Quantity O 6 int The purchased quantity.

UnitCost O 8 int The pre-tax cost per unit of the product in the lowest denomination

Tax O 8 int The tax amount that applies to this line item in the lowest denomination

Total O 8 int The total amount charged for this line item in the lowest denomination

(27)

Options

This section is optional. Anything appearing in this section is not displayed to the customer, but it is returned to the merchant in the result. Up to 99 options can be defined. Each option has just one field:

Field Name Field Type Max Length Data Type Description

Value1 O 254 string This field is not displayed to the customer but is returned in the result. Anything can be used here, which can be useful for tracking transactions

Field types: O – Optional

1 Additional characters are truncated at 254

Response

The response received from eWAY will contain the access code that should be used for all further requests associated with this transaction.

The response will also contain the FormActionURL. This is the URL that the form should be posted to in Step 2 of the process.

Depending on the Method being used for this request, some additional information will be returned in the response.

If processing a payment, the response will also include an echo of the payment information submitted in the request.

If using an existing token customer, the customer’s masked card data will be included in the response. This enables existing token customers to elect to pay without having to enter their card details again, with the exception of the CVN, which cannot be stored.

Sample response - XML

<?xml version="1.0" encoding="utf-8" ?> <CreateAccessCodeResponse> <CreateAccessCodeResult> <AccessCode>44DD7iSMqU89PN9t29FiNJTttAJ2s7CEJA8UiBVVRHPVzOdfrkQOhfO5frIZBZgOES4zXEE p59zxtY5mxc3yF4f2btkXgBe0Qy5gAS2UaJHzwIKTUeiCosNPCnAyWdHc7N6xX</AccessCode>

<FormActionURL>https://api.ewaypayments.com/Process</FormActionURL> <Customer>

(28)

<Url>http://www.dummyshop123.com</Url> <CardNumber/> <CardStartMonth/> <CardStartYear/> <CardIssueNumber/> <CardName/> <CardExpiryMonth/> <CardExpiryYear/> </Customer> <Payment> <TotalAmount>1000</TotalAmount> <InvoiceNumber>19832261</InvoiceNumber>

</Payment>

</CreateAccessCodeResult> </CreateAccessCodeResponse>

Response field descriptions

Field Name Max Length

Data Type

Description

AccessCode 512 string A unique access code that is used to identify this transaction with Rapid 3.0 transparent redirect API. This code will need to be present for all future requests associated with this transaction.

FormActionURL 512 string The URL that the form should be POSTed to in Step 2. TotalAmount 10 int The amount of the transaction in cents, as passed in the

original request.

InvoiceNumber 16 string The merchant’s invoice number for this transaction InvoiceDescription 64 string A description of the purchase that the customer is making InvoiceReference 50 string The merchant’s reference number for this transaction CurrencyCode 3 string The 3 character code that represents the currency that this

transaction is to be processed in. If no value for this field is provided, the merchant’s default currency is used.

TokenCustomerID1 16 long The token customer’s unique Token Customer ID Reference 50 string The merchant’s reference for this customer. Title 5 string The customer’s title. Empty string allowed.

(29)

FirstName 50 string The customer’s first name. LastName 50 string The customer’s last name. CompanyName 50 string The customer’s company name. JobDescription 50 string The customer’s job description / title. Street1 50 string The customer’s street address. Street2 50 string The customer’s street address. City 50 string The customer’s city / town / suburb. State 50 string The customer’s state / county PostalCode 50 string The customer’s post / zip code.

Country 2 string The customer’s country. This should be the two letter ISO 3166-1 alpha-2 code as defined in the ISO 3166 standard. This field must be lower case. For more information see:

http://www.iso.org/ iso/country_names_and_code_elements Example: au for Australia

Email 50 string The customer’s email address, which must be correctly formatted if present.

Phone2 32 string The customer’s phone number. Mobile2 32 string The customer’s mobile phone number.

Comments 255 string Any comments the merchant wishes to add about the customer.

Fax2 32 string The customer’s fax number.

Url 512 string The customer’s website, which must be correctly formatted if present.

CardNumber 50 string The token customer’s masked credit card number CardName 50 string The token customer’s card holder name

CardExpiryMonth 2 string The token customer’s card expiry month CardExpiryYear 2 string The token customer’s card expiry year CardStartMonth* 2 string The token customer’s card valid from month CardStartYear* 2 string The token customer’s card valid from year CardIssueNumber* 2 string The token customer’s card issue number * Applies to UK only

1

(30)

(31)

Step 2: Customer submits card details direct to eWAY

Once the merchant receives the access code response, the customer must be redirected to a secure page that contains an HTML form. eWAY will only accept data from forms that use the POST method. Any data posted from a form that has the method attribute set to GET will be rejected.

This request does not require the “Authorization” HTTP header, authentication is instead performed using the Access Code.

The form’s action attribute must be set to the URL returned in the FormActionURL of the response returned in Step 1.

The merchant’s form will need to contain the following input fields:

Field Name Field Type

Description

EWAY_ACCESSCODE R The access code returned in Step 1. The access code is case sensitive.

EWAY_CARDNAME R The name of the card holder.

EWAY_CARDNUMBER R The card number that is to be processed for this transaction.

EWAY_CARDEXPIRYMONTH R The month that the card expires. EWAY_CARDEXPIRYYEAR R The year that the card expires. EWAY_CARDSTARTMONTH* O The month that the card is valid from. EWAY_CARDSTARTYEAR* O The year that the card is valid from. EWAY_CARDISSUENUMBER* O The card’s issue number.

EWAY_CARDCVN R The Card Verification Number. Field Types: R – Required, O – Optional

(32)

Sample HTML form

Once the customer has entered their card details, the form is submitted directly to eWAY. What happens next depends on the Method selected by the merchant in the initial request. For ProcessPayment, the transaction will be sent to the bank network for authorisation. eWAY will then store the outcome of the transaction.

For TokenPayment, the transaction is also sent to the bank network for authorisation. eWAY will then store the outcome of the transaction, and link it to the specified token customer.

For CreateTokenCustomer and UpdateTokenCustomer, eWAY will store the customer’s details. In all cases, the customer’s browser will then be redirected to the URL specified in the RedirectURL field of the initial request.

JSONP

Sometimes it is necessary for merchants to perform certain functions once the customer has submitted the form, but before or after the payment is processed. To allow for this, eWAY has a JSONP library that merchants can reference, which provides a number of callbacks that can be utilised for this purpose.

To utilise JSONP, load the scripts into the page as follows:

Note that even if utilising JSONP, the form’s action attribute still needs to be set to the value of FormActionURL returned in Step 1.

(33)

Step 3: Request the results

Once the customer has been redirected to the next page, the merchant will need to request the results from eWAY by calling the GetAccessCodeResult method of the Rapid 3.0 transparent redirect API web service.

Live Endpoints

SOAP

https://api.ewaypayments.com/soap.asmx

REST (GET)

https://api.ewaypayments.com/AccessCode/{AccessCode}

HTTP POST XML

https://api.ewaypayments.com/GetAccessCodeResult.xml

JSON

https://api.ewaypayments.com/GetAccessCodeResult.json

RPC

XML

https://api.ewaypayments.com/xml-rpc

JSON

https://api.ewaypayments.com/json-rpc

Sandbox Endpoints

SOAP

https://api.sandbox.ewaypayments.com/soap.asmx

REST (GET)

https://api.sandbox.ewaypayments.com/AccessCode/{AccessCode}

HTTP POST XML

https://api.sandbox.ewaypayments.com/GetAccessCodeResult.xml

JSON

https://api.sandbox.ewaypayments.com/GetAccessCodeResult.json

RPC

XML

https://api.sandbox.ewaypayments.com/xml-rpc

(34)

Sample request - XML

HTTP/1.1 OK

Content-Length: 153

<?xml version="1.0" encoding="utf-8"?> <GetAccessCodeResultRequest>

<AccessCode>nvt0mwZXN9aU43rsIRPlve3aNziYqA7VHLT3RurzaEvm</AccessCode> </GetAccessCodeResultRequest>

Request field descriptions

AccessCode R 512 string The Access Code returned in Step 1. Field Types: R – Required

If a transaction has been processed, the response received from eWAY will contain all relevant details such as the bank authorisation code and a unique number that identifies the transaction in eWAY’s database.

If a token customer was involved, the ID that eWAY uses to identify that customer will also be returned.

All responses will contain a response code and response message that represents the result of the action performed. For detailed information about response codes, see Appendix G

If applicable, the response will also contain information about the payment that has been processed, as well as the results of any Beagle risk analysis that was performed.

Sample response

<?xml version="1.0" encoding="utf-8"?> <GetAccessCodeResultResponse>

<AccessCode>nvt0mwZXN9aU43rsIRPlve3aNziYqA7VHLT3RurzaEvm</AccessCode> <AuthorisationCode>198333</AuthorisationCode>

(35)

<CVN>Unchecked</CVN>

<Address>Unchecked</Address> <Email>Unchecked</Email> <Mobile>Unchecked</Mobile> <Phone>Unchecked</Phone> </Verification>

</GetAccessCodeResultResult> </GetAccessCodeResultResponse>

Response field descriptions

Data Type

Description

AccessCode 512 string An echo of the access code used in the request.

AuthorisationCode 6 string The authorisation code for this transaction as returned by the bank.

ResponseCode 2 string The two digit response code returned from the bank. ResponseMessage 512 string A code that describes the result of the action performed.

For more information, see Appendix G

InvoiceNumber 64 string An echo of the merchant’s invoice number for this transaction.

InvoiceReference 64 string An echo of the merchant’s reference number for this transaction.

TotalAmount 10 int The amount that was authorised for this transaction. TransactionID 8 int A unique identifier that represents the transaction in

eWAY’s system.

TransactionStatus boolean A Boolean value that indicates whether the transaction was successful or not.

TokenCustomerID‡ 16 long An eWAY-issued ID that represents the Token customer that was loaded or created for this transaction (if

applicable).

BeagleScore** 6 string Fraud score representing the estimated probability that the order is fraud, based off analysis of past Beagle Free transactions. This field will only be returned for

transactions using the Beagle Free gateway. ** This field is only present if the transaction was processed using Beagle Free

‡ This field is only present if processing a token transaction, creating or updating a token customer

Options

(36)

Data Type

Description

Value 255 string This field is not displayed to the customer but is returned in the result. Anything can be used here, which can be useful for tracking transactions

Field types: O – Optional

Verification

This will contain the results of certain fraud checks that may have been performed. These will be returned regardless of whether the Method requested was a payment method.

For all fields, the available return options are Valid, Invalid or Unchecked.

Data Type

Description

CVN 10 string The result of the CVN verification. Address 10 string The result of the Address verification. Email 10 string The result of the Email verification.

Mobile 10 string The result of the Mobile Phone verification. Phone 10 string The result of the Phone verification. Field types: O – Optional

Testing

Sandbox

Merchants and partners with a sandbox account can test the Rapid 3.0 transparent redirect API functionality at any time by submitting their sandbox user credentials to the service.

The sandbox version of Rapid 3.0 transparent redirect API works exactly the same as the live version, with two exceptions. Instead of submitting the transaction to the banking network, eWAY will generate the result of the transaction based on the merchant’s sandbox settings. The response message will indicate that it was generated by the sandbox.

Transactions created using the sandbox version of Rapid 3.0 transparent redirect API will be available for review in the sandbox MYeWAY account.

Creating an API Key

1) Log in to your partner portal account using the link below for your country a. https://www.eway.com.au/PartnerPortal

b. https://www.eway.co.uk/PartnerPortal

c. https://www.eway.co.nz/PartnerPortal

2) Navigate to Resources > Sandbox/Testing and click on ‘Request Sandbox’ Note: Skip this step if you already have a Sandbox account

(37)

3) Navigate to the Sandbox using the link below for your country a. https://sandbox.myeway.com.au

b. https://sandbox.myeway.co.uk

c. https://sandbox.myeway.co.nz

4) Go to My Account > User Security > Create User and complete the form. Note: You can use the same email address and password as your main Sandbox account.

5) Click on ‘Actions’ next to the new user and ‘View API Key’. This is your new API key and password for accessing Rapid API.

6) Note: In many Rapid 3.0 transparent redirect API modules and sample code the API Key field is named as ‘Username’. You must use your API Key, not your Email address for Rapid 3.0 transparent redirect API.

Appendix A – Process Payment Examples

SOAP 1.1

Create Access Code

Request

Authorization: Basic BDOM0dF1WeYYjUQ5TZzMQEE74Y5Ef2x55YtlOp0ES1yMzQ= Content-Type: text/xml <?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> <soap:Body> <CreateAccessCode xmlns="https://api.ewaypayments.com/"> <request>

<RedirectUrl>http://www.mysite.com/returnURL</RedirectUrl> <CustomerIP>202.18.50.1</CustomerIP>

<Method>ProcessPayment</Method> <DeviceID>D1234</DeviceID> <Payment>

</Payment> <Customer>

<FirstName>John</FirstName> <LastName>Smith</LastName> <CompanyName>eWAY</CompanyName> <JobDescription></JobDescription> <Street1>Unit 4</Street1>

<Street2>15 Smith St</Street2> <City>Sydney</City>

(38)

<Url>http://www.dummyshop123.com</Url> </Customer>

<ShippingMethod>NextDay</ShippingMethod> <FirstName>John</FirstName>

<LastName>Smith</LastName> <Street1>Unit 4</Street1> <Street2>15 Smith St</Street2> <City>Sydney</City>

<Email>[email protected]</Email> <Phone>1800106565</Phone> <Fax>1800106565</Fax> </ShippingAddress> <Items> <LineItem> <SKU>123456-99</SKU>

<Description>Red Socks</Description> <Quantity>1</Quantity> <UnitCost>909</UnitCost> <Tax>91</Tax> <Total>1000</Total> </LineItem> </Items> <Options> <Option>

Response

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Body> <CreateAccessCodeResponse xmlns="https://api.ewaypayments.com/"> <CreateAccessCodeResult> <AccessCode> F9802xFhUqwnN610e1dg8hf-gyJQxhxJ6QGXJfX7XnijOJuDOo03WVq-IV5eYRT5y703Q3UCJtFkyR64S1OGJ2_4YLNArJ20UmZa5k9hFs_J1XaZAaWZ4lkQG3S1jtx0C3a4M</Acce ssCode> <Customer> <TokenCustomerID/>

(39)

<Url>http://www.dummyshop123.com</Url> <CardNumber/> <CardStartMonth/> <CardStartYear/> <CardIssueNumber/> <CardName/> <CardExpiryMonth/> <CardExpiryYear/> </Customer> <Payment> <TotalAmount>1000</TotalAmount> <InvoiceNumber>19832261</InvoiceNumber>

</Payment>

<FormActionURL>https://secure.ewaypayments.com/Process</FormActionURL> </CreateAccessCodeResult>

</CreateAccessCodeResponse> </soap:Body>

</soap:Envelope>

Get Access Code Result

Request

Authorization: Basic BDOM0dF1WeYYjUQ5TZzMQEE74Y5Ef2x55YtlOp0ES1yMzQ= Content-Type: text/xml <?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> <soap:Body> <GetAccessCodeResult xmlns="https://api.ewaypayments.com/"> <request>

<AccessCode>nvt0mwZXN9aU43rsIRPlve3aNziYqA7VHLT3RurzaEvm</AccessCode> </request> </GetAccessCodeResult> </soap:Body> </soap:Envelope>

Response

<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> <soap:Body> <GetAccessCodeResultResponse xmlns="https://api.ewaypayments.com/">

(40)

<Value>fac9f7a7-1aca-44cf-b5a4-6a76d2494403</Value> </Option> <Option> <Value>188573334-99</Value> </Option> </Options> </GetAccessCodeResultResult> </GetAccessCodeResultResponse> </soap:Body> </soap:Envelope>

XML

Create Access Code

Request

<RedirectUrl>http://www.mysite.co.uk/returnURL</RedirectUrl> <Method>ProcessPayment</Method>

<CompanyName>DEMO SHOP 123</CompanyName> <JobDescription>Developer</JobDescription> <Street1>9/10, Oracle Appartment</Street1> <Street2>St Andrew Square</Street2>

<City>Edinburgh</City> <Country>gb</Country>

(41)

<Email>[email protected]</Email> <Phone>0800 080 3777</Phone>

<ShippingMethod>Unknown</ShippingMethod> <FirstName>John</FirstName>

<Street1>9/10, Oracle Appartment</Street1> <Street2>St Andrew Square</Street2>

<City>Edinburgh</City> <Country>gb</Country>

<PostalCode>EH22AF</PostalCode> <Email>[email protected]</Email> <Phone>0800 080 3777</Phone>

</ShippingAddress> <Items>

<Description>Description1</Description> </LineItem>

</Items> <Options> <Option>

<InvoiceDescription>Individual Invoice Description</InvoiceDescription> <InvoiceReference>513456</InvoiceReference>

(42)

Response

<AccessCode>nvt0mwZXN9aU43rsIRPlve3aNziYqA7VHLT3RurzaEvm</AccessCode> <Customer>

<CompanyName>DEMO SHOP 123</CompanyName> <JobDescription>Developer</JobDescription> <Street1>9/10, Oracle Appartment</Street1> <Street2>St Andrew Square</Street2>

<City>Edinburgh</City> <State/>

<Email>[email protected]</Email> <Phone>0800 080 3777</Phone> <Mobile>0800 080 3777</Mobile> <Comments/> <Fax/> <Url/> <CardNumber/> <CardStartMonth/> <CardStartYear/> <CardIssueNumber/> <CardName/> <CardExpiryMonth/> <CardExpiryYear/> </Customer> <Payment> <TotalAmount>100</TotalAmount>

<InvoiceDescription>Individual Invoice Description</InvoiceDescription> <InvoiceReference>513456</InvoiceReference>

<FormActionURL>https://api.ewaypayments.com/Process</FormActionURL> </CreateAccessCodeResponse>

Get Access Code Result

Request

<GetAccessCodeResult

<AccessCode>nvt0mwZXN9aU43rsIRPlve3aNziYqA7VHLT3RurzaEvm</AccessCode> </GetAccessCodeResult>

Response

(43)

JSON

Create Access Code

Request

Authorization: Basic BDOM0dF1WeYYjUQ5TZzMQEE74Y5Ef2x55YtlOp0ES1yMzQ= Content-Type: application/json { "Customer": { "Reference": "A12345", "Title": "Mr.", "FirstName": "John", "LastName": "Smith",

"CompanyName": "Demo Shop 123", "JobDescription": "Developer", "Street1": "Level 5",

"Street2": "369 Queen Street", "City": "Auckland", "State": "", "PostalCode": "1010", "Country": "nz", "Email": "[email protected]", "Phone": "0800 392 947", "Mobile": "0800 392 947" }, "ShippingAddress": { "ShippingMethod": "NextDay",

Rapid 3.0 Transparent Redirect API. Official eway Documentation. Version 0.82