Esta gem foi criada com o intuito de facilitar o uso da versão 2 das APIs do PagSeguro, como pagamento e notificações através de código Ruby. Esta gem não depende de rails e portanto pode ser utilizada com uma aplicação Rack ou como Backend de outra aplicação sem precisar carregar um environment rails.

Utilizando esta gem é possível enviar informações de compra ao pag seguro sem necessitar renderizar um formulário, impedindo o usuário de forjar informações pois as informações são trocadas apenas entre a sua aplicação e o pagseguro sem intermédio do usuário.

Esta gem foi desenvolvida para utilizar Ruby 1.9.2 ou superior, e não têm compatibilidade com versões anteriores. Caso deseje utilizar esta gem com versões anteriores de ruby, faça um fork desta gem e corrija os problemas encontrados.

Adicione a gem "pag_seguro" ao seu Gemfile:

gem 'pag_seguro'

Além disso, é necessário que tenha uma conta no pag seguro, e que habilite as seguintes configurações:

Em Integrações -> Token de segurança clique em Gerar novo token e guarde esta informação em local seguro
Em Integrações -> Pagamentos via API é necessário ativar a opção "Quero receber somente pagamentos via API."
Em Integrações -> Notificação de transações é necessário ativar a notificação de transações e definir a url de retorno

A nomenclatura dos atributos e recursos (classes) esperados pelo PagSeguro foram mantidas porém usando o padrão de nomenclatura do ruby (ao invés do camelcase utilizado pelo pagseguro). Seguem os links das documentações dos atributos no pagseguro:

• API de pagamentos
• API de notificação

Segue um exemplo de uso para criação de um pagamento no PagSeguro:

payment = PagSeguro::Payment.new(EMAIL, TOKEN)

payment.items = [
  PagSeguro::Item.new(id: 25, description: "A Bic Pen", amount: "1.50",  quantity: "4", shipping_cost: "1.00",  weight: 10),
  PagSeguro::Item.new(id: 17, description: "A pipe",    amount: "3.00",  quantity: "89")
]

redirect_to_url = payment.checkout_payment_url

O método checkout_payment_url envia as informações de payment ao PagSeguro e em caso de sucesso gera a url do PagSeguro para qual o comprador deverá ser redirecionado para efetuar a compra.

Além dos items presentes no exemplo acima, é possível configurar payment.sender (com informações do usuário que está efetuando a compra), payment.shipping ( com as informações de endereço ), entre outras opções (para mais exemplos, olhe o arquivo spec/integration/checkout_spec.rb). Em especial, o attributo payment.id deve ser utilizado para referenciar um pagamento único no seu sistema.

Segue um exemplo mais completo do uso da api de pagamentos:

payment = PagSeguro::Payment.new(EMAIL, TOKEN)

payment.items = [
  PagSeguro::Item.new(id: 25, description: "A Bic Pen", amount: "1.50",  quantity: "4", shipping_cost: "1.00",  weight: 10),
  PagSeguro::Item.new(id: 17, description: "A pipe",    amount: "3.00",  quantity: "89")
]

payment.sender = PagSeguro::Sender.new(name: "Stefano Diem Benatti", email: "[email protected]", phone_ddd: "11", phone_number: "93430994")
payment.shipping = PagSeguro::Shipping.new(
  type: PagSeguro::Shipping::SEDEX,
  state: "SP",
  city: "São Paulo", postal_code: "05363000",
  district: "Jd. PoliPoli",
  street: "Av. Otacilio Tomanik",
  number: "775",
  complement: "apto. 92")

redirect_to_url = payment.checkout_payment_url

Com exceção do atributo response (que é utilizado para armazenar a resposta enviada pelo PagSeguro), todos os outros atributos podem ser inicializados em formato hash na inicialização do PagSeguro::Payment:

payment = PagSeguro::Payment.new(EMAIL, TOKEN, id: 2, items: [ PagSeguro::Item.new(id: 17, description: "A pipe", amount: "3.00",  quantity: "89") ], extra_amount: '1.00' )

As notificações de alteração no status da compra no PagSeguro serão enviadas para a URL que tiver configurado na Notificação de transações (vide Instalação). Obs.: Até o momento o PagSeguro não permite configurar uma url dinâmica para envio das notificação ( e apenas permite uma url por conta ), então provavelemente será necessário que crie uma conta diferente no PagSeguro para cada sistema que desenvolver.

O código da notificação é enviado pelo PagSeguro através do parâmentro notificationCode em uma requisição do tipo POST. Segue um exemplo de uso da notificação em uma aplicação rails (este exemplo supõe a existência de um resources :notifications em suas rotas, e um modelo Invoice responsável pelos pagamentos):

class NotificationsController < ApplicationController
  def create
    EMAIL = "[email protected]"
    TOKEN = "SEU_TOKEN_GERADO_NO_PAG_SEGURO"
    NOTIFICATION_CODE = params(:notificationCode)
    
    notification = PagSeguro::Notification.new(EMAIL, TOKEN, NOTIFICATION_CODE)
    
    if notification.approved?
      # Idealmente faça alguns testes de sanidade, como notification.gross_amount, notification.item_count, etc
      # notification.id referencia o id do payment, caso tenha sido configurado
      # transacation_id identifica o código da transação no pag seguro
      Invoice.find(notification.id).approve!(notification.transaction_id)
    end
    
    if notification.cancelled? || notification.returned?
      Invoice.find(notification.id).void!
    end
  end
end

Os modelos utilizados nesta gem utilizam as validações do ActiveModel (semelhantes às presentes em ActiveRecord/Rails) e incluem diversas validações, permitindo que se verifique a validade (utilizando object.valid?) dos dados antes de enviá-los ao PagSeguro. A gem não bloqueia o envio das informações caso os dados estejam inválidos, deixando este passo a cargo da sua aplicação, mas levanta erros caso o pag seguro retorne algum erro relativo às informações enviadas.

Esta gem possui testes extensivos utilizando Rspec. Para rodar os testes, altere o arquivo spec/pag_seguro/integration/config.yml com seus dados no pag_seguro, entre na pasta onde a gem está instalada e execute:

bundle
guard

Caso queira contribuir, faça um fork desta gem no github, escreva os testes respectivos ao bug/feature desejados e faça um merge request.

Permitir realizar consultas de transações

Desenvolvida por Stefano Diem Benatti