A biblioteca PagSeguro em Ruby é um conjunto de classes de domínio que facilitam, para o desenvolvedor Ruby, a utilização das funcionalidades que o PagSeguro oferece na forma de APIs. Com a biblioteca instalada e configurada, você pode facilmente integrar funcionalidades como:
- Criar requisições de pagamentos (este serviço utiliza a versão V2 da API)
- Consultar transações por código (este serviço utiliza a versão V3 da API)
- Consultar transações por intervalo de datas (este serviço utiliza a versão V3 da API)
- Consultar transações abandonadas (este serviço utiliza a versão V2 da API)
- Receber notificações (este serviço utiliza a versão V3 da API)
- Enviar estorno de transações (este serviço utiliza a versão V2 da API)
- Cancelar transações (este serviço utiliza a versão V2 da API)
- Adicione a biblioteca ao seu Gemfile.
gem"pagseguro-oficial","~> 2.4.0"- Execute o comando
bundle install.
Para fazer a autenticação, você precisará configurar as credenciais do PagSeguro. Crie o arquivo config/initializers/pagseguro.rb com o conteúdo abaixo.
PagSeguro.configuredo |config|
config.token="seu token"config.email="seu e-mail"config.environment=:production# ou :sandbox. O padrão é production.config.encoding="UTF-8"# ou ISO-8859-1. O padrão é UTF-8.endO token de segurança está disponível em sua conta do PagSeguro.
Para iniciar uma requisição de pagamento, você precisa instanciar a classe PagSeguro::PaymentRequest. Isso normalmente será feito em seu controller de checkout.
classCheckoutController < ApplicationControllerdefcreate# O modo como você irá armazenar os produtos que estão sendo comprados# depende de você. Neste caso, temos um modelo Order que referência os# produtos que estão sendo comprados.order=Order.find(params[:id])payment=PagSeguro::PaymentRequest.new# Você também pode fazer o request de pagamento usando credenciais# diferentes, como no exemplo abaixopayment=PagSeguro::PaymentRequest.new(email: 'abc@email',token: 'token')payment.reference=order.idpayment.notification_url=notifications_urlpayment.redirect_url=processing_urlorder.products.eachdo |product|
payment.items << {id: product.id,description: product.title,amount: product.price,weight: product.weight}end# Caso você precise passar parâmetros para a api que ainda não foram# mapeados na gem, você pode fazer de maneira dinâmica utilizando um# simples hash.payment.extra_params << {paramName: 'paramValue'}payment.extra_params << {senderBirthDate: '07/05/1981'}payment.extra_params << {extraAmount: '-15.00'}response=payment.register# Caso o processo de checkout tenha dado errado, lança uma exceção.# Assim, um serviço de rastreamento de exceções ou até mesmo a gem# exception_notification poderá notificar sobre o ocorrido.## Se estiver tudo certo, redireciona o comprador para o PagSeguro.ifresponse.errors.any?raiseresponse.errors.join("\n")elseredirect_toresponse.urlendendendO PagSeguro irá notificar a URL informada no processo de checkout. Isso é feito através do método PagSeguro::PaymentRequest#notification_url. Esta URL irá receber o código da notificação e tipo de notificação. Com estas informações, podemos recuperar as informações detalhadas sobre o pagamento.
classNotificationsController < ApplicationControllerskip_before_filter:verify_authenticity_token,only: :createdefcreatetransaction=PagSeguro::Transaction.find_by_notification_code(params[:notificationCode])iftransaction.errors.empty?# Processa a notificação. A melhor maneira de se fazer isso é realizar# o processamento em background. Uma boa alternativa para isso é a# biblioteca Sidekiq.endrendernothing: true,status: 200endendPara quantificar o número de transações abandonadas, você pode solicitar uma lista com histórico dessas transações.
report=PagSeguro::Transaction.find_abandonedwhilereport.next_page?report.next_page!puts"=> Page #{report.page}"abort"=> Errors: #{report.errors.join("\n")}"unlessreport.valid?puts"=> Report was created at: #{report.created_at}"putsreport.transactions.eachdo |transaction|
puts"=> Abandoned transaction"puts" created at: #{transaction.created_at}"puts" code: #{transaction.code}"puts" type_id: #{transaction.type_id}"puts" gross amount: #{transaction.gross_amount}"putsendendPara facilitar seu controle financeiro e seu estoque, você pode solicitar uma lista com histórico das transações da sua loja.
report=PagSeguro::Transaction.find_by_datewhilereport.next_page?report.next_page!puts"== Page #{report.page}"abort"=> Errors: #{report.errors.join("\n")}"unlessreport.valid?puts"Report created on #{report.created_at}"putsreport.transactions.eachdo |transaction|
puts"=> Transaction"puts" created_at: #{transaction.created_at}"puts" code: #{transaction.code}"puts" cancellation_source: #{transaction.cancellation_source}"puts" payment method: #{transaction.payment_method.type}"puts" gross amount: #{transaction.gross_amount}"puts" updated at: #{transaction.updated_at}"putsendendÉ possível consultar o histórico de mudanças de status em transações
response=PagSeguro::Transaction.find_status_history("transaction_code")response.eachdo |status|
puts"STATUS:"puts" code: #{status.code}"puts" date: #{status.date}"puts" notification_code: #{status.notification_code}"endVocê pode consultar as opções de parcelamento para um determinado valor.
installments=PagSeguro::Installment.find("100.00")puts"=> INSTALLMENTS"putsinstallments.eachdo |installment|
putsinstallment.inspectendvisa_installments=PagSeguro::Installment.find("100.00","visa")putsputs"=> VISA INSTALLMENTS"putsvisa_installments.eachdo |installment|
putsinstallment.inspectendoptions={credentials: PagSeguro::ApplicationCredentials.new("app4521929942","1D47384E6565EBE664DAEF9AD690438B"),permissions: [:searches,:notifications],notification_url: 'foo.com.br',redirect_url: 'bar.com.br'}response=PagSeguro::Authorization.new(options).authorizeEm seguida, acesse o link para confirmar as autorizações
response.urlVocê pode estornar pagamentos que as transações estiverem com status: Paga (3), Disponível (4), Em disputa (5).
refund=PagSeguro::Refund.newrefund.transaction_code="D5D5BE444148407891E497B421975599"response=refund.registerifresponse.errors.any?putsresponse.errors.join("\n")elseputs"=> REFUND RESPONSE"putsresponse.resultendVocê pode cancelar transações que estiverem com status: Aguardando pagamento ou Em análise.
cancellation=PagSeguro::TransactionCancellation.newcancellation.transaction_code="AFB8FCF29496401681257C1ECE3A98FF"cancellation.registerifcancellation.errors.any?putscancellation.errors.join("\n")elseputs"=> CANCELLATION RESPONSE"putscancellation.resultendpayment.reference="ref1234"payment=PagSeguro::PaymentRequest.newpayment.shipping={type_name: "sedex",cost: 20.00,address: {street: "Av. Brig. Faria Lima",number: 1384,complement: "5 andar",district: "Jardim Paulistano",city: "São Paulo",state: "SP",postal_code: "01452002"}}shipping_options={type_name: "sedex",cost: 20.00,address: {street: "Av. Brig. Faria Lima",number: 1384,complement: "5 andar",district: "Jardim Paulistano",city: "São Paulo",state: "SP",postal_code: "01452002"}}payment.shipping=PagSeguro::Shipping.new(shipping_options)payment.sender={name: "John Doe",email: "john@example.org",cpf: "12345678901",phone: {area_code: "11",number: "123456789"}}payment.extra_amount=123.45# acréscimopayment.extra_amount= -123.45# desconto# URL de notificaçãopayment.notification_url="http://example.org/notifications"# URL de retornopayment.return_url="http://example.org/processando"payment.max_uses=100payment.max_age=3600# em segundosPagSeguro.encoding="UTF-8"# UTF-8 ou ISO-8859-1Encontre toda a documentação necessária para o checkout transparente aqui: https://github.com/pagseguro/ruby/blob/master/docs/transparent_checkout.md
Caso tenha dúvidas ou precise de suporte, acesse nosso fórum.
https://github.com/pagseguro/ruby/blob/master/CHANGELOG.md
Copyright 2013 PagSeguro Internet LTDA.
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.
- O PagSeguro somente aceita pagamento utilizando a moeda Real brasileiro (BRL).
- Certifique-se que o email e o token informados estejam relacionados a uma conta que possua o perfil de vendedor ou empresarial.
- Certifique-se que tenha definido corretamente o charset de acordo com a codificação (ISO-8859-1 ou UTF-8) do seu sistema. Isso irá prevenir que as transações gerem possíveis erros ou quebras ou ainda que caracteres especiais possam ser apresentados de maneira diferente do habitual.
- Para que ocorra normalmente a geração de logs, certifique-se que o diretório e o arquivo de log tenham permissões de leitura e escrita.
Achou e corrigiu um bug ou tem alguma feature em mente e deseja contribuir?
- Faça um fork
- Adicione sua feature ou correção de bug (
git checkout -b my-new-feature) - Commit suas mudanças (
git commit -am 'Added some feature') - Rode um push para o branch (
git push origin my-new-feature) - Envie um Pull Request
O código, os commits e os comentários devem ser em inglês. Adicione exemplos para sua nova feature. Se seu Pull Request for relacionado a uma versão específica, o Pull Request não deve ser enviado para o branch master e sim para o branch correspondente a versão.