mercadopago-sdk 3.2.1 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7dfcf7186c9d72f9b02200699acf4807a80aee9014b0c8b1905097850b6ed5fe
-  data.tar.gz: 3cb25341c72de1d3686fe217c7fb81e3ec0bfa87a74cf80cee163b1c3ec6a0d6
+  metadata.gz: fb7488c81eb88390ec65887c4f7626f51fabd3a268fec20e37a21c4bcb857551
+  data.tar.gz: 80ffcd3be59f116220171f3b4b053c0b48a5e222a09c22e4e9063ef6d8514826
 SHA512:
-  metadata.gz: c446ae477af4b97192b150ac3618b2e363d0d98dc8cb060aa08a26f4dc13811612fa69d6f618180fcd315f77cdd83757872f4c052b6689a86ab533411a7fd8bb
-  data.tar.gz: '086a6f76e544b588f0f09a55d59946bd68f9eb373dbd3328841fe977168273e2b5a2d35d9e30cf0b9672d81fd31947b8fcdc1bfaca17d21a1b6529e55adbad7b'
+  metadata.gz: 6fa0b01c59f95ee75586f5685212a899fd717963230cafafd237b2b8d981f7ecb75327446419323f88933e50fcc85850efbddafcb0bdd6b630de1d043b77fd6a
+  data.tar.gz: 101c97f483a49e8317b8ab9748e2433f42a0334969185fa26f21ee61ef0d139883cb22aa80618565dcea6702195868ea886893132b650b4dd2287b5c8c8d59c0

data/.github/workflows/ci.yml

@@ -1,43 +1,45 @@
-name: Ruby
+name: CI
 
 on:
   push:
-    branches: [ master ]
+    branches: ["master"]
   pull_request:
-    branches: [ master ]
+    branches: ["master"]
 
 jobs:
   test:
+    name: Test on Ruby ${{ matrix.ruby-version }}
     runs-on: ubuntu-latest
-    container: ruby:3.4
+    container: ruby:${{ matrix.ruby-version }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ["3.3", "3.4"]
 
     steps:
-    - name: Checkout code
-      uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
-      with:
-        ref: ${{ github.event.pull_request.head.ref }}
-        repository: ${{ github.event.pull_request.head.repo.full_name }}
-
-    - name: Cache gems
-      uses: actions/cache@caa296126883cff596d87d8935842f9db880ef25 # v6
-      with:
-        path: vendor/bundle
-        key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }}
-        restore-keys: |
-          ${{ runner.os }}-gems-
-
-    - name: Install dependencies
-      run: |
-        bundle config set --local path vendor/bundle
-        bundle install
-
-    - name: Rubocop
-      run: bundle exec rubocop lib
-
-    # Integration tests disabled: they require a valid MercadoPago ACCESS_TOKEN
-    # that is not available in the CI environment. To run them locally:
-    #   ACCESS_TOKEN=<your_token> bundle exec rake
-    # - name: Run tests
-    #   run: bundle exec rake
-    #   env:
-    #     ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN_V2 }}
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4
+
+      - name: Configure git safe directory
+        run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
+
+      - name: Install dependencies
+        run: bundle install
+
+      - name: Lint with Rubocop
+        run: bundle exec rubocop lib
+
+      - name: Run unit tests
+        run: bundle exec rake test
+
+      - name: Dependency audit
+        run: |
+          gem install bundler-audit --no-document
+          bundle-audit check --update
+
+      - name: Dependency review
+        if: github.event_name == 'pull_request'
+        uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v4
+        with:
+          fail-on-severity: high

data/.github/workflows/release.yml

@@ -2,7 +2,7 @@ name: Release SDK - Publish Gem
 
 on:
   release:
-    types: [created]
+    types: [published]
 
 jobs:
   release:
@@ -14,14 +14,14 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
-
-      - name: Install dependencies
-        run: bundle install
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
 
       - name: Configure git safe directory
         run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
 
+      - name: Install dependencies
+        run: bundle install
+
       - name: Build gem
         run: gem build *.gemspec
 
@@ -29,6 +29,3 @@ jobs:
         env:
           GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
         run: gem push *.gem
-
-      - name: Wait for release to propagate
-        run: gem install rubygems-await

data/.gitignore

@@ -2,5 +2,6 @@
 bin/
 config/*yml
 pkg/
+vendor/
 *.log
 *.gem

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/.rubocop_todo.yml

@@ -48,8 +48,14 @@ Metrics/MethodLength:
 
 # Offense count: 3
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
+Metrics/ModuleLength:
+  Exclude:
+    - 'lib/mercadopago/resources/order/request.rb'
+
 Metrics/ParameterLists:
   Max: 7
+  Exclude:
+    - 'lib/mercadopago/resources/order/request.rb'
 
 # Offense count: 1
 Naming/AccessorMethodName:

data/CHANGELOG.md

@@ -5,6 +5,44 @@ 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.4.0] - 2026-08-11
+
+### Added
+- **Automatic Payments example**: two-step recurring flow ([#156](https://github.com/mercadopago/sdk-ruby/pull/156))
+- **Pagination**: support `data` key for Orders v2 API and string paging totals ([#156](https://github.com/mercadopago/sdk-ruby/pull/156))
+
+### Fixed
+- **Stored credential**: rename `prev_transaction_ref` to `previous_transaction_reference` ([#156](https://github.com/mercadopago/sdk-ruby/pull/156))
+- **`Iterator#call`**: use keyword args for Ruby 4.0 strict kwarg separation ([#156](https://github.com/mercadopago/sdk-ruby/pull/156))
+
+### CI
+- Standardize CI/CD workflows ([#166](https://github.com/mercadopago/sdk-ruby/pull/166))
+- Migrate tests to mock-based unit tests ([#166](https://github.com/mercadopago/sdk-ruby/pull/166))
+- Fix SDK bugs discovered during mock test migration ([#166](https://github.com/mercadopago/sdk-ruby/pull/166))
+- Fix Ruby CI: drop 3.2 matrix (gemspec requires >=3.3), add `safe.directory` ([#166](https://github.com/mercadopago/sdk-ruby/pull/166))
+
+## [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.1)
+    mercadopago-sdk (3.4.0)
       faraday (~> 2.0)
       json (~> 2.5)
 
@@ -17,7 +17,7 @@ GEM
     faraday-net_http (3.4.4)
       net-http (~> 0.5)
     io-console (0.8.2)
-    json (2.21.1)
+    json (2.21.2)
     language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
     logger (1.7.0)

data/examples/order/create_automatic_payment.rb

@@ -0,0 +1,162 @@
+require_relative '../../lib/mercadopago'
+
+# Mercado Pago Create Order — Automatic Payments (recurring charges).
+#
+# Demonstrates the two-step Automatic Payments flow:
+#   1. First payment  — CVV-validated charge that registers the card credential.
+#   2. Recurring charge — subsequent MIT charge without CVV, referencing step 1.
+#
+# Prerequisites:
+#   - A customer created via POST /v1/customers             → customer_id
+#   - A payment profile created via POST /v1/customers/{id}/payment-profiles → payment_profile_id
+
+sdk = Mercadopago::SDK.new('<ACCESS_TOKEN>')
+
+# ── Step 1: First payment ─────────────────────────────────────────────────────
+# Registers the card credential with first_payment: true.
+# No prev_transaction_ref is needed on the first charge.
+def create_first_payment(sdk, customer_id:, payment_profile_id:, payer_email:, card_token:)
+  request = {
+    type: 'online',
+    processing_mode: 'automatic',
+    total_amount: '100.00',
+    external_reference: 'subscription-001-payment-1',
+    payer: {
+      email: payer_email,
+      customer_id: customer_id
+    },
+    transactions: {
+      payments: [
+        {
+          amount: '100.00',
+          payment_method: {
+            id: 'master',
+            type: 'credit_card',
+            token: card_token,
+            installments: 1
+          },
+          automatic_payments: {
+            payment_profile_id: payment_profile_id
+          },
+          stored_credential: {
+            payment_initiator: 'customer',
+            reason: 'recurring',
+            first_payment: true
+          }
+        }
+      ]
+    }
+  }
+
+  custom_headers = { 'X-Idempotency-Key': '<IDEMPOTENCY_KEY_FIRST>' }
+  request_options = Mercadopago::RequestOptions.new(custom_headers: custom_headers)
+
+  sdk.order.create(request, request_options: request_options)
+rescue StandardError => e
+  puts e.message
+  nil
+end
+
+# ── Step 2: Recurring charge ──────────────────────────────────────────────────
+# Subsequent MIT charge — no card token needed, uses the payment profile.
+# prev_transaction_ref links this charge to the original authorization.
+def create_recurring_charge(sdk,
+                             customer_id:,
+                             payment_profile_id:,
+                             payer_email:,
+                             previous_transaction_reference:,
+                             sequence_number:)
+  request = {
+    type: 'online',
+    processing_mode: 'automatic_async',
+    total_amount: '100.00',
+    external_reference: "subscription-001-payment-#{sequence_number}",
+    payer: {
+      email: payer_email,
+      customer_id: customer_id
+    },
+    transactions: {
+      payments: [
+        {
+          amount: '100.00',
+          automatic_payments: {
+            payment_profile_id: payment_profile_id,
+            retries: 3,
+            schedule_date: '2026-09-01T00:00:00.000-04:00',
+            due_date: '2026-09-05T00:00:00.000-04:00'
+          },
+          stored_credential: {
+            payment_initiator: 'merchant',
+            reason: 'recurring',
+            first_payment: false,
+            previous_transaction_reference: previous_transaction_reference
+          },
+          subscription_data: {
+            invoice_id: "INV-00#{sequence_number}",
+            billing_date: '2026-08-01',
+            subscription_sequence: {
+              number: sequence_number,
+              total: 12
+            },
+            invoice_period: {
+              type: 'monthly',
+              period: 1
+            }
+          }
+        }
+      ]
+    }
+  }
+
+  custom_headers = { 'X-Idempotency-Key': "<IDEMPOTENCY_KEY_RECURRING_#{sequence_number}>" }
+  request_options = Mercadopago::RequestOptions.new(custom_headers: custom_headers)
+
+  sdk.order.create(request, request_options: request_options)
+rescue StandardError => e
+  puts e.message
+  nil
+end
+
+# ── Run the flow ──────────────────────────────────────────────────────────────
+customer_id       = '<CUSTOMER_ID>'
+payment_profile_id = '<PAYMENT_PROFILE_ID>'
+payer_email       = '<PAYER_EMAIL>'
+card_token        = '<CARD_TOKEN>'
+
+# First payment
+first_result = create_first_payment(
+  sdk,
+  customer_id: customer_id,
+  payment_profile_id: payment_profile_id,
+  payer_email: payer_email,
+  card_token: card_token
+)
+
+if first_result
+  first_order = first_result[:response]
+  puts "First payment order ID: #{first_order['id']}"
+  puts "Status: #{first_order['status']}"
+
+  # Save the payment ID for the next recurring charge
+  first_payment_id = first_order.dig('transactions', 'payments', 0, 'id')
+  puts "First payment ID (save for next charge): #{first_payment_id}"
+
+  # Recurring charge
+  if first_payment_id
+    recurring_result = create_recurring_charge(
+      sdk,
+      customer_id: customer_id,
+      payment_profile_id: payment_profile_id,
+      payer_email: payer_email,
+      previous_transaction_reference: first_payment_id,
+      sequence_number: 2
+    )
+
+    if recurring_result
+      recurring_order = recurring_result[:response]
+      puts "\nRecurring charge order ID: #{recurring_order['id']}"
+      puts "Status: #{recurring_order['status']}"
+      puts "Status detail: #{recurring_order['status_detail']}"
+    end
+  end
+end

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/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