Ukash XML Specification - Secure Trading amount tag (e.g. 2000), included within the billing tag, is...

Ukash XML Specification

This document outlines the XML required to submit Ukash Requests to Secure Trading. Version: 1.4 Published: 23 February 2015


© Secure Trading Limited 2015 23 February 2015 / 17

Table of Contents

1 Introduction ...................................................................................................................................... 3

1.1 Parties involved .......................................................................................................................... 4 1.2 Configuration .............................................................................................................................. 4

2 Process Overview ............................................................................................................................ 5

3 Secure Trading Ukash XML Request ............................................................................................. 7

3.1 XML Overview ............................................................................................................................ 7 3.2 <settlement> .............................................................................................................................. 7 3.3 <billing> ...................................................................................................................................... 8 3.4 Table Definition of Ukash specific fields in the Request XML.................................................... 9 3.5 Example Request XML ............................................................................................................ 10

4 Secure Trading Ukash XML Response ........................................................................................ 11

4.1 XML Overview .......................................................................................................................... 11 4.2 <billing> .................................................................................................................................... 12 4.3 <settlement> ............................................................................................................................ 13 4.4 Definition of Ukash Specific fields in Response XML .............................................................. 13 4.5 Example Response XML .......................................................................................................... 14

5 Additional Notes ............................................................................................................................. 15

5.1 Confirmation to the customer ................................................................................................... 15 5.2 Fraud and duplicate checks ..................................................................................................... 15 5.3 Error handling ........................................................................................................................... 15

6 Testing ............................................................................................................................................. 16

6.1 Testing For Successful Payments ........................................................................................... 16 6.2 Testing For Declined Payments ............................................................................................... 16

7 Further Information and Support ................................................................................................. 17

7.1 Useful Documents .................................................................................................................... 17 7.2 Frequently Asked Questions .................................................................................................... 17



1 Introduction

This document is a supplement to the XML Specification. The purpose of this document is to detail the steps required in accepting Ukash vouchers. A Ukash voucher is a way for consumers to purchase online without using a credit or debit card. Ukash vouchers can be purchased at various physical locations. In the UK, PayPoint outlets sell Ukash vouchers, for example. The vouchers have a unique 19-digit code, which is entered by the customer on the payment page when purchasing online. If a customer does not redeem the full voucher amount a new voucher number is issued with the remaining value. If a voucher request has been authorised, it is processed and settled immediately with your sale assured and no chance of repudiation. To enable Ukash as a payment type on your Secure Trading account, please contact the Secure Trading sales team. Please refer to section 7 Further Information and Support on page 17 for contact information. This document pays specific attention to the fields used to create an STTP Ukash voucher Authorisation Request and the subsequent Response. Full examples of the various requests and responses follow each request/response description accordingly.

Of the fields outlined within this document, Secure Trading may add additional fields and tags in the future; we would therefore recommend that you do not build your application to only accept these tags.

Please note the order of the tags cannot be guaranteed. Some tags may be returned in a different order to the examples in this document.

http://www.securetrading.com/files/documentation/STPP-XML-Specification.pdf



1.1 Parties involved

There are four parties that are involved in the processing of Ukash transactions, they are:

The Customer The Merchant Secure Trading Ukash

Party Comment

The Customer The customer, attempting the Ukash payment.

The Merchant The merchant, who has the account with Secure Trading.

Secure Trading The Payment Service Provider.

Ukash The voucher issuer, who manages the voucher details.

1.2 Configuration

The following requirements must be met to process Ukash vouchers:

1.2.1 Secure Trading

You will need to have an account with Secure Trading. For more information, contact Secure Trading Sales (7 Further Information and Support on page 17). You will also need to have setup your system to submit XML Requests through STPP. For more information, contact Secure Trading Support (7 Further Information and Support on page 17).

1.2.2 Ukash

You will need to have an account with Ukash. For more information, contact Ukash (7 Further Information and Support on page 17).

Ukash must be enabled on your test/live account before a Ukash Request can be processed successfully. Please contact Support to get this enabled.



2 Process Overview

Below is a diagrammatic overview that represents the Ukash Authorisation (AUTH) process, followed by a detailed step by step breakdown of each stage.

Step 1) The Customer

makes a purchase on the

Merchant’s website. Step 2) The Merchant

sends an XML request to

Secure Trading.

Step 3) Secure Trading

validates the request and

sends the voucher details

to Ukash.

Step 6) The Merchant

receives the XML and

interprets the response

from Secure Trading.Step 7) The Customer

receives a confirmation

from the Merchant’s

website, along with new

voucher details, if

applicable.

Step 4) Ukash processes

the request and returns a

response to Secure

Trading.

Step 5) Secure Trading

validates the response

received from Ukash, and

submits this to the

merchant.

Figure 1 - Process overview of a Ukash payment

Step 1 - Customer logs on to merchant’s website and requests product/service

The customer initiates a payment using a prepaid Ukash voucher code.

Step 2 - AUTH Request from merchant system

The voucher number, the total amount associated with the voucher and the amount to be redeemed from the voucher are sent to Secure Trading. This is done by sending an AUTH Request in the XML format, as outlined later in the document (see section 3 Secure Trading Ukash XML Request).

Step 3 - Request from Secure Trading to Ukash

Secure Trading validates the request, by ensuring that all of the required data is present and formatted correctly. Once this has been validated, the request is sent to Ukash.



Step 4 - Response from Ukash complete with updated voucher details

Ukash process this request, returning a response that informs Secure Trading of a successful or unsuccessful state of redemption.

If a successful state is returned and the redeemed amount was less than the voucher amount, it is accompanied by a new voucher number, a new voucher expiry date and the remaining amount associated with the voucher number provided.

If a successful state is returned when the redemption amount is the same as the voucher amount, no new voucher details are returned.

If an unsuccessful state is returned, no voucher details are returned.

Step 5 - Response sent to merchant

This response is processed and validated by Secure Trading before being formatted into an XML Response like that seen in section 4 Secure Trading Ukash XML Response. This is then returned to the merchant.

Step 6 – Merchant receives XML response - Transaction completion

The merchant receives the XML response sent by Secure Trading and interprets the response. At this point the request and response handling by Secure Trading is complete, and the response will have been sent to the merchant. If successful, the transaction’s settle status is immediately updated on Secure Trading’s records to ‘100’ (settled), however if the transaction was unsuccessful then the status is updated to settle status ‘3’ (cancelled).

Step 7 – Customer receives confirmation on-screen of payment attempt

After the merchant has interpreted the XML response, the results are displayed on-screen to the customer as confirmation that their payment has been processed successfully which may include new voucher details.



3 Secure Trading Ukash XML Request

In order for a Ukash Request to be successfully processed by Secure Trading, the submitted XML must be in accordance with the following formatting specification.

Please note that an Example Ukash XML Request/Response combination can be found in the STAPI client files within the folder AUTH_UKASH which can be downloaded from our website: http://webapp.securetrading.net/examples/STAPI_JAVA1.6.zip

3.1 XML Overview

alias

+

billing

+merchant

+

customer

request type = “AUTH”

operation

+

Figure 2 - XML overview of a Ukash Authorisation Request

This section describes how the XML structure of a Ukash Authorisation (AUTH) Request differs from the regular e-commerce AUTH Request outlined in the STPP XML Specification document (see section 7.1 Useful Documents on page 17).

As with a regular Authorisation Request, the request type element is set to

“AUTH”.

3.2 <settlement>

The settlement tag is not required for a Ukash Request. This is because a Ukash transaction

is immediately settled (settlestatus = 100) on the completion of a successful transaction.

Please note that it is not possible to defer Ukash payments, as settlement is instantly performed on successful transactions.

http://webapp.securetrading.net/examples/STAPI_JAVA1.6.zip



3.3 <billing>

name

request type = “AUTH”

alias

billing ++

premise

street

county

country

email

payment type= ”UKASHVOUCHER”

postcode

town

amount currencycode=””

+

telephone type=””

voucheramount

vouchernumber

Figure 3 - XML overview of <billing> in a Ukash Authorisation Request

3.3.1 <amount>

The amount tag (e.g. <amount currencycode="GBP">2000</amount>), included within

the billing tag, is used to detail the amount to be redeemed from a Ukash voucher.

3.3.2 <payment>

The payment type for a Ukash payment is “UKASHVOUCHER”

Within the payment tag, instead of passing credit/debit card details within the payment tag, the

following two Ukash specific values are required:

vouchernumber – The 19 digit Ukash voucher number.

voucheramount – The current value associated with the voucher.



3.4 Table Definition of Ukash specific fields in the Request XML

The following table defines the expected lengths and data types of the Ukash fields that are submitted as part of the request.

Tag Type Length Required Comment

billing Y The billing tag

amount an 15 Y The amount you are redeeming from the voucher

payment type =

“UKASHVOUCHER” an 20 Y

This is the only accepted payment type for a Ukash redemption

voucher

number n 19 Y

This is the voucher number provided to you by the customer

voucher

amount n 15 Y

The full amount currently allocated to that voucher



3.5 Example Request XML

Here is an example of an Authorisation Request, with a payment type of

“UKASHVOUCHER”, being submitted to Secure Trading’s systems. The fields relevant to Ukash payments are highlighted in bold. <requestblock version="3.67">

<alias>test_example40000</alias>

<request type="AUTH">

<operation>

<sitereference>test_example40000</sitereference>

<accounttypedescription>ECOM</accounttypedescription>

</operation>

<merchant>

<orderreference>AUTH_VISA</orderreference>

<termurl>https://ww.example.com/termurl.cgi</termurl>

<email></email>

<name>Merchant Name</name>

</merchant>

<customer>

<town>Bangor</town>

<name>

<middle>Mary</middle>

<prefix>Miss</prefix>

<last>Smith</last>

<first>Joanne</first>

</name>

<ip>1.2.3.4</ip>

<telephone type="H">1111111111</telephone>

<street>Second Street</street>

<postcode>CU888ST</postcode>

<premise>111</premise>

</customer>

<billing>

<name>

<middle>joe</middle>

<prefix>Dr</prefix>

<last>bloggs</last>

<suffix>Jr.</suffix>

<first>fred</first>

</name>

<telephone type="M">0777777777</telephone>

<email>[email protected]</email>

<premise>789</premise>

<street>Test Street</street>

<town>Bangor</town>

<postcode>TE45 6ST</postcode>

<county>Gwynedd</county>

<country>GB</country>

<amount currencycode="GBP">100</amount>

<payment type="UKASHVOUCHER">

<vouchernumber>6002349752638446279</vouchernumber>

<voucheramount>200</voucheramount>

</payment>

</billing>

</request>

</requestblock>



4 Secure Trading Ukash XML Response

Following processing the Ukash Authorisation (AUTH) Request (see section 3 Secure Trading Ukash XML Request), Secure Trading will return an AUTH XML Response. The XML will be made up of the tags outlined within this section of the document.

4.1 XML Overview

response type = “AUTH”

+operation

authcode

timestamp

transactionreference

+merchant

live

+settlement

+billing

+error

acquirerresponsecode

acquirerresponsemessage

amount

payment type=“UKASHVOUCHER”

Figure 4 - XML overview of a Ukash Authorisation Response

This section describes how the XML structure of a Ukash AUTH Response differs from the regular e-commerce AUTH Response outlined in the STPP XML Specification document (see 7.1 Useful Documents on page 17).



4.2 <billing>

response type = “AUTH” billing changeissuevoucherexpirydate

payment type=“UKASHVOUCHER”

changeissueamount

changeissuevouchernumber

changeissuevouchercurrencyiso3a

++

Figure 5 - XML overview of <payment> in a Ukash Authorisation Response

Within the billing tag, there are Ukash specific fields returned in the payment tag.

4.2.1 <payment>

The payment type returned for a Ukash payment is “UKASHVOUCHER”.

If the amount redeemed from the customer’s voucher was less than the total value of the voucher, the following Ukash specific fields will be returned in the payment tag:

changeissuevoucherexpirydate - This is the expiration date of the new voucher.

changeissueamount - This is the new voucher amount after a successful purchase.

changeissuevouchernumber - This is the new voucher number.

changeissuevouchercurrencyiso3a - This is the currency of the new voucher.

An example of the payment tag, from the XML Response that follows a successful Ukash

Authorisation Request, is shown below:


<changeissuevouchercurrencyiso3a>GBP</changeissuevouchercurrencyiso3a>

<changeissueamount>1000</changeissueamount>

<changeissuevoucherexpirydate>2013-12-25</changeissuevoucherexpirydate>

<changeissuevouchernumber>1234567890123456789</changeissuevouchernumber>

</payment>

When the above mentioned fields are returned in the XML, they must be passed on to the customer. The customer will need these payment details in order to make further purchases.

Please note that only the changeissuevouchercurrencyiso3a element is

returned within the payment tag when the full amount is redeemed from the

voucher, or if the payment is declined.



4.3 <settlement>

The settlement tag returned, following a successful Ukash Request, will have a

settlestatus of “100”, as Ukash transactions are settled immediately.

An example of the settlement tag, from the XML Response that follows a successful Ukash

Authorisation Request, is shown below: <settlement>

<settleduedate>2013-02-19</settleduedate>

<settlestatus>100</settlestatus>

</settlement>

4.4 Definition of Ukash Specific fields in Response XML

The following table defines the expected lengths and data types of the Ukash fields that are received as part of the response.

Tag Type Length Required Comment

billing Y The billing tag

payment type =

“UKASHVOUCHER” an 20 Y

This is the only accepted payment type for a Ukash redemption.

change

issue

voucher

expirydate

an 10 C The voucher expiration date.

change

issueamount n 15 C

The new total amount of the voucher after redemption.

change

issue

voucher

number

n 19 C The new voucher number that is allocated linking it to its new total amount.

change

issue

voucher

currency

iso3a

an 3 Y The new voucher currency.



4.5 Example Response XML

Please find below an example of a Secure Trading XML Response to a Ukash Authorisation Request for part of a voucher’s full value. The fields relevant to Ukash payments are highlighted in bold.

Please note that only the changeissuevouchercurrencyiso3a element is

returned within the payment tag when the full amount is redeemed from the

voucher, or if the payment is declined.

<?XML version='1.0' encoding='utf-8'?>

<responseblock version="3.67">

<requestreference>X500977429</requestreference>

<response type="AUTH">

<merchant>

<merchantname>Live</merchantname>

<orderreference>Example AUTH</orderreference>

<merchantcountryiso2a>GB</merchantcountryiso2a>

</merchant>

<transactionreference>12-21-4</transactionreference>

<billing>

<amount currencycode="GBP">100</amount>


<changeissuevouchercurrencyiso3a>GBP</changeissuevouchercurrencyiso3a>

<changeissueamount>100</changeissueamount>

<changeissuevoucherexpirydate>2013-12-25</changeissuevoucherexpirydate>

<changeissuevouchernumber>1234567890123456789</changeissuevouchernumber>

</payment>

</billing>

<authcode>10</authcode>

<timestamp>2012-12-14 11:06:00</timestamp>

<settlement>

<settleduedate>2012-12-14</settleduedate>

<settlestatus>100</settlestatus>

</settlement>

<live>1</live>

<error>

<message>Ok</message>

<code>0</code>

</error>

<acquirerresponsecode>0</acquirerresponsecode>

<operation>

<accounttypedescription>ECOM</accounttypedescription>

</operation>

<acquirerresponsemessage>Accepted</acquirerresponsemessage>

</response>

</responseblock>



5 Additional Notes

This section details additional notes, which are relevant to the processing of Ukash payments using the Secure Trading platform.

5.1 Confirmation to the customer

It is recommended that merchants utilising Ukash have a rule set up that automatically sends a confirmation of payment to the customer. The notification will include:

changeissuevouchernumber

changeissueamount

changeissuevoucherexpirydate

The above mentioned fields must be passed on to the customer, as they include the new voucher details. More information on these fields can be found in section 4.4 Definition of Ukash Specific fields in Response XML.

If you would like this rule setting up, please contact our support team (see section 7 Further Information and Support).

5.2 Fraud and duplicate checks

Fraud and duplicate checks are not performed on Ukash transactions.

5.3 Error handling

In the event of an error, the following XML format will be returned: <error>

<message>Invalid field</message>

<code>30000</code>

<data>vouchernumber</data>

</error>

In the above case we see the vouchernumber field is invalid. This would require us to check

the data submitted as part of the request to resolve any issues, before re-submitting with the correct data present.

The Ukash payment type can only be used as a request type of “AUTH”. No refunds or reversals are possible with this payment type as the Authorisation will settle immediately, once processed.



6 Testing

This section outlines information required to perform Ukash testing on the Secure Trading platform.

6.1 Testing For Successful Payments

To test the Ukash integration with your test account (e.g. test_sitereference12345), you can use the following Ukash voucher information to process a SUCCESSFUL transaction: Transaction Amount (£10): 1000 (should be no more than the value of the voucher, below) Ukash Voucher Number : 6002349752638446279 Ukash Voucher Amount (£20): 2000

6.2 Testing For Declined Payments

To test for a DECLINED Ukash payment, use the below details: Transaction Amount (£10.02): 1002 (should be no more than the value of the voucher, below) Ukash Voucher Number: 6002349752638446279 Ukash Voucher Amount (£25.00): 2500

Ukash must be enabled on the merchant’s test/live account before a Ukash Request can be processed successfully. Please contact Support to activate this on your account.



7 Further Information and Support

If you require any further information on the contents of this document, please contact the relevant department.

Secure Trading Support

Method Details

Telephone +44 (0) 1248 672 050

Fax +44 (0) 1248 672 099

Email [email protected]

Website http://www.securetrading.com/support/support.html

Secure Trading Sales

Method Details

Telephone 0800 028 9151

Telephone (Int’l) +44 (0) 1248 672 070

Fax +44 (0) 1248 672 079


Website http://www.securetrading.com

Ukash Support

Method Details

Telephone 0808 234 6244

Telephone (Int’l) +49 30 32768 1678


Website http://www.ukash.com

7.1 Useful Documents

The documents listed below should be read in conjunction with this document:

STAPI User Guide – This document outlines how to install an STAPI java client. This client can be used to process XML Requests and Responses through Secure Trading.

STPP Web Services User Guide – This document describes how to process XML Requests and Responses through Secure Trading’s Web Services solution.

STPP XML Specification– This documentation specifies the XML format accepted by our system and denotes its usage.

All of the above documentation can be found on our Website’s Support section here.

7.2 Frequently Asked Questions

Please visit the FAQ section on our website (http://www.SecureTrading.com/support/faq).

mailto:[email protected]

http://www.securetrading.com/support/support.html

mailto:[email protected]

http://www.securetrading.com/

http://www.ukash.com/

http://www.securetrading.com/sites/default/files/downloads/stapi/STPP%20STAPI%20User%20Guide.pdf

http://www.securetrading.com/sites/default/files/downloads/webservices/STPP%20Web%20Services%20User%20Guide.pdf

http://www.securetrading.com/sites/default/files/downloads/xml/STPP%20XML%20Specification.pdf

http://www.securetrading.com/support

http://www.securetrading.com/support/faq

Ukash XML Specification - Secure Trading amount tag (e.g. 2000), included within the billing tag, is...

Documents

Transcript of Ukash XML Specification - Secure Trading amount tag (e.g. 2000), included within the billing tag, is...