written by PrimeHammer

Introducing a new GoPay gem for handling payments

Hi everyone, I’m Ondrej and I’m a co-author of GoPay Ruby gem. In this blog post, I’ll tell you how we make our lives easier when handling payments via GoPay REST API.


We’ve been using GoPay service for online payments for a long time.  Later on they introduced their new REST API that was more convenient and modern than their previous SOAP service. However, there was no gem at that time so we created our own private library that worked great.  As the application started to grow bigger we needed to use it at more places so we decided to DRY up the library.

Release it!

Next step was to create a public gem under MIT license so that everyone can use it. The main idea was to wrap inside all necessary logic for generating tokens and make it easy for your startup get it running as soon as possible.


What can you do with the gem?

  • Create a payment
  • Retrieve a payment
  • Cancel a payment
  • Refund a payment
  • Handle recurring payments


The solution is based on Unirest gem, a Lightweight HTTP Request Client Library. Unirest helped us avoid writing raw HTTP Requests and handle error states easily.

Let’s take a look at a few examples.

Create a payment

Before charging the user, we need to create a new payment. This will return a hash including a URL which you can use to pop up payment or redirect the user to the GoPay payment page.

[code language=”ruby”] GoPay::Payment.create payment_data [/code]


payment_data structure is defined in GoPay REST API documentation.

Basic example of payment data:

[code language=”ruby”] { "payer": { "allowed_payment_instruments": ["BANK_ACCOUNT"], "contact": { "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com" } }, "target": { "type": "ACCOUNT", "goid": "8123446711" }, "amount":"1000", "currency":"CZK", "order_number":"001", "order_description":"description001", "callback": { "return_url":"url.for.return", "notification_url":"url.for.notification" }, "lang":"en" } [/code]


Retrieve the Payment

To get a status of the payment you usually use the method below which returns a hash.

[code language=”ruby”] GoPay::Payment.retrieve gopay_id [/code]


Refund of the payment

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

[code language=”ruby”] GoPay::Payment.refund gopay_id, amount [/code]


Cancellation of the recurring payment

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

[code language=”ruby”] GoPay::Payment.void_recurrence gopay_id [/code]

Dealing with errors

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

[code language=”ruby”] begin response = GoPay::Payment.refund(gopay_id, gopay_amount) rescue GoPay::Error => exception log_gopay_error exception end [/code]


I believe we created a really handy gem that saves you a lot of time dealing with the new GoPay API. However, there are still a few features that need to be added so everyone is welcome to create a pull request in our GoPay Ruby repository where you can find details about installation and configuration.

Also, I would like to thank David Hrachovy, co-author of GoPay gem, for his help.

Leave a Reply

Your email address will not be published. Required fields are marked *