Skip to main content

Pagseguro API v2 wrapper

Project description

python-pagseguro
[![All Contributors](https://img.shields.io/badge/all_contributors-6-orange.svg?style=flat-square)](#contributors)
================
[![Build
Status](https://travis-ci.org/rochacbruno/python-pagseguro.png)](https://travis-ci.org/rochacbruno/python-pagseguro)
[![Coverage
Status](https://coveralls.io/repos/rochacbruno/python-pagseguro/badge.png)](https://coveralls.io/r/rochacbruno/python-pagseguro)
[![Code Health](https://landscape.io/github/rochacbruno/python-pagseguro/master/landscape.svg)](https://landscape.io/github/rochacbruno/python-pagseguro/master)
[![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://gitter.im/python-pagseguro/Lobby)

<a target="_blank" href="https://www.paypal.com/cgi-bin/webscr?cmd=_donations&amp;business=rochacbruno%40gmail%2ecom&amp;lc=BR&amp;item_name=pythonpagseguro&amp;no_note=0&amp;currency_code=BRL&amp;bn=PP%2dDonationsBF%3abtn_donate_SM%2egif%3aNonHostedGuest"><img alt='Donate with Paypal' src='http://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif' /></a>

Integração com a API v2 de pagamentos e notificações do Pagseguro utilizando requests.

Instalando
==========================
```bash
pip install pagseguro
```

ou


```bash
pip install -e git+https://github.com/rochacbruno/python-pagseguro#egg=pagseguro
```

ou

```
git clone https://github.com/rochacbruno/python-pagseguro
cd python-pagseguro
pip install -r requirements.txt
python setup.py install
```

Rodando os testes
=================

```
make test
```

Como usar
=========

### Carrinho de compras / ordem de venda

Uma instancia de **PagSeguro** funciona como uma ordem de venda, ou um carrinho de compras. É preciso criar a instancia passando como parametro email e token.

> Opcionalmente é possivel passar o parametro **data** contendo valores a serem passados diretamente para a API.

```python
from pagseguro import PagSeguro

pg = PagSeguro(email="seuemail@dominio.com", token="ABCDEFGHIJKLMNO")
```

### Sandbox e Config Customizadas

Ao instanciar um objecto `PagSeguro`, você poderá passar um parâmetro `config` contendo a class de configuração a ser usada pela classe. A variável `config` somente irá aceitar o tipo `dict`.

```python
from pagseguro import PagSeguro

config = {'sandbox': True}
pg = PagSeguro(email="seuemail@dominio.com", token="ABCDEFGHIJKLMNO", config=config)
```

O seu config também pode fazer override de algumas váriaveis pré-definidas na classe de Config padrão. São elas:

- CURRENCY - Moeda utilizada. Valor padrão: `'BRL'`
- DATETIME_FORMAT - Formato de Data/Hora. Valor Padrão: `'%Y-%m-%dT%H:%M:%S'`
- REFERENCE_PREFIX - Formato do valor de referência do produto. Valor Padrão: `'REF%s'` Obs: Nesse caso, sempre é necessário deixar o `%s` ao final do prefixo para que o mesmo seja preenchido automaticamente
- USE_SHIPPING - User endereço de entrega. Valor padrão: `True`


### Configurando os dados do comprador

```python
pg.sender = {
"name": "Bruno Rocha",
"area_code": 11,
"phone": 981001213,
"email": "rochacbruno@gmail.com",
}
```

### Configurando endereço de entrega
```python
pg.shipping = {
"type": pg.SEDEX,
"street": "Av Brig Faria Lima",
"number": 1234,
"complement": "5 andar",
"district": "Jardim Paulistano",
"postal_code": "06650030",
"city": "Sao Paulo",
"state": "SP",
"country": "BRA"
}
```

Caso o **country** não seja informado o valor default será "BRA"

O **type** pode ser pg.SEDEX, pg.PAC, pg.NONE
> Opcionalmente pode ser numerico seguindo a tabela pagseguro:

| Número | Descrição | Type |
| ------ | --------- | ---- |
| 1 | PAC | pg.PAC |
| 2 | SEDEX | pg.SEDEX |
| 3 | Nao especificado | pg.NONE |

Valores opcionais para **shipping**
- "cost": "123456.26"
Decimal, com duas casas decimais separadas por ponto (p.e, 1234.56), maior que 0.00 e menor ou igual a 9999999.00.


### Configurando a referencia

Referencia é geralmente o código que identifica a compra em seu sistema

Por padrão a referencia será prefizada com "REF", mas isso pode ser alterado setando um prefixo diferente

```python
pg.reference_prefix = "CODE"
pg.reference_prefix = None # para desabilitar o prefixo
```

```python
pg.reference = "00123456789"
print pg.reference
"REF00123456789"
```

### Configurando valor extra

Especifica um valor extra que deve ser adicionado ou subtraído ao valor total do pagamento. Esse valor pode representar uma taxa extra a ser cobrada no pagamento ou um desconto a ser concedido, caso o valor seja negativo.

Formato: Float (positivo ou negativo).

```python
pg.extra_amount = 12.70
```

### Inserindo produtos no carrinho

O carrinho de compras é uma lista contendo dicionários que representam cada produto nos seguinte formato.

#### adicionando vários produtos

```python
pg.items = [
{"id": "0001", "description": "Produto 1", "amount": 354.20, "quantity": 2, "weight": 200},
{"id": "0002", "description": "Produto 2", "amount": 50, "quantity": 1, "weight": 1000}
]
```

O **weight** do produto é representado em gramas

#### Adicionando um produto por vez

Da forma tradicional

```python
pg.items.append(
{"id": "0003", "description": "Produto 3", "amount": 354.20, "quantity": 2, "weight": 200},
)
```

Ou atraves do helper

```python
pg.add_item(id="0003", description="produto 4", amount=320, quantity=1, weight=2500)
```

### Configurando a URL de redirect

Para onde o comprador será redirecionado após completar o pagamento

```python
pg.redirect_url = "http://meusite.com/obrigado"
```

### Configurando a URL de notificaçao (opcional)

```python
pg.notification_url = "http://meusite.com/notification"
```

### Efetuando o processo de checkout

Depois que o carrinho esta todo configurado e com seus itens inseridos, ex: quando o seu cliente clicar no botão "efetuar pagamento", o seguinte método deverá ser executado.

```python
response = pg.checkout()
```

O método checkout faz a requisição ao pagseguro e retorna um objeto PagSeguroResponse com os atributos code, date, payment_url, errors.

É aconselhavel armazenar o código da transação em seu banco de dados juntamente com as informações do carrinho para seu controle interno.

Utilize a **payment_url** para enviar o comprador para a página de pagamento do pagseguro.

```python
return redirect(response.payment_url)
```

Após o pagamento o comprador será redirecionado de volta para os eu site através da configuração de url de retorno global ou utilizará a url especificada no parametro **redirect_url**

# Notificações

O PagSeguro envia as notificações para a URL que você configurou usando o protocolo HTTP, pelo método POST.

Suponde que você receberá a notificação em: http://seusite.com/notification

> Pseudo codigo

```python
from pagseguro import PagSeguro

def notification_view(request):
notification_code = request.POST['notificationCode']
pg = PagSeguro(email="seuemail@dominio.com", token="ABCDEFGHIJKLMNO")
notification_data = pg.check_notification(notification_code)
...
```

No exemplo acima pegamos o **notificationCode** que foi enviado através do pagseguro e fizemos uma consulta para pegar os dados da notificação, o retorno será em um dicionário Python com o seguinte formato:

```python
{
"date": datetime(2013, 01, 01, 18, 23, 0000),
"code": "XDFD454545",
"reference": "REF00123456789",
"type": 1,
"status": 3,
"cancellationSource": "INTERNAL",
...
}
```

A lista completa de valores pode ser conferida em https://pagseguro.uol.com.br/v2/guia-de-integracao/api-de-notificacoes.html


# Implementações

> Implementações a serem feitas, esperando o seu Pull Request!!!

## Quokka CMS
[Quokka Cart PagSeguro Processor](https://github.com/pythonhub/quokka-cart/blob/master/processors/pagseguro_processor.py)

## Exemplo em Django

## Exemplo em Flask

[FlaskSeguro](https://github.com/rochacbruno/python-pagseguro/tree/master/examples/flask)
by @shyba

## Exemplo em web2py



## Mantenedores

Thanks goes to these wonderful people ([emoji key](https://github.com/kentcdodds/all-contributors#emoji-key)):

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
| [<img src="https://avatars1.githubusercontent.com/u/1661112?v=4" width="100px;"/><br /><sub>Patrick Mazulo</sub>](http://blog.dunderlabs.com)<br />[💻](https://github.com/rochacbruno/python-pagseguro/commits?author=mazulo "Code") [📖](https://github.com/rochacbruno/python-pagseguro/commits?author=mazulo "Documentation") | [<img src="https://avatars3.githubusercontent.com/u/234982?v=4" width="100px;"/><br /><sub>mauler</sub>](http://mauler.github.io)<br />[💻](https://github.com/rochacbruno/python-pagseguro/commits?author=mauler "Code") [📖](https://github.com/rochacbruno/python-pagseguro/commits?author=mauler "Documentation") | [<img src="https://avatars1.githubusercontent.com/u/178641?v=4" width="100px;"/><br /><sub>Ellison Leão</sub>](http://ellison.rocks)<br />[💻](https://github.com/rochacbruno/python-pagseguro/commits?author=ellisonleao "Code") [📖](https://github.com/rochacbruno/python-pagseguro/commits?author=ellisonleao "Documentation") | [<img src="https://avatars3.githubusercontent.com/u/13952931?v=4" width="100px;"/><br /><sub>Augusto Goulart</sub>](https://augustogoulart.me/)<br />[💻](https://github.com/rochacbruno/python-pagseguro/commits?author=augustogoulart "Code") [📖](https://github.com/rochacbruno/python-pagseguro/commits?author=augustogoulart "Documentation") | [<img src="https://avatars2.githubusercontent.com/u/458654?v=4" width="100px;"/><br /><sub>Bruno Rocha</sub>](http://brunorocha.org)<br />[💻](https://github.com/rochacbruno/python-pagseguro/commits?author=rochacbruno "Code") [📖](https://github.com/rochacbruno/python-pagseguro/commits?author=rochacbruno "Documentation") | [<img src="https://avatars0.githubusercontent.com/u/153288?v=4" width="100px;"/><br /><sub>Guto Maia</sub>](http://gutomaia.net)<br />[💻](https://github.com/rochacbruno/python-pagseguro/commits?author=gutomaia "Code") [📖](https://github.com/rochacbruno/python-pagseguro/commits?author=gutomaia "Documentation") |
| :---: | :---: | :---: | :---: | :---: | :---: |
<!-- ALL-CONTRIBUTORS-LIST:END -->

This project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. Contributions of any kind welcome!

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pagseguro, version 0.3.4
Filename, size File type Python version Upload date Hashes
Filename, size pagseguro-0.3.4.tar.gz (19.4 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page