Module: Cardinity

Defined in:
lib/cardinity.rb,
lib/cardinity/utils.rb,
lib/cardinity/version.rb

Defined Under Namespace

Classes: Auth

Constant Summary collapse

DEFAULT_API_BASE = 
'https://api.cardinity.com/v1/'
API_PAYMENTS = 
'payments'
STATUS_PENDING = 
'pending'
STATUS_APPROVED = 
'approved'
STATUS_DECLINED = 
'declined'
TYPE_AUTHORIZATION = 
'authorization'
TYPE_PURCHASE = 
'purchase'
TYPE_ERROR = 
'https://developers.cardinity.com/api/v1/'
CODES_WITH_RESPONSE = 
[200, 201, 202, 400, 401, 402, 405, 500, 503]
VERSION = 
"0.1.2"

Class Method Summary collapse

Class Method Details

.api_base ⇒ Object 



82
83
84
 
# File 'lib/cardinity/utils.rb', line 82

def self.api_base
  @config[:api_base]
end

.check_payment_data(payment) ⇒ Object 



9
10
11
12
13
14
15
16
17
18
19
20
21
 
# File 'lib/cardinity/utils.rb', line 9

def self.check_payment_data(payment)
  payment = payment.dup
  payment_method = payment['payment_method'] || payment[:payment_method]
  if payment_method.nil?
    payment['payment_method'] = 'card'
  end
  amount = payment['amount'] || payment[:amount]
  if amount.is_a?(Numeric)
    payment.delete(:amount)
    payment['amount'] = format('%.2f', amount)
  end
  payment
end

.configure!(options) ⇒ Object

Configure Cardinity. Must be called before other methods.

Parameters:

  • options (Hash)

Options Hash (options):

  • :key (String) —

    API key.

  • :secret (String) —

    API secret.

  • :api_base (String) — default: DEFAULT_API_BASE —

    API base URL.



29
30
31
32
33
34
35
36
 
# File 'lib/cardinity.rb', line 29

def self.configure!(options)
  @config = {
      # key and secret to be supplied from outside
      api_base: DEFAULT_API_BASE
  }
  @config.merge! options
  @auth = Cardinity::Auth.new(@config)
end

.create_payment(payment_hash) ⇒ Hash

Creates a Payment object

Parameters:

  • payment_hash (Hash) —

    Payment data. Keys can be symbols or strings.

Options Hash (payment_hash):

  • :amount (Numeric, String) —

    #0.00. If a string, two decimals are required.

  • :currency (String) —

    Three-letter ISO currency code, e.g. “EUR”.

  • :settle (Boolean) — default: true —

    If false, creates a pre-authorization instead of settling immediately.

  • :country (String) —

    Customer’s billing country as ISO 3166-1 alpha-2 country code, required.

  • :payment_method (String) — default: 'card'
  • :payment_instrument (Hash) —

    Card details:

    • :pan [String] Card number.

    • :exp_year [Integer] 4-digit year.

    • :exp_month [Integer] 2-digit month

    • :cvc [Integer] Card security code.

    • :holder [String] Cardholder’s name, max length 32 characters.

  • :order_id (String, nil) — default: nil
  • :description (String, nil) — default: nil

Returns:

  • (Hash) —

    Updated payment object or an error object.



59
60
61
62
 
# File 'lib/cardinity.rb', line 59

def self.create_payment(payment_hash)
  checked_payment_data = check_payment_data(payment_hash)
  parse post(payments_uri, serialize(checked_payment_data))
end

.create_refund(payment_id, amount:, description: '') ⇒ Hash

Fully or partially refund a payment

Parameters:

  • payment_id (String)
  • amount (Numeric, String) —

    If a string, two decimals are required.

  • description (String) (defaults to: '')

Returns:

  • (Hash) —

    Refund or error object.



98
99
100
101
102
 
# File 'lib/cardinity.rb', line 98

def self.create_refund(payment_id, amount:, description: '')
  amount = format('%.2f', amount) if amount.is_a?(Numeric)
  parse post(refunds_uri(payment_id),
             serialize(amount: amount, description: description))
end

.finalize_payment(payment_id, authorize_hash) ⇒ Hash

Finalizes a Payment

This is necessary for 3D secure payments, when the customer has completed the 3D secure redirects and authorization.

Parameters:

  • payment_id (String)
  • authorize_data (String) —

    PaRes string received from 3D secure.

Returns:

  • (Hash) —

    Payment or error object.



72
73
74
 
# File 'lib/cardinity.rb', line 72

def self.finalize_payment(payment_id, authorize_hash)
  parse patch(payment_uri(payment_id), serialize(authorize_hash))
end

.get(base_url, params = {}) ⇒ Object 



55
56
57
58
59
60
61
 
# File 'lib/cardinity/utils.rb', line 55

def self.get(base_url, params = {})
  uri = URI.parse(base_url)
  uri.query = URI.encode_www_form(params)
  RestClient.get uri.to_s, headers(:get, base_url, params)
rescue RestClient::ExceptionWithResponse => e
  handle_error_response e
end

.handle_error_response(e) ⇒ Object 



47
48
49
50
51
52
53
 
# File 'lib/cardinity/utils.rb', line 47

def self.handle_error_response(e)
  if CODES_WITH_RESPONSE.index e.response.code
    e.response
  else
    raise e
  end
end

.headers(method, uri, params = {}) ⇒ Object 



75
76
77
78
79
80
 
# File 'lib/cardinity/utils.rb', line 75

def self.headers(method, uri, params = {})
  {
      content_type: 'application/json',
      authorization: @auth.sign_request(method, uri, params)
  }
end

.parse(response) ⇒ Object 



39
40
41
 
# File 'lib/cardinity/utils.rb', line 39

def self.parse(response)
  JSON.parse response.body
end

.patch(uri, body) ⇒ Object 



69
70
71
72
73
 
# File 'lib/cardinity/utils.rb', line 69

def self.patch(uri, body)
  RestClient.patch uri, body, headers(:patch, uri)
rescue RestClient::ExceptionWithResponse => e
  handle_error_response e
end

.payment(payment_id) ⇒ Hash

Get the payment information for the given payment ID.

Parameters:

  • payment_id (String)

Returns:

  • (Hash) —

    Payment or error object.



89
90
91
 
# File 'lib/cardinity.rb', line 89

def self.payment(payment_id)
  parse get(payment_uri(payment_id))
end

.payment_uri(payment_id) ⇒ Object 



27
28
29
 
# File 'lib/cardinity/utils.rb', line 27

def self.payment_uri(payment_id)
  "#{api_base}#{API_PAYMENTS}/#{payment_id}"
end

.payments(limit: nil) ⇒ Array<Hash>, Hash

Get list of the last payments. By default, cardinity returns 10 payments. Pass ‘limit` to override.

Parameters:

  • limit (Integer, nil) (defaults to: nil)

Returns:

  • (Array<Hash>, Hash) —

    Payment objects or an error object.



80
81
82
83
84
 
# File 'lib/cardinity.rb', line 80

def self.payments(limit: nil)
  query = {}
  query[:limit] = limit if limit
  parse get(payments_uri, query)
end

.payments_uri ⇒ Object 



23
24
25
 
# File 'lib/cardinity/utils.rb', line 23

def self.payments_uri
  "#{api_base}#{API_PAYMENTS}"
end

.post(uri, body) ⇒ Object 



63
64
65
66
67
 
# File 'lib/cardinity/utils.rb', line 63

def self.post(uri, body)
  RestClient.post uri, body, headers(:post, uri)
rescue RestClient::ExceptionWithResponse => e
  handle_error_response e
end

.refund(payment_id, refund_id) ⇒ Hash

Get the refund for the given payment ID and refund ID.

Parameters:

  • payment_id (String)
  • refund_id (String)

Returns:

  • (Hash) —

    Refund or error object.



115
116
117
 
# File 'lib/cardinity.rb', line 115

def self.refund(payment_id, refund_id)
  parse get(refund_uri(payment_id, refund_id))
end

.refund_uri(payment_id, refund_id) ⇒ Object 



35
36
37
 
# File 'lib/cardinity/utils.rb', line 35

def self.refund_uri(payment_id, refund_id)
  "#{api_base}#{API_PAYMENTS}/#{payment_id}/refunds/#{refund_id}"
end

.refunds(payment_id) ⇒ Array<Hash>, Hash

Get all the refunds for the given payment ID.

Parameters:

  • payment_id (String)

Returns:

  • (Array<Hash>, Hash) —

    Refund objects or an error object.



107
108
109
 
# File 'lib/cardinity.rb', line 107

def self.refunds(payment_id)
  parse get(refunds_uri(payment_id))
end

.refunds_uri(payment_id) ⇒ Object 



31
32
33
 
# File 'lib/cardinity/utils.rb', line 31

def self.refunds_uri(payment_id)
  "#{api_base}#{API_PAYMENTS}/#{payment_id}/refunds"
end

.serialize(data) ⇒ Object 



43
44
45
 
# File 'lib/cardinity/utils.rb', line 43

def self.serialize(data)
  JSON.generate(data)
end