Ruby SDK

Getting Started

Installation

The easiest way to add the eWAY Ruby SDK to your project is using RubyGems and Bundler – it will add the eWAY Rapid Ruby Gem along with its required dependencies.

To add the eWAY Rapid Ruby Gem, in your project’s Gemfile add the following line:

1
gem 'eway_rapid'

And then execute the following on the command line:

1
bundle

Or you can install it globally by running the following on the command line:

1
gem install eway_rapid

To make development and testing with eWAY easy, get a free partner account which provides access to the eWAY Sandbox.

Now you are all set to build your eWAY integration! You can find code samples for integrating various eWAY functions as part of the eWAY Rapid API reference.

Example Integration

To demonstrate using the eWAY Ruby Gem, this example will show how to accept a payment with the Responsive Shared Page.  This example assumes that Ruby, RubyGems and Bundler are already installed. Only the eWAY specific code is shown so it can be added to your preferred framework.

1. Add the eWAY Ruby Gem
In the project’s Gemfile, add the Ruby Gem:
1
gem 'eway_rapid'
Then on the command line execute:
1
bundle
to install the Gem and its dependencies.
2. Load the eWAY Client
With the eWAY Ruby Gem installed, the next step is to add the eWAY integration to your project. To start, generate an instance of the eWAY Client which interacts with eWAY’s Rapid API. It needs an eWAY Rapid API Key & password, along with the endpoint to connect to (either ‘Production’ or ‘Sandbox’):
1
2
3
4
5
6
7
require 'eway_rapid'

api_key = '60CF3Ce97nRS1Z1Wp5m9kMmzHHEh8Rkuj31QCtVxjPWGYA9FymyqsK0Enm1P6mHJf0THbR'
password = 'API-P4ss'
endpoint = 'Sandbox'

client = EwayRapid::RapidClient.new(api_key, password, endpoint)
3. Create a Shared Payment URL

In order to send a customer to the Responsive Shared Page, a URL must be generated using the

1
create_transaction

function. This accepts a PaymentMethod and a transaction object.

The PaymentMethod determines how the card data will be accepted (in this case RESPONSIVE_SHARED) while the Transaction object contains customer and invoice details – more details of the variables that can be passed can be found in the Rapid API reference.

This step would usually take place after collecting the customer’s information in a checkout process. For this example, just some dummy data will be used:

1
2
3
4
5
6
7
8
9
transaction = EwayRapid::Models::Transaction.new
payment_details = EwayRapid::Models::PaymentDetails.new
payment_details.total_amount = 1000
transaction.payment_details = payment_details
transaction.redirect_url = 'http://www.eway.com.au'
transaction.cancel_url = 'http://www.eway.com.au'
transaction.transaction_type = EwayRapid::Enums::TransactionType::PURCHASE

response = client.create_transaction(EwayRapid::Enums::PaymentMethod::RESPONSIVE_SHARED, transaction)
To make sure everything went well, check the errors array is empty. If it isn’t,
1
user_display_message
can be used to convert any error codes to human readable messages:
1
2
3
if !response.errors.empty?
response.errors.each { |e| puts "Error message: "+ EwayRapid::RapidClient.user_display_message(e) }
end
4. ​Redirect the Customer


​Once the shared page URL has been created, the customer can be redirected. How this is done will depend on the project and framework being used. For example, if using Ruby on Rails, the method would be:

1
redirect_to response.shared_payment_url

So now a Responsive Shared Page URL has been created and the customer is redirected to complete their payment.

5. ​​Fetch the Result

Once the customer has gone to the Responsive Shared Page and submitted their payment information, they will be redirected back to the RedirectUrl specified in the request. This page should use the AccessCode (passed as a query variable) to fetch the result of the transaction.

1
2
response =
client.query_transaction_by_access_code(params[:AccessCode])

Key information such as the success of the transaction and the transaction ID can be found in the transactionStatus of the response. If the transaction wasn’t successful, the reason can be found in the ResponseMessage. An example of handling this information would be:

1
2
3
4
5
if response.transaction_status.status?
puts "Payment successful! ID: #{response.transaction_status.transaction_id.to_s}"
else
puts "Failed! Message #{response.transaction_status.processing_details.response_message}"
end

That’s it – a complete Responsive Shared Page integration!

For more information on the functions available in the eWAY ​Ruby Gem, check out the eWAY Rapid API Reference.

Image: The Ruby logo is Copyright © 2006, Yukihiro Matsumoto.

Become an eWAY merchant today.

With 24/7 support, over 250 integrations and 20+ years experience – the team at eWAY are here to provide you with the leading all-in-one payments solution.