Class: Mercadopago::AdvancedPayment

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

Overview

Manages advanced (split) payments for marketplace integrations.

Advanced payments allow a marketplace to split a single buyer transaction across multiple sellers, each receiving their own disbursement. Supports authorization/capture flows, cancellation, and release-date adjustments.

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(advanced_payment_id, request_options: nil) ⇒ Hash{Symbol => Object}

Cancels an advanced payment by setting its status to “cancelled”.

Parameters:

  • advanced_payment_id (Integer, String) —

    advanced payment ID

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

    per-call configuration override

Returns:

  • (Hash{Symbol => Object}) —

    :status and :response with the cancelled payment



79
80
81
82
 
# File 'lib/mercadopago/resources/advanced_payment.rb', line 79

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)
end

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

Captures a previously authorized advanced payment.

Sends { capture: true } to transition the payment from authorized to captured state.

Parameters:

  • advanced_payment_id (Integer, String) —

    advanced payment ID

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

    per-call configuration override

Returns:

  • (Hash{Symbol => Object}) —

    :status and :response with the captured payment



55
56
57
58
 
# File 'lib/mercadopago/resources/advanced_payment.rb', line 55

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)
end

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

Creates a new advanced payment with split disbursements.

Parameters:

  • advanced_payment_data (Hash) —

    payment attributes (payer, payments array, disbursements, etc.)

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

    per-call configuration override

Returns:

  • (Hash{Symbol => Object}) —

    :status and :response with the created payment

Raises:

  • (TypeError) —

    if advanced_payment_data is not a Hash



41
42
43
44
45
 
# File 'lib/mercadopago/resources/advanced_payment.rb', line 41

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

  _post(uri: '/v1/advanced_payments', data: advanced_payment_data, request_options: request_options)
end

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

Retrieves a single advanced payment by ID.

Parameters:

  • advanced_payment_id (Integer, String) —

    advanced payment ID

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

    per-call configuration override

Returns:

  • (Hash{Symbol => Object}) —

    :status and :response with payment details



31
32
33
 
# File 'lib/mercadopago/resources/advanced_payment.rb', line 31

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

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

Searches advanced payments 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

Raises:

  • (TypeError) —

    if filters is not a Hash



20
21
22
23
24
 
# File 'lib/mercadopago/resources/advanced_payment.rb', line 20

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/advanced_payments/search', filters: filters, request_options: request_options)
end

#update(advanced_payment_id, advanced_payment_data, request_options: nil) ⇒ Hash{Symbol => Object}

Updates an existing advanced payment.

Parameters:

  • advanced_payment_id (Integer, String) —

    advanced payment ID

  • advanced_payment_data (Hash) —

    fields to update

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

    per-call configuration override

Returns:

  • (Hash{Symbol => Object}) —

    :status and :response with the updated payment

Raises:

  • (TypeError) —

    if advanced_payment_data is not a Hash



67
68
69
70
71
72
 
# File 'lib/mercadopago/resources/advanced_payment.rb', line 67

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,
       request_options: request_options)
end

#update_release_date(advanced_payment_id, release_date, request_options: nil) ⇒ Hash{Symbol => Object}

Changes the money release date for an advanced payment’s disbursements.

Parameters:

  • advanced_payment_id (Integer, String) —

    advanced payment ID

  • release_date (Time, DateTime) —

    new release date (formatted as “%Y-%m-%d %H:%M:%S.%f”)

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

    per-call configuration override

Returns:

  • (Hash{Symbol => Object}) —

    :status and :response



90
91
92
93
94
 
# File 'lib/mercadopago/resources/advanced_payment.rb', line 90

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,
        request_options: request_options)
end