Class: Ideal::Gateway

Inherits:
Object
  • Object
show all
Defined in:
lib/ideal/gateway.rb

Overview

The base class for all iDEAL response classes.

Note that if the iDEAL system is under load it will not allow more then two retries per request.

Constant Summary collapse

LANGUAGE =
'nl'
CURRENCY =
'EUR'
API_VERSION =
'3.3.1'
XML_NAMESPACE =
'http://www.idealdesk.com/ideal/messages/mer-acq/3.3.1'

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Gateway

Initializes a new Gateway instance.

You can optionally specify :sub_id. Defaults to 0.


118
119
120
# File 'lib/ideal/gateway.rb', line 118

def initialize(options = {})
  @sub_id = options[:sub_id] || 0
end

Class Attribute Details

.acquirerObject

Returns the current acquirer used


24
25
26
# File 'lib/ideal/gateway.rb', line 24

def acquirer
  @acquirer
end

.environmentObject

Holds the environment in which the run (default is test)


27
28
29
# File 'lib/ideal/gateway.rb', line 27

def environment
  @environment
end

.live_urlObject

Holds the test and production urls for your iDeal acquirer.


37
38
39
# File 'lib/ideal/gateway.rb', line 37

def live_url
  @live_url
end

.merchant_idObject

Holds the global iDEAL merchant id. Make sure to use a string with leading zeroes if needed.


31
32
33
# File 'lib/ideal/gateway.rb', line 31

def merchant_id
  @merchant_id
end

.passphraseObject

Holds the passphrase that should be used for the merchant private_key.


34
35
36
# File 'lib/ideal/gateway.rb', line 34

def passphrase
  @passphrase
end

.test_urlObject

Holds the test and production urls for your iDeal acquirer.


37
38
39
# File 'lib/ideal/gateway.rb', line 37

def test_url
  @test_url
end

Instance Attribute Details

#sub_idObject (readonly)

Returns the merchant `subID' being used for this Gateway instance. Defaults to 0.


113
114
115
# File 'lib/ideal/gateway.rb', line 113

def sub_id
  @sub_id
end

Class Method Details

.acquirersObject


18
19
20
# File 'lib/ideal/gateway.rb', line 18

def self.acquirers
  Ideal::ACQUIRERS
end

.ideal_certificateObject

Returns the global merchant ideal_certificate.


87
88
89
# File 'lib/ideal/gateway.rb', line 87

def self.ideal_certificate
  @ideal_certificate
end

.ideal_certificate=(certificate_data) ⇒ Object

Instantiates and assings a OpenSSL::X509::Certificate instance with the provided iDEAL certificate data.


82
83
84
# File 'lib/ideal/gateway.rb', line 82

def self.ideal_certificate=(certificate_data)
  @ideal_certificate = OpenSSL::X509::Certificate.new(certificate_data)
end

.ideal_certificate_file=(certificate_file) ⇒ Object

Loads the global merchant ideal_certificate from disk.


76
77
78
# File 'lib/ideal/gateway.rb', line 76

def self.ideal_certificate_file=(certificate_file)
  self.ideal_certificate = File.read(certificate_file)
end

.private_certificateObject

Returns the global merchant private_certificate.


71
72
73
# File 'lib/ideal/gateway.rb', line 71

def self.private_certificate
  @private_certificate
end

.private_certificate=(certificate_data) ⇒ Object

Instantiates and assings a OpenSSL::X509::Certificate instance with the provided private certificate data.


66
67
68
# File 'lib/ideal/gateway.rb', line 66

def self.private_certificate=(certificate_data)
  @private_certificate = OpenSSL::X509::Certificate.new(certificate_data)
end

.private_certificate_file=(certificate_file) ⇒ Object

Loads the global merchant private_certificate from disk.


60
61
62
# File 'lib/ideal/gateway.rb', line 60

def self.private_certificate_file=(certificate_file)
  self.private_certificate = File.read(certificate_file)
end

.private_keyObject

Returns the global merchant private_certificate.


55
56
57
# File 'lib/ideal/gateway.rb', line 55

def self.private_key
  @private_key
end

.private_key=(pkey_data) ⇒ Object

Instantiates and assings a OpenSSL::PKey::RSA instance with the provided private key data.


50
51
52
# File 'lib/ideal/gateway.rb', line 50

def self.private_key=(pkey_data)
  @private_key = OpenSSL::PKey::RSA.new(pkey_data, passphrase)
end

.private_key_file=(pkey_file) ⇒ Object

Loads the global merchant private_key from disk.


44
45
46
# File 'lib/ideal/gateway.rb', line 44

def self.private_key_file=(pkey_file)
  self.private_key = File.read(pkey_file)
end

.test?Boolean

Returns whether we're in test mode or not.

Returns:

  • (Boolean)

92
93
94
# File 'lib/ideal/gateway.rb', line 92

def self.test?
  environment.to_sym == :test
end

Instance Method Details

#capture(transaction_id) ⇒ Object

Sends a acquirer status request for the specified transaction_id and returns an StatusResponse.

It is your responsibility as the merchant to check if the payment has been made until you receive a response with a finished status like: `Success', `Cancelled', `Expired', everything else equals `Open'.

Example

capture_response = gateway.capture(@purchase.transaction_id)
if capture_response.success?
  @purchase.update_attributes!(:paid => true)
  flash[:notice] = "Congratulations, you are now the proud owner of a Dutch windmill!"
end

See the Gateway class description for a more elaborate example.


212
213
214
215
216
217
218
# File 'lib/ideal/gateway.rb', line 212

def capture(transaction_id)
  a = build_status_request(:transaction_id => transaction_id)
  log('REQ', a)
  b = post_data request_url, a, StatusResponse
  log('RES', b)
  b
end

#issuersObject

Sends a directory request to the acquirer and returns an DirectoryResponse. Use DirectoryResponse#list to receive the actuall array of available issuers.

gateway.issuers.list # => [{ :id => '1006', :name => 'ABN AMRO Bank' }, …]

134
135
136
137
138
139
140
141
142
# File 'lib/ideal/gateway.rb', line 134

def issuers
  x = build_directory_request

  a= post_data request_url, x, DirectoryResponse

  log('REQ',x)
  log('RES',a.response)
  a
end

#request_urlObject

Returns the endpoint for the request.

Automatically uses test or live URLs based on the configuration.


125
126
127
# File 'lib/ideal/gateway.rb', line 125

def request_url
  self.class.send("#{self.class.environment}_url")
end

#setup_purchase(money, options) ⇒ Object

Starts a purchase by sending an acquirer transaction request for the specified money amount in EURO cents.

On success returns an TransactionResponse with the #transaction_id which is needed for the capture step. (See capture for an example.)

The iDEAL specification states that it is not allowed to use another window or frame when redirecting the consumer to the issuer. So the entire merchant’s page has to be replaced by the selected issuer’s page.

Options

Note that all options that have a character limit are also checked for diacritical characters. If it does contain diacritical characters, or exceeds the character limit, an ArgumentError is raised.

Required

  • :issuer_id - The :id of an issuer available at the acquirer to which the transaction should be made.

  • :order_id - The order number. Limited to 12 characters.

  • :description - A description of the transaction. Limited to 32 characters.

  • :return_url - A URL on the merchant’s system to which the consumer is redirected after payment. The acquirer will add the following GET variables:

    • trxid - The :order_id.

    • ec - The :entrance_code if it was specified.

Optional

  • :entrance_code - This code is an abitrary token which can be used to identify the transaction besides the :order_id. Limited to 40 characters.

  • :expiration_period - The period of validity of the payment request measured from the receipt by the issuer. The consumer must approve the payment within this period, otherwise the StatusResponse#status will be set to `Expired'. E.g., consider an :expiration_period of `P3DT6H10M':

    • P: relative time designation.

    • 3 days.

    • T: separator.

    • 6 hours.

    • 10 minutes.

Example

transaction_response = gateway.setup_purchase(4321, valid_options)
if transaction_response.success?
  @purchase.update_attributes!(:transaction_id => transaction_response.transaction_id)
  redirect_to transaction_response.service_url
end

See the Gateway class description for a more elaborate example.


188
189
190
191
192
193
194
# File 'lib/ideal/gateway.rb', line 188

def setup_purchase(money, options)
  req = build_transaction_request(money, options)
  log('purchase', req)
  resp = post_data request_url, req, TransactionResponse
  #raise SecurityError, "The message could not be verified" if !resp.verified?
  resp
end