mercadopago-sdk 3.0.1 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba9367571c6c8fd1ec045363ea57955ae114ad7ac54ec05970a0c216481713cb
-  data.tar.gz: 3a87bbabeda87b908c5567c10f721b8ce7c4a658d1a05c80fc266a7580473487
+  metadata.gz: d3eb3c15c909d8872d5810ac30966353a794f2c70bfcd983824898a93e2adf96
+  data.tar.gz: cd2bbac8379dcedaae481d4f4715130e21f88f819dc34a73779c238575e98f3b
 SHA512:
-  metadata.gz: d6a7610a8ad7fcb1f52481d67f77f0b650e61f63114e8d4d55ef14d9647fdce1077e7988234b1bab507756f879655a0785ee4cc7533759c5258549775ab456a9
-  data.tar.gz: dbddfd7d001bb22c4073433cd3a11b09e7c85ec3626ed59fef3ebb5d47d58e9b366595771e8cb592ce2c2bde9ccb0f5a335e17362c8bf76f29d204f86297a9e6
+  metadata.gz: 0ec0c57a6703933698e7fb99643274658a871ac3bb3738bcefa756ffde307ac9037d54ddd36f585c5a8b60f90f9bb7c433b7b97047a0f4f5ded2bf3aafbf9a94
+  data.tar.gz: 3379ec1633e23f25eae001deea156c96010e345298b0f8c58113d30916d644d0a263078261ad6bc9d9aff3d65ba2a488bc723d906db7a8196d0aca514d6f0d02

data/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,8 +1,8 @@
 name: 🐛 Bug Report
 description: Report a bug or unexpected behavior in the SDK
 title: "[BUG]: "
-labels: ["bug", "needs-triage"]
-assignees: ["danielalfarourrea","luismeli10","orojaspardo"]
+labels: ["bug"]
+assignees: ["luismeli10","orojaspardo","barajas-d"]
 
 body:
   - type: markdown

data/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,8 +1,8 @@
 name: ✨ Feature Request
 description: Propose a new feature for the Mercado Pago SDK
 title: "[FEATURE]: "
-labels: ["enhancement", "needs-triage"]
-assignees: ["danielalfarourrea","luismeli10","orojaspardo"]
+labels: ["enhancement"]
+assignees: ["luismeli10","orojaspardo","barajas-d"]
 
 body:
   - type: markdown

data/.github/ISSUE_TEMPLATE/question.yml

@@ -1,8 +1,8 @@
 name: 💬 Question
 description: Ask a question about the Mercado Pago SDK
 title: "[QUESTION]: "
-labels: ["question", "needs-triage"]
-assignees: ["danielalfarourrea","luismeli10","orojaspardo"]
+labels: ["question"]
+assignees: ["luismeli10","orojaspardo","barajas-d"]
 
 body:
   - type: markdown

data/.github/dependabot.yml

@@ -0,0 +1,44 @@
+# Dependabot version updates — sdk-ruby
+# Ubicación obligatoria: .github/dependabot.yml
+# Ecosistemas: bundler (Ruby) + github-actions
+version: 2
+
+updates:
+  # ── Ruby / Bundler ───────────────────────────────────────────────────
+  - package-ecosystem: "bundler"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "America/Bogota"
+    open-pull-requests-limit: 5
+    assignees:
+      - "luismeli10"
+      - "orojaspardo"
+      - "barajas-d"
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "chore(deps)"
+      include: "scope"
+    # bundler puede ejecutar código de gemspec durante el update — lo bloqueamos
+    insecure-external-code-execution: "deny"
+    ignore:
+      - dependency-name: "*"
+        update-types: ["version-update:semver-major"]
+
+  # ── GitHub Actions (CI) ──────────────────────────────────────────────
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "America/Bogota"
+    open-pull-requests-limit: 1
+    labels:
+      - "dependencies"
+      - "ci"
+    commit-message:
+      prefix: "chore(ci)"

data/.github/workflows/ci.yml

@@ -1,10 +1,3 @@
-# This workflow uses actions that are not certified by GitHub.
-# They are provided by a third-party and are governed by
-# separate terms of service, privacy policy, and support
-# documentation.
-# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
-# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
-
 name: Ruby
 
 on:
@@ -15,27 +8,36 @@ on:
 
 jobs:
   test:
-
     runs-on: ubuntu-latest
+    container: ruby:3.4
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v3
+      uses: actions/checkout@v7
       with:
         ref: ${{ github.event.pull_request.head.ref }}
         repository: ${{ github.event.pull_request.head.repo.full_name }}
 
-    - name: Set up Ruby
-    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
-    # change this to (see https://github.com/ruby/setup-ruby#versioning):
-      uses: ruby/setup-ruby@v1
+    - name: Cache gems
+      uses: actions/cache@v6
       with:
-        ruby-version: 3.4
+        path: vendor/bundle
+        key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }}
+        restore-keys: |
+          ${{ runner.os }}-gems-
+
     - name: Install dependencies
-      run: bundle install
+      run: |
+        bundle config set --local path vendor/bundle
+        bundle install
+
     - name: Rubocop
-      run: rubocop lib
-    - name: Run tests
-      run: bundle exec rake
-      env:
-        ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN_V2 }}
+      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 }}

data/.github/workflows/release.yml

@@ -7,27 +7,22 @@ on:
 jobs:
   release:
     runs-on: ubuntu-latest
+    container: ruby:3.4
 
     permissions:
       contents: write
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Setup Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          bundler-cache: true
+        uses: actions/checkout@v7
 
       - name: Install dependencies
         run: bundle install
 
-      - name: Validate gemspec
-        run: gem build mercadopago.gemspec
+      - name: Configure git safe directory
+        run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
 
       - name: Build gem
-        shell: bash
         run: gem build *.gemspec
 
       - name: Publish gem to rubygems.org
@@ -36,5 +31,4 @@ jobs:
         run: gem push *.gem
 
       - name: Wait for release to propagate
-        run: |
-          gem install rubygems-await
+        run: gem install rubygems-await

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

@@ -0,0 +1,66 @@
+# Changelog
+
+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
+
+- **OAuth**: authorization URL builder, token exchange, and token refresh
+  (`sdk.oauth.get_authorization_url`, `.create`, `.refresh`).
+  Enables marketplace and platform integrations to operate on behalf of
+  other sellers via the OAuth 2.0 authorization code flow.
+  Endpoints: `POST /oauth/token`.
+
+- **Point**: in-person payment intent management for MercadoPago Point
+  devices (`sdk.point.get_devices`, `.create`, `.get`, `.cancel`).
+  Enables card-present transactions through physical Point card readers.
+  Endpoints: `GET /point/integration-api/devices`,
+  `POST /point/integration-api/devices/{device_id}/payment-intents`,
+  `GET /point/integration-api/payment-intents/{id}`,
+  `DELETE /point/integration-api/devices/{device_id}/payment-intents/{id}`.
+  Note: `change_operating_mode` (PATCH) is not included; requires HttpClient
+  PATCH support.
+
+- **Invoice**: retrieval and search of subscription billing invoices
+  (`sdk.invoice.get`, `.search`). Enables monitoring of authorized
+  payments generated by PreApproval billing cycles.
+  Endpoints: `GET /authorized_payments/{id}`,
+  `GET /authorized_payments/search`.
+
+- **Chargeback**: retrieval and search of payment dispute records
+  (`sdk.chargeback.get`, `.search`). Enables monitoring and response to
+  cardholder disputes.
+  Endpoints: `GET /v1/chargebacks/{id}`,
+  `GET /v1/chargebacks/search`.

data/Gemfile

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

data/Gemfile.lock

@@ -1,51 +1,59 @@
 PATH
   remote: .
   specs:
-    mercadopago-sdk (3.0.1)
+    mercadopago-sdk (3.2.0)
       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.1)
+    faraday (2.14.3)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger
-    faraday-net_http (3.4.2)
+    faraday-net_http (3.4.4)
       net-http (~> 0.5)
-    json (2.9.1)
-    language_server-protocol (3.17.0.3)
+    io-console (0.8.2)
+    json (2.20.0)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
     logger (1.7.0)
-    method_source (1.0.0)
-    minitest (5.25.5)
+    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.0.3)
-    regexp_parser (2.10.0)
-    rubocop (1.70.0)
+    rake (13.4.2)
+    regexp_parser (2.12.0)
+    reline (0.6.3)
+      io-console (~> 0.5)
+    rubocop (1.88.0)
       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.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
     ruby-progressbar (1.13.0)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
@@ -55,15 +63,12 @@ GEM
 PLATFORMS
   ruby
 
-RUBY VERSION
-   ruby 3.4.3p0
-
 DEPENDENCIES
   mercadopago-sdk!
-  minitest (~> 5.0)
+  minitest (~> 5.27)
   pry (~> 0.14)
   rake
-  rubocop (~> 1.70)
+  rubocop (~> 1.88)
 
 BUNDLED WITH
    2.5.23

data/examples/chargeback/search_chargeback.rb

@@ -0,0 +1,14 @@
+require_relative '../../lib/mercadopago'
+
+sdk = Mercadopago::SDK.new('<YOUR_ACCESS_TOKEN>')
+
+# Search chargebacks by payment ID
+result = sdk.chargeback.search(filters: { payment_id: '<PAYMENT_ID>' })
+puts "Chargebacks: #{result[:response]}"
+
+# Get a specific chargeback by ID
+if result[:response]['results']&.any?
+  chargeback_id = result[:response]['results'].first['id']
+  chargeback = sdk.chargeback.get(chargeback_id)
+  puts "Chargeback details: #{chargeback[:response]}"
+end

data/examples/invoice/get_invoice.rb

@@ -0,0 +1,14 @@
+require_relative '../../lib/mercadopago'
+
+sdk = Mercadopago::SDK.new('<YOUR_ACCESS_TOKEN>')
+
+# Search invoices for a subscription
+result = sdk.invoice.search(filters: { preapproval_id: '<YOUR_PREAPPROVAL_ID>', limit: 10 })
+puts "Invoices: #{result[:response]}"
+
+# Get a specific invoice by ID
+if result[:response]['results']&.any?
+  invoice_id = result[:response]['results'].first['id']
+  invoice = sdk.invoice.get(invoice_id)
+  puts "Invoice details: #{invoice[:response]}"
+end

data/examples/oauth/create_token.rb

@@ -0,0 +1,22 @@
+require_relative '../../lib/mercadopago'
+
+sdk = Mercadopago::SDK.new('<YOUR_ACCESS_TOKEN>')
+
+# Step 1: Build the authorization URL and redirect the seller to it
+auth_url = sdk.oauth.get_authorization_url(
+  '<YOUR_APP_ID>',
+  'https://yourapp.com/callback',
+  '<UNIQUE_CSRF_STATE>'
+)
+puts "Redirect seller to: #{auth_url}"
+
+# Step 2: After the seller authorizes, exchange the code for tokens
+oauth_data = {
+  client_secret: '<YOUR_ACCESS_TOKEN>',
+  code: '<AUTHORIZATION_CODE_FROM_CALLBACK>',
+  redirect_uri: 'https://yourapp.com/callback',
+  grant_type: 'authorization_code'
+}
+
+result = sdk.oauth.create(oauth_data)
+puts "Token created: #{result[:response]}"

data/examples/order/create_checkout_pro.rb

@@ -0,0 +1,120 @@
+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'
+      }
+    },
+    shipment: {
+      mode: 'custom',
+      local_pickup: 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'
+      }
+    },
+    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',
+        event_date: '2027-01-15T00:00:00.000-03:00'
+      },
+      {
+        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',
+        event_date: '2027-01-15T00:00:00.000-03:00'
+      }
+    ]
+  }
+
+  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/point/create_payment_intent.rb

@@ -0,0 +1,26 @@
+require_relative '../../lib/mercadopago'
+
+sdk = Mercadopago::SDK.new('<YOUR_ACCESS_TOKEN>')
+
+# List available Point devices
+devices = sdk.point.get_devices
+puts "Devices: #{devices[:response]}"
+
+# Create a payment intent on a specific device
+device_id = '<YOUR_DEVICE_ID>'
+payment_intent_data = {
+  amount: 1500,
+  description: 'Product purchase',
+  payment: {
+    installments: 1,
+    type: 'credit_card'
+  }
+}
+
+result = sdk.point.create(device_id, payment_intent_data)
+puts "Payment intent created: #{result[:response]}"
+
+# Retrieve the payment intent status
+payment_intent_id = result[:response]['id']
+status = sdk.point.get(payment_intent_id)
+puts "Payment intent status: #{status[:response]}"

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.0.1'
+    @@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/http/http_client.rb

@@ -16,7 +16,6 @@ module Mercadopago
   # replace it via +SDK.new(token, http_client: MyClient.new)+ to
   # inject a custom transport (e.g. for testing or logging).
   class HttpClient
-    
     RETRYABLE_STATUSES = [429, 500, 502, 503, 504].freeze
 
     # Performs an HTTP GET request with automatic retry on transient errors.

data/lib/mercadopago/resources/chargeback.rb

@@ -0,0 +1,36 @@
+# typed: true
+# frozen_string_literal: true
+
+module Mercadopago
+  # Provides read access to chargeback disputes.
+  #
+  # Chargebacks are initiated by cardholders through their issuing bank
+  # when they dispute a payment. Use {#get} and {#search} to monitor and
+  # respond to disputes.
+  #
+  # @see https://www.mercadopago.com.br/developers/en/reference/chargebacks/
+  class Chargeback < MPBase
+    # Retrieves a chargeback by its ID.
+    #
+    # @param chargeback_id [Integer, String] unique chargeback identifier
+    # @param request_options [RequestOptions, nil] per-call configuration override
+    # @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)
+    end
+
+    # Searches chargebacks matching the given filters.
+    #
+    # @param filters [Hash, nil] query parameters (e.g. +:payment_id+, +:status+)
+    # @param request_options [RequestOptions, nil] per-call configuration override
+    # @return [Hash{Symbol => Object}] +:status+ and +:response+ with a paginated list of chargebacks
+    # @raise [TypeError] if +filters+ is not a Hash
+    # @see https://www.mercadopago.com.br/developers/en/reference/chargebacks/
+    def search(filters: nil, request_options: nil)
+      raise TypeError, 'Param filters must be a Hash' unless filters.nil? || filters.is_a?(Hash)
+
+      _get(uri: '/v1/chargebacks/search', filters: filters, request_options: request_options)
+    end
+  end
+end