Docdata

Docdata is a Ruby implementation for using Docdata Payments.

Here you can find the Documentation

This gem relies on the awesome Savon gem to communicate with Docdata Payments' SOAP API.

Add this line to your application's Gemfile:

gem 'docdata'

And then execute:

$ bundle

Or install it yourself as:

$ gem install docdata

Each transaction consists of 2 - optionally 3 - parts:

• Docdata::Shopper (details about the shopper: name, email, etc.)
• Docdata::Payment (details about the payment: currency, gross amount, etc.)
• Docdata::LineItem (optionally list the products of this payment) currently not working!

The general workflow is as follows:

1. Set up a Docdata::Shopper object with the details of your shopper: @shopper = Docdata::Shopper.new
2. Set up a Docdata::Payment object with the details of your order: @payment = Docdata::Payment.new(shopper: @shopper)
3. Call the create method (@payment.create)
4. On success, store the payment key and use @payment.redirect_url to redirect the consumer to the transaction page.
5. When the consumer gets back to your application, use the Docdata::Payment.find("PA1M3NTK3Y").status.paid to check if the order was paid for.

All the payment details that Docdata Payments requires, are - obviously - also required to make payments via this gem.

A quick warning about the default values for the Shopper object: For some payment methods, Docdata Payments needs the actual information in order for the payment to take place.

If you use GIROPAY, SEPA and AFTERPAY this is the case. (Maybe also in other payment methods, please let me know!)

Example usage. Use appropriate settings in development.rb, production.rb etc.

config.docdata.username   = "my_app_com"
config.docdata.password   = "HeJ35N"
config.docdata.return_url = "http://localhost:3000/docdata" # gets appended by '/success', '/error', '/pending' depending on response
config.docdata.test_mode  = true

The example below assumes you have your application set up with a Order model, which contains the information needed for this transaction (amount, name, etc.).

def start_transaction
	# find the order from your database
	@order = Order.find(params[:id])
	
	# initialize a shopper, use details from your order
	shopper = Docdata::Shopper.new(first_name: @order.first_name, last_name: @order.last_name)

	# set up a payment
	@payment = Docdata::Payment.new(
		amount: @order.total, 
		currency: @order.currency, 
		shopper: shopper,
		profile: "My Default Profile",
		order_reference: "order ##{@order.id}"
	)
	
	# create the payment via the docdata api and collect the result
	result = @payment.create

	if result.success?
		# Set the transaction key for future reference
		@order.update_column :docdata_key, result.key
		# redirect the user to the docdata payment page
		redirect_to @payment.redirect_url
	else
		# TODO: Display the error and warn the user that something went wrong.
	end
end

After a payment is completed, Docdata Payments will do two things:

1. Sends a GET request to your 'Update URL' (you can set this in the back office) with an 'id' parameter, containing your order_reference. This allows you to check the status of the transaction, before the user gets redirected back to your website.
2. Redirects the consumer back to the return_url.

def check_transaction
	# find the order from your database
  # https://www.example.com/docdata/update?id=12345
	@order = Order.find_by_order_reference(params[:id])

	# Find this payment via the Docdata API,
	# using the previously set 'docdata_key' attribute.
  payment = Docdata::Payment.find(@order.docdata_key)
  response = payment.status
  if response.paid
    # use your own methods to handle a paid order
    # for example:
    @order.mark_as_paid(response.payment_method)
  else
  	# TODO: create logic to handle failed payments
  end

  # This action doesn't need a view template. It only needs to have a status 200 (OK)
	render :nothing => true, :status => 200, :content_type => 'text/html'
end

For transactions in the Netherlands, iDeal is the most common option. To redirect a user directly to the bank page (skipping the Docdata web menu page), you can ask your user to choose a bank from any of the banks listed in the Docdata::Ideal.banks method.

In Docdata::Payment you can set bank_id to any value. If you do, the redirect URI will redirect your user directly to the bank page.

Example code:

def ideal_checkout
	@order = Order.find(params[:order_id])
	@banks = Docdata::Ideal.banks
end

def start_ideal_transaction
	@order = Order.find(params[:order_id])

	# initialize a shopper, use details from your order
	shopper = Docdata::Shopper.new(first_name: @order.first_name, last_name: @order.last_name)

	# set up a payment
	@payment = Docdata::Payment.new(
		amount: @order.total, 
		currency: @order.currency, 
		shopper: shopper,
		profile: "My Default Profile",
		order_reference: "order ##{@order.id}",
		bank_id: params[:bank_id],
		default_act: true # redirect directly to the bank, skipping the Docdata web menu
	)

	# create the payment via the docdata api and collect the result
	result = @payment.create

	if result.success?
		# Set the transaction key for future reference
		@order.update_column :docdata_key, result.key
		# redirect the user to the bank page
		redirect_to @payment.redirect_url
	else
		# TODO: Display the error and warn the user that something went wrong.
	end
end

View template (ideal_checkout.html.erb):

<h2>Choose your bank</h2>
<%= form_tag start_ideal_transaction_path, method: :post, target: "_blank" do %>
<%= select_tag "bank_id", options_from_collection_for_select(@banks, "id", "name") %>
<%= hidden_field_tag :order_id, @order.id %>
<%= submit_tag "Proceed to checkout" %>
<% end %>

When making a new Docdata::Payment, use the default_act parameter to redirect consumers directly to the acquirers website. Example:

@payment = Docdata::Payment.new(
	amount: @order.total, 
	currency: @order.currency, 
	shopper: shopper,
	profile: "My Default Profile",
	order_reference: "order ##{@order.id}",
	bank_id: params[:bank_id],
	default_act: true # redirect directly to the bank, skipping the Docdata web menu
)

Docata::Ideal.banks returns an Array.

Docdata::Payment.find("PAYMENTORDERKEYHERE") returns either a Docdata::Payment object or a 'not found' error.

payment = Docdata::Payment.find("KEY"); payment.status => <Payment::Status>

To cancel an existing Payment, you can do one of the following: payment = Docdata::Payment.find("KEY"); payment.cancel or Docdata::Payment.cancel("KEY")

You can make a refund for a payment. In fact: each payment can have multiple refunds. Each refund has an amount (Integer type - cents) and as long as the refund amount doesn't exceed the total Payment amount, you can make as many partial refunds as you whish. Keep in mind that Docdata will charge you for each refund.

payment = Docdata::Payment.find("KEY") # find the payment
payment.refund(500) # => true or false

In order tot test this gem, you'll need to set the following environment variables to make it work. With other words: you can't test this gem without valid test credentials and you can't use my test credentials. Tip: set the environment variables in your .bash_profile file.

ENV["DOCDATA_PASSWORD"] = "your_password"
ENV["DOCDATA_USERNAME"] = "your_docdata_username"
ENV["DOCDATA_RETURN_URL"] = "http://return-url-here"

Want to contribute? Great!

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Make changes, document them and add tests (rspec)
4. Run the entire test suite and make sure all tests pass (rake)
5. Commit your changes (git commit -am 'Add some feature')
6. Push to the branch (git push origin my-new-feature)
7. Create new Pull Request