GNU Taler payment API for Ruby

The Taler library let's you interact with a Taler merchant backend API to take payments.

Installation

gem install taler # or
bundle add taler

Usage

require "taler"

backend_url = "https://backend.demo.taler.net/instances/sandbox"
password = "sandbox"

order = Taler::Order.new(backend_url:, password:)
order.create(
  amount: "KUDOS:4",
  summary: "Order total",
  fulfillment_message: "Thank you!"
)

puts "Pay at: #{order.status_url}"

while order.fetch("order_status") == "unpaid"
  sleep 1
  order.reload
end

if order.fetch("order_status") == "paid"
  puts "Great. All paid."
else
  puts "Sorry, the order is #{order.fetch("order_status")}. Try again."
end

Errors

Every request raises Taler::RequestError when the backend responds with anything but 200 OK. The message includes the backend's explanation, and the error carries the HTTP status and the response body:

begin
  order.create(amount: "KUDOS:4", summary: "Order total")
rescue Taler::RequestError => e
  puts e.message # The Taler backend responded with 401: The merchant refused the request due to lack of authorization.
  puts e.status  # 401
  puts e.body    # {"code" => 2015, "hint" => "...", "detail" => "..."}
rescue Taler::Error => e
  puts e.message # E.g. could not reach destination
  puts e.cause   # A StandardError that was raised during the request, e.g. Errno::ETIMEDOUT
end

Read more in the official documentation:

• https://rubydoc.info/gems/taler

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake to run the tests. You can also run bin/console for an interactive prompt.

Release

• Update the version number in lib/taler/version.rb.
• Update the CHANGELOG.md file.
• Run bundle update.
• Commit.
• Run bundle exec rake release to build, tag and push the gem.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/openfoodfoundation/taler-ruby.