ukash xml specification - secure trading amount tag (e.g. 2000), included within the billing tag, is...
TRANSCRIPT
Ukash XML Specification
This document outlines the XML required to submit Ukash Requests to Secure Trading. Version: 1.4 Published: 23 February 2015
Ukash XML Specification
© Secure Trading Limited 2015 23 February 2015 Page 2 / 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
Ukash XML Specification
© Secure Trading Limited 2015 23 February 2015 Page 3 / 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.
Ukash XML Specification
© Secure Trading Limited 2015 23 February 2015 Page 4 / 17
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.
Ukash XML Specification
© Secure Trading Limited 2015 23 February 2015 Page 5 / 17
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.
Ukash XML Specification
© Secure Trading Limited 2015 23 February 2015 Page 6 / 17
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.
Ukash XML Specification
© Secure Trading Limited 2015 23 February 2015 Page 7 / 17
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.
Ukash XML Specification
© Secure Trading Limited 2015 23 February 2015 Page 8 / 17
3.3 <billing>
name
request type = “AUTH”
alias
billing ++
premise
street
county
country
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.
Ukash XML Specification
© Secure Trading Limited 2015 23 February 2015 Page 9 / 17
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
Ukash XML Specification
© Secure Trading Limited 2015 23 February 2015 Page 10 / 17
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>
Ukash XML Specification
© Secure Trading Limited 2015 23 February 2015 Page 11 / 17
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).
Ukash XML Specification
© Secure Trading Limited 2015 23 February 2015 Page 12 / 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:
<payment type="UKASHVOUCHER">
<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.
Ukash XML Specification
© Secure Trading Limited 2015 23 February 2015 Page 13 / 17
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.
Ukash XML Specification
© Secure Trading Limited 2015 23 February 2015 Page 14 / 17
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>
<payment type="UKASHVOUCHER">
<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>
Ukash XML Specification
© Secure Trading Limited 2015 23 February 2015 Page 15 / 17
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.
Ukash XML Specification
© Secure Trading Limited 2015 23 February 2015 Page 16 / 17
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.
Ukash XML Specification
© Secure Trading Limited 2015 23 February 2015 Page 17 / 17
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
Email [email protected]
Website http://www.securetrading.com
Ukash Support
Method Details
Telephone 0808 234 6244
Telephone (Int’l) +49 30 32768 1678
Email [email protected]
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).