PxPayPy¶

PxPayPy is a Python library for DPS PaymentExpress PxPay 2.0 API.

Features
Installation
Setting Up
First Transaction
Stored Credit Card Transactions
- Token based rebilling with PxPost
Make Transaction Request
Get Transaction Status
PxPost: Make token based transaction
Errors and Exceptions
Contribute
License

Features¶

PxPayPy supports DPS PxPay 2.0 API.
PxPayPy supports DPS PxPost token based payments with CardNumber2.

Installation¶

Install this library with pip:

pip install pxpaypy

Setting Up¶

To initialize PxPay with URL, PxPay User ID and PxPay Key:

pxpay = PxPay("https://<pxpay url>", "<user id>", "<pxpay key>")

First Transaction¶

Example purchase transaction (TXN_PURCHASE) of $1.00 of currency type NZD:

url = pxpay.make_transaction_request(
    merchant_reference="<merchant reference>",
    transaction_type=TXN_PURCHASE,
    amount=1.00,
    currency="NZD",
    transaction_id="<unique transaction id>",
    url_success="<success url>",
    url_fail="<fail url>")

make_transaction_request method returns an URL which allows user to enter credit card details, depending on success or failure of the transaction, user will be directed to either url_success or url_fail.

To determind the status of the transaction, retrieve the result parameter from the redirected URL’s query string and pass it to get_transaction_status method:

status = pxpay.get_transaction_status(result)

status is a Python dictionary with XML tags returned by PxPay API.

Stored Credit Card Transactions¶

To store credit card for future billing purpases, we should make a transaction request of type TXN_AUTH and amount of $1.00 or more:

url = pxpay.make_transaction_request(
    merchant_reference="<merchant reference>",
    transaction_type=TXN_AUTH,
    amount=1.00,
    currency="NZD",
    add_bill_card=True,
    billing_id="<billing id>",
    transaction_id="<unique transaction id>",
    url_success="<success url>",
    url_fail="<fail url>")

add_bill_card must be set to True. billing_id is optional, if billing_id is not specified we have to use dps_billing_id generated by PxPay. The URL returened by the make_transaction_request will allow user to enter their credit card information.

Retrieve the result parameter from the redirected URL’s query string to determeind the success or failure of the transaction:

status = pxpay.get_transaction_status(result)
if int(status["Success"]) == 1:
    dps_blling_id = status["DpsBillingId"]
    # DpsBillingId requires, if billing_id not set
    card_number2 = status["CardNumber2"]
    # CardNumber2 optinal for token based automated billing via PxPost

Rebill a stored credit card with user interation. User will have to enter correct CVC on PaymentExpress hosted page. We can either user BillingID or DpsBillingID:

url = pxpay.make_transaction_request(
    merchant_reference="<merchant reference>",
    transaction_type=TXN_PURCHASE,
    amount=1.00,
    currency="NZD",
    dps_billing_id = dps_blling_id, # or we could use billing_id
    transaction_id="<unique transaction id>",
    url_success="<success url>",
    url_fail="<fail url>")

URL will present user with transaction details and allow them to enter CVC, on the success or failure user will be directed to correct URL. Grab result from query string of the redirected URL to get transaction status:

status = pxpay.get_transaction_status(result)

If status["Success"] is 1 then transaction was a success.

Token based rebilling with PxPost¶

Automated token based transactions can be done using PaymentExpress PxPost API. This requires CardNumber2 generated by PxPay’s add billing card transaction and BillingID used in that transaction.

Initiate PxPost with URL, PxPost User Name and PxPost Password:

pxpost = PxPost("https://<pxpost url>", "<user name>", "<password>")

To initate token based transaction use make_token_based_transaction method:

result = pxpost.make_token_based_transaction(
    merchant_reference="<merchant reference>",
    transaction_type=TXN_PURCHASE,
    amount=1.00,
    currency="NZD",
    card_number_2=card_number_2,
    transaction_id="<unique transaction id>",
    billing_id=billing_id)

result is a Python dictionary with XML tags returned by PaymentExpress PxPost.

Make Transaction Request¶

make_transaction_request method returns an URL with credit card details form. This method can be used to make both Auth and Purchase transactions, as well as rebilling with user insteraction (i.e. user has to enter CSC).

Argument	Description
`merchant_reference`	Merchant reference (required)
`transaction_type`	Transaction type (required) Possible values: `TXN_AUTH` Auth transaction `TXN_PURCHASE` Purchase transaction
`amount`	Amount (required)
`currency`	Currency type (required)
`transaction_id`	Unique transaction ID (required)
`url_success`	URL for suceessful transactions (required)
`url_fail`	URL for failed transactions (required)
`add_bill_card`	Set this to `True` to store the card for rebilling. Default is `False`.
`billing_id`	Billing ID
`dps_billing_id`	DPS billing ID (use this when rebill a stored card)
`data_1`	Data 1
`data_2`	Data 2
`data_3`	Data 3
`email_address`	email address
`optional_text`	Optional text
`mock`	If set to `True`, XML string will be retunred without sending it the server. Default is `False`.

Get Transaction Status¶

get_transaction_status method can be used to get the status of a completed transaction. This method requires result parameter from query string of the redirected URL.

This method returns a Python dictionary with XML tags returned by PxPay API.

Argument Description

result result paramenter from the redirected URL’s query string. (required)

mock

If set to True, XML string will be retunred without sending it the server.

Default is False.

PxPost: Make token based transaction¶

make_token_based_transaction method on PxPost class can be used to purform automated token based rebill transactions. This requires CardNumber2 and BillingId from the add card transaction performed using PxPay.

This method returns a Python dictionary with XML tags returned by PxPost API.

Argument	Description
`merchant_reference`	Merchant reference (required)
`transaction_type`	Transaction type (required) Possible values: `TXN_AUTH` Auth transaction `TXN_COMPLETE` Comlete transaction `TXN_PURCHASE` Purchase transaction `TXN_REFUND` Refund transaction
`amount`	Amount (required)
`currency`	Currency type (required)
`transaction_id`	Unique transaction ID (required)
`card_number_2`	Card number 2 returned by PxPay (required)
`billing_id`	Billing ID used in PxPay add credit card transaction (required)
`data_1`	Data 1
`data_2`	Data 2
`data_3`	Data 3
`mock`	If set to `True`, XML string will be retunred without sending it the server. Default is `False`.

Errors and Exceptions¶

In case of any error like invalid XML, API server cannot be reached etc, PxPayPy will throw an Exception.

Contribute¶

Issue Tracker: https://github.com/NZRS/pxpaypy/issues
Source Code: https://github.com/NZRS/pxpaypy

License¶

The project is licensed under the GNU GPL version 3.