Documentação django-pagseguro!

Aplicação para facilitar integração do django com pagseguro.

Para versão 2 da API do PagSeguro use: django-pagseguro2

Tutorial django-pagseguro

Instalação

Para instalar através do PyPi usando pip

pip install django-pagseguro

Configurando a app django-pagseguro

Adicione a app no INSTALLED_APPS no settings.py

INSTALLED_APPS = (
    ...
    'django_pagseguro',
    ...
)

Configure no settings.py as constantes necessárias para utilizar a app.

PAGSEGURO_EMAIL_COBRANCA = 'seu@email.com' # email de cobrança usado no pagseguro
PAGSEGURO_TOKEN = '1a3ea7wq2e7eq8e1e223add23ad23' # token gerado no sistema de url de retorno do pagseguro
PAGSEGURO_URL_RETORNO = '/pagseguro/retorno/' # url para receber o POST de retorno do pagseguro
PAGSEGURO_URL_FINAL = '/obrigado/' # url final para redirecionamento
PAGSEGURO_ERRO_LOG  = '/tmp/pagseguro_erro.log' # arquivo para salvar os erros de validação de retorno com o pagseguro(opcional)

Configure a rota para url de retorno do PagSeguro no urls.py

from django_pagseguro.urls import pagseguro_urlpatterns
...
urlpatterns += pagseguro_urlpatterns()

Criando o Carrinho

Importe o Carrinho do PagSeguro

from django_pagseguro.pagseguro import ItemPagSeguro, CarrinhoPagSeguro

Configure o carrinho do PagSeguro de acordo com seu projeto, no exemplo abaixo compra de Crédito

carrinho = CarrinhoPagSeguro(ref_transacao=1)
carrinho.set_cliente(email='email@cliente.com', cep='60000000')
carrinho.add_item(ItemPagSeguro(cod=1, descr='Crédito', quant=1, valor=35.53))
form_pagseguro = carrinho.form()    # Form do pagseguro para usar no template de acordo com as configurações

Capturando sinais do retorno

O django-pagseguro foi feito para que o desenvolvedor decida como vai tratar o retorno do PagSeguro, portanto os dados enviados pelo PagSeguro não são alterados, eles são encaminhados através de um signal do django.

Existem duas opções para capturar o retorno, de forma global ou específica para cada estado do pagamento.

Signal Global:

  • pagamento_atualizado: dispara em qualquer atualização do pagamento

Signals específicos para cada status do pagamento:

  • pagamento_aprovado: Aprovado
  • pagamento_cancelado: Cancelado
  • pagamento_aguardando: Aguardando Pagamento
  • pagamento_em_analise: Em Análise
  • pagamento_completo: Completo
  • pagamento_devolvido: Devolvido

Capturando o sinal e processando os dados de retorno do PagSeguro

from django_pagseguro.signals import pagamento_aprovado
...
def liberar_pedido(sender, **kwargs):
    ref = sender.referencia
    tipo_pagamento = sender.dados['TipoPagamento'] # exemplo de como pegar informações enviada pelo PagSeguro
    # aqui você deve executar seu código para liberar o pedido para a Referência
...
pagamento_aprovado.connect(liberar_pedido)

Configurando logs

Caso queira configurar os logs, você deve fazer conforme a documentação do Django sobre a configuração de logs, por exemplo:

LOGGING = {
    ...
    'loggers': {
        'django_pagseguro': {
            'handlers': ['console'],
            'level': 'INFO',
        }
    }
    ...
}

django-pagseguro API

Documentação detalha da interface de desenvolvimento para construção de um carrinho de compras

CarrinhoPagSeguro

class django_pagseguro.pagseguro.CarrinhoPagSeguro(email_cobranca='seu@email.com', **kwargs)

CarrinhoPagSeguro deve ser criado para gerar o Form para o PagSeguro.

As configurações do carrinho, cliente e itens do pedido são definidas usando esta classe.

A configuração geral dos atributos do carrinho é feita no atributo self.config. Os possíveis atributos podem ser encontrados na documentação oficial do PagSeguro:

Configurações do cliente devem ser feitas através do método set_cliente.

Para adicionar items ao carrinho use método add_item.

Para obter o HTML do Form do PagSeguro com o botão de Comprar use o método form.

add_item(item)

Adiciona um novo item ao carrinho.

Para mais informações, consulte a documentação da classe ItemPagSeguro

form(template='pagseguro_form.html')

Realiza o render do formulário do PagSeguro baseado no template.

Por padrão, o template usado é ‘django_pagaseguro/templates/pagseguro_form.html’, porém é possível sobrescrever o template ou passar outro template que desejar como parâmetro.

set_cliente(**kwargs)

Define as configurações do cliente. Essas informações são opcionais, mas, se existirem essa informações, é interessante defini-las para facilitar para o cliente no site do PagSeguro.

Os campos válidos são: nome, cep, end, num, compl, bairro, cidade, uf, pais, ddd, tel e email.

IMPORTANTE: Todos os valores devem ser passados como parâmetros nomeados.

ItemPagSeguro

class django_pagseguro.pagseguro.ItemPagSeguro(cod, descr, quant, valor, frete=0, peso=0)

ItemPagSeguro é usado no CarrinhoPagSeguro para representar cada Item de compra.

O frete e o valor são convertidos para o formato exigido pelo PagSeguro. Regra do PagSeguro: valor real * 100.

Dinheiro Decimal/Float PagSeguro
R$ 1,50 1.50 150
R$ 32,53 32.53 3253