NAV
XML

Introduction

The wiPlatform is an open, interoperable platform that facilitates mobile transactions between a Retailer, Customer and Value Service Provider (VSP) at a Point of Sale. A single integration with the wiPlatform enables a Point of Sale to interact with any Mobile Application and enable a Customer to transact using a wiCode (token) in store.

Monetary values

Monetary amounts are both accepted and returned in minor denominations.

Versioning

This API exposes two optional versioning fields.

<apiCredentials>
  <!--Optional:-->
  <apiClientVersion></apiClientVersion>
  <!--Optional:-->
  <apiServerVersion></apiServerVersion>
  <id></id>
  <password></password>
</apiCredentials>
Fields Data Type Required/Optional Description
apiClientVersion String Optional This field can be used by POS integrators to send the version of their implementation to the wiPlatform.
apiServerVersion String Optional This field allows POS integrators to send the version of the wiGroup server in use as at their time of integration, ensuring strict backwards compatibility.

API server versions

The following API server versions are currently being supported:

apiServerVersion Description Environment(s)
1.5 Base Integration, Production
1.8 Support added for loyalty on split tender. VSP Name included on Transaction History. Integration, Production
1.9 List Redemptions in transaction API. Integration, Production
1.10 tokenInfo flags added. Integration, Production
1.11 getVasToken API call added. Enable main VSP for loyalty redemption. Integration

POSTman

Run in Postman

Transaction

A transaction is logged in the transaction engine and routed to the relevant VSP.

HTTP Protocol: SOAP
Available HTTP Methods: POST
Integrations Environment WSDL URL: http://rad2.wigroup.co:8080/wigroup-transactionengine/PosProviderWS?wsdl

Transaction Request

The basic layout of a Transaction Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:pos="http://posprovider.te.wigroup.com/">
  <soapenv:Header/>
  <soapenv:Body>
    <pos:transaction>
      <request>
        <apiCredentials>
          <!--Optional:-->
          <apiClientVersion></apiClientVersion>
          <!--Optional:-->
          <apiServerVersion></apiServerVersion>
          <id></id>
          <password></password>
        </apiCredentials>
        <basketAmount></basketAmount>
        <cashbackAmount></cashbackAmount>
        <!--Zero or more repetitions:-->
        <product>
          <id></id>
          <pricePerUnit></pricePerUnit>
          <units></units>
        </product>
        <storeTrxDetails>
          <basketId></basketId>
          <cashierId></cashierId>
          <posId></posId>
          <remoteStoreId></remoteStoreId>
          <retailerId></retailerId>
          <storeId></storeId>
          <trxId></trxId>
        </storeTrxDetails>
        <switchTrxId></switchTrxId>
        <tipAmount></tipAmount>
        <token>
          <id></id>
          <type></type>
        </token>
        <totalAmount></totalAmount>
        <type></type>
      </request>
    </pos:transaction>
  </soapenv:Body>
</soapenv:Envelope>

The Transaction Request is performed when a transaction is logged to the wiPlatform Transaction Engine and routed to the relevant VSP.

The basic layout of the Transaction Request looks as follows:

Fields Data Type Required/Optional Description
apiCredentials apiCredentials Required API credentials are used to authenticate each API call. Find information about the apiCredentials object here.
basketAmount Integer Required This is the total transaction amount (in cents) of all products in the basket.
cashBackAmount Integer Optional This is the amount of cash in cent being withdrawn as part of the transaction. It can either be used in conjunction with a basked payment or on its own. cashBackAmount is only used with a transaction of type: PAYMENT.
product products Optional A list of products in the basket. Please find information about the Product object here.
storeTrxDetails storeTrxDetails Required This object contains information about the store in which the transaction took place. Find information about the StoreTrxDetails object here.
switchTrxId String Optional If applicable, the switch will assign their ID to the transaction.
tipAmount Integer Optional The tipAmount must be included in the total amount for the VSP to process the full amount. Not all VSP’s support tipAmount.
token token Required This object contains information about the wiPlatform token associated with this transaction. Please find information about the Token object here.
totalAmount Integer Required This is the total transaction amount in cent. This is the sum of the basketAmount, the cashbackAmount, and tipAmount.
type String Required This is the type of transaction. It can be set to either PAYMENT, DEPOSIT or WITHDRAWAL.

Transaction Response

The basic layout of a Transaction Response:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <ns2:transactionResponse xmlns:ns2="http://posprovider.te.wigroup.com/">
      <response>
        <responseCode></responseCode>
        <responseDesc></responseDesc>
        <amountToSettle></amountToSettle>
        <basketAmountProcessed></basketAmountProcessed>
        <cashbackAmountProcessed></cashbackAmountProcessed>
        <storeTrxDetails>
          <basketId></basketId>
          <cashierId></cashierId>
          <posId></posId>
          <remoteStoreId></remoteStoreId>
          <storeId></storeId>
          <trxId></trxId>
        </storeTrxDetails>
        <tipAmountProcessed></tipAmountProcessed>
        <token>
          <id></id>
          <type></type>
        </token>
        <totalAmountProcessed></totalAmountProcessed>
        <type></type>
        <vsp>
          <id></id>
          <message></message>
          <name></name>
          <responseCode></responseCode>
          <responseDesc></responseDesc>
          <trxId></trxId>
        </vsp>
        <wiTrxId></wiTrxId>
        <discount>
            <amount></amount>
            <name></name>
            <product>
                <id></id>
                <units></units>
            </product>
        </discount>
        <loyalty>
          <name></name>
          <type></type>
          <earned></earned>
        </loyalty>
      </response>
    </ns2:transactionResponse>
  </S:Body>
</S:Envelope>

The POS receives a Transaction Response from the wiPlatform Transaction Engine.

The basic layout of the Transaction Response looks as follows:

Fields Data Type Description
responseCode Integer A code indicating the result of the request. -1 means successful. All other codes are treated as failed. Find a list of response codes and their descriptions here.
responseDescription String Readable description of responseCode. Find a list of response codes and their descriptions here.
amountToSettle Integer This is the amount, in cent, of the total transaction amount that will be settled to the retailer. The deficit between amountToSettle and totalAmountProcessed is regarded as the discount amount for non/partially-settled campaigns and should be handled as such. This field is only displayed when using apiClientVersion 1.6 and above.
basketAmountProcessed Integer Returns the basketAmount that was used in processing of the transaction.
cashbackAmountProcessed Integer This is the amount of cash in cents being withdrawn as part of the transaction. It can either be used in conjunction with a basket payment or on its own.
storeTrxDetails storeTrxDetails This object contains information about the store in which the transaction took place. Please find information about the StoreTrxDetails object here.
tipAmountProcessed Integer Returns the tipAmount that was used in processing of the transaction.
token token This object contains information about the wiPlatform token associated with this transaction. Please find information about the Token object here.
totalAmountProcessed Integer This is the total transaction amount in cent. This value is the sum of the basketAmount, the cashbackAmount, and tipAmount.
type String The transaction type that was processed. It can be set to either PAYMENT, DEPOSIT or WITHDRAWAL.
vsp vsp This object contains information about the VSP associated with the transaction. Please find information about the VSP object here.
wiTrxId Long This is the unique wiGroup transaction id generated by the wiPlatform and assigned to the original transaction. This field is important for processing an Advice transaction call.
discount discount This object contains information about the discount associated with this transaction. Please find information about the Discount object here.

Advise

After a transaction has completed at POS (tender is completed) an Advise Request must be sent from the POS to the wiPlatform. The Advise Request determines whether a Pending Transaction is Completed or the transaction is Canceled. This is done by setting the action field to REVERSE or FINALISE. This will change the transaction from a “Pending” state to a “Successful” or “Reversed” state on the wiPlatform.

HTTP protocol: SOAP
Available HTTP methods: POST
Integrations Environment WSDL URL: http://rad2.wigroup.co:8080/wigroup-transactionengine/PosProviderWS?wsdl

Advise Request

The basic layout of an Advise Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:pos="http://posprovider.te.wigroup.com/">
  <soapenv:Header/>
  <soapenv:Body>
   <pos:advise>
     <request>
      <apiCredentials>
        <!--Optional:-->
        <apiClientVersion></apiClientVersion>
        <!--Optional:-->
        <apiServerVersion></apiServerVersion>
        <id></id>
        <password></password>
      </apiCredentials>
      <action></action>
      <originalTrx>
        <storeTrxDetails>
         <basketId></basketId>
         <cashierId></cashierId>
         <posId></posId>
         <storeId></storeId>
         <trxId></trxId>
        </storeTrxDetails>
       <type></type>
       <vspTrxId></vspTrxId>
       <wiTrxId></wiTrxId>
       </originalTrx>
     </request>
   </pos:advise>
  </soapenv:Body>
</soapenv:Envelope>

The basic layout of the Advise Request looks as follows:

Fields Data Type Required/Optional Description
apiCredentials apiCredentials Required API credentials are used to authenticate each API call. Find information about the apiCredentials object here.
action String Required Must be either FINALISE or REVERSE.
originalTrx originalTrx Required This object contains information about the original transaction. Please find information about the originalTrx object here.
type String Required This is the type of transaction. It can be set to either PAYMENT, DEPOSIT or WITHDRAWAL. It should correspond with the transaction it is trying to advise.
vspTrxId String Optional The transaction id supplied by the VSP.
wiTrxId Long Required The transaction id supplied by the wiPlatform.
This field is returned in the Transaction Response. The wiTrxId links the Transaction and the Advise.

Advise Response

The basic layout of an Advise Response:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
   <ns2:adviseResponse xmlns:ns2="http://posprovider.te.wigroup.com/">
     <response>
      <responseCode></responseCode>
      <responseDesc></responseDesc>
      <action></action>
      <originalTrx>
        <storeTrxDetails>
         <basketId></basketId>
         <cashierId></cashierId>
         <posId></posId>
         <storeId></storeId>
         <trxId></trxId>
        </storeTrxDetails>
        <type></type>
        <vspTrxId></vspTrxId>
        <wiTrxId></wiTrxId>
      </originalTrx>
     </response>
   </ns2:adviseResponse>
  </S:Body>
</S:Envelope>

The POS will receive an Advise Response from the wiPlatform as the final leg of the transaction.

The basic layout of the Advise Response looks as follows:

Fields Data Type Description
responseCode Integer A code indicating the result of the request. -1 means successful. All other codes are treated as failed. Find a list of response codes and their descriptions here.
responseDescription String Readable description of responseCode. Find a list of response codes and their descriptions here.
action String Will be either FINALISE or REVERSE.
originalTrx originalTrx This object contains information about the original transaction. Please find information about the originalTrx object here.
type String The transaction type that was processed. It can be set to either PAYMENT, DEPOSIT or WITHDRAWAL.
vspTrxId String The unique VSP transaction id.
wiTrxId Long This is the unique wiGroup transaction id generated by the wiPlatform and assigned to the original transaction.

VAS Token

The VAS token method allows the POS integration to get a token representing the VAS item requested on behalf of the customer. This is followed by a standard deposit transaction using the returned token. If the VSP is set to be settled on the platform, then the next settlement run will ensure that the funds received by the merchant for the deposit transaction are transferred to the VSP.

HTTP Protocol: SOAP
Available HTTP Methods: POST
Integrations Environment WSDL URL: http://rad2.wigroup.co:8080/wigroup-transactionengine/PosProviderWS?wsdl

Get VAS Token Request

The basic layout of a getVasToken request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pos="http://posprovider.te.wigroup.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <pos:getVasToken>
         <request>
            <apiCredentials>
               <!--Optional:-->
               <apiClientVersion>?</apiClientVersion>
               <!--Optional:-->
               <apiServerVersion>?</apiServerVersion>
               <id>?</id>
               <password>?</password>
            </apiCredentials>
            <!--Optional:-->
            <cardNumber>?</cardNumber>
            <mobileNumber>?</mobileNumber>
            <providerId>?</providerId>
            <storeTrxDetails>
               <basketId>?</basketId>
               <cashierId>?</cashierId>
               <posId>?</posId>
               <!--Optional:-->
               <remoteStoreId>?</remoteStoreId>
               <!--Optional:-->
               <retailerId>?</retailerId>
               <!--Optional:-->
               <storeId>?</storeId>
               <trxId>?</trxId>
            </storeTrxDetails>
            <vasType>?</vasType>
         </request>
      </pos:getVasToken>
   </soapenv:Body>
</soapenv:Envelope>

The basic layout of getVasToken looks as follows:

Fields Data Type Required/Optional Description
apiCredentials apiCredentials Required API credentials are used to authenticate each API call. Find information about the apiCredentials object here.
vasType String Required This will allow Transaction Engine to book a token representing the VAS item requested on behalf of the customer.
mobileNumber String Required This is refers to the customer’s mobile number.
cardNumber String Optional This refers to a number which is associated with the VAS item.
providerId String Required This refers to a unique identifier which is associated with vasType.
storeTrxDetails storeTrxDetails Required This object contains information about the store in which the transaction took place. Find information about the StoreTrxDetails object here.

Get VAS Token Response

The basic layout of a PosProviderGetVasTokenResponse:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <ns2:PosProviderGetVasTokenResponse xmlns:ns2="http://posprovider.te.wigroup.com/">
      <response>
        <responseCode></responseCode>
        <responseDesc></responseDesc>
        <vspDetails>
          <id></id>
          <cashierId></cashierId>
          <name></name>
          <remoteStoreId></remoteStoreId>
          <storeId></storeId>
          <trxId></trxId>
        </vspDetails>
        <tipAmountProcessed></tipAmountProcessed>
        <token>
          <id></id>
          <type></type>
        </token>
      </response>
    </ns2:PosProviderGetVasTokenResponse>
  </S:Body>
</S:Envelope>

The basic layout of the Transaction Response looks as follows:

Fields Data Type Description
token token This object contains information about the wiPlatform token associated with this transaction. Please find information about the Token object here.
responseCode String A code indicating the result of the request. -1 means successful. All other codes are treated as failed. Find a list of response codes and their descriptions here.
responseDescription String Readable description of responseCode. Find a list of response codes and their descriptions here.
vspDetails vspDetails This object contains information about the VSP.

Transaction History

The TE API service exposes a Transaction History call that is intended to return details for transactions that were not initiated by the client system making the call (e.g. the point of sale). The purpose is to allow the client system to look up transactions that have taken place on its basket on the wiCode Platform in order to confirm that payment has taken place. Transaction History can be linked to a specific retail store and is used to summarize a list of partial transactions associated with a particular basket or store (or a combination of the two).

The typical interactions for processing a transaction and performing the Transaction History call is displayed in the figure below.

some text

HTTP Protocol: SOAP
Available HTTP Methods: POST
Integrations Environment WSDL URL: http://rad2.wigroup.co:8080/wigroup-transactionengine/PosProviderWS?wsdl

Transaction history request

The basic layout of a Transaction History Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:pos="http://posprovider.te.wigroup.com/">
  <soapenv:Header/>
  <soapenv:Body>
   <pos:transactionHistory>
     <request>
       <apiCredentials>
         <!--Optional:-->
         <apiClientVersion></apiClientVersion>
         <!--Optional:-->
         <apiServerVersion></apiServerVersion>
         <id></id>
         <password></password>
       </apiCredentials>
       <dateFrom></dateFrom>
       <dateTo></dateTo>
       <pageOffset></pageOffset>
       <pageSize></pageSize>
       <storeTrxDetails>
         <basketId></basketId>
         <storeId></storeId>
      </storeTrxDetails>
    </request>
  </pos:transactionHistory>
 </soapenv:Body>
</soapenv:Envelope>

The Transaction History Request returns a summary of the transactions that are linked to the storeTrxDetails provided. It is recommended that the following combination of fields are sent in the Transaction History Request to find all the (partial) transactions associated with a particular basket:

The basic layout of the Transaction History Request looks as follows:

Fields Data Type Required/Optional Description
apiCredentials apiCredentials Required API credentials are used to authenticate each API call. Find information about the apiCredentials object here.
dateFrom String Required This is the Start Date for the Transaction History call. The format should be as follows:
yyyy-MM-dd HH:mm:ss
dateTo String Optional This is the End Date for the Transaction History call. The format should be as follows:
yyyy-MM-dd HH:mm:ss. By default it will be set to the date-time of the request.
pageOffset Integer Optional This is the page that should be returned from the Transaction History result set. The first page starts at 0.
pageSize Integer Optional The number of transactions returned per page from the Transaction History result set. The default page size is 10.
storeTrxDetails storeTrxDetails Required This object contains information about the store in which the transaction took place. Please find information about the StoreTrxDetails object here.

Transaction history response

The basic layout of a Transaction history response:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <ns2:transactionHistoryResponse xmlns:ns2="http://posprovider.te.wigroup.com/">
      <response>
        <responseCode></responseCode>
          <responseDesc></responseDesc>
          <dateFrom></dateFrom>
          <dateTo></dateTo>
          <pageOffset></pageOffset>
          <pageSize></pageSize>
          <storeTrxDetails>
            <basketId></basketId>
            <storeId></storeId>
          </storeTrxDetails>
          <transactions>
            <basketAmountProcessed></basketAmountProcessed>
            <cashbackAmountProcessed></cashbackAmountProcessed>
            <amountToSettle></amountToSettle>
            <createDate></createDate>
            <id></id>
            <lastModifiedDate></lastModifiedDate>
            <state></state>
            <tipAmountProcessed></tipAmountProcessed>
            <token>
              <id></id>
              <type></type>
            </token>
            <totalAmountProcessed></totalAmountProcessed>
           <type></type>
           <vspId></vspId>
         </transactions>
         <transactions>
           <basketAmountProcessed></basketAmountProcessed>
           <cashbackAmountProcessed></cashbackAmountProcessed>
           <amountToSettle></amountToSettle>
           <createDate></createDate>
           <id></id>
           <lastModifiedDate></lastModifiedDate>
           <state></state>
           <tipAmountProcessed></tipAmountProcessed>
           <token>
             <id></id>
             <type></type>
           </token>
           <totalAmountProcessed></totalAmountProcessed>
           <type></type>
           <vspId></vspId>
        </transactions>
      </response>
    </ns2:transactionHistoryResponse>
  </S:Body>
</S:Envelope>

The POS receives a Transaction History Response from the wiPlatform Transaction Engine.

The basic layout of the Transaction History Response looks as follows:

Fields Data Type Description
responseCode Integer A code indicating the result of the request. -1 means successful. All other codes are treated as failed.
responseDescription String Readable description of responseCode.
dateFrom String This is the Start Date for the Transaction History call. The format is as follows:
yyyy-MM-dd HH:mm:ss
dateTo String This is the End Date for the Transaction History call. The format is as follows:
yyyy-MM-dd HH:mm:ss
pageOffset This is the page that is returned from the Transaction History result set. The first page starts at 0.
pageSize The number of transactions returned per page from the Transaction History result set. The default page size is 10.
storeTrxDetails storeTrxDetails This object contains information about the store in which the transaction took place. Please find information about the StoreTrxDetails object here.
transactions A list of transactions that meet the criteria for the transaction history request. Each transaction is represented by a MainTransaction object. Please find information about the MainTransaction object here.

Bills

HTTP Protocol: REST
Available HTTP Methods: POST, GET
Integrations Environment WADL URL: http://rad2.wigroup.co:8080/wigroup-bill/application.wadl

Create Bill

Example request


curl -X POST 'http://rad2.wigroup.co:8080/wigroup-bill/bills'
     -H 'Content-Type: application/xml'
     -d
        '<bill>
           <amount>100</amount>
           <basketId>basket_1</basketId>
           <cashierId>John Doe</cashierId>
           <storeId>1050</storeId>
           <posId>pos_1</posId>
           <basket>
            <!--Zero or more repetitions:-->
            <product>
                <sku>1234</sku>
                <desc>Product 1</desc>
                <qty>1</qty>
                <price>100</price>
            </product>
           </basket>
        </bill>'

Example response

<bill>
   <amount>100</amount>
   <basketId>basket_123</basketId>
   <createDate>2016-10-18T14:05:58.009Z</createDate>
   <footer>|Apps accepted:|Example App</footer>
   <header>| |*** Scan the QR code below: ***| |</header>
   <id>44</id>
   <mobilePaymentUrl>http://rad2.wigroup.co/bill/9999</mobilePaymentUrl>
   <posId>1</posId>
   <qrData>sampledata</qrData>
   <qrImage></qrImage>
   <state>A</state>
   <storeId>1050</storeId>
</bill>
Field Data Type Required/Optional Description
amount Integer Required This is the total transaction amount (in cents) associated with the bill.
basketId String Required The store’s identifier for a particular basket/cheque. Must be unique per store per day.
storeId Long Required The wiGroup storeId as provided by wiGroup.
posId String Optional The store’s posId from which the Bill is/was created.
basket basket Required Describes the set of goods or services outlined in the bill. Find information about the basket object here.
createDate String This is the createDate for the Bill Response. The format is as follows:
yyyy-MM-dd HH:mm:ss
footer String This is a text field that must be printed on the till slip (below the qrImage).
header String This is a text field that must be printed on the till slip (above the transactional QR code).
id Long This is a unique Bill id that is generated on wiGroup’s Bill Server for the original Create Bill Request.
mobilePaymentUrl String The URL to retrieve the Bill for mobile payment applications.
posId String The store’s posId from which the Bill was created.
qrData String Raw data for generating the QR code if the bitmap is not being used. This field must not be processed in any way other than to generate a QR image.
qrImage String This is a base64 encoded monochrome bitmap of the QR code to be printed on the till slip.
state String This is the state of a Bill (‘A’ = Active). 'A’ is the only applicable state constant at the moment. Future wiGroup developments will allow for the state field to be used for other state metadata.

Get Bill

Get Bill enables a POS to Retrieve a Bill during the pre-configured time window that is 24 hours.

Example request

curl -X GET 'http://rad2.wigroup.co:8080/wigroup-bill/bills?storeId=1050&posId=1&basketId=basket_123'

Example response

<bill>
   <amount>100</amount>
   <basketId>basket_123</basketId>
   <createDate>2016-10-18T14:05:58.009Z</createDate>
   <footer>|Apps accepted:|Example App</footer>
   <header>| |*** Scan the QR code below: ***| |</header>
   <id>44</id>
   <mobilePaymentUrl>http://rad2.wigroup.co/bill/9999</mobilePaymentUrl>
   <posId>1</posId>
   <qrData>sampledata</qrData>
   <qrImage></qrImage>
   <state>A</state>
   <storeId>1050</storeId>
</bill>
Field Data Type Required/Optional Description
amount Integer Required This is the total transaction amount (in cents) associated with the bill.
basketId String Required The store’s identifier for a particular basket/cheque. Must be unique per store per day.
storeId Long Required The wiGroup storeId as provided by wiGroup.
posId String Optional The store’s posId from which the Bill is/was created.
basket basket Required Describes the set of goods or services outlined in the bill. Find information about the basket object here.
createDate String This is the createDate for the Bill Response. The format is as follows:
yyyy-MM-dd HH:mm:ss
footer String This is a text field that must be printed on the till slip (below the qrImage).
header String This is a text field that must be printed on the till slip (above the transactional QR code).
id Long This is a unique Bill id that is generated on wiGroup’s Bill Server for the original Create Bill Request.
mobilePaymentUrl String The URL to retrieve the Bill for mobile payment applications.
posId String The store’s posId from which the Bill was created.
qrData String Raw data for generating the QR code if the bitmap is not being used. This field must not be processed in any way other than to generate a QR image.
qrImage String This is a base64 encoded monochrome bitmap of the QR code to be printed on the till slip.
state String This is the state of a Bill ('A’ = Active). 'A’ is the only applicable state constant at the moment. Future wiGroup developments will allow for the state field to be used for other state metadata.

Refund

A refund transaction is logged in the transaction engine and routed to the relevant VSP. It can only be used with payment transactions.

HTTP Protocol: SOAP
Available HTTP Methods: POST
WSDL URL: http://rad2.wigroup.co:8080/wigroup-transactionengine/PosProviderWS?wsdl

Refund Request

The basic layout of a Refund Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pos="http://posprovider.te.wigroup.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <pos:refund>
         <request>
            <apiCredentials>
               <!--Optional:-->
               <apiClientVersion></apiClientVersion>
               <!--Optional:-->
               <apiServerVersion></apiServerVersion>
               <id></id>
               <password></password>
            </apiCredentials>
            <originalTrxDetails>
               <wiTrxId></wiTrxId>
               <type></type>
               <storeTrxDetails>
                 <basketId></basketId>
                 <cashierId></cashierId>
                 <posId></posId>
                 <storeId></storeId>
                 <trxId></trxId>
               </storeTrxDetails>
             </originalTrxDetails>
            <!--Zero or more repetitions:-->
            <product>
               <id></id>
               <pricePerUnit></pricePerUnit>
               <units></units>
            </product>
            <refundAmount></refundAmount>
            <storeTrxDetails>
               <basketId></basketId>
               <cashierId></cashierId>
               <posId></posId>
               <remoteStoreId></remoteStoreId>
               <retailerId></retailerId>
               <storeId></storeId>
               <trxId></trxId>
            </storeTrxDetails>
            <switchTrxId></switchTrxId>
         </request>
      </pos:refund>
   </soapenv:Body>
</soapenv:Envelope>

The Refund Request is performed when a refund is logged to the wiPlatform Transaction Engine and routed to the relevant VSP.

The basic layout of the Refund Request looks as follows:

Fields Data Type Required/Optional Description
apiCredentials apiCredentials Required API credentials are used to authenticate each API call. Find information about the apiCredentials object here.
originalTrxDetails originalTrx Required This object contains information about the originnal transaction. Please find information about the originalTrx object here.
product Products Optional A list of products in the basket. Please find information about the Product object here.
refundAmount Integer Required This is the refund amount (in cents).
storeTrxDetails StoreTrxDetails Required This object contains information about the store in which the transaction took place. Find information about the StoreTrxDetails object here.
switchTrxId String Should there be a transaction switch involved in between the POS and the wiPlatform this must be the switch’s transaction reference.

Refund Response

The basic layout of a Refund Response:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <ns2:transactionResponse xmlns:ns2="http://posprovider.te.wigroup.com/">
      <response>
        <responseCode></responseCode>
        <responseDesc></responseDesc>
        <refundAmountProcessed></refundAmountProcessed>
        <amountToSettle></amountToSettle>
        <storeTrxDetails>
          <basketId></basketId>
          <cashierId></cashierId>
          <posId></posId>
          <remoteStoreId></remoteStoreId>
          <storeId></storeId>
          <trxId></trxId>
        </storeTrxDetails>
        <vsp>
          <id></id>
          <name></name>
          <responseCode></responseCode>
          <responseDesc></responseDesc>
          <trxId></trxId>
        </vsp>
        <wiTrxId></wiTrxId>
        <switchTrxId></switchTrxId>
      </response>
    </ns2:transactionResponse>
  </S:Body>
</S:Envelope>

The POS receives a Refund Response from the wiPlatform Transaction Engine.

The basic layout of the Refund Response looks as follows:

Fields Data Type Description
responseCode Integer A code indicating the result of the request. -1 means successful. All other codes are treated as failed.
responseDescription String Readable description of responseCode.
refundAmountProcessed Integer This is the total refund amount processed in cent.
amountToSettle Integer This is the amount, in cent, of the total transaction amount that will be settled to the retailer. The deficit between amountToSettle and totalAmountProcessed is regarded as the discount amount for non/partially-settled campaigns and should be handled as such. This field is only displayed when using apiClientVersion 1.6 and above.
storeTrxDetails StoreTrxDetails Required
vsp VSP This object contains information about the VSP associated with the transaction. Please find information about the VSP object here.
wiTrxID Long This is the unique wiGroup transaction id assigned to the transaction. This field is important for processing and ADVICE transaction call.
switchTrxId String Should there be a transaction switch involved in between the POS and the wiPlatform this must be the switch’s transaction reference.

Token Info

Retrieves information about the token, including the VSP and consumer information related to the token.

HTTP protocol: SOAP
Available HTTP methods: POST
Integrations Environment WSDL URL: https://rad2.wigroup.co:8181/wigroup-transactionengine/PosProviderWS?wsdl

Token Info Request

The basic layout of an Token Info Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pos="http://posprovider.te.wigroup.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <pos:tokenInfo>
         <request>
            <apiCredentials>
               <!--Optional:-->
               <apiClientVersion>?</apiClientVersion>
               <!--Optional:-->
               <apiServerVersion>?</apiServerVersion>
               <id>?</id>
               <password>?</password>
            </apiCredentials>
            <storeTrxDetails>
               <!--Optional:-->
               <basketId>?</basketId>
               <!--Optional:-->
               <cashierId>?</cashierId>
               <!--Optional:-->
               <posId>?</posId>
               <!--Optional:-->
               <remoteStoreId>?</remoteStoreId>
               <!--Optional:-->
               <retailerId>?</retailerId>
               <!--Optional:-->
               <storeId>?</storeId>
               <!--Optional:-->
               <trxId>?</trxId>
            </storeTrxDetails>
            <token>
               <id>?</id
               <type>?</type>
            </token>
         </request>
      </pos:tokenInfo>
   </soapenv:Body>
</soapenv:Envelope>

The basic layout of the Token Info Request looks as follows:

Fields Data Type Required/Optional Description
apiCredentials apiCredentials Required API credentials are used to authenticate each API call. Find information about the apiCredentials object here.
storeTrxDetails storeTrxDetails Required This object contains information about the store in which the transaction took place. Find information about the StoreTrxDetails object here.
token token Required This object contains information about the wiPlatform token associated with this transaction. Please find information about the Token object here.

Token Info Response

The basic layout of an Token Info Response:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
     <ns2:tokenInfoResponse xmlns:ns2="http://posprovider.te.wigroup.com/">
        <response>
           <responseCode></responseCode>
           <responseDesc></responseDesc>
           <vsp>
              <hasCoupon></hasCoupon>
              <hasGiftCard></hasGiftCard>
              <hasVoucher></hasVoucher>
              <hasWallet></hasWallet>
              <id></id>
              <name><name>
           </vsp>
        </response>
     </ns2:tokenInfoResponse>
  </S:Body>
</S:Envelope>

The POS will receive an Token Info Response from the wiCode Platform. The basic layout of the Token Info Response looks as follows:

Fields Data Type Description
responseCode Integer A code indicating the result of the request. -1 means successful. All other codes are treated as failed. Find a list of response codes and their descriptions here.
responseDescription String Readable description of responseCode. Find a list of response codes and their descriptions here.
vsp vsp This object contains information about the VSP associated with the transaction. Please find information about the VSP object here.

In addition to the standard VSP elements, the platform will also respond with boolean flags describing value linked to the token:

Fields Data Type Description
hasCoupon Boolean Is there a coupon linked to this token.
hasGiftCard Boolean Is there a gift card linked to this token.
hasVoucher Boolean Is there a voucher linked to this token.
hasWallet Boolean Is there a wallet value linked to this token.

Objects

API credentials

<apiCredentials>
  <!--Optional:-->
  <apiClientVersion></apiClientVersion>
  <!--Optional:-->
  <apiServerVersion></apiServerVersion>
  <id></id>
  <password></password>
</apiCredentials>
Fields Data Type Required/Optional Description
apiClientVersion String Optional This field can be used by POS integrators to send the version of their implementation to the wiPlatform.
apiServerVersion String Optional This field allows POS integrators to send the version of the wiGroup server in use as at their time of integration, ensuring strict backwards compatibility.
id String Required API id, issued to you by wiGroup.
password String Required API password, issued to you by wiGroup.

Product

<product>
  <id></id>
  <pricePerUnit></pricePerUnit>
  <units></units>
</product>

This object contains information about each product in a user’s basket.

Fields Data Type Required/Optional Description
id String Required The SKU/Barcode of product purchased. The id should be consistent in either always sending through the product SKU or product barcode.
pricePerUnit Integer Required The price per unit.
units Integer Required The number of units of this product purchased.

Store transaction details

<storeTrxDetails>
  <basketId></basketId>
  <cashierId></cashierId>
  <posId></posId>
  <remoteStoreId></remoteStoreId>
  <retailerId></retailerId>
  <storeId></storeId>
  <trxId></trxId>
</storeTrxDetails>

This object contains information about the store in which the transaction took place.

Fields Data Type Required/Optional Description
basketId String Required This is the identifier for the basket as assigned by the POS. The POS system must ensure that it stays the same across multiple transactions of the same basket so that unique baskets can be tracked and identified.
cashierId String Required Identifies the cashier that processed the transaction.
posId String Required Identifies the POS terminal the transaction was processed on.
remoteStoreId Long Optional This is the store’s own identifier. Can be used instead of the storeId. Must be used in combination with the retailerId.
retailerId Long Optional This is the unique wiGroup retailer identifier. Required if using the remoteStoreId field instead of the storeId field.
storeId Long Optional This is the unique wiGroup store identifier.
trxId String Required This identifies and groups multiple wiPlatform transactions together into a single POS transaction. The POS system must ensure that it stays the same across multiple transactions of the same basket so that unique baskets can be tracked and identified.

Token

<token>
  <id></id>
  <type></type>
</token>

This object contains information about the wiPlatform token associated with this transaction.

Fields Data Type Required/Optional Description
id String Required The unique token which the wiPlatform uses to identify and route the transaction to the VSP to authorize.
type String Required The token type is derived from how the token is received at the POS and can be either WICODE, WIQR or BIN.

VSP

<vsp>
  <id></id>
  <message></message>
  <name></name>
  <responseCode></responseCode>
  <responseDesc></responseDesc>
  <trxId></trxId>
</vsp>

This object contains information about the VSP associated with this transaction. This object will only be returned if the token is valid.

Fields Data Type Description
id String This is an unique VSP identifier.
message String This is a message that can be printed on the user’s till slip. Sent back from the VSP on successful transactions.
name String This is the name of the VSP.
responseCode String The responseCode returned by the VSP. This should not be used to determine whether the transaction was approved or not. This should only be used for logging and error reporting to VSP.
responseDesc String The VSP’s response description. Can be displayed addition to the transactionResponse.responseDesc if available to give more information on why the transaction failed.
trxId String The VSP’s transaction ID for a transaction. This is optionally returned by the VSP in the transaction response.

Discount

<discount>
    <amount></amount>
    <name></name>
    <product>
        <id></id>
        <units></units>
    </product>
</discount>

This object contains information about the discount associated with this transaction.

Fields Data Type Description
name String Discount name/description.
amount Integer The total discount amount for all products in discount.
product String The products on which the discounts are applied. Please find information about the discount product object here.

Discount product

<product>
    <id></id>
    <units></units>
</product>

This object contains information about the products on which discounts are applied in this transaction.

Fields Data Type Description
id String The product id used.
units Integer The number of units processed in the discount.
discount String The discount per product.

Loyalty

<loyalty>
  <name></name>
  <type></type>
  <earned></earned>
</loyalty>

This object contains information about the loyalty earned on this transaction.

Fields Data Type Description
name String The name of the loyalty program earned against.
type String The type of loyalty earned. Valid values are cent, points or count.
earned Integer The loyalty amount earned.

Original transaction details

<originalTrxDetails>
   <wiTrxId></wiTrxId>
   <type></type>
   <storeTrxDetails>
     <basketId></basketId>
     <cashierId></cashierId>
     <posId></posId>
     <storeId></storeId>
     <trxId></trxId>
   </storeTrxDetails>
 </originalTrxDetails>

This object contains information about the original transaction.

Fields Data Type Required/Optional Description
wiTrxId Long Required The wiPlatform unique transaction identifier. It is assigned to the transaction by TE and returned in the transaction response. It is then used, thereafter, in advises to identify the original transaction.
type String Required The transaction type.Value that are allowed: PAYMENT, DEPOSIT and WITHDRAWAL.
storeTrxDetails StoreTrxDetails Required This object contains information about the store in which the transaction took place. Find information about the StoreTrxDetails object here.

Transactions

<transactions>
  <basketAmountProcessed></basketAmountProcessed>
  <cashbackAmountProcessed></cashbackAmountProcessed>
  <amountToSettle></amountToSettle>
  <createDate></createDate>
  <id></id>
  <lastModifiedDate></lastModifiedDate>
  <state></state>
  <tipAmountProcessed></tipAmountProcessed>
  <token>
    <id></id>
    <type></type>
  </token>
  <totalAmountProcessed></totalAmountProcessed>
 <type></type>
 <vspId></vspId>
</transactions>
Fields Data Type Description
basketAmountProcessed Long This is the amount in the basket that was processed for this transaction.
cashbackAmountProcessed Long This is the cashback amount that was processed for this transaction.
tipAmountProcessed Long This is the tip amount that was processed for this transaction.
totalAmountProcessed Long This is the total amount of the transaction that was processed.
amountToSettle Long This is the amount, in cent, of the total transaction amount that will be settled to the retailer. The deficit between amountToSettle and totalAmountProcessed is regarded as the discount amount for non/partially-settled campaigns and should be handled as such. This field is only displayed when using apiClientVersion 1.6 and above.
createDate String This is the date and time for when transaction engine first received this transaction. The format is as follows:
yyyy-MM-dd HH:mm:ss.
id Long The unique identifier for the transaction in the transaction engine.
lastModifiedDate String This is the date and time for when TE last did any process related to this transaction. The format is as follows:
yyyy-MM-dd HH:mm:ss.
state String This is the current status of the transaction.
type String This is the type of transaction. It can be set to either PAYMENT, DEPOSIT or WITHDRAWAL.
vspId Long This is the identifier of the VSP where this transaction was sent to
token Token This object contains information about the wiPlatform token associated with this transaction. Please find information about the Token object here.

Basket

Fields Data Type Description
product product The collection of items being charged for in the containing bill.
sku String Stock Keeping Unit - Identifies this type of product within a store.
desc String Description of the product.
qty Integer Number of units of this product within the containing Basket.
price Integer Unit price of this product, in minor denomination.

Response Codes

Below is a list of Transaction Engine and Bill Server Response Codes:

Transaction Engine

Response Code Response Description
-1 Successful
00001 General System Error.
00002 General System Error. System configuration incorrect.
00003 System Error. Request not found.
00004 General Database Error.
00005 Duplicate key found.
00006 Duplicate entry in DB.
00007 Could not process your request. We are experiencing connection problems to external service providers.
00021 Email address format invalid.
00022 Mobile number invalid.
00023 Required field missing or invalid type used.
00024 General Input Error.
00025 Date format is invalid.
00026 Time format is invalid.
00027 Integer format is invalid.
00100 Invalid request. API credentials missing.
00300 Interface does not exist.
00301 Interface not activated.
00302 Invalid interface credentials.
00303 Interface method does not exist.
01000 VSP Reference invalid. A valid VSP Reference must be specified. Max 255 characters.
01001 VSP invalid. Must specify a value > 0.
01002 The wiCode life is invalid. Must specify a value > 0.
01003 wiCode Pool depleted.
01004 wiCode is not reserved.
01005 wiCode reserved by another VSP.
01006 wiCode vspReference differs. Might be new transaction.
01007 wiCode cannot be refreshed. Either busy being processed or being expired.
01008 wiCode has expired.
01009 wiCode locked. Currently being used in a transaction.
01010 Lock type is invalid. Value must be either ‘True’ to lock or 'False’ to unlock.
01011 The wiCode is invalid. A valid wiCode must be specified.
01012 The transaction type is not allowed for wiCode.
01013 Transaction type invalid.
01014 The wiCode life is invalid, it exceeds the maximum wicode length allowed for the pool.
01501 Invalid State supplied.
01501 Invalid State supplied.
01502 Invalid Country id supplied.
01503 Invalid POS id supplied.
01504 Invalid Retailer id supplied.
01505 Invalid Store Owner id supplied.
01506 Invalid Store Group id supplied.
01507 Invalid subdivision id supplied.
01508 Invalid Store id supplied.
01509 Invalid VSP id supplied.
01510 User Authentication failed.
01511 User Authentication failed.
01512 User Authentication failed.
01513 Bank account credentials invalid.
01514 Invalid id supplied.
01515 Invalid batch time format.
01516 Invalid recon time format.
01517 Invalid bank account type.
01518 Invalid Bank account supplied.
02001 Invalid transaction type supplied.
02002 Invalid token type supplied.
02101 Invalid token id.
02102 Could not parse VSP transaction response to JSON.
02103 Could not parse Wiprofile lock response to JSON.
02104 Timeout while waiting for Wiprofile response.
02105 Transaction to VSP timed out.
02106 Timeout while waiting for VSP response.
02107 Transaction failed.
02108 VSP not found.
02109 Advice request failed.
02110 Failed to log transaction products.
02111 API POS not found.
02112 Store not found.
02113 Lock failed.
02114 Store does not support Deposits.
02115 Store does not support Payments.
02116 Store does not support Withdrawals.
02117 VSP does not support Deposits.
02118 VSP does not support Payments.
02119 VSP does not support Withdrawals.
02120 Invalid token.
02121 Cashback can only be processed on a Payment.
02122 The totalAmount does not match basketAmount + cashbackAmount.
02123 Connection to VSP could not be established.
02124 POS provider not active.
02125 Store is not active.
02126 Store is not linked to POS provider.
02127 Store does not support Cashbacks.
02128 VSP does not support Cashbacks.
02129 Store does not accept VSP.
02130 Store does not allow Deposits for VSP.
02131 Store does not allow Payments for VSP.
02132 Store does not allow Withdrawals for VSP.
02133 Store does not allow Cashback on Payments for VSP.
02134 Token Info request failed.
02135 Store Group not found
02136 Store Group is not active.
02137 Store Group does not support Deposits
02138 Store Group does not support Payments
02139 Store Group does not support Withdrawals
02140 Store Group does not support Cashbacks.
02141 Invalid response received from VSP. Required fields missing.
02142 Tip can only be processed on a Payment.
02143 The transaction amount exceeds maximum amount allowed on token.
02144 VSP does not support partial settlement.
02145 Original transaction not found.
02146 Refund can only be processed on a Payment.
02147 Refund can only be processed on a finalised transaction.
02148 Store does not support Refunds
02149 VSP does not support Refunds.
02150 Store does not allow Refunds for VSP.
02151 Store not linked to original transaction store.
02151 Store retailer not linked to original transaction retailer.
02152 The refundAmount exceeds the total amount processed minus previous refunds.
02153 The transaction is locked. Refund in progress.
02154 The transaction is locked. Refund in progress.
02155 Refund request failed
02156 Transaction limit exceeded.
02157 API VSP not found
02158 The amountToSettle exceeds the total amount settled minus previous amounts settled.
02159 The amountToSettle exceeds the totalAmount.
02160 The total amount processed by the VSP exceeds the total amount.
02161 Invalid apiServerVersion
02170 Invalid VAS type
02171 VAS type not configured for retailer
03001 Invalid request. User credentials missing.
03002 Invalid user credentials.
03003 User not activated.
03004 Invalid user credentials.
03051 Password invalid. A valid password must be specified.
03052 Invalid state. Available states are {A, D, P, RP}.
03053 Invalid delivery method. Available methods are {SMS, Email}.
03054 Invalid token type specified.
03055 Country code invalid. A valid country code must be specified.
03056 OTP invalid. A valid OTP must be specified.
03057 General OTP Error.
03058 OTP is expired.
03059 Id invalid. A valid id must be specified.
03060 Date invalid. Must have format YYYY-MM-DD HH:MM:SS.
03101 Name invalid. Max length allowed is 255 Characters.
03102 Surname invalid. Max length allowed is 255 Characters.
03103 Gender invalid. Available options are {M, F}.
03104 Date of birth invalid. Must have format yyyy-MM-dd.
03105 User registration request failed.
03106 WiTag is already linked to a user.
03107 Username invalid. A valid username must be specified.
03108 User already activated.
03109 User already linked to VSP.
03110 User not linked to wiTag.
03111 User already linked to a wiTag with the same description.
03112 User not linked to VSP.
03113 User and VSP linked state inactive.
03114 User in progress with a transaction.
03115 User already reserved wiCode for VSP with the same VSP reference.
03116 User not reserved by VSP.
03117 Another user with the same email is already registered.
03118 Another user with the same mobile number is already registered.
03151 VSP not activated.
03152 VSP registration request failed. VSP already exists.
03153 VSP description invalid. Max length allowed is 255 Characters.
03154 User cancelled.
03155 VSP is not a discount VSP.
03156 VSP is not a loyalty VSP.
03157 VSP is not linked to discount VSP.
03158 VSP is not linked to loyalty VSP.
03201 WiTag length invalid.
03202 WiTag description invalid.
03203 The WiTag life is invalid. Must specify a value > 0.
03204 WiTag not linked to a user.
03205 No session active for wiTag.
03230 WiQR invalid.
03231 WiQR is expired.
03251 VSP invalid. Must specify a value > 0.
03252 VSP Reference invalid. Max length allowed is 255 Characters.
03253 The token life is invalid. Must specify a value > 0.
03254 The WiCode is invalid. A valid WiCode must be specified.
03255 There is no wiCode Pool available for your request parameters.
03256 WiCode Pool not activated.
03257 WiCode Pool Connection Error.
03258 Invalid WiCode Pool interface credentials.
03259 General WiCode Pool Error.
03260 wiCode is expired.
03261 wiCode not reserved.
03262 wiCode already locked.
03263 wiCode not linked to a user.
03264 wiCode Pool depleted.
03265 wiCode linked to Discount/Loyalty wiCodes.
03300 Invalid BIN.
04001 Invalid date supplied.

Bill Server

Response Code Response Description
8000 General server error, 500
8001 No Bill found, 404
8002 No unique Bill found, 404
8003 Invalid parameters, 400
XML