vsafe-ruby

VSafe

Installation

Add this line to your application's Gemfile:

gem 'vsafe-ruby'

And then execute:

$ bundle

Or install it yourself as:

$ gem install vsafe-ruby

Configuration

VSafe.configure do |config|
  config.account_name = "YOUR VESTA ACCOUNT"
  config.password = "YOUR VESTA PASSWORD"
  config.sandbox = true # Sandbox mode, Default to true
  config.request_timeout = 20 # Request timeout, default to 20
end

Config can also be overridden when initializing a request client:

client = VSafe::Client.new do |config|
  config.sandbox = !Rails.env.production?
  config.request_timeout = 3
end

Vesta URLs

All four Vesta URLs can be specified in config:

VSafe.configure do |config|
  config.sandbox_url = 'https://my.sandbox.url/GatewayV4Proxy/Service'
  config.sandbox_jsonp_url = 'https://my.sandboxtoken.url/GatewayV4ProxyJSON/Service'
  config.production_url = 'https://my.production.url/GatewayV4Proxy/Service'
  config.production_jsonp_url = 'https://my.production.url/GatewayV4ProxyJSON/Service'
end

Logging

The logger passed to HTTParty can be specified in config:

VSafe.configure do |config|
  config.logger = Rails.logger
end

Request & Response

First, Setup a client for making request:

client = VSafe::Client.new

Heartbeat request

Check if VSafe API is up or not.

client.heartbeat.success?

Get vesta session tags

Get web session id for WEB charge source.

response = client.get_session_tags # => #<VSafe::Responses::GetSessionTags ...>

# Response attributes
response.org_id
response.web_session_id

Authorize charge

Authorize a credit card charge attempt for later confirm usage.

auth_params = {
  TransactionID: "...",
  ChargeAccountNumberToken: "...",
  ChargeAmount: 10,
  WebSessionID: "100_000000000", # Fingerprint generated by get_session_tags as part of ChargeSource::WEB transaction
  PaymentDescriptor: "...",
  ChargeSource: VSafe::ChargeSource::WEB, # Or VSafe::ChargeSource::PPD/VSafe::ChargeSource::TEL
  RiskInformation: "...", # XML string for the transaction
  IsTempToken: false,
  CardHolderFirstName: "Foo",
  CardHolderLastName: "Bar",
  CardHolderAddressLine1: "...",
  CardHolderAddressLine2: "...",
  CardHolderCity: "...",
  CardHolderRegion: "...",
  CardHolderPostalCode: "...",
  CardHolderCountryCode: "...",
  ChargeCVN: 123, # Card's CVV
  ChargeExpirationMMYY: "1221", # Card's expiration date in MMYY format
  StoreCard: true # Get a permanent token or not
}

response = client.charge_authorize(params) # => #<VSafe::Responses::ChargeAuthorize ...>

# Response attributes
response.avs_result
response.auth_result
response.cvn_result
response.charge_permanent_token
response.payment_acquirer_name
response.payment_id
response.payment_status

Confirm charge

This should coupled with charge_authorize, confirms the previous authorized charge attempt.

auth_response = client.charge_authorize(auth_params)

confirm_params = {
  PaymentID: auth_response.payment_id,
  ChargeAmount: auth_params[:ChargeAmount],
  TransactionID: auth_params[:TransactionID]
}

response = client.charge_confirm(confirm_params) # => #<VSafe::Responses::ChargeConfirm ...>

response.payment_status

Charge sale

Directly charge credit card.

charge_params = {
                  #... Same as authorize charge params
                }

response = client.charge_sale(charge_params) # => #<VSafe::Responses::ChargeSale ...>

# Response attributes
response.avs_result
response.auth_result
response.cvn_result
response.charge_permanent_token
response.payment_acquirer_name
response.payment_id
response.payment_id_pk
response.payment_status

Reverse payment

Reverse a previously charged payment.

params = {
  RefundAmount: 10.0,
  PaymentID: "...", # payment id from charge_confirm or charge_sale
  TransactionID: "..." # transaction id passed-in in charge/auth params
}

response = client.reverse_payment(params) # => #<VSafe::Responses::ReversePayment ...>

# Response attributes
response.available_refund_amount
response.payment_acquirer_name
response.payment_id

Validate Credit card

Check to see if a credit card is valid.

params = {
  TransactionID: "...",
  ChargeAccountNumberToken: "...",
  WebSessionID: "100_000000000", # Fingerprint generated by get_session_tags as part of ChargeSource::WEB transaction
  IsTempToken: true,
  StoreCard: true,
  PaymentDescriptor: "...",
  ChargeSource: VSafe::ChargeSource::WEB,
  CardHolderFirstName: "Foo",
  CardHolderLastName: "Bar",
  CardHolderAddressLine1: "...",
  CardHolderAddressLine2: "...",
  CardHolderCity: "...",
  CardHolderRegion: "...",
  CardHolderPostalCode: "...",
  CardHolderCountryCode: "...",
  ChargeCVN: 123, # Card's CVV
  ChargeExpirationMMYY: "1221", # Card's expiration date in MMYY format
}

response = client.validate_charge_account(params)

response.avs_result
response.auth_result
response.cvn_result
response.charge_permanent_token
response.payment_acquirer_name
response.payment_id
response.payment_status

Get Payment Status

Get the payment status by the partner transaction ID or Vesta Payment ID.

params = {
  PartnerTransactionID: '333c1b85-c5db-4648-a946-ba408582fc1c'
}
response = client.get_payment_status(params) # => #<VSafe::Responses::GetPaymentStatus ...>

# Response attributes
response.amount
response.payment_id
response.payment_status
response.response_code
response.transaction_id

Note: If transaction does not exist on Vesta, result of response.success? will be false.

Contributing

1. Fork it ( https://github.com/[my-github-username]/vsafe-ruby/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request