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

Transcription

1 Rapid 3.0 Transparent Redirect API Official eway Documentation Version 0.82 Published on 8/08/2013

2 Contents Welcome from eway CEO... 5 Overview... 6 Payment types included... 7 Individual payments... 7 Beagle Alerts (powered by ReD)... 7 Beagle (free) D Secure... 7 Token... 8 Global Endpoint... 8 Beagle Alerts... 9 Rule sets... 9 Customised protection... 9 Beagle Alert types... 9 Beagle Alert Actions Review PreAuth Allow Block Integration and cost Beagle (free) vs Beagle Alerts Beagle (free) Beagle Alerts Who is ReD? Summary for the process of a challenged transaction Supported technologies SOAP REST (POST) HTTP POST RPC JSONP Supported countries Infrastructure PCI DSS Compliance Available Methods Page 1 of 82

3 ProcessPayment TokenPayment CreateTokenCustomer UpdateTokenCustomer Authentication Implementation Step 1: Create an Access Code Live Endpoints Sandbox Endpoints Sample request XML Request field descriptions Response Sample response - XML Response field descriptions Step 2: Customer submits card details direct to eway Sample HTML form JSONP Step 3: Request the results Live Endpoints Sandbox Endpoints Sample request - XML Request field descriptions Sample response Response field descriptions Options Verification Testing Sandbox Creating an API Key Appendix A Process Payment Examples SOAP Create Access Code Get Access Code Result XML Create Access Code Get Access Code Result JSON Create Access Code Page 2 of 82

4 Get Access Code Result Appendix B Token Payment Examples SOAP Create Access Code Get Access Code Result XML Create Access Code Get Access Code Result JSON Create Access Code Get Access Code Result Appendix C Create Token Customer Examples SOAP Create Access Code Get Access Code Result XML Create Access Code Get Access Code Result JSON Create Access Code Get Access Code Result Appendix D Update Token Customer Examples SOAP Create Access Code Get Access Code Result XML Create Access Code Get Access Code Result JSON Create Access Code Get Access Code Result Appendix E JSONP Script Example Available Options Sample Script Appendix F Supporting Diagram Rapid 3.0 transparent redirect API Transaction Flow Appendix G Response Messages Transaction Response Messages Page 3 of 82

5 Beagle (Free) and Beagle Alerts Fraud Response Messages System Response Codes Validation Response Codes Appendix H PCI DSS Compliance Disclaimer Page 4 of 82

6 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 Page 5 of 82

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. Please see Appendix F for a larger version of this diagram. Page 6 of 82

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 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 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. Page 7 of 82

9 Token Global Endpoint 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. 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. Page 8 of 82

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 addresses have been used for a single credit card How many different 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 Deny Challenge When a transaction is accepted, this means that the risk level has been assessed as low. A transaction which has been denied by Beagle alerts has been judged to be high risk. Merchants are able to request or text message notifications so as they are aware of the Denied transactions. 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 or text message notifications so as they are aware of the Challenged transactions. Page 9 of 82

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. Pricing for Beagle Alerts is available on the eway website. Page 10 of 82

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 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 addresses is from a high-risk domain, the IP address is from a high risk country, or for a variety of other reasons. Page 11 of 82

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. If you select Allow, eway will process the transaction and your merchant provider will attempt to Page 12 of 82

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 and set your 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. Page 13 of 82

15 Page 14 of 82

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. Page 15 of 82

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. Page 16 of 82

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. For a security review by our QSA, Stratsec, please see Appendix H. Page 17 of 82

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. Page 18 of 82

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. Page 19 of 82

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 REST (POST) HTTP POST XML JSON RPC XML JSON Page 20 of 82

22 Sandbox Endpoints SOAP REST (POST) HTTP POST XML JSON RPC XML JSON Sample request XML HTTP/1.1 OK Authorization: Basic BDOM0dF1WeYYjUQ5TZzMQEE74Y5Ef2x55YtlOp0ES1yMzQ= Content-Type: text/xml <?xml version="1.0" encoding="utf-8"?> <CreateAccessCodeRequest> <RedirectUrl> <CustomerIP> </CustomerIP> <DeviceID>1234</DeviceID> <Method>ProcessPayment</Method> <Payment> <TotalAmount>1000</TotalAmount> <InvoiceNumber> </InvoiceNumber> <InvoiceDescription>Online Purchase</InvoiceDescription> <InvoiceReference> AA12/1</InvoiceReference> <CurrencyCode>AUD</CurrencyCode> </Payment> <Customer> <TokenCustomerID></TokenCustomerID> <Reference>Test123</Reference> <Title>Mr.</Title> <FirstName>John</FirstName> <LastName>Smith</LastName> <CompanyName>Demo Shop 123</CompanyName> <JobDescription></JobDescription> <Street1>Unit 4</Street1> <Street2>15 Smith St</Street2> <City>Sydney</City> <State>NSW</State> <PostalCode>2000</PostalCode> <Country>au</Country> <Phone> </Phone> <Mobile> </Mobile> <Comments>Customer comments</comments> <Fax> </Fax> <Url> </Customer> <ShippingAddress> <ShippingMethod>NextDay</ShippingMethod> <FirstName>John</FirstName> <LastName>Smith</LastName> Page 21 of 82

23 <Street1>Unit 4</Street1> <Street2>15 Smith St</Street2> <City>Sydney</City> <State>NSW</State> <PostalCode>2000</PostalCode> <Country>au</Country> <Phone> </Phone> <Fax> </Fax> </ShippingAddress> <Items> <LineItem> <SKU> </SKU> <Description>Red Socks</Description> <Quantity>1</Quantity> <UnitCost>909</UnitCost> <Tax>91</Tax> <Total>1000</Total> </LineItem> </Items> <Options> <Option> <Value>fac9f7a7-1aca-44cf-b5a4-6a76d </Value> </Option> <Option> <Value> </Value> </Option> </Options> </CreateAccessCodeRequest> Request field descriptions Field Name Field Type Max Length Data Type Description RedirectUrl 1 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. ** When this field is present along with the Customer Country field, any transaction will be processed using Beagle (free) Page 22 of 82

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 Field Name Field Type Max Length Data Type Description 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. Field Name Field Type Max Length Data Type Description TokenCustomerID 1 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. Page 23 of 82

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 alpha-2 code as defined in the ISO 3166 standard. This field must be lower case. For more information see: iso/country_names_and_code_elements Example: au for Australia O 50 string The customer s address, which must be correctly formatted if present. Phone 2 O 32 string The customer s phone number. Mobile 2 O 32 string The customer s mobile phone number. Comments O 255 string Any comments the merchant wishes to add about the customer. Fax 2 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 Field Name Field Type Max Length Data Type Description 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. Page 24 of 82

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 alpha-2 code as defined in the ISO 3166 standard. This field must be lower case. For more information see: iso/country_names_and_code_elements Example: au for Australia O 50 string The address of the person the order is shipped to, which must be correctly formatted if present. Phone 2 O 32 string The phone number of the person the order is shipped to Fax 2 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: Field Name Field Type Max Length Data Type Description 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 Field types: O Optional Page 25 of 82

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 Value 1 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> <Customer> <TokenCustomerID/> <Reference>Test123</Reference> <Title>Mr.</Title> <FirstName>John</FirstName> <LastName>Smith</LastName> <CompanyName>Demo Shop 123</CompanyName> <JobDescription/> <Street1>Unit 4</Street1> <Street2>15 Smith St</Street2> <City>Sydney</City> <State>NSW</State> <PostalCode>2000</PostalCode> Page 26 of 82

28 <Country>au</Country> <Phone> </Phone> <Mobile> </Mobile> <Comments>Customer comments</comments> <Fax> </Fax> <Url> <CardNumber/> <CardStartMonth/> <CardStartYear/> <CardIssueNumber/> <CardName/> <CardExpiryMonth/> <CardExpiryYear/> </Customer> <Payment> <TotalAmount>1000</TotalAmount> <InvoiceNumber> </InvoiceNumber> <InvoiceDescription>Online Purchase</InvoiceDescription> <InvoiceReference> AA12/1</InvoiceReference> <CurrencyCode>AUD</CurrencyCode> </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. TokenCustomerID 1 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. Values: Mr., Ms., Mrs., Miss, Dr., Sir., Prof. Page 27 of 82

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 alpha-2 code as defined in the ISO 3166 standard. This field must be lower case. For more information see: iso/country_names_and_code_elements Example: au for Australia 50 string The customer s address, which must be correctly formatted if present. Phone 2 32 string The customer s phone number. Mobile 2 32 string The customer s mobile phone number. Comments 255 string Any comments the merchant wishes to add about the customer. Fax 2 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 Only returned if included in the CreateAccessCodeRequest on TokenPayment and UpdateTokenCustomer methods Page 28 of 82

30 2 Accepts 0-9, +, *, (, ) Page 29 of 82

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 * Applies to UK only Page 30 of 82

32 Sample HTML form <form method="post" action="<<placeholder>>"> <input type="hidden" name="eway_accesscode" value="nvt0mwzxn9au43rsirpl..." /> <input type="text" name="eway_cardname" /> <input type="text" name="eway_cardnumber" /> <input type="text" name="eway_cardexpirymonth" /> <input type="text" name="eway_cardexpiryyear" /> <input type="text" name="eway_cardstartmonth" /> <input type="text" name="eway_cardstartyear" /> <input type="text" name="eway_cardissuenumber" /> <input type="text" name="eway_cardcvn" /> <input type="submit" value="process" text="process" /> </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: <script type="text/javascript" src=" 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. See Appendix E for more information. Page 31 of 82

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 REST (GET) HTTP POST XML JSON RPC XML JSON Sandbox Endpoints SOAP REST (GET) HTTP POST XML JSON RPC XML JSON Page 32 of 82

34 Sample request - XML HTTP/1.1 OK Authorization: Basic BDOM0dF1WeYYjUQ5TZzMQEE74Y5Ef2x55YtlOp0ES1yMzQ= Content-Type: text/xml Content-Length: 153 <?xml version="1.0" encoding="utf-8"?> <GetAccessCodeResultRequest> <AccessCode>nvt0mwZXN9aU43rsIRPlve3aNziYqA7VHLT3RurzaEvm</AccessCode> </GetAccessCodeResultRequest> Request field descriptions Field Name Field Type Max Length Data Type Description 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> <GetAccessCodeResultResult> <AccessCode>nvt0mwZXN9aU43rsIRPlve3aNziYqA7VHLT3RurzaEvm</AccessCode> <AuthorisationCode>198333</AuthorisationCode> <ResponseCode>00</ResponseCode> <ResponseMessage>A2000</ResponseMessage> <InvoiceNumber> </InvoiceNumber> <InvoiceReference> AA12/1</InvoiceReference> <TotalAmount>1000</TotalAmount> <TransactionID> </TransactionID> <TransactionStatus>true</TransactionStatus> <TokenCustomerID> </TokenCustomerID> <BeagleScore>10.23</BeagleScore> <Options/> Page 33 of 82

35 <Verification> <CVN>Unchecked</CVN> <Address>Unchecked</Address> < >Unchecked</ > <Mobile>Unchecked</Mobile> <Phone>Unchecked</Phone> </Verification> </GetAccessCodeResultResult> </GetAccessCodeResultResponse> Response field descriptions Field Name Max Length 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 The Options collection passed in the original request will be echoed back in the response here. Page 34 of 82

36 Field Name Max Length 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. Field Name Max Length Data Type Description CVN 10 string The result of the CVN verification. Address 10 string The result of the Address verification. 10 string The result of the 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. b. c. 2) Navigate to Resources > Sandbox/Testing and click on Request Sandbox Note: Skip this step if you already have a Sandbox account Page 35 of 82

37 3) Navigate to the Sandbox using the link below for your country a. b. c. 4) Go to My Account > User Security > Create User and complete the form. Note: You can use the same 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 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=" <soap:body> <CreateAccessCode xmlns=" <request> <RedirectUrl> <CustomerIP> </CustomerIP> <Method>ProcessPayment</Method> <DeviceID>D1234</DeviceID> <Payment> <TotalAmount>1000</TotalAmount> <InvoiceNumber> </InvoiceNumber> <InvoiceDescription>Online Purchase</InvoiceDescription> <InvoiceReference> AA12/1</InvoiceReference> <CurrencyCode>AUD</CurrencyCode> </Payment> <Customer> <Reference>Test123</Reference> <Title>Mr.</Title> <FirstName>John</FirstName> <LastName>Smith</LastName> <CompanyName>eWAY</CompanyName> <JobDescription></JobDescription> <Street1>Unit 4</Street1> <Street2>15 Smith St</Street2> <City>Sydney</City> <State>NSW</State> <PostalCode>2000</PostalCode> <Country>au</Country> < >sales@dummyshop123.com</ > <Phone> </Phone> Page 36 of 82

38 <Mobile> </Mobile> <Comments>Customer comments</comments> <Fax> </Fax> <Url> </Customer> <ShippingAddress> <ShippingMethod>NextDay</ShippingMethod> <FirstName>John</FirstName> <LastName>Smith</LastName> <Street1>Unit 4</Street1> <Street2>15 Smith St</Street2> <City>Sydney</City> <State>NSW</State> <PostalCode>2000</PostalCode> <Country>au</Country> <Phone> </Phone> <Fax> </Fax> </ShippingAddress> <Items> <LineItem> <SKU> </SKU> <Description>Red Socks</Description> <Quantity>1</Quantity> <UnitCost>909</UnitCost> <Tax>91</Tax> <Total>1000</Total> </LineItem> </Items> <Options> <Option> <Value>fac9f7a7-1aca-44cf-b5a4-6a76d </Value> </Option> <Option> <Value> </Value> </Option> </Options> </request> </CreateAccessCode> </soap:body> </soap:envelope> Response <soap:envelope xmlns:soap=" xmlns:xsi=" xmlns:xsd=" <soap:body> <CreateAccessCodeResponse xmlns=" <CreateAccessCodeResult> <AccessCode>F9802xFhUqwnN610e1dg8hf-gyJQxhxJ6QGXJfX7XnijOJuDOo03WVq- IV5eYRT5y703Q3UCJtFkyR64S1OGJ2_4YLNArJ20UmZa5k9hFs_J1XaZAaWZ4lkQG3S1jtx0C3a4M</Acce sscode> <Customer> <TokenCustomerID/> <Reference>Test123</Reference> <Title>Mr.</Title> <FirstName>John</FirstName> <LastName>Smith</LastName> Page 37 of 82