PayWay interface

This will not be of interest to most of my readers, but one person did ask.

This is just to document how my system (which was built quite a few years ago) handles credit card payments via Westpac’s payment gateway, PayWay. The interface is rather dated and the way my system uses it is a bit hackish (in other words, this is not best practice!) but for what it’s worth:

Step 1. On the server, generate a unique transaction reference, e.g. id123456

Step 2. On the server, request a token via HTTP Post:

http://www.payway.com.au/RequestToken

Data (all one line):

biller_code=my-vendor-code
&merchant_id=my-merchant-id
&payment_reference_text=Our+Reference
&payment_reference=id123456
&payment_amount_text=Amount
&payment_amount=123.45
&receipt_address=customer@example.com
&username=my-payway-username
&password=my-payway-password
&payment_alert=bookkeeper@example.com
&return_link_url=http://example.com/return/gamesfestid12345
&return_link_redirect=true
&information_fields=CustomField1,CustomField2
&CustomField1=foo
&CustomField2=bar

Make sure all the values are url encoded.

Some of the fields are optional. The “information_fields” is a list of custom attributes that you can add if you want.

Step 3. Read the response

The response data will be something like this:

token=xyz1234567890

If it doesn’t start with “token=”, I interpret it as an error message.

Step 4. On the client, redirect browser to this URL:

http://www.payway.com.au/MakePayment?biller_code=my-vendor-code&token=xyz1234567890

Step 5. After the user comes back to your site (or in a separate server job) you have to query PayWay’s system to find out the result of the transaction, using the payment reference you generated earlier. This is a REST-style interface.

http://api.payway.com.au/rest/v1/transactions/search-customer?customerNumber=id123456

This returns a JSON document listing one or more transactions for the given reference, including transactionid (e.g. 12345678901234567890), status, transactionType, paymentAmount, and settlementDate.

Step 6. For each transaction, query PayWay’s system again to get all the details, using the transactionid retrieved earlier.

http://api.payway.com.au/rest/v1/transactions/12345678901234567890

This returns a JSON document with attributes including: receiptNumber, status, responseCode, responseText, transactionType, customerName, customerEmail, principalAmount, creditcard.cardScheme, creditCard.cardNumber, creditCard.expiryDateMonth, creditCard.expiryDateYear, creditCard.cardholderName, transactionDateTime, settlementDate, declinedDate, isRefundable

My system keeps track of the payment references generated in step #1, and periodically requeries PayWay to get the results (and I give up after about a day or two – this happens if the customer never completes the transaction).

Note that for all this to work, you have to first get the bank to enable both interfaces for your client – the token interface on www.payway.com.au) as well as the REST-style interface on api.payway.com.au. It took quite a few emails and phone calls before it was all working.