Mollie API client for Ruby

LOOKING FOR VERSION v2.2.X README? CLICK HERE

LOOKING FOR VERSION v3.1.X README? CLICK HERE

Accepting iDEAL, Bancontact, SOFORT Banking, Creditcard, SEPA Bank transfer, SEPA Direct debit, PayPal, KBC/CBC Payment Button, Belfius Direct Net, paysafecard, ING Home’Pay, Gift cards, EPS, Giropay and Apple Pay online payments without fixed monthly costs or any punishing registration procedures. Just use the Mollie API to receive payments directly on your website or easily refund transactions to your customers.

Requirements

To use the Mollie API client, the following things are required:

Get yourself a free Mollie account. No sign up costs.
Create a new Website profile to generate API keys (live and test mode) and setup your webhook.
Now you're ready to use the Mollie API client in test mode.
In order to accept payments in live mode, payment methods must be activated in your account. Follow a few of steps, and let us handle the rest.

Installation

By far the easiest way to install the Mollie API client is to install it with gem. Note: v4.8.0 and higher are not published on rubygems.org, see GH-140 for details.

# Gemfile
gem "mollie-api-ruby", github: "mollie/mollie-api-ruby", tag: "v4.11.0"

$ gem install mollie-api-ruby

You may also git checkout or download all the files, and include the Mollie API client manually.

How to receive payments

To successfully receive a payment, these steps should be implemented:

Use the Mollie API client to create a payment with the requested amount, description and optionally, a payment method. It is important to specify a unique redirect URL where the customer is supposed to return to after the payment is completed.
Immediately after the payment is completed, our platform will send an asynchronous request to the configured webhook to allow the payment details to be retrieved, so you know when exactly to start processing the customer's order.
The customer returns, and should be satisfied to see that the order was paid and is now being processed.

Getting started

Require the Mollie API Client. Not required when used with a Gemfile

require 'mollie-api-ruby'

Create an initializer and add the following line:

Mollie::Client.configure do |config|
  config.api_key = '<your-api-key>'
  # Timeouts (default - 60)
  # config.open_timeout = 60
  # config.read_timeout = 60
end

You can also include the API Key in each request you make, for instance if you are using the Connect API:

Mollie::Payment.get('pay-id', api_key: '<your-api-key>')

If you need to do multiple calls with the same API Key, use the following helper:

Mollie::Client.with_api_key('<your-api-key>') do
  mandates = Mollie::Customer::Mandate.all(customer_id: params[:customer_id])
  if mandates.any?
    payment = Mollie::Payment.create(
      amount:       { value: '10.00', currency: 'EUR' },
      description:  'My first API payment',
      redirect_url: 'https://webshop.example.org/order/12345/',
      webhook_url:  'https://webshop.example.org/mollie-webhook/'
    )
  end
end

Creating a new payment

payment = Mollie::Payment.create(
  amount:       { value: '10.00', currency: 'EUR' },
  description:  'My first API payment',
  redirect_url: 'https://webshop.example.org/order/12345/',
  webhook_url:  'https://webshop.example.org/mollie-webhook/'
)

Note: If you specify an amount, you must specify the correct number of decimals. We strongly recommend sending value as a string. Note that even though most currencies use two decimals, some use three or none, like JPY. All amounts returned in the v2 API will use this format.

Retrieving a payment

payment = Mollie::Payment.get(payment.id)

if payment.paid?
  puts 'Payment received.'
end

Refunding payments

The API also supports refunding payments. Note that there is no confirmation and that all refunds are immediate and definitive. Refunds are only supported for certain payment methods.

payment = Mollie::Payment.get(payment.id)
refund  = payment.refund!(amount: { value: '10.00', currency: 'EUR' })

Pagination

Fetching all objects of a resource can be convenient. At the same time, returning too many objects at once can be unpractical from a performance perspective. Doing so might be too much work for the Mollie API to generate, or for your website to process. The maximum number of objects returned is 250.

For this reason the Mollie API only returns a subset of the requested set of objects. In other words, the Mollie API chops the result of a certain API method call into pages you’re able to programmatically scroll through.

payments = Mollie::Payment.all
payments.next
payments.previous

Upgrading

API documentation

If you wish to learn more about our API, please visit the Mollie API Documentation.

Want to help us make our API client even better?

Want to help us make our API client even better? We take pull requests, sure. But how would you like to contribute to a technology oriented organization? Mollie is hiring developers and system engineers. Check out our vacancies or get in touch.

License

Support

Contact: www.mollie.com — info@mollie.com — +31 20-612 88 55

fynsta/mollie-api-ruby