The Buckaruby gem provides a Ruby library for communicating with the Buckaroo Payment Engine 3.0.
Add this line to your application's Gemfile:
gem 'buckaruby'
And then execute:
$ bundle
Or install it yourself as:
$ gem install buckaruby
Buckaruby provides a global configuration object that allows you to customize logger output and HTTP timeouts. You can set these options via the Buckaruby.configure block:
Buckaruby.configure do |config|
# Set a global logger for Buckaruby output
config.logger = Logger.new($stdout)
# Set Net::HTTP timeout values (in seconds)
config.open_timeout = 30
config.read_timeout = 30
endCreate 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_methodsTo start a new transaction, use the method setup_transaction:
options = {
amount: 10,
payment_method: Buckaruby::PaymentMethod::IDEAL,
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 transactionThe 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,
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.