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.

Problem?

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.

gem_logo_inbox

What can you do with the gem?

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

Dependency

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.


GoPay::Payment.create payment_data

 

payment_data structure is defined in GoPay REST API documentation.

Basic example of payment data:


{
 "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"
}

 

Retrieve the Payment

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


GoPay::Payment.retrieve gopay_id

 

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.


GoPay::Payment.refund gopay_id, amount

 

Cancellation of the recurring payment

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


GoPay::Payment.void_recurrence gopay_id

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.


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

Summary

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.