Skip to content


Folders and files

Last commit message
Last commit date

Latest commit



18 Commits

Repository files navigation

Scanpay ruby client

The official Ruby client library for the Scanpay API (docs). You can always e-mail us at, or chat with us on IRC at #scanpay


You need Ruby version >= 2.0 with httpclient. The code is published at rubygems and you can install it with:

gem install scanpay

And include it in your project:

require 'scanpay'
client ='API key')

Manual installation

Download the latest release and include in into your project:

require_relative 'lib/scanpay'
scanpay ='API key')


The API documentation is available here. Most methods accept an optional per-request object with options, here referred to as options.

Create a Scanpay client to start using this library:

scanpay =' APIKEY ')

Payment Link

newURL(Object, options)

Create a link to our hosted payment window (docs | example).

order = {
    'items' => [{ 'total' => '199.99 DKK' }]
puts "Payment url: #{scanpay.newURL(order, options)}"


To know when transactions, charges, subscribers and subscriber renewal succeeds, you need to use the synchronization API. It consists of pings which notify you of changes, and the seq request which allows you to pull changes.

handlePing(String, String)

Handle and validate synchronization pings. The method accepts two arguments, the body of the received ping and the X-Signature HTTP header. The method returns a hash (docs | example).

json = scanpay.handlePing(body, signature)

seq(Integer, options)

Make a sequence request to pull changes after a specified sequence number (docs | example).

localSeq = 921;
seqobj = scanpay.seq(localSeq, options)


capture(Integer, Object, options)

Use Capture to capture a transaction. (docs | example).

transactionId = 5;
data = {
    'total' => '123 DKK',
    'index' => 0,
scanpay.capture(transactionId, data, options)

refund(Integer, Object, options)

Use Refund to refund a captured transaction (docs | example).

transactionId = 5;
data = {
    'total' => '123 DKK',
    'index' => 0,
scanpay.refund(transactionId, data, options)

void(Integer, Object, options)

Use Void to void the amount authorized by the transaction (docs | example).

transactionId = 5;
data = {
    'index' => 0,
scanpay.void(transactionId, data, options)


Create a subscriber by using newURL with a Subscriber parameter (docs | example).

order = {
    'subscriber' => { 'ref' => 'sub123' },
puts "Payment url: #{scanpay.newURL(order, options)}"

charge(Integer, Object, options)

Use charge to charge a subscriber. The subscriber id is obtained with seq (docs | example).

subscriberId = 11;
data = {
    'items' => [{ 'total' => '199.99 DKK' }],
scanpay.charge(subscriberId, data, options)

renew(Integer, Object, options)

Use renew to renew a subscriber, i.e. to attach a new card, if it has expired docs | example).

subscriberId = 11;
data = {
    'successurl' => '',
scanpay.renew(subscriberId, data, options)


All methods, except handlePing, accept an optional per-request options hash. You can use this to:

  • Set the API key for this request (example)
  • Set HTTP headers, e.g. the highly recommended X-Cardholder-IP (example)
  • Change the hostname to use our test environment (example)
  • Enable debugging mode (example)


Everything in this repository is licensed under the MIT license.