Iugu python API
This package is the more idiomatic python lib to work with Iugu service. The lib is compatible with Iugu API v1
This package was original developed by horacioibrahim in https://github.com/horacioibrahim/iugu-python
Updates
- Updated to Python 3
- Create a new argument in create_charge, named tokenid if you want to work with Iugu.js
Overview
This iugu-python lib is the more pythonic way to work with the webservices of payments iugu.com. This provides python objects to each entity of the service as Subscriptions, Plans, Customers, Invoices, etc. http://iugu.com/referencias/api - API Reference
Prerequisites
In order to use the code in this package, you need to obtain an account (API key) from http://iugu.com/referencias/api. You'll also find full API documentation on that page.
In order to run the sample code, you need a user account on the test mode service where you will do your development. Sign up for an account at https://iugu.com/signup and change mode in https://iugu.com/a/administration ("Modo de Teste")
In order to run the client sample code, you need a account user token. This is automatically created. See https://iugu.com/settings/profile
Quick Install
Using pip
pip3 install iugu-python3
or
Using setup.py
# Downloading package master or release:
# https://github.com/fellipeh/iugu-python3/archive/master.zip
# or https://github.com/fellipeh/iugu-python3/releases
unzip iugu-python3-master.zip
cd iugu-python3-master
python3 setup.py install
or
Clone the git
git clone https://github.com/fellipeh/iugu-python3
pip3 install -e iugu_python3
Usage (Quick Start)
Export environment variable IUGU_API_TOKEN
# For linux users:
export IUGU_API_TOKEN=XXX
Merchant operations
from iugu.merchant import IuguMerchant, Item
client = IuguMerchant(account_id="YOUR ACCOUN ID",
api_mode_test=True)
token = client.create_payment_token('4111111111111111', 'JA', 'Silva',
'12', '2010', '123')
=> https://api.iugu.com/v1/payment_token
How create an item for charge
item = Item("Produto My Test", 1, 10000)
Now you can to create charge
charge = client.create_charge(EMAIL_CUSTOMER, item, token=token.id)Check invoice ID created. All payment pass by Invoice.
charge.invoice_id
Or create a blank_slip ("Boleto Bancário")
charge = client.create_charge(EMAIL_CUSTOMER, item)
=> https://api.iugu.com/v1/charge
Customer operations
from iugu.customers import IuguCustomer
client = IuguCustomer()
customer = client.create(email='your_customer@example.com')
=> https://api.iugu.com/v1/customersNow you can to retrieve customer
client.get(customer_id)
You can edit existent customer
client.set(CUSTOMER_ID, name="Sub Zero Wins")
Or you can to use save()
customer.name = "Sub Zero Wins"
customer.save()
To remove or delete customer
client.delete(CONSUMER_ID) # by id
or
customer.remove() # by current instance
Operations with lists of customer
Get all customer
from iugu.customers import IuguCustomer
client = IuguCustomer()
# your flavor of options
# client.getitems([limit, skip, query, sort, created_at_from, created_at_to,
# updated_since])
Use one option per time. Samples:
client.getitems(limit=30) # Get most recent (latest) 30 customers
client.getitems(skip=14) # Skip X customers. Useful for pagination
client.getitems(updated_since="2014-06-05T15:02:40-03:00")
In tests SORT is not support by API:
client.getitems(sort="-name") # Sort by field >>name<< (descending)
client.getitems(sort="name") # Sort by field >>name<< (ascending)
=> http://iugu.com/referencias/api#listar-os-clientesOperations with Invoices
Create an invoice
from iugu.invoices import IuguInvoice
from iugu.merchant import Item
item = Item("Curso: High Self Learning", 1, 6900) # qtd:1; price: 69,00
invoice_obj = IuguInvoice()
new_invoice = invoice_obj.create(due_date='24/06/2014',
email='customer@example.com', items=item)
Get invoice by id
# not is need previous instance/obj (classmethod)
invoice_existent = IuguInvoice.get('A4AF853BC5714380A8708B2A4EDA27B3')
Get all invoices
# not is need previous instance/obj
invoices = IuguInvoice.getitems() # outcomes list of invoices (max 100 by API)
Get all with filter
invoices = IuguInvoice.getitems(limit=10)
invoices = IuguInvoice.getitems(skp=5)
invoices = IuguInvoice.getitems(sort="-email") # DESC
invoices = IuguInvoice.getitems(sort="email") # ASC
...
Edit/change invoice. Only invoices with status "draft" can be changed all fields otherwise (if status pending, cancel or paid) only the logs field can to change
invoice_existent = IuguInvoice.get('A4AF853BC5714380A8708B2A4EDA27B3')
invoice_existent.email = "other@other.com"
invoice_existent.save()
Remove
invoice_existent.remove()
Cancel
IuguInvoice.to_cancel('A4AF853BC5714380A8708B2A4EDA27B3')
Refund
invoice_existent = IuguInvoice.get('A4AF853BC5714380A8708B2A4EDA27B3')
invoice_existent.refund()
Operations with Subscriptions
Create a subscription
from subscriptions import IuguSubscription
client = IuguSubscription()
# from plans import IuguPan
# plan_x = IuguPlan().create("Plano Collor", "plano_collor")
# from customers import IuguCustomer
# mario = IuguCustomer().create(email='supermario@gmail.com')
# subscription = client.create(customer_id=mario.id,
# plan_identifier=plan_x.identifier)
subscription = client.create(customer_id="XXX", plan_identifier="XXX")
Get one
subscription = IuguSubscription.get('ID')
Edit/Change
subscription = IuguSubscription.get('ID')
subscription.expires_at = "14/07/2014"
subscription.save()
Remove
subscription.remove()
References
- API Document: http://iugu.com/referencias/api
Known Issues
Date Types
It's need to use date formatted as string "2014-06-05T15:02:40-03:00", but in new release date will python date.
