Docdata::Order

Docdata::Order is a Ruby client for the Docdata Order API version 1.3.

Table of Contents

• Installation
• Usage
  • Initialization
  • Subject merchant
  • Create an order
  • Redirecting directly to the payment page
  • Initial payment request
  • Start a payment order
  • Recurring payment request
  • Retrieve status of an order
  • Retrieve payment methods
  • Refund a payment
• Development
• Contributing
• License

Installation

Add this line to your application's Gemfile:

gem 'docdata-order'

And then execute:

$ bundle

Or install it yourself as:

$ gem install docdata-order

Usage

Initialization

Create a Docdata Order client and configure it with your merchant name and password:

client = Docdata::Order::Client.new("name", "password")

The client is configured to use the production environment by default. To use the Docdata test environment, add the parameter test: true when creating the client.

Subject merchant

If you want to use a merchant on whose behalf the requests should be executed (subject merchant), then you can add this to the parameters:

client = Docdata::Order::Client.new("name", "password", subject_merchant: {
  name: "subname",
  token: "12345678"
})

Create an order

Create a new order with the create method. You need to provide at least the following parameters to create the order:

options = {
  amount: "12.50",
  order_reference: "12345",
  description: "Test order",
  profile: "profile",
  shopper: {
    first_name: "John",
    last_name: "Doe",
    email: "john.doe@example.com",
    language: "en",
    gender: Docdata::Order::Gender::MALE
  },
  address: {
    street: "Jansbuitensingel",
    house_number: "29",
    postal_code: "6811AD",
    city: "Arnhem",
    country: "NL"
  }
}

response = client.create(options)

if response.success?
  puts response.order_key
  puts response.redirect_url
else
  puts response.error_message
end

The redirect_url in the response will redirect the user to the Docdata Payment Menu (One Page Checkout).

Redirecting directly to the payment page

For some payment methods you can skip the Docdata One Page Checkout and redirect directly to the payment page of the specified payment method. This works for the payment methods iDEAL, Sofort and PayPal. For iDEAL, you also need to provide the issuer:

response = client.create(options.merge(
  payment_method: Docdata::Order::PaymentMethod::IDEAL,
  issuer_id: "INGBNL2A",
  return_url: "http://yourwebshop.nl/payment_return"
))

Initial payment request

If you want to use this order to do recurring payments then you must first make an initial payment request and provide an unique merchant reference. This reference should then be used when a making recurring payments.

response = client.create(options.merge(
  initial: {
    merchant_reference: "12345"
  }
))

See Recurring payment request how to make recurring payment requests.

Start a payment order

When the One Page Checkout is not used (i.e. WebDirect) then you need to use start to start a payment order.

options = {
  order_key: "12345",
  payment_method: Docdata::Order::PaymentMethod::SEPA_DIRECT_DEBIT,
  consumer_name: "Onderheuvel",
  consumer_iban: "NL44RABO0123456789"
}

response = client.start(options)

if response.success?
  puts response.payment_id
else
  puts response.error_message
end

Recurring payment request

To start a recurring payment request, you need to provide the unique merchant reference, used in the initial payment request:

response = client.start(options.merge(
  recurring: {
    merchant_reference: "12345"
  }
))

Retrieve status of an order

To retrieve the status of an order, use status with the order key:

response = client.status(order_key: "12345")

if response.success?
  puts response.paid?
else
  puts response.error_message
end

Retrieve payment methods

When an order has been created, you can retrieve the available payment methods (including issuers) by using payment_methods with the order key:

response = client.payment_methods(order_key: "12345")

if response.success?
  puts response.payment_methods
else
  puts response.error_message
end

Refund a payment

To refund a payment, use refund with the payment ID:

response = client.refund(payment_id: "12345")

if !response.success?
  puts response.error_message
end

Development

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.

Contributing

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

License

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