Buckaruby

The Buckaruby gem provides a Ruby library for communicating with the Buckaroo Payment Engine 3.0.

• Installation
• Usage
  • Payment methods
  • Get issuers
  • Start transaction
  • Recurrent transaction
  • Refund transaction
  • Cancel transaction
  • Push response
  • Get status
  • Merchant variables
  • Transaction request specification
  • Error handling
• Example
• Development
• Contributing
• License

Add this line to your application's Gemfile:

gem 'buckaruby'

And then execute:

$ bundle

Or install it yourself as:

$ gem install buckaruby

Create the gateway and configure it using your Buckaroo website key and secret key:

gateway = Buckaruby::Gateway.new(
  website: "123456789",       # website key
  secret: "abcdef1234567890"  # secret key for digital signing
)

As hashing method for the digital signature, Buckaruby uses SHA-1 by default. You can change this to SHA-256 or SHA-512 by setting the parameter hash_method when creating the gateway:

gateway = Buckaruby::Gateway.new(
  website: "123456789",
  secret: "abcdef1234567890",
  hash_method: :sha512        # hash method for the digital signature (:sha1, :sha256 or :sha512)
)

The gateway is created for the live environment by default. If you want to use the testing environment, then add test: true:

gateway = Buckaruby::Gateway.new(
  website: "123456789",
  secret: "abcdef1234567890",
  test: true                  # use the testing environment; default is false
)

To retrieve the payment methods enabled in Buckaroo and supported by this library, you can use the method payment_methods. This method will return an array with all payment methods that can be used. See also Buckaruby::PaymentMethod for predefined constants.

payment_methods = gateway.payment_methods

When using iDEAL as payment method, it is mandatory to send the issuer parameter in the start transaction request. You can retrieve the list of available issuers with the method issuers. This will return a hash with the ID of the issuer (hash key) and the issuer name (hash value).

issuers = gateway.issuers(Buckaruby::PaymentMethod::IDEAL)

To start a new transaction, use the method setup_transaction:

options = {
  amount: 10,
  payment_method: Buckaruby::PaymentMethod::IDEAL,
  issuer: "INGBNL2A",
  invoicenumber: "12345",
  return_url: "http://www.return.url/"
}

response = gateway.setup_transaction(options)

The response includes a status to check if the transaction was successful and a redirect_url which you can use to redirect the user to when present.

See Buckaruby::SetupTransactionResponse for more details.

Recurrent transactions are supported for all credit cards, PayPal and SEPA Direct Debit.

You first need to execute a normal transaction, with the parameter recurring set to true.

options = {
  amount: 10,
  payment_method: Buckaruby::PaymentMethod::PAYPAL,
  invoicenumber: "12345",
  return_url: "http://www.return.url/",
  recurring: true
}

response = gateway.setup_transaction(options)

transaction = response.transaction_id  # use this for the recurrent transaction

The response will include a transaction_id which you must use to make a recurrent transaction:

options = {
  amount: 10,
  payment_method: Buckaruby::PaymentMethod::PAYPAL,
  invoicenumber: "12345",
  transaction_id: "abcdefg"
}

response = gateway.recurrent_transaction(options)

The response includes a status to check if the transaction was successful.

See Buckaruby::RecurrentTransactionResponse for more details.

For some transactions it's possible to do a refund: Buckaroo creates a new "reverse" transaction based on the original transaction.

First check if the transaction is refundable, with the parameter transaction_id set to the original transaction ID:

response = gateway.refundable_transaction?(transaction_id: "abcdefg")

If the reponse is positive then you can refund the transaction with:

response = gateway.refund_transaction(transaction_id: "abcdefg")

The response includes a status to check if the refund was successful.

If you try to refund a transaction that's not refundable, then a Buckaruby::NonRefundableTransactionException will be raised.

See Buckaruby::RefundTransactionResponse for more details.

Sometimes a transaction can be cancelled, for example a SEPA Direct Debit transaction before it has been offered to the bank.

You can check if the transaction is cancellable, by using the method cancellable_transaction? with the parameter transaction_id:

response = gateway.cancellable_transaction?(transaction_id: "abcdefg")

If the response is positive then you can cancel the transaction with:

response = gateway.cancel_transaction(transaction_id: "abcdefg")

If this does not result in an exception, then the cancel was successful.

If you try to cancel a transaction that's not cancellable, then a Buckaruby::NonCancellableTransactionException will be raised.

Buckaroo can be configured to send push notifications for transactions. You can use the method parse_push to verify and parse the push response:

response = gateway.parse_push(params)

This method can also be used to parse the post data on the return page.

See Buckaruby::PushResponse for more details.

To query the status of any transaction, use the method status with either the parameter transaction_id or payment_id:

response = gateway.status(transaction_id: 12345)

See Buckaruby::StatusResponse for more details.

You can send custom variables and additional variables with each request.

Use the parameter custom to build a hash with custom variables and additional for building a hash with additional variabeles. For example:

options = {
  amount: 10,
  payment_method: Buckaruby::PaymentMethod::IDEAL,
  issuer: "INGBNL2A",
  invoicenumber: "12345",
  return_url: "http://www.return.url/",
  custom: {
    foo: "bar",
    quux: "42"
  },
  additional: {
    myreference: "12345"
  }
}

response = gateway.setup_transaction(options)

In the response, you can retrieve the custom and additional variables with the methods custom and additional:

puts response.custom[:foo]
puts response.additional[:myreference]

To retrieve a specification about what needs to be sent with transaction request, you can use the method specify_transaction. The parameter payment_method is optional. When supplied it will only send the specification for that payment method.

This request is also used by the payment_methods method to determine which services (payment methods) are enabled in Buckaroo.

response = gateway.specify_transaction(payment_method: Buckaruby::PaymentMethod::IDEAL)

See Buckaruby::TransactionSpecificationResponse for more details.

When missing or invalid parameters are passed to any method, an ArgumentError will be raised.

When a request to Buckaroo fails because of connection problems, a Buckaruby::ConnectionException will be raised.

When Buckaroo returns an invalid response (status code is not 2xx), a Buckaruby::InvalidResponseException will be raised.

When an API call to Buckaroo results in a "Fail" returned, a Buckaruby::ApiException will be raised.

When the signature could not be verified, a Buckaruby::SignatureException will be raised.

All Buckaruby exceptions listed here inherit from the class Buckaruby::BuckarooException.

For a complete and working example project check out Buckaruby PoC.

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

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/KentaaNL/buckaruby.

The gem is available as open source under the terms of the MIT License.