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 = 
{
  'ADP' => '020', 'AED' => '784', 'AFA' => '004', 'ALL' => '008', 'AMD' => '051',
  'ANG' => '532', 'AOA' => '973', 'ARS' => '032', 'AUD' => '036', 'AWG' => '533',
  'AZM' => '031', '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',
  '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)



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

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



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

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



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

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.



275
276
277
 
# File 'lib/active_merchant/billing/first_data_gateway.rb', line 275

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

#credit(amount, trans_id = nil) ⇒ Object 



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

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

#endpoint_url ⇒ Object 



279
280
281
 
# File 'lib/active_merchant/billing/first_data_gateway.rb', line 279

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



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

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



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

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



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

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 



283
284
285
286
287
 
# File 'lib/active_merchant/billing/first_data_gateway.rb', line 283

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



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

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



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

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



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

def update_recurring(params = {})
  params = params.reverse_merge(
    :command => :p,
    :amount => 0,
    :currency => default_currency,
    :msg_type => 'SMS',
    :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