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
22
 
# 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
  @version = 31

  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



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

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:



167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
 
# File 'lib/eway_rapid/rapid_client.rb', line 167

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, @version, 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:



189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
 
# File 'lib/eway_rapid/rapid_client.rb', line 189

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, @version, 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, @version, 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, @version, 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:



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
92
93
94
95
96
97
98
99
 
# File 'lib/eway_rapid/rapid_client.rb', line 48

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, @version, 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, @version, 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, @version, 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, @version, 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, @version, 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, @version, 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



323
324
325
 
# File 'lib/eway_rapid/rapid_client.rb', line 323

def get_errors
  @list_error || []
end

#get_valid? ⇒ Boolean

Gets the valid status of this Rapid client

Returns:

  • (Boolean) —

    Rapid Client status



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

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:



264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
 
# File 'lib/eway_rapid/rapid_client.rb', line 264

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, @version, 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:



113
114
115
 
# File 'lib/eway_rapid/rapid_client.rb', line 113

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:



122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/eway_rapid/rapid_client.rb', line 122

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:



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

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:



146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
 
# File 'lib/eway_rapid/rapid_client.rb', line 146

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, @version, 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



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

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

  validate_api_param
end

#set_version(version) ⇒ Object

Sets the Rapid API version to use (e.g. 40)

Parameters:

  • version (Integer) —

    eWAY Rapid API version



38
39
40
 
# File 'lib/eway_rapid/rapid_client.rb', line 38

def set_version(version)
  @version = version
end

#settlement_search(search_request) ⇒ SettlementSearchResponse

Performs a search of settlements

Parameters:

  • (SettlementSearch)

Returns:



286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
 
# File 'lib/eway_rapid/rapid_client.rb', line 286

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, @version)
    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:



227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/eway_rapid/rapid_client.rb', line 227

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, @version, 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, @version, 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, @version, 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