Using WireXfers¶

This section should give you an introduction on how to integreate WireXfers with various applications and web frameworks.

Note

Code snippets below use pseudocode and will not work when using them in real application. Consult framework-specific examples for real working code.

Basic flow of the payment process is following:

Initialize provider-specific keychain
Initialize provider
Create payment information
Show user the payment form which takes him to provider page
Process the return results

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.

Note

Return url support varies with providers. Please consult each providers documentation to see which return urls are supported. By default we need at least the return URL.

Note

Return urls should be absolute!

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¶

Note

Depending on the provider, we need either handle single or multiple return urls.

Note

Depending on the provider we need to either handle GET or POST request data.

Note

Depending on the provider we also need to handle responses in non-utf8 charsets.

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! :)