mercadopago-sdk 3.1.0 → 3.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3f9c30f87f2a16606d96b4b955e9c84b2297608fa13ae849c7c1fa0c5e81e8e
-  data.tar.gz: a85e57aab4d0cb2a0916e272b3cba305d0c43bc8b71ac395c5f20436e19b5ba0
+  metadata.gz: 7dfcf7186c9d72f9b02200699acf4807a80aee9014b0c8b1905097850b6ed5fe
+  data.tar.gz: 3cb25341c72de1d3686fe217c7fb81e3ec0bfa87a74cf80cee163b1c3ec6a0d6
 SHA512:
-  metadata.gz: eb1e14c6daa97a705470095aad0577f4b16691b62e88afde38337a65cb459adc3875611c9c245bab111ed67dece2c52552bf28bddb2f3d190974b562e0197100
-  data.tar.gz: 63222ba960570cec0eeeae9a267d4d549ef5862bd9da27918c62acee2aa6689d93e21fb5f91c5ffe0be374d28fcad6bb429bafb34011376cfb18d85c53234731
+  metadata.gz: c446ae477af4b97192b150ac3618b2e363d0d98dc8cb060aa08a26f4dc13811612fa69d6f618180fcd315f77cdd83757872f4c052b6689a86ab533411a7fd8bb
+  data.tar.gz: '086a6f76e544b588f0f09a55d59946bd68f9eb373dbd3328841fe977168273e2b5a2d35d9e30cf0b9672d81fd31947b8fcdc1bfaca17d21a1b6529e55adbad7b'

data/.github/workflows/ci.yml

@@ -13,13 +13,13 @@ jobs:
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v6
+      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@v4
+      uses: actions/cache@caa296126883cff596d87d8935842f9db880ef25 # 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@v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
 
       - name: Install dependencies
         run: bundle install

data/.pre-commit-config.yaml

@@ -4,7 +4,7 @@ repos:
     rev: v2.0.0
     hooks:
       - id: pre_commit_hook
-        stages: [commit]
+        stages: [pre-commit]
       - id: post_commit_hook
         stages: [post-commit]
 
@@ -13,7 +13,7 @@ repos:
     rev: 1.2.2
     hooks:
       - id: pre_commit_hook
-        stages: [commit]
+        stages: [pre-commit]
         verbose: true
       - id: post_commit_hook
         stages: [post-commit]

data/CHANGELOG.md

@@ -5,6 +5,34 @@ 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.2.0] - 2026-06-30
+
+### Added
+
+- **Orders**: helper for creating Checkout Pro orders
+  (`sdk.order.create_checkout_pro`). The helper defaults the required
+  Checkout Pro fields when omitted, validates conflicting values, and
+  returns the created order response with the `checkout_url`.
+
+### Fixed
+
+- **Request options**: custom headers now replace generated headers
+  case-insensitively, avoiding duplicate idempotency headers.
+
+## [3.2.0-beta.1] - 2026-06-24
+
+### Added
+
+- **Orders**: helper for creating Checkout Pro orders
+  (`sdk.order.create_checkout_pro`). The helper defaults the required
+  Checkout Pro fields when omitted, validates conflicting values, and
+  returns the created order response with the `checkout_url`.
+
+### Fixed
+
+- **Request options**: custom headers now replace generated headers
+  case-insensitively, avoiding duplicate idempotency headers.
+
 ## [3.1.0] - 2026-05-27
 
 ### Added

data/Gemfile

@@ -5,7 +5,7 @@ source 'https://rubygems.org'
 group :development, :test do
   gem 'rake'
   gem 'minitest', '~> 5.27'
-  gem 'rubocop', '~> 1.70', require: false
+  gem 'rubocop', '~> 1.88', require: false
 end
 
 gemspec

data/Gemfile.lock

@@ -1,51 +1,59 @@
 PATH
   remote: .
   specs:
-    mercadopago-sdk (3.1.0)
+    mercadopago-sdk (3.2.1)
       faraday (~> 2.0)
       json (~> 2.5)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    ast (2.4.2)
+    ast (2.4.3)
     coderay (1.1.3)
-    faraday (2.14.2)
+    faraday (2.14.3)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger
-    faraday-net_http (3.4.3)
+    faraday-net_http (3.4.4)
       net-http (~> 0.5)
-    json (2.19.5)
-    language_server-protocol (3.17.0.3)
+    io-console (0.8.2)
+    json (2.21.1)
+    language_server-protocol (3.17.0.6)
+    lint_roller (1.1.0)
     logger (1.7.0)
-    method_source (1.0.0)
+    method_source (1.1.0)
     minitest (5.27.0)
     net-http (0.9.1)
       uri (>= 0.11.1)
-    parallel (1.26.3)
-    parser (3.3.6.0)
+    parallel (2.1.0)
+    parser (3.3.11.1)
       ast (~> 2.4.1)
       racc
-    pry (0.14.1)
+    prism (1.9.0)
+    pry (0.16.0)
       coderay (~> 1.1)
       method_source (~> 1.0)
+      reline (>= 0.6.0)
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.4.2)
-    regexp_parser (2.10.0)
-    rubocop (1.70.0)
+    regexp_parser (2.12.0)
+    reline (0.6.3)
+      io-console (~> 0.5)
+    rubocop (1.88.2)
       json (~> 2.3)
-      language_server-protocol (>= 3.17.0)
-      parallel (~> 1.10)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.36.2, < 2.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.37.0)
-      parser (>= 3.3.1.0)
+    rubocop-ast (1.50.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
     ruby-progressbar (1.13.0)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
@@ -60,7 +68,7 @@ DEPENDENCIES
   minitest (~> 5.27)
   pry (~> 0.14)
   rake
-  rubocop (~> 1.70)
+  rubocop (~> 1.88)
 
 BUNDLED WITH
    2.5.23

data/examples/order/create_checkout_pro.rb

@@ -0,0 +1,167 @@
+require_relative '../../lib/mercadopago'
+
+
+sdk = Mercadopago::SDK.new('<ACCESS_TOKEN>')
+
+def create_checkout_pro_order(sdk)
+  request = {
+    total_amount: '500.00',
+    external_reference: 'ext_ref_checkout_pro',
+    capture_mode: 'automatic',
+    marketplace_fee: '5.00',
+    description: 'Travel package SAO-RIO with insurance',
+    expiration_time: 'P1D',
+    payer: {
+      email: '<PAYER_EMAIL>',
+      first_name: 'John',
+      last_name: 'Smith',
+      phone: {
+        area_code: '11',
+        number: '999998888'
+      },
+      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: {
+        zip_code: '01310-100',
+        street_name: 'Av. Paulista',
+        street_number: '1000',
+        neighborhood: 'Bela Vista',
+        city: 'Sao Paulo',
+        state_name: 'Sao Paulo',
+        city_name: 'Sao Paulo',
+        floor: '2',
+        apartment: 'A'
+      }
+    },
+    config: {
+      statement_descriptor: 'MYSTORE',
+      default_payment_due_date: 'P1D',
+      online: {
+        available_from: '2026-01-01T00:00:00Z',
+        allowed_user_type: 'account_only',
+        success_url: 'https://example.com/success',
+        failure_url: 'https://example.com/failure',
+        pending_url: 'https://example.com/pending',
+        auto_return: 'approved',
+        tracks: [
+          {
+            type: 'google_ad',
+            values: {
+              conversion_id: '21312312312123',
+              conversion_label: 'TEST'
+            }
+          },
+          {
+            type: 'facebook_ad',
+            values: {
+              pixel_id: '21312312312123'
+            }
+          }
+        ]
+      },
+      payment_method: {
+        max_installments: 12,
+        not_allowed_ids: ['amex'],
+        not_allowed_types: ['ticket'],
+        installments: {
+          interest_free: {
+            type: 'range',
+            values: [2, 6]
+          }
+        }
+      }
+    },
+    items: [
+      {
+        external_code: 'ITEM-001',
+        title: 'Flight SAO-RIO',
+        description: 'Round trip, economy class',
+        category_id: 'travels',
+        picture_url: 'https://example.com/img.jpg',
+        quantity: 1,
+        unit_price: '450.00',
+        type: 'travel',
+        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',
+        title: 'Travel insurance',
+        description: 'Basic coverage during trip',
+        category_id: 'travels',
+        picture_url: 'https://example.com/insurance.jpg',
+        quantity: 1,
+        unit_price: '50.00',
+        type: 'travel',
+        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'
+          }
+        }
+      }
+    ]
+  }
+
+  custom_headers = {
+    'X-Idempotency-Key': '<SOME_UNIQUE_VALUE>'
+  }
+  custom_request_options = Mercadopago::RequestOptions.new(custom_headers: custom_headers)
+
+  result = sdk.order.create_checkout_pro(request, request_options: custom_request_options)
+  order = result[:response]
+
+  puts "Order id: #{order['id']}"
+  puts "Status: #{order['status']}"
+  puts "Redirect buyer to Checkout Pro: #{order['checkout_url']}"
+
+rescue StandardError => e
+  puts e.message
+end
+
+create_checkout_pro_order(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/config.rb

@@ -9,7 +9,7 @@ module Mercadopago
   # there is no need to instantiate this class directly.
   class Config
     # Current SDK version following SemVer.
-    @@VERSION = '3.1.0'
+    @@VERSION = '3.2.0'
 
     # User-Agent string sent with every HTTP request for server-side tracking.
     @@USER_AGENT = "MercadoPago Ruby SDK v#{@@VERSION}"

data/lib/mercadopago/config/request_options.rb

@@ -77,9 +77,7 @@ module Mercadopago
       headers['x-integrator-id'] = @integrator_id unless @integrator_id.nil?
       headers['x-platform-id'] = @platform_id unless @platform_id.nil?
 
-      headers.merge!(@custom_headers) unless @custom_headers.nil?
-
-      headers
+      merge_custom_headers(headers)
     end
 
     # @param value [String, nil] OAuth access token
@@ -137,5 +135,15 @@ module Mercadopago
 
       @max_retries = value
     end
+
+    private
+
+    def merge_custom_headers(headers)
+      return headers if @custom_headers.nil?
+
+      custom_header_names = @custom_headers.keys.map { |key| key.to_s.downcase }
+      headers.reject! { |key, _value| custom_header_names.include?(key.to_s.downcase) }
+      headers.merge!(@custom_headers)
+    end
   end
 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")

data/lib/mercadopago/resources/advanced_payment.rb

@@ -29,7 +29,7 @@ module Mercadopago
     # @param request_options [RequestOptions, nil] per-call configuration override
     # @return [Hash{Symbol => Object}] +:status+ and +:response+ with payment details
     def get(advanced_payment_id, request_options: nil)
-      _get(uri: "/v1/advanced_payments/#{advanced_payment_id}", request_options: request_options)
+      _get(uri: "/v1/advanced_payments/#{_path_param(advanced_payment_id)}", request_options: request_options)
     end
 
     # Creates a new advanced payment with split disbursements.
@@ -54,7 +54,7 @@ module Mercadopago
     # @return [Hash{Symbol => Object}] +:status+ and +:response+ with the captured payment
     def capture(advanced_payment_id, request_options: nil)
       capture_data = { capture: true }
-      _put(uri: "/v1/advanced_payments/#{advanced_payment_id}", data: capture_data, request_options: request_options)
+      _put(uri: "/v1/advanced_payments/#{_path_param(advanced_payment_id)}", data: capture_data, request_options: request_options)
     end
 
     # Updates an existing advanced payment.
@@ -67,7 +67,7 @@ module Mercadopago
     def update(advanced_payment_id, advanced_payment_data, request_options: nil)
       raise TypeError, 'Param advanced_payment_data must be a Hash' unless advanced_payment_data.is_a?(Hash)
 
-      _put(uri: "/v1/advanced_payments/#{advanced_payment_id}", data: advanced_payment_data,
+      _put(uri: "/v1/advanced_payments/#{_path_param(advanced_payment_id)}", data: advanced_payment_data,
            request_options: request_options)
     end
 
@@ -78,7 +78,7 @@ module Mercadopago
     # @return [Hash{Symbol => Object}] +:status+ and +:response+ with the cancelled payment
     def cancel(advanced_payment_id, request_options: nil)
       cancel_data = { status: 'cancelled' }
-      _put(uri: "/v1/advanced_payments/#{advanced_payment_id}", data: cancel_data, request_options: request_options)
+      _put(uri: "/v1/advanced_payments/#{_path_param(advanced_payment_id)}", data: cancel_data, request_options: request_options)
     end
 
     # Changes the money release date for an advanced payment's disbursements.
@@ -89,7 +89,7 @@ module Mercadopago
     # @return [Hash{Symbol => Object}] +:status+ and +:response+
     def update_release_date(advanced_payment_id, release_date, request_options: nil)
       disbursement_data = { money_release_date: release_date.strftime('%Y-%m-%d %H:%M:%S.%f') }
-      _post(uri: "/v1/advanced_payments/#{advanced_payment_id}/disburses", data: disbursement_data,
+      _post(uri: "/v1/advanced_payments/#{_path_param(advanced_payment_id)}/disburses", data: disbursement_data,
             request_options: request_options)
     end
   end

data/lib/mercadopago/resources/card.rb

@@ -18,7 +18,7 @@ module Mercadopago
     # @return [Hash{Symbol => Object}] +:status+ and +:response+ with card details
     # @see https://www.mercadopago.com/developers/en/reference/online-payments/checkout-api/cards/get-card/get
     def get(customer_id, card_id, request_options: nil)
-      _get(uri: "/v1/customers/#{customer_id}/cards/#{card_id}", request_options: request_options)
+      _get(uri: "/v1/customers/#{_path_param(customer_id)}/cards/#{_path_param(card_id)}", request_options: request_options)
     end
 
     # Saves a new card for a customer using a previously generated card token.
@@ -32,7 +32,7 @@ module Mercadopago
     def create(customer_id, card_data, request_options: nil)
       raise TypeError, 'Param card_data must be a Hash' if card_data.nil? || !card_data.is_a?(Hash)
 
-      _post(uri: "/v1/customers/#{customer_id}/cards/", data: card_data, request_options: request_options)
+      _post(uri: "/v1/customers/#{_path_param(customer_id)}/cards/", data: card_data, request_options: request_options)
     end
 
     # Deletes a saved card from a customer.
@@ -43,7 +43,7 @@ module Mercadopago
     # @return [Hash{Symbol => Object}] +:status+ and +:response+
     # @see https://www.mercadopago.com/developers/en/reference/online-payments/checkout-api/cards/delete-card/delete
     def delete(customer_id, card_id, request_options: nil)
-      _delete(uri: "/v1/customers/#{customer_id}/cards/#{card_id}", request_options: request_options)
+      _delete(uri: "/v1/customers/#{_path_param(customer_id)}/cards/#{_path_param(card_id)}", request_options: request_options)
     end
 
     # Lists all saved cards for a customer.
@@ -53,7 +53,7 @@ module Mercadopago
     # @return [Hash{Symbol => Object}] +:status+ and +:response+ with an array of cards
     # @see https://www.mercadopago.com/developers/en/reference/online-payments/checkout-api/cards/get-customer-cards/get
     def list(customer_id, request_options: nil)
-      _get(uri: "/v1/customers/#{customer_id}/cards", request_options: request_options)
+      _get(uri: "/v1/customers/#{_path_param(customer_id)}/cards", request_options: request_options)
     end
   end
 end

data/lib/mercadopago/resources/card_token.rb

@@ -16,7 +16,7 @@ module Mercadopago
     # @param request_options [RequestOptions, nil] per-call configuration override
     # @return [Hash{Symbol => Object}] +:status+ and +:response+ with token details
     def get(card_token_id, request_options: nil)
-      _get(uri: "/v1/card_tokens/#{card_token_id}", request_options: request_options)
+      _get(uri: "/v1/card_tokens/#{_path_param(card_token_id)}", request_options: request_options)
     end
 
     # Creates a new card token from raw card data.

data/lib/mercadopago/resources/chargeback.rb

@@ -17,7 +17,7 @@ module Mercadopago
     # @return [Hash{Symbol => Object}] +:status+ and +:response+ with the full chargeback object
     # @see https://www.mercadopago.com.br/developers/en/reference/chargebacks/
     def get(chargeback_id, request_options: nil)
-      _get(uri: "/v1/chargebacks/#{chargeback_id}", request_options: request_options)
+      _get(uri: "/v1/chargebacks/#{_path_param(chargeback_id)}", request_options: request_options)
     end
 
     # Searches chargebacks matching the given filters.