Assist eCommerce Ruby SDK

The Assist Ruby SDK provides Ruby APIs to create, process and manage payments via Assist online payment service provider.

Features

• Creating payments
  • Instance payments
  • Delayed payments
  • Recurring payments
• Receiving status by order number
• Canceling payments

Read the documentation [EN | RU] for more information about Assist's features.

Requirements

• Ruby 1.9 or above
• Bundler

Installation

Add this line to your application's Gemfile:

gem 'assist-ruby-sdk'

And then execute:

$ bundle

Or install it yourself as:

$ gem install assist-ruby-sdk

Usage

Sample Rails application https://github.com/chumakoff/assist-ruby-sample

Configuration

You have to configure Assist before using it.

Assist.setup do |config|
  config.login = "login"
  config.password = "password"
  config.merchant_id = "111111"
  config.mode = :test # or :production
  # Provide secret word in order to activate check value (MD5) verification.
  # Make sure that the secret word is set in merchant's Personal account settings.
  config.secret_word = "secret_word"

  # Payment methods.
  # All payment methods are allowed by default. Specify this option only if you need to limit them.
  #
  # Default:
  # config.payment_methods = {card: true, ym: true, wm: true, qiwi: {mts: true, megafon: true, beeline: true, tele2: true}}
  #
  # Allow payments using credit card and QIWI(Megafon):
  # config.payment_methods = {card: true, wm: false, qiwi: {mts: false, megafon: true}}
  # Methods that are not present in the hash are considered as false.
  #
  # Allow payments using WebMoney and QIWI:
  # config.payment_methods = {wm: true, qiwi: true}
  config.payment_methods = {card: true}

  # The following options are not mandatory. If not specified,
  # merchant's settings in Personal account will be used (options should be enabled)
  config.success_url = "https://example.org/payment/success"
  config.fail_url = "https://example.org/payment/fail"
  # In the case when `success_url` and `fail_url` are the same, specify `return_url` instead.
  # config.return_url = "https://example.org/payment/return"
end

Creating payments

In order to create a payment a user is redirected to the Assist payment page with necessary payment parameters:

# `order_number` - order number in the merchant payment system
# `order_amount` - payment amount,  in original currency
# `extra_params` - hash of any other parameters (default = {}).
url = Assist.payment_url(order_number, order_amount, extra_params)

See "List of the authorized request parameters" in the documentation [EN | RU].

Checking payment status

# `order_number` - order number in the merchant payment system
order_number = 999
order_status = Assist.order_status(order_number)

# with additional parameters
extra_params = {}
order_status = Assist.order_status(order_number, extra_params)

order_status.status     # => "Approved"
order_status.billnumber # => "5775486652369300"

# parameters sent in the HTTP request
order_status.request_params # => {merchant_id: '111111', login: 'login',
                            #     password: 'password', ...}

# response parameters
order_status.result # => [{:ordernumber=>"999", :billnumber=>"5775486652369300",
                    #      :orderamount=>"111.00", :ordercurrency=>"RUB",
                    #      :orderstate=>"Approved", :packetdate=>"28.09.2016 23:32",
                    #      :signature=>nil}]

# raw http response returned from Assist server (in XML format)
order_status.original_response # => #<Net::HTTPOK 200 OK readbody=true>

See "Receiving status by order number" and "OrderState field values" in the documentation for more information.

Canceling payment

billnumber = "5775486652369300" # number of payment in Assist
result = Assist.cancel_order(billnumber)

# with additional parameters
extra_params = {}
result = Assist.cancel_order(billnumber, extra_params)

# parameters sent in the HTTP request
result.request_params # => {merchant_id: '111111', login: 'login',
                      #     password: 'password', ...}

# response parameters
result.result # => {:ordernumber=>"999", :responsecode=>"AS000",
              #     :orderstate=>"Canceled", :orderdate=>"28.09.2016 23:31:00",
              #     :amount=>"111.00", :currency=>"RUB", :billnumber=>"5775486652369300",
              #     ...
              #    }

# raw http response returned from Assist server (in XML format)
result.original_response # => #<Net::HTTPOK 200 OK readbody=true>

Delayed (double-stage) payment

When the double-stage operation mode is used the customer's account is withdrawn only after the payment has been confirmed by the merchant. In order to use this mode you need to send the parameter Delay=1 in the authorization request.

# authorization url
url = Assist.payment_url(order_number, order_amount, delay: 1)

# Confirm order
billnumber = "5775486652369300" # number of payment in Assist
extra_params = {}               # additional parameters
result = Assist.confirm_order(billnumber, extra_params)

# response parameters
result.result # => {:ordernumber=>"999", :responsecode=>"AS000",
              #     :orderstate=>"Approved", :orderdate=>"28.09.2016 23:31:00",
              #     :amount=>"111.00", :currency=>"RUB", :billnumber=>"5775486652369300",
              #     ...
              #    }

API Errors

When Assist API returns failure response, assist-ruby-sdk raises Assist::Exception::APIError containing error description and error codes.

begin
  # Invalid API Request
rescue Assist::Exception::APIError => e
  e.message # => "Assist API error: firstcode=10, secondcode=201
end

See "Codes of automated interfaces" in the documentation for more information about error codes.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/chumakoff/assist-ecommerce-sdk-ruby.

License

The gem is available as open source under the terms of the MIT License.