Class: ActiveMerchant::Billing::FirstDataGateway

Inherits:
Gateway
  • Object
show all
Defined in:
lib/active_merchant/billing/first_data_gateway.rb

Defined Under Namespace

Classes: Error

Constant Summary collapse

CURRENCY_CODES =

en.wikipedia.org/wiki/ISO_4217

{
  'ADP' => '020', 'AED' => '784', 'AFA' => '004', 'ALL' => '008', 'AMD' => '051',
  'ANG' => '532', 'AOA' => '973', 'ARS' => '032', 'AUD' => '036', 'AWG' => '533',
  'AZM' => '031', 'AZN' => '944', 'BAM' => '977', 'BBD' => '052', 'BDT' => '050',
  'BGL' => '100', 'BGN' => '975', 'BHD' => '048', 'BIF' => '108', 'BMD' => '060',
  'BND' => '096', 'BOB' => '068', 'BOV' => '984', 'BRL' => '986', 'BSD' => '044',
  'BTN' => '064', 'BWP' => '072', 'BYR' => '974', 'BZD' => '084', 'CAD' => '124',
  'CDF' => '976', 'CHF' => '756', 'CLF' => '990', 'CLP' => '152', 'CNY' => '156',
  'COP' => '170', 'CRC' => '188', 'CUP' => '192', 'CVE' => '132', 'CYP' => '196',
  'CZK' => '203', 'DJF' => '262', 'DKK' => '208', 'DOP' => '214', 'DZD' => '012',
  'ECS' => '218', 'ECV' => '983', 'EEK' => '233', 'EGP' => '818', 'ERN' => '232',
  'ETB' => '230', 'EUR' => '978', 'FJD' => '242', 'FKP' => '238', 'GBP' => '826',
  'GEL' => '981', 'GHC' => '288', 'GIP' => '292', 'GMD' => '270', 'GNF' => '324',
  'GTQ' => '320', 'GWP' => '624', 'GYD' => '328', 'HKD' => '344', 'HNL' => '340',
  'HRK' => '191', 'HTG' => '332', 'HUF' => '348', 'IDR' => '360', 'ILS' => '376',
  'INR' => '356', 'IQD' => '368', 'IRR' => '364', 'ISK' => '352', 'JMD' => '388',
  'JOD' => '400', 'JPY' => '392', 'KES' => '404', 'KGS' => '417', 'KHR' => '116',
  'KMF' => '174', 'KPW' => '408', 'KRW' => '410', 'KWD' => '414', 'KYD' => '136',
  'KZT' => '398', 'LAK' => '418', 'LBP' => '422', 'LKR' => '144', 'LRD' => '430',
  'LSL' => '426', 'LTL' => '440', 'LVL' => '428', 'LYD' => '434', 'MAD' => '504',
  'MDL' => '498', 'MGF' => '450', 'MKD' => '807', 'MMK' => '104', 'MNT' => '496',
  'MOP' => '446', 'MRO' => '478', 'MTL' => '470', 'MUR' => '480', 'MVR' => '462',
  'MWK' => '454', 'MXN' => '484', 'MXV' => '979', 'MYR' => '458', 'MZM' => '508',
  'NAD' => '516', 'NGN' => '566', 'NIO' => '558', 'NOK' => '578', 'NPR' => '524',
  'NZD' => '554', 'OMR' => '512', 'PAB' => '590', 'PEN' => '604', 'PGK' => '598',
  'PHP' => '608', 'PKR' => '586', 'PLN' => '985', 'PYG' => '600', 'QAR' => '634',
  'ROL' => '642', 'RON' => '946', 'RUB' => '643', 'RUR' => '810', 'RWF' => '646',
  'SAR' => '682', 'SBD' => '090', 'SCR' => '690', 'SDD' => '736', 'SEK' => '752',
  'SGD' => '702', 'SHP' => '654', 'SIT' => '705', 'SKK' => '703', 'SLL' => '694',
  'SOS' => '706', 'SRG' => '740', 'STD' => '678', 'SVC' => '222', 'SYP' => '760',
  'SZL' => '748', 'THB' => '764', 'TJS' => '972', 'TMM' => '795', 'TND' => '788',
  'TOP' => '776', 'TPE' => '626', 'TRL' => '792', 'TRY' => '949', 'TTD' => '780',
  'TWD' => '901', 'TZS' => '834', 'UAH' => '980', 'UGX' => '800', 'USD' => '840',
  'UYU' => '858', 'UZS' => '860', 'VEB' => '862', 'VND' => '704', 'VUV' => '548',
  'XAF' => '950', 'XCD' => '951', 'XOF' => '952', 'XPF' => '953', 'YER' => '886',
  'YUM' => '891', 'ZAR' => '710', 'ZMK' => '894', 'ZWD' => '716'
}

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ FirstDataGateway

Creates a new FirstDataGateway

The gateway requires that a valid pem and password be passed in the options hash.

Parameters:

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :pem (String) —

    First Data cert/key (REQUIRED)

  • :pem_password (String) —

    First Data cert password (REQUIRED)



75
76
77
78
79
 
# File 'lib/active_merchant/billing/first_data_gateway.rb', line 75

def initialize(options = {})
  requires!(options, :pem, :pem_password)
  @options = options
  super
end

Instance Method Details

#authorize(amount, params = {}) ⇒ ActiveSupport::HashWithIndifferentAccess

Performs an authorization, which reserves the funds on the customer’s credit card, but does not charge the card.

Registering of DMS authorisation

Parameters:

  • amount (Integer) —

    transaction amount in minor units, mandatory

  • params (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (params):

  • :currency (Integer, String) —

    transaction currency code, mandatory

  • :client_ip_addr (String) —

    client’s IP address, mandatory

  • :description (String) —

    description of transaction, optional

  • :language (String) —

    authorization language identificator, optional

Returns:

  • (ActiveSupport::HashWithIndifferentAccess) —

    TRANSACTION_ID



115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/active_merchant/billing/first_data_gateway.rb', line 115

def authorize(amount, params = {})
  params = params.reverse_merge(
    :command => :a,
    :msg_type => 'DMS',
    :amount => amount,
    :currency => default_currency
  )
  lookup_currency(params)
  requires!(params, :amount, :currency, :client_ip_addr, :msg_type)
  commit(params)
end

#capture(amount, trans_id, params = {}) ⇒ ActiveSupport::HashWithIndifferentAccess

Captures the funds from an authorized transaction.

Making of DMS transaction

Parameters:

  • amount (Integer) —

    transaction amount in minor units, mandatory

  • trans_id (Integer) —

    id of previously made successeful authorisation

  • params (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (params):

  • :currency (Integer, String) —

    transaction currency code, mandatory

  • :client_ip_addr (String) —

    client’s IP address, mandatory

  • :description (String) —

    description of transaction, optional

Returns:

  • (ActiveSupport::HashWithIndifferentAccess) —

    RESULT, RESULT_CODE, RRN, APPROVAL_CODE



138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/active_merchant/billing/first_data_gateway.rb', line 138

def capture(amount, trans_id, params = {})
  params = params.reverse_merge(
    :command => :t,
    :msg_type => 'DMS',
    :trans_id => trans_id,
    :amount => amount,
    :currency => default_currency
  )
  lookup_currency(params)
  requires!(params, :trans_id, :amount, :currency, :client_ip_addr)
  commit(params)
end

#close_day ⇒ Object

Close business day.



273
274
275
 
# File 'lib/active_merchant/billing/first_data_gateway.rb', line 273

def close_day
  commit({ :command => :b })
end

#credit(amount, trans_id = nil) ⇒ Object 



184
185
186
187
 
# File 'lib/active_merchant/billing/first_data_gateway.rb', line 184

def credit(amount, trans_id = nil)
  deprecated CREDIT_DEPRECATION_MESSAGE
  refund(amount, trans_id)
end

#endpoint_url ⇒ Object 



277
278
279
 
# File 'lib/active_merchant/billing/first_data_gateway.rb', line 277

def endpoint_url
  test? ? test_url : live_url
end

#execute_recurring(amount, params = {}) ⇒ ActiveSupport::HashWithIndifferentAccess

Execute subsequent recurring payment

Parameters:

  • amount (Integer) —

    transaction amount in minor units, mandatory (up to 12 digits)

  • params (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (params):

  • :currency (Integer, String) —

    transaction currency code, mandatory

  • :client_ip_addr (String) —

    client’s IP address, mandatory (the same IP address which was provided when registered recurring payment)

  • :description (String) —

    transaction details, mandatory (up to 125 characters)

  • :biller_client_id (String) —

    recurring payment identifier, mandatory (up to 30 characters)

Returns:

  • (ActiveSupport::HashWithIndifferentAccess) —

    TRANSACTION_ID, RESULT, RESULT_CODE, RRN, APPROVAL_CODE



231
232
233
234
235
236
237
238
239
240
 
# File 'lib/active_merchant/billing/first_data_gateway.rb', line 231

def execute_recurring(amount, params = {})
  params = params.reverse_merge(
    :command => :e,
    :amount => amount,
    :currency => default_currency
  )
  lookup_currency(params)
  requires!(params, :amount, :currency, :client_ip_addr, :description, :biller_client_id)
  commit(params)
end

#purchase(amount, params = {}) ⇒ ActiveSupport::HashWithIndifferentAccess

Perform a purchase, which is essentially an authorization and capture in a single operation.

Registering of SMS transaction

Parameters:

  • amount (Integer) —

    transaction amount in minor units, mandatory

  • params (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (params):

  • :currency (Integer, String) —

    transaction currency code, mandatory

  • :client_ip_addr (String) —

    client’s IP address, mandatory

  • :description (String) —

    description of transaction, optional

  • :language (String) —

    authorization language identificator, optional

Returns:

  • (ActiveSupport::HashWithIndifferentAccess) —

    TRANSACTION_ID



92
93
94
95
96
97
98
99
100
101
 
# File 'lib/active_merchant/billing/first_data_gateway.rb', line 92

def purchase(amount, params = {})
  params = params.reverse_merge(
    :command => :v,
    :amount => amount,
    :currency => default_currency
  )
  lookup_currency(params)
  requires!(params, :amount, :currency, :client_ip_addr)
  commit(params)
end

#recurring(amount, params = {}) ⇒ ActiveSupport::HashWithIndifferentAccess

Register new recurring payment along with the first payment

Afterwards when transaction result is requested then result response includes also RECC_PMNT_ID and RECC_PMNT_EXPIRY

Parameters:

  • amount (Integer) —

    transaction amount in minor units, mandatory (up to 12 digits)

  • params (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (params):

  • :currency (Integer, String) —

    transaction currency code, mandatory

  • :client_ip_addr (String) —

    client’s IP address, mandatory

  • :description (String) —

    transaction details, mandatory (up to 125 characters)

  • :biller_client_id (String) —

    recurring payment identifier, mandatory (up to 30 characters)

  • :perspayee_expiry (String) —

    preferred deadline for a Recurring payment, mandatory (MMYY) (system will compare two expiry dates - recurring payment expiry date provided by Merchant and card expiry date provided by Cardholder. In response Merchant will receive back the earliest expiry dates of both). For example, Recurring payment date is 1214 but card expiry date 1213 then Merchant will receive back 1213. First Data system will save the earliest expiry date as Recurring payment expiry date.

  • :perspayee_overwrite (Integer) —

    set to 1 to overwrite existing recurring payment card data together with payment, optional

  • :language (String) —

    authorization language identificator, optional

Returns:

  • (ActiveSupport::HashWithIndifferentAccess) —

    TRANSACTION_ID



208
209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/active_merchant/billing/first_data_gateway.rb', line 208

def recurring(amount, params = {})
  params = params.reverse_merge(
    :command => :z,
    :amount => amount,
    :currency => default_currency,
    :msg_type => 'SMS',
    :perspayee_gen => 1
  )
  lookup_currency(params)
  requires!(params, :amount, :currency, :client_ip_addr, :description, :biller_client_id, :perspayee_expiry)
  commit(params)
end

#redirect_url(trans_id = nil) ⇒ Object 



281
282
283
284
285
 
# File 'lib/active_merchant/billing/first_data_gateway.rb', line 281

def redirect_url(trans_id = nil)
  url = test? ? test_redirect_url : live_redirect_url
  url += "?trans_id=#{CGI.escape trans_id}" if trans_id
  url
end

#refund(amount, trans_id = nil) ⇒ ActiveSupport::HashWithIndifferentAccess

refund() allows you to return money to a card that was previously billed.

Transaction reversal

Parameters:

  • amount (Integer) —

    transaction amount in minor units, mandatory

  • trans_id (Integer) (defaults to: nil) —

    transaction identifier, mandatory

Returns:

  • (ActiveSupport::HashWithIndifferentAccess) —

    RESULT, RESULT_CODE



174
175
176
177
178
179
180
181
182
 
# File 'lib/active_merchant/billing/first_data_gateway.rb', line 174

def refund(amount, trans_id = nil)
  params = {
    :command => :r,
    :trans_id => trans_id,
    :amount => amount
  }
  requires!(params, :command, :trans_id, :amount)
  commit(params)
end

#result(trans_id, params = {}) ⇒ ActiveSupport::HashWithIndifferentAccess

Transaction result

Parameters:

  • trans_id (Integer) —

    transaction identifier, mandatory

  • params (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (params):

  • :client_ip_addr (String) —

    client’s IP address, mandatory

Returns:

  • (ActiveSupport::HashWithIndifferentAccess) —

    RESULT, RESULT_CODE, 3DSECURE, AAV, RRN, APPROVAL_CODE



157
158
159
160
161
162
163
164
 
# File 'lib/active_merchant/billing/first_data_gateway.rb', line 157

def result(trans_id, params = {})
  params = params.reverse_merge(
    :command => :c,
    :trans_id => trans_id
  )
  requires!(params, :trans_id, :client_ip_addr)
  commit(params)
end

#update_recurring(params = {}) ⇒ ActiveSupport::HashWithIndifferentAccess

Overwriting existing recurring payment card data without payment

Afterwards when transaction result is requested then result response includes also RECC_PMNT_ID and RECC_PMNT_EXPIRY

Parameters:

  • params (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (params):

  • :currency (Integer, String) —

    transaction currency code, mandatory

  • :client_ip_addr (String) —

    client’s IP address, mandatory

  • :description (String) —

    transaction details, mandatory (up to 125 characters)

  • :biller_client_id (String) —

    existing recurring payment identifier, mandatory (up to 30 characters)

  • :perspayee_expiry (String) —

    preferred deadline for a Recurring payment, mandatory (MMYY) (system will compare two expiry dates - recurring payment expiry date provided by Merchant and card expiry date provided by Cardholder. In response Merchant will receive back the earliest expiry dates of both). For example, Recurring payment date is 1214 but card expiry date 1213 then Merchant will receive back 1213. First Data system will save the earliest expiry date as Recurring payment expiry date.

  • :language (String) —

    authorization language identificator, optional

Returns:

  • (ActiveSupport::HashWithIndifferentAccess) —

    TRANSACTION_ID



258
259
260
261
262
263
264
265
266
267
268
269
270
 
# File 'lib/active_merchant/billing/first_data_gateway.rb', line 258

def update_recurring(params = {})
  params = params.reverse_merge(
    :command => :p,
    :amount => 0,
    :currency => default_currency,
    :msg_type => 'AUTH',
    :perspayee_gen => 1,
    :perspayee_overwrite => 1
  )
  lookup_currency(params)
  requires!(params, :currency, :client_ip_addr, :description, :biller_client_id, :perspayee_expiry)
  commit(params)
end