QuickPay::API::Client

The quickpay-ruby-client gem is a official client for QuickPay API. The Quickpay API enables you to accept payments in a secure and reliable manner.

This gem currently support QuickPay v10 api.

Installation

Add to your Gemfile

gem"quickpay-ruby-client"

or install from Rubygems:

$ gem install quickpay-ruby-client

It is currently tested with Ruby ( >= 2.6.x)

• MRI
• Rubinius (2.0)

Usage

Before doing anything you should register yourself with QuickPay and get access credentials. If you haven't please click here to apply.

Create a new API client

First you should create a client instance that is anonymous or authorized with your API key or login credentials provided by QuickPay.

To initialise an anonymous client:

require"quickpay/api/client"client=QuickPay::API::Client.new

To initialise a client with QuickPay API Key:

require"quickpay/api/client"client=QuickPay::API::Client.new(password: ENV["QUICKPAY_API_KEY"])

Or you can provide login credentials like:

require"quickpay/api/client"client=QuickPay::API::Client.new(username: ENV["QUICKPAY_LOGIN"],password: ENV["QUICKPAY_PASSWORD"])

You can also set some connection specific options (default values shown):

client=QuickPay::API::Client.new(options: {read_timeout: 60,write_timeout: 60,connect_timeout: 60,json_opts: {symbolize_names: false}})

Sending request

You can afterwards call any method described in QuickPay API with corresponding http method and endpoint. These methods are supported currently: get, post, put, patch, delete and head.

Any request will return an array in the form [body, status, headers]:

# Shortest form when interested in the response body onlybody,=client.get("/ping")putsbody.inspect# Get all response informationbody,status,headers=client.get("/ping")putsbody.inspect,status.inspect,headers.inspect

You can also do requests in block form:

client.get("/ping")do |body,status,headers|
putsbody.inspectend

It is even possible to pass the QuickPay::API::Error to the block as the 4th parameter to be able to handle the errors that would have otherwise been raised. This parameter is nil when the response is a success.

# the error is not raised but passed to the block as the fourth parameterclient.get("/ping")do |body,status,headers,error|
caseerrorwhennilbody[:id]whenQuickPay::API::NotFoundnilelseraiseerrorendend# will raise `QuickPay::API::Error::NotFound` since the fourth block param is not definedclient.get("/non-existing-path")do |body,status,headers| doend

If you want raw http response body, you can add :raw => true parameter:

body,status,headers=client.get("/ping",raw: true)ifstatus == 200putsJSON.parse(body).inspectelse# do something elseend

Beyond the endpoint, the client accepts the following options (default values shown):

• body: ""
• headers: {}
• query: {}
• raw: false
• json_opts: nil

Full example:

response,=client.post("/payments/1/capture",body: {amount: 100}.to_json,headers: {"Content-Type"=>"application/json"},query: {"synchronized"=>""},raw: false,json_opts: {symbolize_names: true})

Handling API exceptions

By default (get|post|patch|put|delete) will return JSON parsed body on success (i.e. 2xx response code) otherwise it will raise appropriate error. Your code should handle the errors appropriately. Following error codes are supported currently:

Response status	Error
400	QuickPay::API::BadRequest
401	QuickPay::API::Unauthorized
402	QuickPay::API::PaymentRequired
403	QuickPay::API::Forbidden
404	QuickPay::API::NotFound
405	QuickPay::API::MethodNotAllowed
406	QuickPay::API::NotAcceptable
409	QuickPay::API::Conflict
500	QuickPay::API::ServerError
502	QuickPay::API::BadGateway
503	QuickPay::API::ServiceUnavailable
504	QuickPay::API::GatewayTimeout

All exceptions inherits QuickPay::API::Error, so you can listen for any api error like:

beginclient.post("/payments",body: {currency: "DKK",order_id: "1212"},headers: {"Content-Type"=>"application/json"})rescueQuickPay::API::Error=>eputse.inspectend

Example error object:

#<QuickPay::API::Error::NotFound:
status=404,
body="404 Not Found",
headers={"Server"=>"nginx", "Date"=>"Sun, 21 Mar 2021 09:10:12 GMT", "Connection"=>"keep-alive", "X-Cascade"=>"pass", "Vary"=>"Origin"}
request=#<struct QuickPay::API::Client::Request
method=:post,
path="/payments",
body="{\"currency\":\"DKK\",\"order_id\":\"1212\"}",
headers={"User-Agent"=>"quickpay-ruby-client, v2.0.3", "Accept-Version"=>"v10", "Content-Type"=>"application/json"},
query=nil>>

You can read more about QuickPay API responses at https://learn.quickpay.net/tech-talk/api.

Contributions

To contribute:

1. Write a test that fails
2. Fix test by adding/changing code
3. Add feature or bugfix to changelog in the "Unreleased" section
4. Submit a pull request
5. World is now a better place! :)

Running the specs

$ bundle exec rake test