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.
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.
[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]
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.