​
Introduction

The Mangopay Ruby SDK makes working with the Mangopay API easier in a Ruby environment. This SDK is open-source and available on GitHub.

Mangopay Ruby SDK

Prerequisites

To run the Mangopay Ruby SDK, you’ll need:

  • A ClientId and an API key – if you don’t have these, contact Sales to get access to the Mangopay Dashboard
  • Ruby 1.9.2 or higher (tested from 1.9.2 up to 3.4.4)

​
Getting started

  1. Install the SDK
gem install mangopay
  1. Initialize and configure the SDK
require 'mangopay'

MangoPay.configure do |c|
  c.preproduction = true
  c.client_id = 'your-mangopay-client-id'
  c.client_apiKey = 'your-mangopay-api-key'
  c.http_timeout = 30000
  c.Http_open_timeout = 60000
  c.Log_file = File.join('mypath', 'mangopay.log')
end

The configuration object of the SDK supports all the following properties:

KeyTypeDefault valueDescription
preproduction booleanfalseDefines whether the SDK calls the Production or Sandbox endpoints.
client_idstringNoneYour Mangopay ClientId – can be found in the Dashboard.
client_apiKeystringNoneYour Mangopay API key – can be found in the Dashboard.
http_timeout int milliseconds30Specifies the amount of time until request failure because a chunk of data cannot be read.
http_open_timeoutint milliseconds30Specifies the amount of time until request failure because a connection cannot be made.
log_filestringNoneEnables logging. Results and responses are filtered so that confidential data is not saved in the log.
uk_header_flagbooleanfalsePlatforms that have contracted with Mangopay’s UK entity (MANGOPAY U.K. LIMITED) must include the following header in all requests. If you’re using an SDK, you need to set it to true.

​
SDK usage

All endpoints are documented with the related Ruby SDK method throughout the Mangopay documentation. You should adjust the code examples provided for your usage.

​
Multi configurations

The Ruby SDK offers the option to create multiple configuration objects tailored to your specific needs:

config = MangoPay::Configuration.new
config.client_id = 'your-client-id'
config.client_apiKey = 'your-api-key'
config.preproduction = true

Once configured, you can the use the add_config method to add the new configuration:

MangoPay.add_config('config1', config)

When you need to use a specific configuration, you can retrieve the needed configuration by using the get_config and apply_configuration methods:

MangoPay.get_config('config1').apply_configuration

​
Pagination

For endpoints that support pagination, you can use an object containing the page and per_page keys.

As a result, the answer will be paginated, and the total number of items and the total number of pages will be provided.

Pagination example
require 'mangopay'
# configuration
MangoPay.configure do |client|
    client.preproduction = true
    client.client_id = 'your-client-id'
    client.client_apiKey = 'your-api-key'
end

def getAllUsers(parameters)
    begin
        response = MangoPay::User.fetch(parameters)
        puts response
        puts parameters
        return response
    rescue MangoPay::ResponseError => error
        puts "Error details: #{error.details}"
    end
end

pagination = {'page' => 1, 'per_page' => 8}
getAllUsers(pagination)

​
Filtering

For endpoints that support filtering, you can use an object containing the filtering parameters.

Usage example
require 'mangopay'

# configuration
MangoPay.configure do |client|
    client.preproduction = true
    client.client_id = 'your-client-id'
    client.client_apiKey = 'your-api-key'
end

def indexEvents(filters)
    begin
        response = MangoPay::Event.fetch(filters)
        puts response
        return response
    rescue MangoPay::ResponseError => error
        puts "Error details: #{error.details}"
    end
end

myFilters = { 'BeforeDate': 1688020455, 'AfterDate': 1686378855 }
indexEvents(myFilters)

​
Error handling

As an alternative to logging, you can use the following example to surface errors returned by the Ruby SDK within your app.

Error handling example
begin
  MangoPay::NaturalUser.create({})
rescue MangoPay::ResponseError => ex

  ex # => #<MangoPay::ResponseError: One or several required parameters are missing or incorrect. [...] FirstName: The FirstName field is required. LastName: The LastName field is required. Nationality: The Nationality field is required.>

  ex.details # => {
             #   "Message"=>"One or several required parameters are missing or incorrect. [...]",
             #   "Type"=>"param_error",
             #   "Id"=>"5c080105-4da3-467d-820d-0906164e55fe",
             #   "Date"=>1409048671.0,
             #   "errors"=>{
             #     "FirstName"=>"The FirstName field is required.",
             #     "LastName"=>"The LastName field is required.", ...},
             #   "Code"=>"400",
             #   "Url"=>"/v2/.../users/natural"
             # }
end

​
Rate limiting

Along with each request, the rate limiting headers are automatically updated in the MangoPay object:

  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset
Rate limiting example
MangoPay.ratelimit
  {
    :limit=>["74", "74", "75", "908"],
    :remaining=>["2226", "4426", "8725", "104692"],
    :reset=>["1495615620", "1495616520", "1495618320", "1495701060"]
  }

​
Report an issue

Found a problem with the SDK? Create an issue on GitHub:

Report an issue →