mercadopago-sdk 3.2.1 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7dfcf7186c9d72f9b02200699acf4807a80aee9014b0c8b1905097850b6ed5fe
-  data.tar.gz: 3cb25341c72de1d3686fe217c7fb81e3ec0bfa87a74cf80cee163b1c3ec6a0d6
+  metadata.gz: 518cbc2c53d00de1452bf210afff62915ba381a970d084ca42a848e5604fa582
+  data.tar.gz: 85468b9a03305eb33e4b053a4aae7149cbacd1ceb33df494e25bf63391b2bfea
 SHA512:
-  metadata.gz: c446ae477af4b97192b150ac3618b2e363d0d98dc8cb060aa08a26f4dc13811612fa69d6f618180fcd315f77cdd83757872f4c052b6689a86ab533411a7fd8bb
-  data.tar.gz: '086a6f76e544b588f0f09a55d59946bd68f9eb373dbd3328841fe977168273e2b5a2d35d9e30cf0b9672d81fd31947b8fcdc1bfaca17d21a1b6529e55adbad7b'
+  metadata.gz: 59839cc98cb80e2718b5694f05559b0a73fe23f04b953c0d172bb80b0609c220f673bd88952326eab551bcd52edd0beec0cb2173c188b9ea9cace45c5513b75b
+  data.tar.gz: 4e2e68a2fef69a84eafba9c8fa6b877d214f953e764d26525f48dca5cb812686195fe7fea80085704c8827de1d023fe385c366dede92156a98e680d51ae8dbce

data/.github/workflows/ci.yml

@@ -13,13 +13,13 @@ jobs:
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # 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@caa296126883cff596d87d8935842f9db880ef25 # 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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # 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.1)
+    mercadopago-sdk (3.3.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/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

data/lib/mercadopago/core/mp_base.rb

@@ -81,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.
@@ -101,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.
@@ -119,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.
@@ -132,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

data/lib/mercadopago/errors/exceptions.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Mercadopago
+  # Base exception for all MercadoPago API errors.
+  #
+  # All subtypes inherit from this class, preserving backward-compatible
+  # +rescue MercadoPagoError+ patterns while enabling specific handling
+  # per HTTP status code.
+  #
+  # @attr_reader [Integer] status_code HTTP status code (e.g. 400, 401, 500)
+  # @attr_reader [String]  error       Machine-readable error code from the API body
+  # @attr_reader [Array]   causes      List of detailed cause hashes from the API body
+  # @attr_reader [String, nil] request_id x-request-id header for support diagnostics
+  class MercadoPagoError < StandardError
+    attr_reader :status_code, :error, :causes, :request_id
+
+    # @param status_code [Integer] HTTP status code
+    # @param response_body [Hash] parsed API error body
+    # @param request_id [String, nil] value of the x-request-id response header
+    def initialize(status_code, response_body = nil, request_id = nil)
+      body = (response_body.is_a?(Hash) ? response_body : {})
+      super(body['message'] || body[:message] || body['error'] || body[:error] || 'MercadoPago API error')
+      @status_code = status_code
+      @error       = body['error']  || body[:error]  || ''
+      @causes      = body['cause']  || body[:cause]  || []
+      @request_id  = request_id
+    end
+  end
+
+  # HTTP 400 Bad Request — validation or syntax error.
+  class MPBadRequestError < MercadoPagoError; end
+
+  # HTTP 401 Unauthorized — missing or invalid credentials.
+  class MPAuthenticationError < MercadoPagoError; end
+
+  # HTTP 402 Payment Required — transaction processing error (AP/Orders).
+  class MPPaymentError < MercadoPagoError; end
+
+  # HTTP 403 Forbidden.
+  class MPForbiddenError < MercadoPagoError; end
+
+  # HTTP 404 Not Found.
+  class MPNotFoundError < MercadoPagoError; end
+
+  # HTTP 409 Conflict — idempotency-key conflict or state-machine conflict.
+  class MPIdempotencyError < MercadoPagoError; end
+
+  # HTTP 422 Unprocessable Entity — business-rule violation.
+  class MPValidationError < MercadoPagoError; end
+
+  # HTTP 423 Locked — idempotency key temporarily locked (retryable).
+  class MPResourceLockedError < MercadoPagoError; end
+
+  # HTTP 424 Failed Dependency — internal dependency failure (retryable).
+  class MPDependencyError < MercadoPagoError; end
+
+  # HTTP 429 Too Many Requests.
+  # Exposes +retry_after+ (seconds) from the +Retry-After+ response header.
+  #
+  # @attr_reader [Integer, nil] retry_after seconds to wait before retrying
+  class MPRateLimitError < MercadoPagoError
+    attr_reader :retry_after
+
+    def initialize(status_code, response_body = nil, retry_after = nil, request_id = nil)
+      super(status_code, response_body, request_id)
+      @retry_after = retry_after
+    end
+  end
+
+  # HTTP 5xx Server Error.
+  class MPServerError < MercadoPagoError; end
+
+  # Transport-level or network error (timeout, DNS failure, SSL error).
+  class MPConnectionError < MercadoPagoError
+    def initialize(cause)
+      super(0, { 'error' => 'connection_error', 'message' => cause.to_s })
+    end
+  end
+
+  # @!visibility private
+  STATUS_MAP = {
+    400 => MPBadRequestError,
+    401 => MPAuthenticationError,
+    402 => MPPaymentError,
+    403 => MPForbiddenError,
+    404 => MPNotFoundError,
+    409 => MPIdempotencyError,
+    422 => MPValidationError,
+    423 => MPResourceLockedError,
+    424 => MPDependencyError
+  }.freeze
+
+  # Factory: maps an HTTP status code to the most specific exception subtype.
+  #
+  # @param status_code [Integer] HTTP status code from the API response
+  # @param response_body [Hash] parsed API error body
+  # @param retry_after [Integer, nil] seconds from Retry-After header (429 only)
+  # @return [MercadoPagoError] the appropriate subtype instance
+  def self.build_error(status_code, response_body = nil, retry_after = nil)
+    return MPRateLimitError.new(status_code, response_body, retry_after) if status_code == 429
+
+    klass = STATUS_MAP[status_code]
+    return klass.new(status_code, response_body) if klass
+    return MPServerError.new(status_code, response_body) if status_code >= 500
+
+    MercadoPagoError.new(status_code, response_body)
+  end
+end

data/lib/mercadopago/errors/response.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Mercadopago
+  # Backward-compatible Hash wrapper for MercadoPago API responses.
+  #
+  # Wraps the raw +{ status:, response: }+ hash returned by every
+  # {MPBase} helper. Existing code that reads +result[:status]+ or
+  # +result[:response]+ continues to work unchanged.
+  #
+  # New code may call {#raise_for_status!} to get a typed exception or
+  # use the convenience accessors {#success?}, {#error_message}, {#error_causes}.
+  class MPResponse < Hash
+    # @param raw [Hash] the raw response hash with +:status+ and +:response+ keys
+    # @param request_id [String, nil] value of the +x-request-id+ response header
+    def initialize(raw = {}, request_id: nil)
+      super()
+      update(raw)
+      @request_id = request_id
+    end
+
+    # @return [Integer] HTTP status code
+    def status_code
+      self[:status] || self['status'] || 0
+    end
+
+    # @return [Boolean] true for 2xx status codes
+    def success?
+      status_code >= 200 && status_code < 300
+    end
+
+    # @return [String] human-readable error message from the API body
+    def error_message
+      body = self[:response] || self['response'] || {}
+      body.is_a?(Hash) ? (body['message'] || body[:message] || '') : ''
+    end
+
+    # @return [Array] cause list from the API body
+    def error_causes
+      body = self[:response] || self['response'] || {}
+      body.is_a?(Hash) ? (body['cause'] || body[:cause] || []) : []
+    end
+
+    # @return [String, nil] x-request-id header value
+    def request_id
+      @request_id
+    end
+
+    # Raises a typed {MercadoPagoError} subclass when the response status is not 2xx.
+    #
+    # @raise [MercadoPagoError] (or subtype) when status >= 300
+    def raise_for_status!
+      return if success?
+
+      body = self[:response] || self['response'] || {}
+      raise Mercadopago.build_error(status_code, body)
+    end
+  end
+end