> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mangopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ruby

## Introduction

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

The SDK package is available on RubyGems: <a href="https://rubygems.org/gems/mangopay4-ruby-sdk" target="_blank">mangopay4-ruby-sdk</a>

<Warning>
  **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).
</Warning>

<Info>
  **Prerequisites**

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

  * A `ClientId` and an API key – if you don't have these, <a href="https://mangopay.com/contact" target="_blank">contact Sales</a> to get access to the <a href="https://hub.mangopay.com/" target="_blank">Mangopay Dashboard</a>
  * Ruby 1.9.2 or higher (tested from 1.9.2 up to 3.4.4)
</Info>

## Getting started

1. Install the SDK

```ruby theme={null}
gem install mangopay4-ruby-sdk
```

2. Initialize and configure the SDK

```ruby theme={null}
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:

<table>
  <thead>
    <tr>
      <th class="header">Key</th>
      <th class="header">Type</th>
      <th class="header">Default value</th>
      <th class="header">Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td class="table-content">`preproduction `</td>
      <td class="table-content">boolean</td>
      <td class="table-content">`false`</td>
      <td class="table-content">Defines whether the SDK calls the Production or Sandbox endpoints.</td>
    </tr>

    <tr>
      <td class="table-content">`client_id`</td>
      <td class="table-content">string</td>
      <td class="table-content">None</td>
      <td class="table-content">Your Mangopay ClientId – can be found in the <a href="https://hub.mangopay.com/" target="_blank">Dashboard</a>.</td>
    </tr>

    <tr>
      <td class="table-content">`client_apiKey`</td>
      <td class="table-content">string</td>
      <td class="table-content">None</td>
      <td class="table-content">Your Mangopay API key – can be found in the <a href="https://hub.mangopay.com/" target="_blank">Dashboard</a>.</td>
    </tr>

    <tr>
      <td class="table-content">`http_timeout `</td>
      <td class="table-content">int milliseconds</td>
      <td class="table-content">30</td>
      <td class="table-content">Specifies the amount of time until request failure because a chunk of data cannot be read.</td>
    </tr>

    <tr>
      <td class="table-content">`http_open_timeout`</td>
      <td class="table-content">int milliseconds</td>
      <td class="table-content">30</td>
      <td class="table-content">Specifies the amount of time until request failure because a connection cannot be made.</td>
    </tr>

    <tr>
      <td class="table-content">`log_file`</td>
      <td class="table-content">string</td>
      <td class="table-content">None</td>
      <td class="table-content">Enables logging. Results and responses are filtered so that confidential data is not saved in the log.</td>
    </tr>
  </tbody>
</table>

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

```ruby theme={null}
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:

```ruby theme={null}
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:

```ruby theme={null}
MangoPay.get_config('config1').apply_configuration
```

### Pagination

For endpoints that support <a href="/api-reference/overview/pagination">pagination</a>, 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.

```ruby Pagination example theme={null}
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 <a href="/api-reference/overview/filtering-sorting">filtering</a>, you can use an object containing the filtering parameters.

```ruby Usage example theme={null}
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.

```ruby Error handling example theme={null}
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 <a href="/api-reference/overview/rate-limiting">rate limiting</a> headers are automatically updated in the MangoPay object:

* X-RateLimit-Limit
* X-RateLimit-Remaining
* X-RateLimit-Reset

```ruby Rate limiting example theme={null}
MangoPay.ratelimit
  {
    :limit=>["74", "74", "75", "908"],
    :remaining=>["2226", "4426", "8725", "104692"],
    :reset=>["1495615620", "1495616520", "1495618320", "1495701060"]
  }
```

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

```ruby theme={null}

    begin
        MangoPay::Wallet.fetch(walletId, nil, {'ScaContext': 'USER_PRESENT'})
        puts response
        return response
    rescue MangoPay::ResponseError => error
        puts "Failed to fetch wallet: #{error.message}"
        puts "Error details: #{error.details}"
        return false
    end
```