WireTransfers’s documentation!¶

Philosophy¶

WireTransfers is being developed while keeping a few PEP 20 idioms in mind:

1. Beautiful is better than ugly.
2. Explicit is better than implicit.
3. Simple is better than complex.
4. Complex is better than complicated.
5. Readability counts.

Therefore all contributions to WireTransfers should keep these important words in mind.

ISC License¶

WireTransfers is released under the terms of The ISC License.

“Why the ISC license?”, you may ask? That’s because this license allows software to be used freely in proprietary, closed-source software.

WireTransfers License¶

Copyright (c) 2012-2014 Priit Laes.

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Setting up the provider¶

Each provider has to be initialized by provider-specific keychain. Depending on keychain, its arguments are either simple strings (Solo/TUPAS) or consists of private/public key pair objects (IPizza).

from wirexfers.providers import PseudoProvider

# Create and initialize provider-specific keychain
keychain = PseudoProvider.KeyChain(...)

# Create and initialize the provider
#: user - user id used at provider's side
#: endpoint - endpoint address where to send payment request
provider = PseudoProvider(user, keychain, endpoint)

Creating the payment and initializing the payment request¶

In order to make a payment, we first need to set up a payment information by filling out relevant fields of PaymentInfo.

from wirexfers import PaymentInfo, utils
info = PaymentInfo('1.00', 'Test transfer', utils.ref_731('123'))

Now that we have the PaymentInfo, in order to create a payment request, we have to create a dictionary containing return urls to views where our application handles the payment response.

urls = {'return': 'http://example.com'}

With that, everything we need to create a payment request (PaymentRequest) has been done:

payment = provider(info, urls)

All we need now is to pass the payment info into template and create a HTML form visible to the user:

This is all from application side, we just have to pass the payment to the template in order to show the payment form to the user. Lets assume that payment request has been passed into template context as payment variable, so can use form iterator to create form fields, info to display the payment information and various provider fields to initialize a simple HTML form.

Basic Jinja2 template should look like this:

<form method="POST" action="{{ payment.provider.endpoint }}" accept-charset="{{ payment.provider.form_charset }}">
{% for item in payment.form -%}
    {% set name, value = item -%}
    <input name="{{ name }}" value="{{ value }}" type="hidden">
{% endfor -%}
<dl>
  <dt>Amount:</dt>
  <dd>{{ payment.info.amount }}</dd>
  <dt>Message:</dt>
  <dd>{{ payment.info.message }}</dd>
</dl>
<input type="submit">
</form>

Handling the Payment response¶

In order to verify payment status, we just need to parse the request data using parse_response(). This create a PaymentResponse which contains is_valid and various other data related to payment.

from wirexfers.exc import InvalidResponseError
# data contains either POST or GET request data
try:
    payment = provider.parser_response(data)
except InvalidResponseError
    # Signature failure, we should redirect to proper error page
    pass

if payment.is_valid:
    # Show "Successful order page!"
else:
    # Show "Order failure page"

And that’s basically how it works! :)

Providers supporting IPizza protocol¶

• Supported Estonian banks:

  • Danske Bank Estonia - wirexfers.providers.ipizza.EEDanskeProvider
  • Krediidipank - wirexfers.providers.ipizza.EEKrediidipankProvider
  • LHV Bank Estonia - wirexfers.providers.ipizza.EELHVProvider
  • SEB Bank Estonia - wirexfers.providers.ipizza.EESEBProvider
  • Swedbank Estonia - wirexfers.providers.ipizza.EESwedBankProvider

Providers supporting Solo/TUPAS protocol¶

• Supported Estonian banks:

  • Nordea Estonia - wirexfers.providers.tupas.EENordeaProvider

Payment Providers¶

Base Classes¶

class wirexfers.providers.KeyChainBase¶

Base class for protocol-specific key handling.

class wirexfers.providers.ProviderBase(user, keychain, endpoint, extra_info={})¶

Base class for all payment providers.

endpoint = None¶

Endpoint address used to initiate payment requests.

extra_info = None¶

Dictionary containing extra user-supplied information. Can be used for supplying provider url, etc.

keychain = None¶

Protocol-specific keychain implementation - wirexfers.providers.KeyChainBase

parse_response(data)¶

Parse the payment request.

Parameters:	form – Raw payment response data.

user = None¶

User id for payment processor.

ProviderBase.__call__(payment, return_urls)¶

Create and return a payment request.

Parameters:	payment (PaymentInfo) – payment information
Return type:	PaymentRequest

class wirexfers.PaymentRequest(provider, info, return_urls)¶

PaymentRequest class.

Parameters:	provider (ProviderBase.) – Payment provider info (PaymentInfo.) – Payment information return_urls (Dict) – Dictionary of return URLs. Depends on the specific provider, but generally {'return': ... } is required.

Raises ValueError when invalid configuration is detected.

form = None¶

List containing (name, value) tuples for HTML-form setup.

info = None¶

PaymentInfo containing various payment information (sum, etc..)

provider = None¶

ProviderBase that handles the payment request.

class wirexfers.PaymentResponse(provider, data, successful=False)¶

PaymentResponse class.

data = None¶

Dictionary containing payment-related data, specific to provider

provider = None¶

ProviderBase that handles the payment request.

successful = None¶

Whether payment response is successful (some providers don’t provide this status, therefore allow setting it from the view)

Exceptions¶

Utility Classes¶

class wirexfers.PaymentInfo(amount, message, refnum)¶

Payment information required for PaymentRequest.

amount = None¶

Payment amount as string, uses . as decimal point separator.

message = None¶

Message used for payment description.

refnum = None¶

Reference number.

Utility Functions¶