mercadopago-sdk 3.2.0 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3eb3c15c909d8872d5810ac30966353a794f2c70bfcd983824898a93e2adf96
-  data.tar.gz: cd2bbac8379dcedaae481d4f4715130e21f88f819dc34a73779c238575e98f3b
+  metadata.gz: 518cbc2c53d00de1452bf210afff62915ba381a970d084ca42a848e5604fa582
+  data.tar.gz: 85468b9a03305eb33e4b053a4aae7149cbacd1ceb33df494e25bf63391b2bfea
 SHA512:
-  metadata.gz: 0ec0c57a6703933698e7fb99643274658a871ac3bb3738bcefa756ffde307ac9037d54ddd36f585c5a8b60f90f9bb7c433b7b97047a0f4f5ded2bf3aafbf9a94
-  data.tar.gz: 3379ec1633e23f25eae001deea156c96010e345298b0f8c58113d30916d644d0a263078261ad6bc9d9aff3d65ba2a488bc723d906db7a8196d0aca514d6f0d02
+  metadata.gz: 59839cc98cb80e2718b5694f05559b0a73fe23f04b953c0d172bb80b0609c220f673bd88952326eab551bcd52edd0beec0cb2173c188b9ea9cace45c5513b75b
+  data.tar.gz: 4e2e68a2fef69a84eafba9c8fa6b877d214f953e764d26525f48dca5cb812686195fe7fea80085704c8827de1d023fe385c366dede92156a98e680d51ae8dbce

data/.github/workflows/ci.yml

@@ -13,13 +13,13 @@ jobs:
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v7
+      uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
       with:
         ref: ${{ github.event.pull_request.head.ref }}
         repository: ${{ github.event.pull_request.head.repo.full_name }}
 
     - name: Cache gems
-      uses: actions/cache@v6
+      uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
       with:
         path: vendor/bundle
         key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }}

data/.github/workflows/release.yml

@@ -14,7 +14,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
 
       - name: Install dependencies
         run: bundle install

data/.rubocop.yml

@@ -1 +1,9 @@
 inherit_from: .rubocop_todo.yml
+
+Metrics/AbcSize: {Max: 32}
+Metrics/CyclomaticComplexity: {Max: 18}
+Metrics/ParameterLists: {Max: 12}
+Metrics/PerceivedComplexity: {Max: 18}
+Style/ExplicitBlockArgument: {Enabled: false}
+Style/NumericPredicate: {Enabled: false}
+Style/TrivialAccessors: {Enabled: false}

data/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 This project follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.3.0] - 2026-08-04
+
+### Added
+
+- **SDK ergonomics**: typed exceptions, configurable retry, and auto-pagination ([#162](https://github.com/mercadopago/sdk-ruby/pull/162))
+  - `MercadoPago::ApiError` now has 12 specific subtypes per HTTP status code
+  - Request options gain optional `max_retries`, `retry_on`, `initial_delay_ms`, `max_delay_ms` and `on_retry` callback
+  - New auto-pagination support on search endpoints
+- **Missing API methods** — `disbursement_refund.list`, `advanced_payment.update`, `customer_card.update`, `payment.update` ([#161](https://github.com/mercadopago/sdk-ruby/pull/161))
+- **CREDENTIAL_ON_FILE messaging fields** on Payment types ([#158](https://github.com/mercadopago/sdk-ruby/pull/158)): `first_transaction`, `storage`, `transaction_initiator`, `reference`
+
+### Fixed
+
+- Webhook `tolerance_seconds` unit mismatch — `ts` header value compared in seconds against a millisecond clock ([#163](https://github.com/mercadopago/sdk-ruby/pull/163))
+- `constant_time_equals` error on multibyte v1 hash ([#163](https://github.com/mercadopago/sdk-ruby/pull/163))
+
+### Dependencies
+
+- Bump `json` gem ([#159](https://github.com/mercadopago/sdk-ruby/pull/159))
+- Bump `actions/cache` to `v6.1.0` ([#160](https://github.com/mercadopago/sdk-ruby/pull/160))
+- Bump `actions/checkout` to `v7.0.1` ([#157](https://github.com/mercadopago/sdk-ruby/pull/157))
+
 ## [3.2.0] - 2026-06-30
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mercadopago-sdk (3.2.0)
+    mercadopago-sdk (3.3.0)
       faraday (~> 2.0)
       json (~> 2.5)
 
@@ -17,8 +17,8 @@ GEM
     faraday-net_http (3.4.4)
       net-http (~> 0.5)
     io-console (0.8.2)
-    json (2.20.0)
-    language_server-protocol (3.17.0.5)
+    json (2.21.2)
+    language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
     logger (1.7.0)
     method_source (1.1.0)
@@ -40,7 +40,7 @@ GEM
     regexp_parser (2.12.0)
     reline (0.6.3)
       io-console (~> 0.5)
-    rubocop (1.88.0)
+    rubocop (1.88.2)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -51,7 +51,7 @@ GEM
       rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.49.1)
+    rubocop-ast (1.50.0)
       parser (>= 3.3.7.2)
       prism (~> 1.7)
     ruby-progressbar (1.13.0)

data/examples/order/create_checkout_pro.rb

@@ -22,11 +22,18 @@ def create_checkout_pro_order(sdk)
       identification: {
         type: 'CPF',
         number: '12345678909'
-      }
+      },
+      date_created: '2024-01-01T00:00:00Z',
+      authentication_type: 'Gmail',
+      is_prime_user: false,
+      is_first_purchase_online: false,
+      last_purchase: '2024-01-01T00:00:00Z',
+      registration_date: '2023-01-01T00:00:00Z'
     },
     shipment: {
       mode: 'custom',
       local_pickup: false,
+      express_shipment: false,
       cost: '15.00',
       free_shipping: false,
       address: {
@@ -34,7 +41,11 @@ def create_checkout_pro_order(sdk)
         street_name: 'Av. Paulista',
         street_number: '1000',
         neighborhood: 'Bela Vista',
-        city: 'Sao Paulo'
+        city: 'Sao Paulo',
+        state_name: 'Sao Paulo',
+        city_name: 'Sao Paulo',
+        floor: '2',
+        apartment: 'A'
       }
     },
     config: {
@@ -85,7 +96,25 @@ def create_checkout_pro_order(sdk)
         quantity: 1,
         unit_price: '450.00',
         type: 'travel',
-        event_date: '2027-01-15T00:00:00.000-03:00'
+        warranty: false,
+        event_date: '2027-01-15T00:00:00.000-03:00',
+        category_descriptor: {
+          passenger: {
+            first_name: 'John',
+            last_name: 'Smith',
+            identification: {
+              type: 'CPF',
+              number: '12345678909'
+            }
+          },
+          route: {
+            departure: 'SAO',
+            destination: 'RIO',
+            departure_date_time: '2027-01-15T08:00:00.000-03:00',
+            arrival_date_time: '2027-01-15T09:30:00.000-03:00',
+            company: 'LATAM'
+          }
+        }
       },
       {
         external_code: 'ITEM-002',
@@ -96,7 +125,25 @@ def create_checkout_pro_order(sdk)
         quantity: 1,
         unit_price: '50.00',
         type: 'travel',
-        event_date: '2027-01-15T00:00:00.000-03:00'
+        warranty: true,
+        event_date: '2027-01-15T00:00:00.000-03:00',
+        category_descriptor: {
+          passenger: {
+            first_name: 'John',
+            last_name: 'Smith',
+            identification: {
+              type: 'CPF',
+              number: '12345678909'
+            }
+          },
+          route: {
+            departure: 'SAO',
+            destination: 'RIO',
+            departure_date_time: '2027-01-15T08:00:00.000-03:00',
+            arrival_date_time: '2027-01-15T09:30:00.000-03:00',
+            company: 'LATAM'
+          }
+        }
       }
     ]
   }

data/examples/payment/automatic_payment_credential_on_file.rb

@@ -0,0 +1,194 @@
+# Example: Automatic Payments with CREDENTIAL_ON_FILE (COF).
+#
+# CREDENTIAL_ON_FILE replaces the deprecated SUBSCRIPTIONS type for recurring
+# and unscheduled automatic payments. It covers three main scenarios:
+#
+#   1. CIT – Customer-Initiated Transaction (enrollment / first charge):
+#      The customer actively authorizes the initial payment and consents to
+#      storing their credentials for future merchant-initiated charges.
+#
+#   2. MIT – Merchant-Initiated Transaction (recurring charge):
+#      Subsequent charges triggered by the merchant without customer
+#      interaction (e.g. monthly subscription billing).
+#
+#   3. UCOF-CIT – Unscheduled COF Customer-Initiated Transaction:
+#      A one-off purchase where the customer uses previously stored
+#      credentials, but the amount / date was not pre-agreed.
+#
+# Reference: https://www.mercadopago.com/developers/en/reference
+
+require_relative '../../lib/mercadopago'
+
+sdk = Mercadopago::SDK.new('<ACCESS_TOKEN>')
+
+# ---------------------------------------------------------------------------
+# 1. CIT — Customer-Initiated Transaction (enrollment)
+#
+# The customer completes the first payment and grants permission to store
+# their card credentials for future recurring charges.
+# ---------------------------------------------------------------------------
+def create_cit_payment(sdk)
+  request = {
+    transaction_amount: 100.00,
+    token: '<CARD_TOKEN>',
+    description: 'Monthly subscription — enrollment',
+    installments: 1,
+    payment_method_id: '<PAYMENT_METHOD_ID>',
+    payer: {
+      email: '<PAYER_EMAIL>',
+      identification: {
+        type: '<ID_TYPE>',
+        number: '<ID_NUMBER>'
+      }
+    },
+    # CREDENTIAL_ON_FILE block for the enrollment (first) transaction.
+    point_of_interaction: {
+      linked_to: 'subscription',
+      transaction_data: {
+        # type: "CREDENTIAL_ON_FILE" — new credential-on-file payment type.
+        type: 'CREDENTIAL_ON_FILE',
+        # sub_type: "recurring" — charge is part of a recurring series.
+        sub_type: 'recurring',
+        # storage: "store" — instructs the processor to persist the credentials.
+        storage: 'store',
+        # transaction_initiator: "customer" — the customer triggered this charge.
+        transaction_initiator: 'customer',
+        # first_transaction: true — marks this as the enrollment / anchor payment.
+        first_transaction: true
+      }
+    }
+  }
+
+  custom_headers = {
+    'X-Idempotency-Key': '<SOME_UNIQUE_VALUE>'
+  }
+  custom_request_options = Mercadopago::RequestOptions.new(custom_headers: custom_headers)
+
+  result = sdk.payment.create(request, request_options: custom_request_options)
+  payment = result[:response]
+  puts "CIT payment created. ID: #{payment['id']}, status: #{payment['status']}"
+  payment['id'] # return payment ID to use as reference in subsequent MITs
+rescue MercadoPago::MPApiException => e
+  puts "Status code: #{e.api_response.status_code}"
+  puts "Content: #{e.api_response.content}"
+rescue StandardError => e
+  puts e.message
+end
+
+# ---------------------------------------------------------------------------
+# 2. MIT — Merchant-Initiated Transaction (recurring monthly charge)
+#
+# The merchant charges the customer without customer interaction, using the
+# credentials stored during the CIT enrollment. The CIT payment ID is
+# provided as a reference to the original agreement.
+# ---------------------------------------------------------------------------
+def create_mit_payment(sdk, cit_payment_id)
+  request = {
+    transaction_amount: 100.00,
+    token: '<CARD_TOKEN>',
+    description: 'Monthly subscription — recurring charge',
+    installments: 1,
+    payment_method_id: '<PAYMENT_METHOD_ID>',
+    payer: {
+      email: '<PAYER_EMAIL>',
+      identification: {
+        type: '<ID_TYPE>',
+        number: '<ID_NUMBER>'
+      }
+    },
+    # CREDENTIAL_ON_FILE block for merchant-initiated recurring charges.
+    point_of_interaction: {
+      linked_to: 'subscription',
+      transaction_data: {
+        # type: "CREDENTIAL_ON_FILE" — same type as the enrollment.
+        type: 'CREDENTIAL_ON_FILE',
+        # sub_type: "recurring" — charge belongs to a recurring series.
+        sub_type: 'recurring',
+        # storage: "stored" — credentials were already stored in a prior CIT.
+        storage: 'stored',
+        # transaction_initiator: "merchant" — the merchant triggered this charge.
+        transaction_initiator: 'merchant',
+        # first_transaction: false — not the enrollment; uses stored credentials.
+        first_transaction: false,
+        # reference.id — ID of the CIT payment that anchors this agreement.
+        reference: {
+          id: cit_payment_id.to_s
+        }
+      }
+    }
+  }
+
+  custom_headers = {
+    'X-Idempotency-Key': '<SOME_UNIQUE_VALUE>'
+  }
+  custom_request_options = Mercadopago::RequestOptions.new(custom_headers: custom_headers)
+
+  result = sdk.payment.create(request, request_options: custom_request_options)
+  payment = result[:response]
+  puts "MIT payment created. ID: #{payment['id']}, status: #{payment['status']}"
+rescue MercadoPago::MPApiException => e
+  puts "Status code: #{e.api_response.status_code}"
+  puts "Content: #{e.api_response.content}"
+rescue StandardError => e
+  puts e.message
+end
+
+# ---------------------------------------------------------------------------
+# 3. UCOF-CIT — Unscheduled COF Customer-Initiated Transaction
+#
+# The customer actively initiates a one-off purchase using previously stored
+# credentials. The amount and date were not pre-agreed (unscheduled), but the
+# customer is present and initiates the transaction themselves.
+# ---------------------------------------------------------------------------
+def create_ucof_cit_payment(sdk)
+  request = {
+    transaction_amount: 250.00,
+    token: '<CARD_TOKEN>',
+    description: 'One-off purchase with stored credentials',
+    installments: 1,
+    payment_method_id: '<PAYMENT_METHOD_ID>',
+    payer: {
+      email: '<PAYER_EMAIL>',
+      identification: {
+        type: '<ID_TYPE>',
+        number: '<ID_NUMBER>'
+      }
+    },
+    # CREDENTIAL_ON_FILE block for an unscheduled customer-initiated purchase.
+    point_of_interaction: {
+      linked_to: 'subscription',
+      transaction_data: {
+        # type: "CREDENTIAL_ON_FILE" — credential-on-file payment type.
+        type: 'CREDENTIAL_ON_FILE',
+        # sub_type: "unscheduled" — amount/date not pre-agreed; ad-hoc purchase.
+        sub_type: 'unscheduled',
+        # storage: "stored" — credentials already stored from a prior enrollment.
+        storage: 'stored',
+        # transaction_initiator: "customer" — the customer triggered this charge.
+        transaction_initiator: 'customer',
+        # first_transaction: false — uses previously stored credentials.
+        first_transaction: false
+      }
+    }
+  }
+
+  custom_headers = {
+    'X-Idempotency-Key': '<SOME_UNIQUE_VALUE>'
+  }
+  custom_request_options = Mercadopago::RequestOptions.new(custom_headers: custom_headers)
+
+  result = sdk.payment.create(request, request_options: custom_request_options)
+  payment = result[:response]
+  puts "UCOF-CIT payment created. ID: #{payment['id']}, status: #{payment['status']}"
+rescue MercadoPago::MPApiException => e
+  puts "Status code: #{e.api_response.status_code}"
+  puts "Content: #{e.api_response.content}"
+rescue StandardError => e
+  puts e.message
+end
+
+# Run all three scenarios sequentially.
+# In production, CIT runs once at enrollment; MIT runs on each billing cycle.
+cit_payment_id = create_cit_payment(sdk)
+create_mit_payment(sdk, cit_payment_id) if cit_payment_id
+create_ucof_cit_payment(sdk)

data/examples/preference/create_with_industry_fields.rb

@@ -0,0 +1,137 @@
+# Example: Create a Checkout Preference with industry-specific fields.
+# Demonstrates payer authentication info, item category descriptors,
+# passenger/route details, and shipment address enrichment.
+
+require_relative '../../lib/mercadopago'
+
+sdk = Mercadopago::SDK.new('<ACCESS_TOKEN>')
+
+def create_preference_with_industry_fields(sdk)
+  request = {
+    payer: {
+      name: 'John',
+      surname: 'Smith',
+      email: '<PAYER_EMAIL>',
+      phone: {
+        area_code: '11',
+        number: '999998888'
+      },
+      identification: {
+        type: 'CPF',
+        number: '12345678909'
+      },
+      address: {
+        zip_code: '01310-100',
+        street_name: 'Av. Paulista',
+        street_number: 1000
+      },
+      date_created: '2024-01-01T00:00:00Z',
+      authentication_type: 'Gmail',
+      is_prime_user: false,
+      is_first_purchase_online: false,
+      last_purchase: '2024-01-01T00:00:00Z',
+      registration_date: '2023-01-01T00:00:00Z'
+    },
+    items: [
+      {
+        id: 'ITEM-001',
+        title: 'Flight SAO-RIO',
+        description: 'Round trip, economy class',
+        category_id: 'travels',
+        picture_url: 'https://example.com/img.jpg',
+        quantity: 1,
+        currency_id: 'BRL',
+        unit_price: 450.00,
+        warranty: false,
+        event_date: '2027-01-15T00:00:00.000-03:00',
+        category_descriptor: {
+          passenger: {
+            first_name: 'John',
+            last_name: 'Smith',
+            identification: {
+              type: 'CPF',
+              number: '12345678909'
+            }
+          },
+          route: {
+            departure: 'SAO',
+            destination: 'RIO',
+            departure_date_time: '2027-01-15T08:00:00.000-03:00',
+            arrival_date_time: '2027-01-15T09:30:00.000-03:00',
+            company: 'LATAM'
+          }
+        }
+      },
+      {
+        id: 'ITEM-002',
+        title: 'Travel insurance',
+        description: 'Basic coverage during trip',
+        category_id: 'travels',
+        picture_url: 'https://example.com/insurance.jpg',
+        quantity: 1,
+        currency_id: 'BRL',
+        unit_price: 50.00,
+        warranty: true,
+        event_date: '2027-01-15T00:00:00.000-03:00',
+        category_descriptor: {
+          passenger: {
+            first_name: 'John',
+            last_name: 'Smith',
+            identification: {
+              type: 'CPF',
+              number: '12345678909'
+            }
+          },
+          route: {
+            departure: 'SAO',
+            destination: 'RIO',
+            departure_date_time: '2027-01-15T08:00:00.000-03:00',
+            arrival_date_time: '2027-01-15T09:30:00.000-03:00',
+            company: 'LATAM'
+          }
+        }
+      }
+    ],
+    shipments: {
+      mode: 'custom',
+      local_pickup: false,
+      express_shipment: false,
+      cost: 15.0,
+      free_shipping: false,
+      receiver_address: {
+        zip_code: '01310-100',
+        street_name: 'Av. Paulista',
+        street_number: 1000,
+        state_name: 'Sao Paulo',
+        city_name: 'Sao Paulo',
+        floor: '2',
+        apartment: 'A'
+      }
+    },
+    back_urls: {
+      success: 'https://example.com/success',
+      failure: 'https://example.com/failure',
+      pending: 'https://example.com/pending'
+    },
+    auto_return: 'approved',
+    external_reference: 'MP0001',
+    notification_url: 'https://example.com/notifications',
+    statement_descriptor: 'MYSTORE'
+  }
+
+  custom_headers = {
+    'X-Idempotency-Key': '<SOME_UNIQUE_VALUE>'
+  }
+  custom_request_options = Mercadopago::RequestOptions.new(custom_headers: custom_headers)
+
+  result = sdk.preference.create(request, request_options: custom_request_options)
+  preference = result[:response]
+
+  puts "Preference id: #{preference['id']}"
+  puts "Init point: #{preference['init_point']}"
+
+rescue StandardError => e
+  puts e.message
+end
+
+create_preference_with_industry_fields(sdk)

data/lib/mercadopago/config/request_options.rb

@@ -13,6 +13,9 @@ module Mercadopago
   #   opts = Mercadopago::RequestOptions.new(access_token: token, connection_timeout: 120.0)
   #   sdk.payment.get(123, request_options: opts)
   class RequestOptions
+    DEFAULT_RETRY_ON  = [429, 500, 502, 503, 504].freeze
+    DEFAULT_MAX_DELAY = 30_000
+
     # @!attribute [r] access_token
     #   @return [String, nil] OAuth access token used for Bearer authentication
     # @!attribute [r] connection_timeout
@@ -27,8 +30,18 @@ module Mercadopago
     #   @return [String, nil] MercadoPago platform identifier (x-platform-id header)
     # @!attribute [r] max_retries
     #   @return [Integer] maximum automatic retries on transient HTTP errors (default: 3)
+    # @!attribute [r] initial_delay_ms
+    #   @return [Integer, nil] initial backoff delay in ms (nil = SDK default)
+    # @!attribute [r] max_delay_ms
+    #   @return [Integer] maximum backoff delay cap in ms (default: 30_000)
+    # @!attribute [r] jitter
+    #   @return [Boolean] add random jitter to retry delay using SecureRandom
+    # @!attribute [r] retry_on
+    #   @return [Array<Integer>, nil] HTTP status codes to retry (nil = DEFAULT_RETRY_ON)
+    # @!attribute [r] on_retry
+    #   @return [Proc, nil] callback(attempt, error) invoked before each retry
     attr_reader :access_token, :connection_timeout, :custom_headers, :corporation_id, :integrator_id,
-                :platform_id, :max_retries
+                :platform_id, :max_retries, :initial_delay_ms, :max_delay_ms, :jitter, :retry_on, :on_retry
 
     # Builds a new request configuration.
     #
@@ -39,6 +52,11 @@ module Mercadopago
     # @param integrator_id [String, nil] integrator identifier for certified partners
     # @param platform_id [String, nil] platform identifier for marketplace integrations
     # @param max_retries [Integer] retry limit for transient failures (429, 5xx)
+    # @param initial_delay_ms [Integer, nil] initial backoff delay in ms
+    # @param max_delay_ms [Integer] maximum backoff delay cap in ms
+    # @param jitter [Boolean] add SecureRandom jitter to retry delay
+    # @param retry_on [Array<Integer>, nil] HTTP status codes to retry
+    # @param on_retry [Proc, nil] callback invoked before each retry
     # @raise [TypeError] if any parameter is not the expected type
     def initialize(access_token: nil,
                    connection_timeout: 60.0,
@@ -46,7 +64,12 @@ module Mercadopago
                    corporation_id: nil,
                    integrator_id: nil,
                    platform_id: nil,
-                   max_retries: 3)
+                   max_retries: 3,
+                   initial_delay_ms: nil,
+                   max_delay_ms: DEFAULT_MAX_DELAY,
+                   jitter: false,
+                   retry_on: nil,
+                   on_retry: nil)
       self.access_token = access_token
       self.connection_timeout = connection_timeout
       self.custom_headers = custom_headers
@@ -54,6 +77,11 @@ module Mercadopago
       self.integrator_id = integrator_id
       self.platform_id = platform_id
       self.max_retries = max_retries
+      @initial_delay_ms = initial_delay_ms
+      @max_delay_ms     = max_delay_ms
+      @jitter           = jitter
+      @retry_on         = retry_on
+      @on_retry         = on_retry
 
       @config = Config.new
     end

data/lib/mercadopago/core/mp_base.rb

@@ -1,6 +1,8 @@
 # typed: false
 # frozen_string_literal: true
 
+require 'cgi'
+
 module Mercadopago
   # Abstract base class for every API resource (Payment, Customer, Order, etc.).
   #
@@ -61,6 +63,11 @@ module Mercadopago
       headers
     end
 
+    # Encodes a dynamic URL path segment before interpolation.
+    def _path_param(value)
+      CGI.escape(value.to_s).gsub('+', '%20')
+    end
+
     # Performs a GET request against the MercadoPago API.
     #
     # @param uri [String] API path (e.g. "/v1/payments/123")
@@ -74,8 +81,16 @@ module Mercadopago
       request_options = _check_request_options(request_options)
       headers = _check_headers(request_options)
 
-      @http_client.get(url: @config.api_base_url + uri, headers: headers, params: filters,
-                       timeout: request_options.connection_timeout, maxretries: request_options.max_retries)
+      MPResponse.new(
+        @http_client.get(url: @config.api_base_url + uri, headers: headers, params: filters,
+                         timeout: request_options.connection_timeout,
+                         maxretries: request_options.max_retries,
+                         retry_on: request_options.retry_on,
+                         initial_delay_ms: request_options.initial_delay_ms,
+                         max_delay_ms: request_options.max_delay_ms,
+                         jitter: request_options.jitter,
+                         on_retry: request_options.on_retry)
+      )
     end
 
     # Performs a POST request against the MercadoPago API.
@@ -94,7 +109,10 @@ module Mercadopago
       headers = _check_headers(request_options, { 'Content-Type': @config.mime_json })
       payload = data&.to_json
 
-      @http_client.post(url: @config.api_base_url + uri, data: payload, headers: headers, timeout: request_options.connection_timeout)
+      MPResponse.new(
+        @http_client.post(url: @config.api_base_url + uri, data: payload, headers: headers,
+                          timeout: request_options.connection_timeout)
+      )
     end
 
     # Performs a PUT request against the MercadoPago API.
@@ -112,8 +130,10 @@ module Mercadopago
       request_options = _check_request_options(request_options)
       headers = _check_headers(request_options, { 'Content-Type': @config.mime_json })
 
-      @http_client.put(url: @config.api_base_url + uri, data: data.to_json, headers: headers,
-                       timeout: request_options.connection_timeout)
+      MPResponse.new(
+        @http_client.put(url: @config.api_base_url + uri, data: data.to_json, headers: headers,
+                         timeout: request_options.connection_timeout)
+      )
     end
 
     # Performs a DELETE request against the MercadoPago API.
@@ -125,8 +145,10 @@ module Mercadopago
       request_options = _check_request_options(request_options)
       headers = _check_headers(request_options)
 
-      @http_client.delete(url: @config.api_base_url + uri, headers: headers,
-                          timeout: request_options.connection_timeout)
+      MPResponse.new(
+        @http_client.delete(url: @config.api_base_url + uri, headers: headers,
+                            timeout: request_options.connection_timeout)
+      )
     end
   end
 end