Ruby | Mangopay docs

Introduction

The Mangopay Ruby SDK makes working with the Mangopay API easier in a Ruby environment.

The SDK package is available on RubyGems: mangopay4-ruby-sdk

Caution – Use only the mangopay4 package (late Nov 2025)

Please ensure you use only the package with mangopay4 in the name (this is the package name and has no connection with the SDK version number).

Any other package must not be used. You need to update your package manually.

Since November 25, 2025, Mangopay’s official SDKs are no longer accessible on GitHub (with the exception of PHP for publication reasons).

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

Install the SDK

1 gem install mangopay4-ruby-sdk

Initialize and configure the SDK

1 require 'mangopay'
2 
3 MangoPay.configure do |c|
4   c.preproduction = true
5   c.client_id = 'your-mangopay-client-id'
6   c.client_apiKey = 'your-mangopay-api-key'
7   c.http_timeout = 30000
8   c.Http_open_timeout = 60000
9   c.Log_file = File.join('mypath', 'mangopay.log')
10 end

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

Key	Type	Default value	Description
`preproduction`	boolean	`false`	Defines whether the SDK calls the Production or Sandbox endpoints.
`client_id`	string	None	Your Mangopay ClientId – can be found in the Dashboard.
`client_apiKey`	string	None	Your Mangopay API key – can be found in the Dashboard.
`http_timeout`	int milliseconds	30	Specifies the amount of time until request failure because a chunk of data cannot be read.
`http_open_timeout`	int milliseconds	30	Specifies the amount of time until request failure because a connection cannot be made.
`log_file`	string	None	Enables logging. Results and responses are filtered so that confidential data is not saved in the log.

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:

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

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

1 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:

1 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

1 require 'mangopay'
2 # configuration
3 MangoPay.configure do |client|
4     client.preproduction = true
5     client.client_id = 'your-client-id'
6     client.client_apiKey = 'your-api-key'
7 end
8 
9 def getAllUsers(parameters)
10     begin
11         response = MangoPay::User.fetch(parameters)
12         puts response
13         puts parameters
14         return response
15     rescue MangoPay::ResponseError => error
16         puts "Error details: #{error.details}"
17     end
18 end
19 
20 pagination = {'page' => 1, 'per_page' => 8}
21 getAllUsers(pagination)

Filtering

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

Usage example

1 require 'mangopay'
2 
3 # configuration
4 MangoPay.configure do |client|
5     client.preproduction = true
6     client.client_id = 'your-client-id'
7     client.client_apiKey = 'your-api-key'
8 end
9 
10 def indexEvents(filters)
11     begin
12         response = MangoPay::Event.fetch(filters)
13         puts response
14         return response
15     rescue MangoPay::ResponseError => error
16         puts "Error details: #{error.details}"
17     end
18 end
19 
20 myFilters = { 'BeforeDate': 1688020455, 'AfterDate': 1686378855 }
21 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

1 begin
2   MangoPay::NaturalUser.create({})
3 rescue MangoPay::ResponseError => ex
4 
5   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.>
6 
7   ex.details # => {
8              #   "Message"=>"One or several required parameters are missing or incorrect. [...]",
9              #   "Type"=>"param_error",
10              #   "Id"=>"5c080105-4da3-467d-820d-0906164e55fe",
11              #   "Date"=>1409048671.0,
12              #   "errors"=>{
13              #     "FirstName"=>"The FirstName field is required.",
14              #     "LastName"=>"The LastName field is required.", ...},
15              #   "Code"=>"400",
16              #   "Url"=>"/v2/.../users/natural"
17              # }
18 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

1 MangoPay.ratelimit
2   {
3     :limit=>["74", "74", "75", "908"],
4     :remaining=>["2226", "4426", "8725", "104692"],
5     :reset=>["1495615620", "1495616520", "1495618320", "1495701060"]
6   }

Error handling

The SDK provides the MangoPay::ResponseError exception object to wrap HTTP errors returned by the API.

You can wrap your function in a begin…rescue block to catch errors, and the ex.details hash to create specific logic, for example:

1     begin
2         MangoPay::Wallet.fetch(walletId, nil, {'ScaContext': 'USER_PRESENT'})
3         puts response
4         return response
5     rescue MangoPay::ResponseError => error
6         puts "Failed to fetch wallet: #{error.message}"
7         puts "Error details: #{error.details}"
8         return false
9     end