Mercadopago-Rails
=================

[![Gem Version](https://badge.fury.io/rb/mercado_pago_rails.png)](http://badge.fury.io/rb/mercado_pago_rails)
[![Build Status](https://travis-ci.org/Wolox/mercadopago-rails.png?branch=master)](https://travis-ci.org/Wolox/mercadopago-rails)
[![Coverage Status](https://coveralls.io/repos/Wolox/mercadopago-rails/badge.png)](https://coveralls.io/r/Wolox/mercadopago-rails)

**MercadoPago-Rails** is a very simple gem that helps you interact with mercadopago api. It uses [meracado pago gem](https://github.com/kauplus/mercadopago) and [mercado pago sdk](https://github.com/mercadopago/sdk-ruby) to work internally.
For the moment, this gem only supports buying only ONE type of product at a time.

## Install

To install the gem just run

```
gem install mercado_pago_rails
```

or if you are using bundler add the following line to your `Gemfile`

```ruby
gem 'mercado_pago_rails'
```

## Usage

### MercadoPagoModule
To start communicating with mercado pago, you need to include **MercadoPagoModule**. This module adds the method generate_purchase that receives two parameters:
* An object that holds the information of the purchase to be made
* A hash containing three urls: success_url, failure_url and pending_url

The object needs to respond to the following methods:
* **external_reference**: this will and id to be used by MercadoPago to refer to the object (it can be your database ID or whatever reference you wish).
* **quantity**: amount of products to be bought.
* **unit_price**: unit price of the product you are buying (hence, the total amount to be paid is quantity * unit_price).
* **currency**: the currency in which the payment must be made (for instance, "ARS". For more information about this, refer [here](http://developers.mercadopago.com/documentacion/api/preferences).
* **picture_url**: url for the picture of the product. This is shown by MercadoPago at the time of the payment (this is optional)
* **payer_name**: payer's name
* **payer_surname**: payer's surname
* **payer_email**: payer's email

The following object is an example of the mentioned above:

```ruby
class MercadoPagoVoucherAdapter

  def initialize(voucher)
    @voucher = voucher
  end

  def quantity
    1
  end

  def unit_price
    @voucher.paid
  end

  def currency
    "ARS"
  end

  def picture_url
    @voucher.brand.logo.url
  end

  def payer_namer
    @voucher.user.name
  end

  def payer_surname
    @voucher.user.name
  end

  def payer_email
    @voucher.user.email
  end

  def external_reference
    @voucher.id
  end

  def title
    @voucher.brand.name
  end

  def new_status(status)
    @voucher.status = status
    @voucher.save
  end
end

```

The urls passed as a hash are used by MercadoPago to create links back to your application once the user has finished with the payment.

When the method returns, it creates an instance of MercadoPagoResponse. To check if there was an error while just invoke `mercado_pago_response.success?`. If there was an error, you can call
`mercado_pago_response.error_msg` to get the error message. Otherwise, you can call `mercado_pago_response.redirect_url` and it will return the url where the user must go to complete the
payment.


```ruby
mercado_pago_response = generate_purchase(MercadoPagoVoucherAdapter.new(@voucher), success_url: root_url, pending_url: root_url, failure_url: root_url)
if !mercado_pago_response.success?
  flash[:error] = I18n.t('voucher.confirm.mercadopago.error')
  render action: "new", brand_id: params[:voucher][:brand_id]
else
  redirect_to mercado_pago_response.redirect_url
end

```

### MercadoPagoHelper
This class contains the object in charge of communicating with MercadoPago. To use it, you must include  [AppConfiguration](https://github.com/guidomb/app_configuration). Usign this gem, **MercadoPagoHelper** will load
the client_id and client_secret that you where provided to interact with MercadoPago from the file .mercadopago.yml (or environment variable, just check the gem's documentation).
This class also contains constants representing the different status that a purchase can adquire: **APPROVED**, **PENDING**, **IN_PROCESS**, **REJECTED**, **REFUNDED**, **CANCELLED**, **IN_MEDIATION**.

If you want, you can set handlers for the different status that a purchase might adquire. Just add the following lines in an initializer.
```ruby
MercadoPagoHelper.set_handlers(approved: SuccessfulPurchaseContext, pending: PendingPurchaseContext, in_process: InProcessPurchaseContext,
              in_mediation: InMediationPurchaseContext, rejected: RejectedPurchaseContext, cancelled: CancelledPurchaseContext,
              refunded: RefundedPurchaseContext)
```
This handlers will be instanciated when `get_context(response, obj)` is called. The method checks the purchase's status instantiates the corresponding handler. All this handlers must receive in their initializer 
the response and the object that want to modify. This can be used in the following way: `MercadoPagoHelper.get_context(info, voucher).handle`

## License ##

Copyright 2013 Wolox S.A.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.