[![Gem Version](https://badge.fury.io/rb/payanyway.svg)](http://badge.fury.io/rb/payanyway)
[![Build Status](https://travis-ci.org/RuntimeLLC/payanyway.svg?branch=master)](https://travis-ci.org/RuntimeLLC/payanyway)
[![Code Climate](https://codeclimate.com/github/ssnikolay/payanyway.svg)](https://codeclimate.com/github/ssnikolay/payanyway)
[![Test Coverage](https://codeclimate.com/github/ssnikolay/payanyway/badges/coverage.svg)](https://codeclimate.com/github/ssnikolay/payanyway)

# Payanyway

Этот gem предназначен для быстрой интеграции платежного шлюза [payanyway](http://payanyway.ru) в ваше ruby приложение.

При возникновении вопросов следует ознакомиться с [документацией к шлюзу](http://moneta.ru/doc/MONETA.Assistant.ru.pdf).

- [Установка](#installation)
- [Подключение](#setup)
- [Использование](#usage)
    - [Запрос на оплату](#payment_url)
    - [Получение URL для отображения виджета оплаты](#widget_url)
    - [Специальные URL'ы](#special_urls)
        - [Check URL](#check_url)
        - [Return URL и InProgress URL](#return_url)
    - [Расшифровка параметров](#params)
        - [Автоматическое прохождение MONETA.Assistant](#auto_assistant)

##<a name="installation"></a> Установка

Добавьте эти строки в Gemfile вашего приложения:

```ruby
gem 'payanyway'
```

И выполните:

    $ bundle

Или установите напрямую:

    $ gem install payanyway

##<a name="setup"></a> Подключение

Добавьте engine в `config/routes.rb`
```ruby
Rails.application.routes.draw do
  mount Payanyway::Engine => '/payanyway'
end
```

Создайте `app/controllers/payanyway_controller.rb` со следующим кодом:

```ruby
class PayanywayController < ApplicationController
  include Payanyway::Controller

  def success_implementation(transaction_id)
    # вызывается при отправке шлюзом пользователя на Success URL.
    #
    # ВНИМАНИЕ: является незащищенным действием!
    # Для выполнения действий после успешной оплаты используйте pay_implementation
  end
  
  def pay_implementation(params)
    # вызывается при оповещении магазина об 
    # успешной оплате пользователем заказа. (Pay URL)
    #
    # params[ KEY ], где KEY ∈ [ :moneta_id, :transaction_id, :operation_id,
    # :amount, :currency, :subscriber_id, :test_mode, :user, :corraccount,
    # :custom1, :custom2, :custom3 ]
  end
  
  def fail_implementation(transaction_id)
    # вызывается при отправке шлюзом пользователя на Fail URL.
  end
end
```

Создайте конфигурационный файл: `config/payanyway.yml`

```yml
development: &config
    moneta_id: YOUR_MONETA_ID
    currency: RUB
    payment_url: https://demo.moneta.ru/assistant.htm
    test_mode: 1
    token: secret_token
production: <<: *config
    payment_url: https://moneta.ru/assistant.htm
    test_mode: 0
```

В настройках счета **moneta.ru** выберите `HTTP метод: GET`

![Settings](https://raw.github.com/ssnikolay/payanyway/master/settings.jpg)

##<a name="usage"></a> Использование

###<a name="payment_url"></a> Запрос на оплату

Чтобы получить ссылку на платежный шлюз для оплаты заказа пользователем,
используйте хелпер

```ruby
Payanyway::Gateway.payment_url(params, use_signature = true)
```

###<a name="widget_url"></a> Получение URL для отображения виджета оплаты

Чтобы получить ссылку на виджет для оплаты заказа пользователем,
используйте хелпер

```ruby
Payanyway::Gateway.widget_url(params, use_signature = true)
```

Описание всех возможных параметров запроса (ключей params) находится [здесь](#params).

Если в настройках счета в системе **moneta.ru** выставлен флаг «Можно переопределять настройки в URL», то можно так же передавать
`[:success_url, :in_progress_url, :fail_url, :return_url]`.

Пример минимальной ссылки для оплаты:

```ruby
class Order < ActiveRecord::Base; end

class OrdersController < ApplicationController
  def create
    order = Order.create(params[:order])
    redirect_to Payanyway::Gateway.payment_url(
      transaction_id: order.id,
      amount: order.total_amount,
      description: "Оплата заказа № #{ order.number } на сумму #{ order.total_amount }руб."
    )
  end
end
```

*Примечание: при необходимости можно переопределить `moneta_id`, `currency`, `test_mode`, так же передав их в payment_url.*

###<a name="special_urls"></a> Специальные URL'ы

Gem **payanyway** добавляет специальные роуты для обработки запросов от шлюза.

####<a name="check_url"></a> Check URL

```ruby
class PayanywayController
  ...
  def check_implementation(params)
    # Вызывается при обработке проверочных запросов (Check URL)
    # params[ KEY ], где KEY ∈ [ :moneta_id, :transaction_id, :operation_id,
    # :amount, :currency, :subscriber_id, :test_mode, :user, :corraccount,
    # :custom1, :custom2, :custom3, :payment_system_unit_id ]

    # ВНИМАНИЕ: при отправке корректного ответа со стороны магазина,
    #   необходимо вернуть в методе параметры для генерации статус-кода.
    #   { amount: AMOUNT, state: STATE, description: DESCRIPTION,
    #   attributes: ATTRIBUTES, logger: true\false }
  end
end
```

Пример метода:

```ruby
...
def check_implementation(params)
  order = Order.find(params[:transaction_id])
  {
    amount: order.total_amount,
    state: order.state_for_payanyway, # нужно реализовать
    attributes: { name: 'John Smith', email: 'js@gmail.com' }
  }
end
...
```

**Возвращаемые параметры:**

 Название                  | Описание
---------------------------|:-----------------------------------------------------------
`:amount`                  | Сумма заказа
`:state`                   | Состояние оплаты заказа. (см. [таблицу состояний](#states))
`:description`             | Описание состояния заказа. Задается в произвольной форме.
`:attributes`              | Необязательный элемент. Содержит хеш произвольных параметров, которые будут сохранены в операции.
`:logger`                  | Вывести XML ответ в log (`Rails.logger`)

<a name="states"></a>**Возможные состояния оплаты заказа:**

 Состояние               | Описание
-------------------------|:-----------------------------------------------------------
`:paid`                  | Заказ оплачен. Уведомление об оплате магазину доставлено.
`:in_progress`           | Заказ находится в обработке. Точный статус оплаты заказа определить невозможно. (например, если пользователя отправило на InProgress URL, но уведомления на Pay URL от шлюза еще не поступало)
`:unpaid`                | Заказ создан и готов к оплате. Уведомление об оплате магазину не доставлено.
`:canceled`              | Заказ не является актуальным в магазине (например, заказ отменен).

####<a name="return_url"></a> Return URL и InProgress URL

```ruby
class PayanywayController
  ...
  def return_implementation(transaction_id)
    # Вызывается при добровольном отказе пользователем от оплаты (Return URL)
  end

  def in_progress_implementation(transaction_id)
    # Вызывается после успешного запроса на авторизацию средств,
    # до подтверждения списания и зачисления средств (InProgress URL)
    #
    # ВНИМАНИЕ: InProgress URL может быть использован в любом способе оплаты.
    #   Если к моменту, когда пользователя надо вернуть в магазин оплата,
    #   по какой-либо причине не завершена, то его перекинет на InProgress,
    #   если он указан, если не указан, то на Success URL.
    #   Если операция уже успешно выполнилась, то сразу на Success.
    #   В случае с картами чаще всего получается так, что операция не успевает выполниться,
    #   поэтому InProgress будет использован с бОльшей вероятностью, чем Success URL.
  end
  ...
end
```

###<a name="params"></a> Расшифровка параметров

 params[ KEY ], где KEY    | В документации           | Описание
---------------------------|:-------------------------|:-----------------------------------------
`:moneta_id`               | `MNT_ID`                 | Идентификатор магазина в системе MONETA.RU.
`:transaction_id`          | `MNT_TRANSACTION_ID`     | Внутренний идентификатор заказа, однозначно определяющий заказ в магазине.
`:operation_id`            | `MNT_OPERATION_ID`       | Номер операции в системе MONETA.RU.
`:amount`                  | `MNT_AMOUNT`             | Фактическая сумма, полученная на оплату заказа.
`:currency`                | `MNT_CURRENCY_CODE`      | ISO код валюты, в которой произведена оплата заказа в магазине.
`:test_mode`               | `MNT_TEST_MODE`          | Флаг оплаты в тестовом режиме (1 - да, 0 - нет).
`:description`             | `MNT_DESCRIPTION`        | Описание оплаты.
`:subscriber_id`           | `MNT_SUBSCRIBER_ID`      | Внутренний идентификатор пользователя в системе магазина.
`:corraccount`             | `MNT_CORRACCOUNT`        | Номер счета плательщика.
`:custom[1|2|3]`           | `MNT_CUSTOM1`            | Поля произвольных параметров. Будут возвращены магазину в параметрах отчета о проведенной оплате.
`:user`                    | `MNT_USER`               | Номер счета пользователя, если оплата производилась с пользовательского счета в системе «MONETA.RU».
`:locale`                  | `moneta.locale`          | (ru\|en) Язык пользовательского интерфейса.
`:success_url`             | `MNT_SUCCESS_URL`        | URL страницы магазина, куда должен попасть покупатель после успешно выполненных действий.
`:in_progress_url`         | `MNT_INPROGRESS_URL`     | URL страницы магазина, куда должен попасть покупатель после успешного запроса на авторизацию средств, до подтверждения списания и зачисления средств.
`:fail_url`                | `MNT_FAIL_URL`           | URL страницы магазина, куда должен попасть покупатель после отмененной или неуспешной оплаты.
`:return_url`              | `MNT_RETURN_URL`         | URL страницы магазина, куда должен вернуться покупатель при добровольном отказе от оплаты.
`:attributes`              | `MNT_ATTRIBUTES`         | Содержит произвольные параметры, которые будут сохранены в операции.
`:payment_system_limit_ids`| `paymentSystem.limitIds` | Список (разделенный запятыми) идентификаторов платежных систем.

####<a name="auto_assistant"></a> Автоматическое прохождение MONETA.Assistant

params[ KEY ], где KEY       | В документации           | Описание
-----------------------------|:--------------------------|:-----------------------------------------
`:followup`                  | `followup`                | Пройти весь MONETA.Assistant с предустановленными значениями. Для этого необходимо выбрать платежную систему и заполнить параметры платежной системы (если они есть).
`:payment_system_unit_id`    | `paymentSystem.unitId`    | (1015 – МОНЕТА.РУ, 1020 – Яндекс.Деньги, 1017 – WebMoney и т.п.) Предварительный выбор платежной системы. Полный список способов оплаты можно посмотреть: https://www.moneta.ru/viewPaymentMethods.htm
`:javascript_enabled`        | `javascriptEnabled`       | (true\|false) Признак возможности использовать javascript для автоматической обработки форм.
`:payment_system_account_id` | `paymentSystem.accountId` | Номер счета платежной системы. Например, тип кошелька WebMoney, 2 – WMR, 3 – WMZ, 4 – WME.

## Contributing

1. Fork it ( https://github.com/ssnikolay/payanyway/fork )
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request