gopay-ruby

The GoPay Ruby allows Ruby applications to access to the GoPay REST API.

Benefits

It does authorization under the hood automatically, supports multiple accounts. Easy configuration.

Installation

Add this line to your application's Gemfile:

gem 'gopay-ruby', require: 'gopay'

And then execute:

$ bundle

Or install it yourself as:

$ gem install gopay-ruby

Usage

Gateway

Before creating a payment, use Gateway object to configure your access to GoPay:

gateway = GoPay::Gateway.new(gate: 'https://testgw.gopay.cz', goid: 123, client_id: 456, client_secret: 'xxx')

The values above are just examples. Note that you can use multiple Gateway objects to connect to different accounts. With one Gateway, you can do multiple requests.

Create a Payment

Before charging a user, we need to create a new payment using our gateway object. The method will return a hash including a URL which you can use to popup payment modal or redirect the user to the GoPay payment page.

gateway.create payment_data

payment_data example

{
  "payer":{"allowed_payment_instruments": ["BANK_ACCOUNT"],
            "contact":{"first_name": "John",
                       "last_name": "Doe",
                       "email": "[email protected]"
                      }
          },
  "target":{"type": "ACCOUNT",
            "goid": "8123456789"
           },
  "amount":"1000",
  "currency":"CZK",
  "order_number":"001",
  "order_description":"description001",
  "callback":{"return_url":"url.for.return",
              "notification_url":"url.for.notification"
             },
  "lang":"en"
}

Response example

This is a basic example of response hash, for more complex examples visit GoPay API docs.

{
  "id":3000006529,
  "order_number":"001",
  "state":"CREATED",
  "amount":1000,"currency":"CZK",
  "payer":{"allowed_payment_instruments":["BANK_ACCOUNT"],
           "contact": {"first_name":"John",
                       "last_name":"Doe",
                       "email":"[email protected]",
                      }
          },
  "target":{"type":"ACCOUNT",
            "goid":8123456789
           },
  "additional_params":[{"name":"invoicenumber",
                        "value":"2015001003"
                      }],
  "lang":"en",
  "gw_url":" https://gw.sandbox.gopay.com/gw/v3/bCcvmwTKK5hrJx2aGG8ZnFyBJhAvF"
}

Retrieve the Payment

If you want to return a payment object from GoPay REST API.

gateway.retrieve gopay_id

Refund of the payment

This functionality allows you to refund payment paid by a customer. You can use the refund in two ways. First option is a full refund payment and the other one is a partial refund. Both based on amount parameter.

gateway.refund gopay_id, amount

Cancellation of the recurring payment

The functionality allows you to cancel recurrence of a previously created recurring payment.

gateway.void_recurrence gopay_id

Dealing with errors

Errors are raised as GoPay::Error. The error contains error code error body returned by GoPay API. You can easily catch errors in your models as shown below.

begin
  response = gateway.refund(gopay_id, gopay_amount)
rescue GoPay::Error => exception
  log_gopay_error exception
end

Testing

Use these env variables in .env file:

GOPAY_GATE='https://testgw.gopay.cz'

GOPAY_1_GOID=1111111111
GOPAY_1_CLIENT_ID=1
GOPAY_1_CLIENT_SECRET=x

GOPAY_2_GOID=2222222222
GOPAY_2_CLIENT_ID=2
GOPAY_2_CLIENT_SECRET=x

Then run:

bundle exec rspec

Upgrading

0.4.0

In short, using GoPay class and GoPay::Payment was deprecated.

Using GoPay.configure and GoPay.request is discouraged in favor of Gateway object. Instead of this:

GoPay.configure do |config|
  config.goid = GOPAY_ID
  config.client_id = GOPAY_CLIENT_ID
  config.client_secret = GOPAY_SECRET
  config.return_host = RETURN_HOST_URL
  config.notification_host = NOTIFICATION_HOST_URL
  config.gate = GATE_URL
end

please use Gateway object:

gateway = GoPay::Gateway.new(gate: GATE_URL, goid: GOPAY_ID, client_id: GOPAY_CLIENT_ID, client_secret: GOPAY_SECRET)

return_host and notification_host will be deprecated as well.

Also GoPay::Payment will be deprecated. Instead of this:

GoPay::Payment.retrieve gopay_id

use Gateway for creating payments, retrieval, refunds:

gateway.retrieve gopay_id

Full Documentation

Parameters for all GoPay methods follow the official documentation. For further explanation please visit GoPay API docs.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/PrimeHammer/gopay-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

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