mollie-ruby-sdk
Developer-friendly & type-safe Ruby SDK specifically catered to leverage mollie-ruby-sdk API.
Important
This SDK is not yet ready for production use. To complete setup please follow the steps outlined in your workspace. Delete this section before > publishing to a package manager.
Summary
Table of Contents
- mollie-ruby-sdk
- SDK Installation
- SDK Example Usage
- Authentication
- Available Resources and Operations
- Global Parameters
- Retries
- Error Handling
- Server Selection
- Development
- Maturity
- Contributions
SDK Installation
The SDK can be installed using RubyGems:
gem install mollie-ruby-sdkSDK Example Usage
Example
require "mollie_ruby_sdk"
Models = ::Mollie::Models
s = ::Mollie::Client.new
res = s.oauth.generate(
security: Models::Operations::OauthGenerateTokensSecurity.new(
username: "",
password: ""
),
idempotency_key: "123e4567-e89b-12d3-a456-426",
body: Models::Operations::OauthGenerateTokensRequestBody.new(
grant_type: Models::Components::OauthGrantType::AUTHORIZATION_CODE,
code: "auth_...",
refresh_token: "refresh_...",
redirect_uri: "https://example.com/redirect"
)
)
unless res.object.nil?
# handle response
endAuthentication
Per-Client Security Schemes
This SDK supports the following security schemes globally:
| Name | Type | Scheme |
|---|---|---|
api_key |
http | HTTP Bearer |
advanced_access_token |
http | HTTP Bearer |
o_auth |
oauth2 | OAuth2 token |
You can set the security parameters through the security optional parameter when initializing the SDK client instance. The selected scheme will be used by default to authenticate with the API for all operations that support it. For example:
require "mollie_ruby_sdk"
Models = ::Mollie::Models
s = ::Mollie::Client.new(
security: Models::Components::Security.new(
api_key: "<YOUR_BEARER_TOKEN_HERE>"
),
testmode: true
)
req = Models::Operations::ListBalancesRequest.new(
currency: "EUR",
limit: 50,
idempotency_key: "123e4567-e89b-12d3-a456-426",
x_client_signature: "MEUCIQDx8sJvK3z...",
x_client_signed_at: "2025-01-01T12:00:00Z"
)
res = s.balances.list(request: req)
unless res.object.nil?
# handle response
endPer-Operation Security Schemes
Some operations in this SDK require the security scheme to be specified at the request level. For example:
require "mollie_ruby_sdk"
Models = ::Mollie::Models
s = ::Mollie::Client.new
res = s.oauth.generate(
security: Models::Operations::OauthGenerateTokensSecurity.new(
username: "",
password: ""
),
idempotency_key: "123e4567-e89b-12d3-a456-426",
body: Models::Operations::OauthGenerateTokensRequestBody.new(
grant_type: Models::Components::OauthGrantType::AUTHORIZATION_CODE,
code: "auth_...",
refresh_token: "refresh_...",
redirect_uri: "https://example.com/redirect"
)
)
unless res.object.nil?
# handle response
endAvailable Resources and Operations
- create_account - Create business account
- list_accounts - List business accounts
- get_account - Get business account
- list - List transactions
- get - Get transaction
- create - Create a Connect balance transfer
- list - List all Connect balance transfers
- get - Get a Connect balance transfer
- list - List balances
- get - Get balance
- get_primary - Get primary balance
- get_report - Get balance report
- list_transactions - List balance transactions
- list - List capabilities
- create - Create client link
- create - Create customer
- list - List customers
- get - Get customer
- update - Update customer
- delete - Delete customer
- create_payment - Create customer payment
- list_payments - List customer payments
- create - Create draft transfer
- list - List draft transfers
- get - Get draft transfer
- cancel - Cancel draft transfer
- list - List payment methods
- all - List all payment methods
- get - Get payment method
- enable - Enable payment method
- disable - Disable payment method
- enable_issuer - Enable payment method issuer
- disable_issuer - Disable payment method issuer
- get - Get organization
- get_current - Get current organization
- get_partner - Get partner status
- create - Create payment link
- list - List payment links
- get - Get payment link
- update - Update payment link
- delete - Delete payment link
- list_payments - Get payment link payments
- create - Create payment
- list - List payments
- get - Get payment
- update - Update payment
- cancel - Cancel payment
- release_authorization - Release payment authorization
- create - Create profile
- list - List profiles
- get - Get profile
- update - Update profile
- delete - Delete profile
- get_current - Get current profile
- create - Create payment refund
- list - List payment refunds
- get - Get payment refund
- cancel - Cancel payment refund
- all - List all refunds
- create - Create sales invoice
- list - List sales invoices
- get - Get sales invoice
- update - Update sales invoice
- delete - Delete sales invoice
- list - List settlements
- get - Get settlement
- get_open - Get open settlement
- get_next - Get next settlement
- list_payments - List settlement payments
- list_captures - List settlement captures
- list_refunds - List settlement refunds
- list_chargebacks - List settlement chargebacks
- create - Create subscription
- list - List customer subscriptions
- get - Get subscription
- update - Update subscription
- cancel - Cancel subscription
- all - List all subscriptions
- list_payments - List subscription payments
- list - List terminals
- get - Get terminal
- terminals_request_pairing_code - Request terminal pairing code
- terminals_list_pairing_codes - List terminal pairing codes
- terminals_get_pairing_code - Get terminal pairing code
- terminals_revoke_pairing_code - Revoke terminal pairing code
- list - List unmatched credit transfers
- get - Get unmatched credit transfer
- match - Match unmatched credit transfer
- return - Return unmatched credit transfer
- create - Verify Payee
- request_apple_pay_session - Request Apple Pay payment session
- get - Get a Webhook Event
- create - Create a webhook
- list - List all webhooks
- update - Update a webhook
- get - Get a webhook
- delete - Delete a webhook
- test - Test a webhook
Global Parameters
Certain parameters are configured globally. These parameters may be set on the SDK client instance itself during initialization. When configured as an option during SDK initialization, These global values will be used as defaults on the operations that use them. When such operations are called, there is a place in each to override the global value, if needed.
For example, you can set profileId to `` at SDK initialization and then you do not have to pass the same value on calls to operations like list. But if you want to do so you may, which will locally override the global setting. See the example code below for a demonstration.
Available Globals
The following global parameters are available.
| Name | Type | Description |
|---|---|---|
| profile_id | ::String | The identifier referring to the profile you wish to retrieve the resources for. Most API credentials are linked to a single profile. In these cases the profileId must not be sent. Fororganization-level credentials such as OAuth access tokens however, the profileId parameter is required. |
| testmode | T::Boolean | Most API credentials are specifically created for either live mode or test mode. In those cases the testmode queryparameter must not be sent. For organization-level credentials such as OAuth access tokens, you can enable test mode by setting the testmode query parameter to true.Test entities cannot be retrieved when the endpoint is set to live mode, and vice versa. |
| custom_user_agent | ::String | Custom user agent string to be appended to the default Mollie SDK user agent. |
Example
require "mollie_ruby_sdk"
Models = ::Mollie::Models
s = ::Mollie::Client.new(
testmode: true,
profile_id: "<id>",
custom_user_agent: "<value>",
security: Models::Components::Security.new(
advanced_access_token: "<YOUR_BEARER_TOKEN_HERE>"
)
)
req = Models::Operations::ListBalancesRequest.new(
currency: "EUR",
limit: 50,
idempotency_key: "123e4567-e89b-12d3-a456-426",
x_client_signature: "MEUCIQDx8sJvK3z...",
x_client_signed_at: "2025-01-01T12:00:00Z"
)
res = s.balances.list(request: req)
unless res.object.nil?
# handle response
endRetries
Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.
To change the default retry strategy for a single API call, simply provide a RetryConfig object to the call:
require "mollie_ruby_sdk"
Models = ::Mollie::Models
s = ::Mollie::Client.new
res = s.oauth.generate(
security: Models::Operations::OauthGenerateTokensSecurity.new(
username: "",
password: ""
),
idempotency_key: "123e4567-e89b-12d3-a456-426",
body: Models::Operations::OauthGenerateTokensRequestBody.new(
grant_type: Models::Components::OauthGrantType::AUTHORIZATION_CODE,
code: "auth_...",
refresh_token: "refresh_...",
redirect_uri: "https://example.com/redirect"
)
)
unless res.object.nil?
# handle response
endIf you'd like to override the default retry strategy for all operations that support retries, you can use the retry_config optional parameter when initializing the SDK:
require "mollie_ruby_sdk"
Models = ::Mollie::Models
s = ::Mollie::Client.new(
retry_config: Utils::RetryConfig.new(
backoff: Utils::BackoffStrategy.new(
exponent: 1.1,
initial_interval: 1,
max_elapsed_time: 100,
max_interval: 50
),
retry_connection_errors: false,
strategy: "backoff"
)
)
res = s.oauth.generate(
security: Models::Operations::OauthGenerateTokensSecurity.new(
username: "",
password: ""
),
idempotency_key: "123e4567-e89b-12d3-a456-426",
body: Models::Operations::OauthGenerateTokensRequestBody.new(
grant_type: Models::Components::OauthGrantType::AUTHORIZATION_CODE,
code: "auth_...",
refresh_token: "refresh_...",
redirect_uri: "https://example.com/redirect"
)
)
unless res.object.nil?
# handle response
endError Handling
Handling errors in this SDK should largely match your expectations. All operations return a response object or raise an error.
By default an API error will raise a Errors::APIError, which has the following properties:
| Property | Type | Description |
|---|---|---|
message |
string | The error message |
status_code |
int | The HTTP status code |
raw_response |
Faraday::Response | The raw HTTP response |
body |
string | The response content |
When custom error responses are specified for an operation, the SDK may also throw their associated exception. You can refer to respective Errors tables in SDK docs for more details on possible exception types for each operation. For example, the generate method throws the following exceptions:
| Error Type | Status Code | Content Type |
|---|---|---|
| Models::Errors::ErrorResponse | 429 | application/hal+json |
| Errors::APIError | 4XX, 5XX | */* |
Example
require "mollie_ruby_sdk"
Models = ::Mollie::Models
s = ::Mollie::Client.new
begin
res = s.oauth.generate(
security: Models::Operations::OauthGenerateTokensSecurity.new(
username: "",
password: ""
),
idempotency_key: "123e4567-e89b-12d3-a456-426",
body: Models::Operations::OauthGenerateTokensRequestBody.new(
grant_type: Models::Components::OauthGrantType::AUTHORIZATION_CODE,
code: "auth_...",
refresh_token: "refresh_...",
redirect_uri: "https://example.com/redirect"
)
)
unless res.object.nil?
# handle response
end
rescue Models::Errors::ErrorResponse => e
# handle e.container data
raise e
rescue Errors::APIError => e
# handle default exception
raise e
endServer Selection
Override Server URL Per-Client
The default server can be overridden globally by passing a URL to the server_url (String) optional parameter when initializing the SDK client instance. For example:
require "mollie_ruby_sdk"
Models = ::Mollie::Models
s = ::Mollie::Client.new(
server_url: "https://api.mollie.com"
)
res = s.oauth.generate(
security: Models::Operations::OauthGenerateTokensSecurity.new(
username: "",
password: ""
),
idempotency_key: "123e4567-e89b-12d3-a456-426",
body: Models::Operations::OauthGenerateTokensRequestBody.new(
grant_type: Models::Components::OauthGrantType::AUTHORIZATION_CODE,
code: "auth_...",
refresh_token: "refresh_...",
redirect_uri: "https://example.com/redirect"
)
)
unless res.object.nil?
# handle response
endDevelopment
Maturity
This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally looking for the latest version.
Contributions
While we value open-source contributions to this SDK, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.