Class: EwayRapid::RapidClient

Inherits:
Object
  • Object
show all
Defined in:
lib/eway_rapid/rapid_client.rb

Overview

This class abstracts the Rapid API 3.1 functions so that it can be consumed by Ruby applications

Author:

  • eWAY

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key, password, rapid_endpoint) ⇒ RapidClient

Returns a new instance of RapidClient.

Parameters:

  • api_key (String) —

    eWAY Rapid API key

  • password (String) —

    eWAY Rapid API password

  • rapid_endpoint (String) —

    eWAY Rapid endpoint - either Sandbox or Production



12
13
14
15
16
17
18
19
20
21
 
# File 'lib/eway_rapid/rapid_client.rb', line 12

def initialize(api_key, password, rapid_endpoint)
  @logger = RapidLogger.logger
  @logger.info "Initiate client with end point: #{rapid_endpoint}" if @logger

  @api_key = api_key
  @password = password
  @rapid_endpoint = rapid_endpoint

  validate_api_param
end

Class Method Details

.user_display_message(code, language = 'en') ⇒ String

Translate an error code to a user friendly message

Parameters:

  • code (String) —

    The code to translate

  • language (String) (defaults to: 'en') —

    The 2 letter code for the language to translate to (only en at this time)

Returns:

  • (String) —

    Error message



301
302
303
 
# File 'lib/eway_rapid/rapid_client.rb', line 301

def self.user_display_message(code, language = 'en')
  find_error_code(code, language.downcase)
end

Instance Method Details

#cancel(refund) ⇒ RefundResponse

Cancel a non-captured transaction (an authorisation)

Parameters:

Returns:



159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/eway_rapid/rapid_client.rb', line 159

def cancel(refund)
  unless @is_valid
    return make_response_with_exception(Exceptions::APIKeyInvalidException.new('API key, password or Rapid endpoint missing or invalid'), RefundResponse)
  end
  begin
    url = @web_url + Constants::CANCEL_AUTHORISATION_METHOD

    request = Message::RefundProcess::CancelAuthorisationMsgProcess.create_request(refund)
    response = Message::RefundProcess::CancelAuthorisationMsgProcess.send_request(url, @api_key, @password, request)
    Message::RefundProcess::CancelAuthorisationMsgProcess.make_result(response)
  rescue => e
    @logger.error(e.to_s) if @logger
    make_response_with_exception(e, RefundResponse)
  end
end

#create_customer(payment_method, customer) ⇒ CreateCustomerResponse

Creates a token customer to store card details in the secure eWAY Vault for charging later

Parameters:

  • payment_method (Enums::PaymentMethod) —

    Describes where the card details will be coming from for this transaction (Direct, Responsive Shared, Transparent Redirect etc).

  • customer (Models::Customer) —

    The customer’s details

Returns:



181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
 
# File 'lib/eway_rapid/rapid_client.rb', line 181

def create_customer(payment_method, customer)
  unless get_valid?
    return make_response_with_exception(Exceptions::APIKeyInvalidException.new('API key, password or Rapid endpoint missing or invalid'), CreateCustomerResponse)
  end
  begin
    case payment_method
    when Enums::PaymentMethod::DIRECT
      url = @web_url + Constants::DIRECT_PAYMENT_METHOD_NAME + Constants::JSON_SUFFIX

      request = Message::CustomerProcess::CustDirectPaymentMsgProcess.create_request(customer)
      response = Message::CustomerProcess::CustDirectPaymentMsgProcess.send_request(url, @api_key, @password, request)
      Message::CustomerProcess::CustDirectPaymentMsgProcess.make_result(response)
    when Enums::PaymentMethod::RESPONSIVE_SHARED
      url = @web_url + Constants::RESPONSIVE_SHARED_METHOD_NAME + Constants::JSON_SUFFIX

      request = Message::CustomerProcess::CustResponsiveSharedMsgProcess.create_request(customer)
      response = Message::CustomerProcess::CustResponsiveSharedMsgProcess.send_request(url, @api_key, @password, request)
      Message::CustomerProcess::CustResponsiveSharedMsgProcess.make_result(response)
    when Enums::PaymentMethod::TRANSPARENT_REDIRECT
      url = @web_url + Constants::TRANSPARENT_REDIRECT_METHOD_NAME + Constants::JSON_SUFFIX

      request = Message::CustomerProcess::CustTransparentRedirectMsgProcess.create_request(customer)
      response = Message::CustomerProcess::CustTransparentRedirectMsgProcess.send_request(url, @api_key, @password, request)
      Message::CustomerProcess::CustTransparentRedirectMsgProcess.make_result(response)
    else
      make_response_with_exception(Exceptions::ParameterInvalidException.new('Unsupported payment type'), CreateCustomerResponse)
    end
  rescue => e
    @logger.error(e.to_s) if @logger
    make_response_with_exception(e, CreateCustomerResponse)
  end
end

#create_transaction(payment_method, transaction) ⇒ CreateTransactionResponse

Creates a transaction either using an authorisation, the responsive shared page, transparent redirect, or direct as the source of funds

Parameters:

  • payment_method (Enums::PaymentMethod) —

    Describes where the card details will be coming from for this transaction (Direct, Responsive Shared, Transparent Redirect etc)

  • transaction (Models::Transaction) —

    Request containing the transaction details

Returns:



40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/eway_rapid/rapid_client.rb', line 40

def create_transaction(payment_method, transaction)
  unless get_valid?
    return make_response_with_exception(Exceptions::APIKeyInvalidException.new('API key, password or Rapid endpoint missing or invalid'), CreateTransactionResponse)
  end
  begin
    case payment_method
    when Enums::PaymentMethod::DIRECT
      url = @web_url + Constants::DIRECT_PAYMENT_METHOD_NAME + Constants::JSON_SUFFIX

      request = Message::TransactionProcess::TransDirectPaymentMsgProcess.create_request(transaction)
      response = Message::TransactionProcess::TransDirectPaymentMsgProcess.send_request(url, @api_key, @password, request)
      Message::TransactionProcess::TransDirectPaymentMsgProcess.make_result(response)
    when Enums::PaymentMethod::RESPONSIVE_SHARED
      url = @web_url + Constants::RESPONSIVE_SHARED_METHOD_NAME + Constants::JSON_SUFFIX

      request = Message::TransactionProcess::TransResponsiveSharedMsgProcess.create_request(transaction)
      response = Message::TransactionProcess::TransResponsiveSharedMsgProcess.send_request(url, @api_key, @password, request)
      Message::TransactionProcess::TransResponsiveSharedMsgProcess.make_result(response)
    when Enums::PaymentMethod::TRANSPARENT_REDIRECT
      url = @web_url + Constants::TRANSPARENT_REDIRECT_METHOD_NAME + Constants::JSON_SUFFIX

      request = Message::TransactionProcess::TransTransparentRedirectMsgProcess.create_request(transaction)
      response = Message::TransactionProcess::TransTransparentRedirectMsgProcess.send_request(url, @api_key, @password, request)
      Message::TransactionProcess::TransTransparentRedirectMsgProcess.make_result(response)
    when Enums::PaymentMethod::WALLET
      if transaction.capture
        url = @web_url + Constants::DIRECT_PAYMENT_METHOD_NAME + Constants::JSON_SUFFIX

        request = Message::TransactionProcess::TransDirectPaymentMsgProcess.create_request(transaction)
        response = Message::TransactionProcess::TransDirectPaymentMsgProcess.send_request(url, @api_key, @password, request)
        Message::TransactionProcess::TransDirectPaymentMsgProcess.make_result(response)
      else
        url = @web_url + Constants::CAPTURE_PAYMENT_METHOD

        request = Message::TransactionProcess::CapturePaymentMsgProcess.create_request(transaction)
        response = Message::TransactionProcess::CapturePaymentMsgProcess.send_request(url, @api_key, @password, request)
        Message::TransactionProcess::CapturePaymentMsgProcess.make_result(response)
      end
    when Enums::PaymentMethod::AUTHORISATION
      url = @web_url + Constants::CAPTURE_PAYMENT_METHOD

      request = Message::TransactionProcess::CapturePaymentMsgProcess.create_request(transaction)
      response = Message::TransactionProcess::CapturePaymentMsgProcess.send_request(url, @api_key, @password, request)
      Message::TransactionProcess::CapturePaymentMsgProcess.make_result(response)
    else
      make_response_with_exception(Exceptions::ParameterInvalidException.new('Unsupported payment type'), CreateTransactionResponse)
    end
  rescue => e
    @logger.error(e.to_s) if @logger
    make_response_with_exception(e, CreateTransactionResponse)
  end
end

#get_errors ⇒ Object

Returns all errors related to the query request of this client

Returns:

  • List of error codes



315
316
317
 
# File 'lib/eway_rapid/rapid_client.rb', line 315

def get_errors
  @list_error || []
end

#get_valid? ⇒ Boolean

Gets the valid status of this Rapid client

Returns:

  • (Boolean) —

    Rapid Client status



308
309
310
 
# File 'lib/eway_rapid/rapid_client.rb', line 308

def get_valid?
  @is_valid
end

#query_customer(token_customer_id) ⇒ QueryCustomerResponse

Returns the details of a Token Customer. This includes the masked card information for displaying in a UI

Parameters:

  • token_customer_id (Integer) —

    eWAY Token Customer ID to look up.

Returns:



256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
 
# File 'lib/eway_rapid/rapid_client.rb', line 256

def query_customer(token_customer_id)
  @logger.debug('Query customer with id:' + token_customer_id.to_s) if @logger
  unless @is_valid
    return make_response_with_exception(Exceptions::APIKeyInvalidException.new('API key, password or Rapid endpoint missing or invalid'), QueryCustomerResponse)
  end
  begin
    url = @web_url + Constants::DIRECT_CUSTOMER_SEARCH_METHOD + Constants::JSON_SUFFIX
    url = URI.encode(url)

    request = Message::CustomerProcess::QueryCustomerMsgProcess.create_request(token_customer_id.to_s)
    response = Message::CustomerProcess::QueryCustomerMsgProcess.send_request(url, @api_key, @password, request)
    Message::CustomerProcess::QueryCustomerMsgProcess.make_result(response)
  rescue => e
    @logger.error(e.to_s) if @logger
    make_response_with_exception(e, QueryCustomerResponse)
  end
end

#query_transaction_by_access_code(access_code) ⇒ QueryTransactionResponse

Gets transaction details given an access code

Parameters:

  • access_code (String) —

    Access code for the transaction to query

Returns:



105
106
107
 
# File 'lib/eway_rapid/rapid_client.rb', line 105

def query_transaction_by_access_code(access_code)
  query_transaction_with_path(access_code, Constants::TRANSACTION_METHOD)
end

#query_transaction_by_filter(filter) ⇒ QueryTransactionResponse

Query a transaction by one of four properties transaction id, access code, invoice number, invoice reference

Parameters:

Returns:



114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/eway_rapid/rapid_client.rb', line 114

def query_transaction_by_filter(filter)
  index_of_value = filter.calculate_index_of_value
  if index_of_value.nil?
    return make_response_with_exception(Exceptions::APIKeyInvalidException.new('Invalid transaction filter'), QueryTransactionResponse)
  end

  case index_of_value
  when Enums::TransactionFilter::TRANSACTION_ID_INDEX
    query_transaction_by_id(filter.transaction_id.to_s)
  when Enums::TransactionFilter::ACCESS_CODE_INDEX
    query_transaction_by_access_code(filter.access_code)
  when Enums::TransactionFilter::INVOICE_NUMBER_INDEX
    query_transaction_with_path(filter.invoice_number, Constants::TRANSACTION_METHOD + '/' + Constants::TRANSACTION_QUERY_WITH_INVOICE_NUM_METHOD)
  when Enums::TransactionFilter::INVOICE_REFERENCE_INDEX
    query_transaction_with_path(filter.invoice_reference, Constants::TRANSACTION_METHOD + '/' + Constants::TRANSACTION_QUERY_WITH_INVOICE_REF_METHOD)
  else
    make_response_with_exception(Exceptions::APIKeyInvalidException.new('Invalid transaction filter'), QueryTransactionResponse)
  end
end

#query_transaction_by_id(transaction_id) ⇒ QueryTransactionResponse

Gets transaction details given an eWAY Transaction ID

Parameters:

  • transaction_id (Integer) —

    eWAY Transaction ID

Returns:



97
98
99
 
# File 'lib/eway_rapid/rapid_client.rb', line 97

def query_transaction_by_id(transaction_id)
  query_transaction_by_access_code(transaction_id.to_s)
end

#refund(refund) ⇒ RefundResponse

Refunds all or part of a transaction

Parameters:

Returns:



138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/eway_rapid/rapid_client.rb', line 138

def refund(refund)
  unless @is_valid
    return make_response_with_exception(Exceptions::APIKeyInvalidException.new('API key, password or Rapid endpoint missing or invalid'), RefundResponse)
  end

  begin
    url = @web_url + Constants::TRANSACTION_METHOD

    request = Message::RefundProcess::RefundMsgProcess.create_request(refund)
    response = Message::RefundProcess::RefundMsgProcess.send_request(url, @api_key, @password, request)
    Message::RefundProcess::RefundMsgProcess.make_result(response)
  rescue => e
    @logger.error(e.to_s) if @logger
    make_response_with_exception(e, RefundResponse)
  end
end

#set_credentials(api_key, password) ⇒ Object

Changes the API Key and Password the Client is configured to use

Parameters:

  • api_key (String) —

    eWAY Rapid API key

  • password (String) —

    eWAY Rapid API password



27
28
29
30
31
32
 
# File 'lib/eway_rapid/rapid_client.rb', line 27

def set_credentials(api_key, password)
  @api_key = api_key
  @password = password

  validate_api_param
end

#settlement_search(search_request) ⇒ SettlementSearchResponse

Performs a search of settlements

Parameters:

  • (SettlementSearch)

Returns:



278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
 
# File 'lib/eway_rapid/rapid_client.rb', line 278

def settlement_search(search_request)
  unless @is_valid
    return make_response_with_exception(Exceptions::APIKeyInvalidException.new('API key, password or Rapid endpoint missing or invalid'), QueryCustomerResponse)
  end
  begin

    request = Message::TransactionProcess::SettlementSearchMsgProcess.create_request(search_request)
    url = @web_url + Constants::SETTLEMENT_SEARCH_METHOD +  request

    response = Message::TransactionProcess::SettlementSearchMsgProcess.send_request(url, @api_key, @password)
    Message::TransactionProcess::SettlementSearchMsgProcess.make_result(response)

  rescue => e
    @logger.error(e.to_s) if @logger
    make_response_with_exception(e, SettlementSearchResponse)
  end
end

#update_customer(payment_method, customer) ⇒ CreateCustomerResponse

Updates an existing token customer for the merchant in their eWAY account.

Parameters:

  • payment_method (Enums::PaymentMethod) —

    Describes where the card details will be coming from for this transaction (Direct, Responsive Shared, Transparent Redirect etc).

  • customer (Models::Customer) —

    The customer’s details

Returns:



219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
 
# File 'lib/eway_rapid/rapid_client.rb', line 219

def update_customer(payment_method, customer)
  unless get_valid?
    return make_response_with_exception(Exceptions::APIKeyInvalidException.new('API key, password or Rapid endpoint missing or invalid'), CreateCustomerResponse)
  end
  begin
    case payment_method
    when Enums::PaymentMethod::DIRECT
      url = @web_url + Constants::DIRECT_PAYMENT_METHOD_NAME + Constants::JSON_SUFFIX
      request = Message::CustomerProcess::CustDirectUpdateMsgProcess.create_request(customer)
      response = Message::CustomerProcess::CustDirectUpdateMsgProcess.send_request(url, @api_key, @password, request)
      Message::CustomerProcess::CustDirectUpdateMsgProcess.make_result(response)
    when Enums::PaymentMethod::RESPONSIVE_SHARED
      url = @web_url + Constants::RESPONSIVE_SHARED_METHOD_NAME + Constants::JSON_SUFFIX

      request = Message::CustomerProcess::CustResponsiveUpdateMsgProcess.create_request(customer)
      response = Message::CustomerProcess::CustResponsiveUpdateMsgProcess.send_request(url, @api_key, @password, request)
      Message::CustomerProcess::CustResponsiveUpdateMsgProcess.make_result(response)
    when Enums::PaymentMethod::TRANSPARENT_REDIRECT
      url = @web_url + Constants::TRANSPARENT_REDIRECT_METHOD_NAME + Constants::JSON_SUFFIX

      request = Message::CustomerProcess::CustTransparentUpdateMsgProcess.create_request(customer)
      response = Message::CustomerProcess::CustTransparentUpdateMsgProcess.send_request(url, @api_key, @password, request)
      Message::CustomerProcess::CustTransparentUpdateMsgProcess.make_result(response)
    else
      return make_response_with_exception(Exceptions::ParameterInvalidException.new('Unsupported payment type'), CreateCustomerResponse)
    end
  rescue => e
    @logger.error(e.to_s) if @logger
    make_response_with_exception(e, CreateCustomerResponse)
  end
end