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



135
136
137
 
# File 'lib/mercadopago/resources/order.rb', line 135

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



144
145
146
 
# File 'lib/mercadopago/resources/order.rb', line 144

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

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

Creates a Checkout Pro order.

This is a convenience wrapper over create that applies the Checkout Pro Orders API defaults: type "online" and processing_mode "manual" when omitted. If those fields are provided, they must already match the Checkout Pro flow.

Parameters:

  • order_data (Hash) —

    Checkout Pro order attributes

  • 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

  • (ArgumentError) —

    if type or processing_mode are incompatible



84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/mercadopago/resources/order.rb', line 84

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

  validate_checkout_pro_field(order_data, :type, 'online')
  validate_checkout_pro_field(order_data, :processing_mode, 'manual')
  checkout_pro_data = order_data.dup
  checkout_pro_data[:type] = 'online' unless checkout_pro_data.key?(:type) || checkout_pro_data.key?('type')
  checkout_pro_data[:processing_mode] = 'manual' unless checkout_pro_data.key?(:processing_mode) || checkout_pro_data.key?('processing_mode')

  _post(uri: '/v1/orders', data: checkout_pro_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



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

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



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

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



124
125
126
127
128
 
# File 'lib/mercadopago/resources/order.rb', line 124

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



153
154
155
 
# File 'lib/mercadopago/resources/order.rb', line 153

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