Class: Mercadopago::Order

Inherits:
MPBase
  • Object
show all
Defined in:
lib/mercadopago/resources/order.rb

Overview

Manages orders through the Checkout API v1.

An order groups one or more transactions and supports the full lifecycle: create, process, capture, refund, cancel, and search. Use OrderTransaction to manage individual transactions within an order.

Automatic Payments (AP) — supported Hash keys for stored_credential

{
  payment_initiator:    String,   # "cardholder" | "merchant"
  reason:               String,   # "recurring" | "installment" | "unscheduled"
  store_payment_method: Boolean,
  first_payment:        Boolean,
  prev_transaction_ref: String    # ID of the previous transaction in the series.
                                  # Required from the second charge onwards.
}

Supported Hash keys for automatic_payments

{
  payment_profile_id: String,   # Stored payment profile ID.
  retries:            Integer,  # Max retry attempts on failure.
  schedule_date:      String,   # ISO 8601 scheduled charge date.
  due_date:           String    # ISO 8601 payment due date.
}

Supported Hash keys for subscription_data

{
  invoice_id:   String,  # ID of the invoice being paid.
  billing_date: String,  # ISO 8601 billing date.
  subscription_sequence: {
    number: Integer,     # Current payment number (1-based).
    total:  Integer      # Total payments in the plan.
  },
  invoice_period: {
    type:   String,      # "monthly" | "daily" | "yearly".
    period: Integer      # Number of period units.
  }
}

Supported Hash keys for integration_data (root of order request)

{
  integrator_id:  String,  # Certified integrator ID.
  platform_id:    String,  # Platform ID assigned by MercadoPago.
  corporation_id: String,  # Corporation ID for multi-account setups.
  sponsor: {
    id: String             # MercadoPago user ID of the sponsor.
  }
}

See Also:

Instance Method Summary collapse

Methods inherited from MPBase

#_check_headers, #_check_request_options, #_delete, #_get, #_post, #_put, #initialize

Constructor Details

This class inherits a constructor from Mercadopago::MPBase

Instance Method Details

#cancel(order_id, request_options: nil) ⇒ Hash{Symbol => Object}

Cancels an order that has not yet been captured.

Parameters:

  • order_id (String) —

    order ID

  • request_options (RequestOptions, nil) (defaults to: nil) —

    per-call configuration override

Returns:

  • (Hash{Symbol => Object}) —

    :status and :response with the cancelled order



111
112
113
 
# File 'lib/mercadopago/resources/order.rb', line 111

def cancel(order_id, request_options: nil)
  _post(uri: "/v1/orders/#{order_id}/cancel", data: nil, request_options: request_options)
end

#capture(order_id, request_options: nil) ⇒ Hash{Symbol => Object}

Captures a previously authorized order.

Parameters:

  • order_id (String) —

    order ID

  • request_options (RequestOptions, nil) (defaults to: nil) —

    per-call configuration override

Returns:

  • (Hash{Symbol => Object}) —

    :status and :response with the captured order



120
121
122
 
# File 'lib/mercadopago/resources/order.rb', line 120

def capture(order_id, request_options: nil)
  _post(uri: "/v1/orders/#{order_id}/capture", data: nil, request_options: request_options)
end

#create(order_data, request_options: nil) ⇒ Hash{Symbol => Object}

Creates a new order.

Parameters:

  • order_data (Hash) —

    order attributes (type, total_amount, transactions, etc.)

  • request_options (RequestOptions, nil) (defaults to: nil) —

    per-call configuration override

Returns:

  • (Hash{Symbol => Object}) —

    :status and :response with the created order

Raises:

  • (TypeError) —

    if order_data is not a Hash



66
67
68
69
70
 
# File 'lib/mercadopago/resources/order.rb', line 66

def create(order_data, request_options: nil)
  raise TypeError, 'Param order_data must be a Hash' unless order_data.is_a?(Hash)

  _post(uri: '/v1/orders', data: order_data, request_options: request_options)
end

#get(order_id, request_options: nil) ⇒ Hash{Symbol => Object}

Retrieves a single order by ID.

Parameters:

  • order_id (String) —

    order ID

  • request_options (RequestOptions, nil) (defaults to: nil) —

    per-call configuration override

Returns:

  • (Hash{Symbol => Object}) —

    :status and :response with order details



77
78
79
 
# File 'lib/mercadopago/resources/order.rb', line 77

def get(order_id, request_options: nil)
  _get(uri: "/v1/orders/#{order_id}", request_options: request_options)
end

#process(order_id, request_options: nil) ⇒ Hash{Symbol => Object}

Processes (confirms) an order, triggering payment execution.

Parameters:

  • order_id (String) —

    order ID

  • request_options (RequestOptions, nil) (defaults to: nil) —

    per-call configuration override

Returns:

  • (Hash{Symbol => Object}) —

    :status and :response with the processed order



86
87
88
 
# File 'lib/mercadopago/resources/order.rb', line 86

def process(order_id, request_options: nil)
  _post(uri: "/v1/orders/#{order_id}/process", data: nil, request_options: request_options)
end

#refund(order_id, refund_data: nil, request_options: nil) ⇒ Hash{Symbol => Object}

Refunds an order (full or partial).

Omit refund_data for a full refund, or pass { amount: 10.0 } for a partial refund.

Parameters:

  • order_id (String) —

    order ID

  • refund_data (Hash, nil) (defaults to: nil) —

    optional refund attributes

  • request_options (RequestOptions, nil) (defaults to: nil) —

    per-call configuration override

Returns:

  • (Hash{Symbol => Object}) —

    :status and :response with the refund result

Raises:

  • (TypeError) —

    if refund_data is provided but is not a Hash



100
101
102
103
104
 
# File 'lib/mercadopago/resources/order.rb', line 100

def refund(order_id, refund_data: nil, request_options: nil)
  raise TypeError, 'Param refund_data must be a Hash' unless refund_data.nil? || refund_data.is_a?(Hash)

  _post(uri: "/v1/orders/#{order_id}/refund", data: refund_data, request_options: request_options)
end

#search(filters: nil, request_options: nil) ⇒ Hash{Symbol => Object}

Searches orders matching the given filters.

Parameters:

  • filters (Hash, nil) (defaults to: nil) —

    query parameters

  • request_options (RequestOptions, nil) (defaults to: nil) —

    per-call configuration override

Returns:

  • (Hash{Symbol => Object}) —

    :status and :response with search results



129
130
131
 
# File 'lib/mercadopago/resources/order.rb', line 129

def search(filters: nil, request_options: nil)
  _get(uri: '/v1/orders', params: filters, request_options: request_options)
end