Ruby
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 SDKPrerequisites
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 Hub - Ruby 1.9.2 (or higher) installed
Note - Mangopay SDK compatibility
The Ruby SDK is only compatible with the v2.01 version of the Mangopay API.
Getting started
- Install the SDK
gem install mangopay
- 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:
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 Hub. |
client_apiKey | string | None | Your Mangopay API key – can be found in the Hub. |
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. |
uk_header_flag | boolean | false | Platforms 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.
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.
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.
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
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 →