Payanyway

Этот gem предназначен для быстрой интеграции платежного шлюза payanyway в ваше ruby приложение.

При возникновении вопросов следует ознакомиться с документацией к шлюзу.

• Установка
• Подключение
• Использование
  • Запрос на оплату
  • Получение URL для отображения виджета оплаты
  • Специальные URL'ы
    • Check URL
    • Return URL и InProgress URL
  • Расшифровка параметров
    • Автоматическое прохождение MONETA.Assistant

## Установка

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

gem 'payanyway'

И выполните:

$ bundle

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

$ gem install payanyway

## Подключение

Добавьте engine в config/routes.rb

Rails.application.routes.draw do
  mount Payanyway::Engine => '/payanyway'
end

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

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

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

## Использование

### Запрос на оплату

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

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

### Получение URL для отображения виджета оплаты

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

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

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

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

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

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.

### Специальные URL'ы

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

#### Check URL

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

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

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

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

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

Возможные состояния оплаты заказа:

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

#### Return URL и InProgress URL

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

### Расшифровка параметров

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]`
: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	Список (разделенный запятыми) идентификаторов платежных систем.

#### Автоматическое прохождение 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