NAV
shell

Overview - Value Store Provider

The wiCode Platform (WP) allows mobile payment providers like mobile wallet systems to redeem value at wiCode-enabled retailers. Since payment providers authorise a transaction value to the retailer point of sale (POS), they are referred to as Value Store Providers (VSPs).

APIs are exposed to allow the VSP system to enable the processing of mobile transactions initiated at a POS, both where QR codes get scanned by the VSP Application from a POS slip (sit-down model) and where a wiCode or QR code is presented to the user application and scanned into the POS at transaction time (over-the-counter model).

The Platform enables the VSP to book out a transactional token that gets redeemed during transaction time and POSTs transactional information to a gateway end-point provided by the VSP system for authorisation.

Transaction Types

Transaction types facilitated by the wiPlatform include:

All transactions across different value store providers occur at point of sale through the exact same transaction process, thus cashiers do not require special knowledge of each provider, and cashier training is not required per application that is accepted by a merchant. Similarly, recon and settlement mechanisms are aggregated across all providers so that the merchant need only process recon and settlement once. It should be noted that low-level reporting is provided per transaction provider, to ensure that the merchant has access to all data potentially useful for business intelligence activities.

Platform Architecture

For any transaction to occur, there are primarily three entities: a Value Store Provider (VSP), storing some redeemable value on behalf of a customer. The retailer themselves, and the WP, facilitating the routing (low-level) and settlement (high-level) legs of the transaction.

The diagram below shows how these various role-players interact. The VSP platform will be entirely responsible for communicating with the mobile device of the customer through whichever channel is applicable for that particular VSP (USSD, mobile website, application, etc.). As shown in Figure 1, the WP aggregates a number of VSP’s, each containing their own customer treasury system. The WP interacts with this VSP system on behalf of the retailer, and offers the retailer access to multiple VSP’s with one single technical integration.

some text

Figure 1

Dual messaging

wiGroup supports a dual message transaction flow architecture. Transactions using the WP consists of interactions between the POS system, the wiCode platform and the VSP. The WP can act as a platform for processing the resulting settlement and reconciliation. Two basic requests are used to process a complete transaction:

The transaction request submits a request (payment, deposit or withdraw) to the WP to switch to the appropriate VSP for authorization. The transaction response from the WP will contain the transaction authorization result from the VSP or an error if it is not able to receive a valid response from the VSP.

For successful transaction responses, the final state of the transaction at the POS needs to be send as an advice request one the outcome of the transaction in store is known. The POS sends an advice request (instruction) to the WP to update the transaction state and inform the VSP system that the transaction was either FINALISED if concluded successfully or that it was REVERSED in the case of a cancellation or time-out scenario experienced at the POS.

The only exception is if the VSP system is not able to log the advice message due to system downtime. The WP will subsequently retry the advice a number of times if the advice is either declined or if the WP is not able to deliver the advice request to the VSP system successfully.

The transaction flow for the various integration models will be described in the following section.

Transaction Models

wiGroup offers three transactional models, each with its own unique use case.

Model Applications Description
Over-the-counter Relevant for USSD, Mobi Site, Mobile Applications.

Transaction types, Payment, Withdrawal and Deposits can be used.

Predominantly used in Tier 1 & 2 and Self Service Hospitality environments with full POS integration.		 To start the transaction, the user taps ‘Pay’ within their app and immediately gets presented with a wiCode. This wiCode is then either scanned by a scanner near the POS, or manually entered into the POS.

An ‘over-the-counter’ transactional VSP can also incorporate both Sit Down and Informal Models.
Sit-down Relevant for Mobile Applications.

Transaction type, Payment.

Predominantly used in Seated / Serviced Hospitality environments with POS integration		 The app user scans the printed QR code on the bill. Bill data is extracted from the QR code by the app, and the user is then permitted to add extra information about the transaction, for example the tip amount.
Informal merchant Relevant for USSD or Mobile Applications.

Transaction types, Payment, with Withdrawal and Deposits being used in special cases.

Predominantly used in Informal environments without POS integration.		 In this model, a once-off QR code is given to the store, this QR code uniquely identifies the store on the wiCode Platform.

The user starts the transaction by scanning the store’s QR code, where after the user manually enters the transaction details. The mobile app then initiates the transaction by pushing the captured transaction information to the wiCode Platform (via a VSP).

Over-the-counter

There are only three main components involved during a transaction: the Retailer, the wiCode Platform and the VSP. The wiCode Platform connects the retailers and VSPs to enable a VSP’s users to transact at retailers connected to the platform. The same transaction flow is applicable for Payment, Withdrawal and Deposits. In the over-the-counter model, the POS requests the value of the transaction into the VSP for authorisation. We encourage all apps to implement the over-the-counter model as well as the sit-down model as it increases access to a larger retail footprint.

Transaction flow

some text

  1. A customer has access to a mobile channel (i.e mobile application) which is provisioned to them by a VSP. The customer ‘signs in’ to their mobile wallet to make a payment at a store (does not specify which store).
  2. The VSP requests a transactional token from the wiGroup Token Manager via the Token Manager API.
  3. The token is displayed to the customer through the appropriate mobile channel.
  4. The cashier selects the “mobile” tender button. At this point; if the POS is integrated directly to WP, the transaction request will be sent to the Transaction Engine via the wiPlatform POS API. If the POS is integrated to the WP through a retail switch, a standard “card” transaction is sent through to the switch with the transactional token in the “PAN” field of the ISO message (prefixed with a standard WP BIN number). It is then routed by the switch to the WP.
  5. Optionally the VSP can have the ability to process a tokenInfo request, which is used to relay information about an active user token back to the POS. This is generally not required.
  6. The Transaction Engine receives the request from POS to process a transaction and interfaces with the Token Manager in order to discover which VSP reserved the token.
  7. A transaction processing request is sent to the VSP’s Transactional Gateway via the VSP POST API, including transactional information such as the token, the basket value, and the merchant information, in order to execute a transaction (purchase, earn, deposit, refund or withdrawal). At this point the VSP system can request a confirmation from the customer (i.e. Confirm R25 at Retailer X?), but this step is often skipped (especially for coupons/vouchers).
  8. Optionally the customer can be prompted to accept or decline the transaction. This interface is provided by the VSP to the customer. The confirmation process should not materially increase the customer’s time at till.
  9. Should the customer confirm the transaction, and the VSP authorises the transaction based on other criteria (sufficient funds, etc.), the VSP may respond to the transaction processing request from the WP in [7]. This will need to occur within the standard transaction timeout range of less than 15 seconds.
  10. The WP will provide the response of the transaction to the POS.
  11. Once the tender has been received by the POS, a transaction advice is sent to the WP, to FINALISE the transaction with the VSP. Should the POS need to cancel the pending transaction, a REVERSE advice is sent to the WP, and to the VSP.

Sit-down

In the sit-down model, the user begins a transaction by scanning a QR code off of a bill. Essentially, two steps are carried out to perform a transaction.

some text

Step 1 - QR parsing

In the QR parsing stage the app sends the raw QR data to the VSP, the VSP in turn sends the raw QR data to the Transaction Engine VSP API via the GET /bills call. After the WP decodes the data, all relevant information about the bill is returned to the VSP.

Step 2 - Transaction

In the second stage the actual financial transaction begins. The VSP uses the bill information to initiate the transaction with the WP by doing the POST /transactions call to the Transaction Engine VSP API.

Once the transaction is initiated the WP will route the request to the VSP’s Transactional Gateway for authorisation. Upon a successful transaction response form the VSP the WP will automatically send the FINALISE advice to the VSP’s Transactional Gateway. Payment notification is sent to the app once the transaction outcome is known.

Transaction flow

This is what the transaction flow would look like for the sit-down model.

some text

Example QR code

An example sit-down QR code.

Informal merchant

If the merchant does not have a physical POS, they might employ a static QR code in the form of a wobbler at the place where they sell their goods/services. This is normally used in informal settings and typically means reduced functionality.

Transaction flow

This is what the transaction flow would look like for the informal model.

Informal merchant transaction flow.

Example QR code

An example informal QR code.

Token Manager REST API

This API is used by the VSP to reserve a token. A token is reserved for a specific time frame as required by the VSP. Tokens will automatically expire and the wiCode will be returned to the available wiCode pool. The number of digits a wiCode consists of is determined by the lifespan of the token as well as the availability of wiCodes. The VSP can request a specific length wiCode, but it will only be issued should the lifespan be allowed for the length and there are wiCodes of that length available.

Date format

A strict ISO 8601 date format is followed for dates. In Java a date can be formatted in the ISO 8601 format with the following snippet:

Monetary format

Monetary amounts are both accepted and returned in cents.

API credentials

This section provides interface definitions to allow for implementation on various platforms and in different programming languages. Note that:

API references

The Token Manager VSP API RESTful web service endpoints may be accessed by utilising the following WADL (<#endpointURL#>):

Test credentials

All calls to the wiCode platform must contain the issuing channel credentials in the header of the API call. This table contains a set of VSP-specific API credentials that may be used to authenticate all API calls made to CVS and wiPlatform.

API ID API Password
<#apiID#> <#apiPassword#>

Linking multiple VSP’s

The wiCode Platform has the ability to link multiple VSP’s to a main transactional VSP. This gives the main VSP access to other VSP services such as the wiGroup Coupon Voucher Service and the wiGroup Loyalty Service. This functionality is referred to auto-redeem whereby multiple wiCodes can be grouped or merged into single user token. This reduces the number of QR scans or wiCode entries for these scenarios at the point of sale, thus enhancing the user journey and reducing time at the till.

Use-cases

Discount wiCode

In order to add a discount wiCode into a payment wiCode the VSP’s application server will need to make an Issue Coupon API call to the CVS API, once the response is received the VSP server must dynamically add the wiCode from CVS into the main Token Manager createToken request as a discountWicode.

When the User redeems the main Payment wiCode in store, the wiCode platform will route the discount wiCode to CVS for authorisation, if approved the discount will be passed back into the wiCode Platform against the basket amount before the total processed amount is sent into the VSP for authorisation.

Auto-redeem a discount wiCode.

Discount and Loyalty wiCodes

In order to add a Loyalty wiCode into a payment wiCode the VSP’s application server will need to make an Issue wiCode API call to the wiLoyalty API, once the response is received the VSP server must dynamically add the wiCode from wiLoyalty into the main Token Manager createToken request as a loyaltyWicode along with the discountWicode.

When the User redeems the main Payment wiCode in store, the wiCode platform will route the discount wiCode to CVS for authorisation and the loyalty wiCode to wiLoyalty, if approved the discount will be passed back into the wiCode Platform against the basket amount before the total processed amount is sent into the VSP for authorisation, loyalty is earned against the total processed amount after the discount is processed. Loyalty auto redemption can be added to the payment and deposit transaction types without the discount wiCode if the business model requires it.

Auto-redeem a discount wiCode.

/tokens

POST /tokens

    # EXAMPLE REQUEST

    curl "http://rad2.wigroup.co:8080/wigroup-tokenmanager/vsp/tokens" \
     -H "apiId: <#apiId#>" \
     -H "sha1Password: <#sha1Password#>" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "discountWicodes": "1234567,999999999"",
       "loyaltyWicodes": "7654321,999999999",
       "maxTrxAmount": "15000",
       "tokenLifeInMin": "15",
       "transactionType": "PAYMENT",
       "vspReference": "VSP_User_Id_001",
       "tipAmount":"5000"
     }'

    # EXAMPLE RESPONSE without Tip
    {
    "token": {
    "wiCode": "5286264",
    "wiQR": "5286264",
    },
    "responseCode": "-1",
    "responseDesc": "Success"
    }

    # EXAMPLE RESPONSE with Tip
    {
    "token": {
    "wiCode": "5286264",
    "wiQR": "5286264|5000",
    },
    "responseCode": "-1",
    "responseDesc": "Success"
    }

This resource can be used to issue new wiCodes. Two parameters must be supplied: tokenLifeInMin and vspReference.

Endpoint: {root}/tokens

Available methods: POST

Parameter Type Desciption Request Response
vspReference String A reference which will be echoed back to the VSP during the transact call, documented in the Transaction Engine VSP POST API. ✓
tokenLifeInMin Integer The life of the token in minutes. This will determine the length of the wiCode returned. Longer time frames produce longer wiCodes. ✓
transactionType String Used to return only brands that have deals of this dealType. ✓
transactionType String This is the type of transaction. It can set to either PAYMENT, DEPOSIT or WITHDRAWAL. ✓
discountWicodes List<Long> A list of discount wicodes to link to wicode. ✓
loyaltyWicodes List<Long> A list of loyalty wicodes to link to wicode. ✓
wiCode String The wiCode linked to the user token. ✓
wiQR String The wiCode linked to the user token. If a tipAmount is specified, the wiQR field will contain a pipe and the tip amount in cents as per the example. ✓
tipAmount Integer The tip amount included with the token ✓

Transactional Gateway

The wiCode Platform requires the VSP to implement a transactional API to which Transaction Engine can POST the transactional requests as JSON objects. This section describes the methods that need to be implemented by the VSP.

Authorisation

The WP will send the API id and password to the VSP for additional security.

Error handling

Test cases will be provided for negative tests, however we do request that the VSP provide us with a list of Errors and that they be as accurate and as informative as possible so that the Customer and the Merchant teller will understand what the errors mean. The more accurate the human readable error message is the less support requests the VSP will receive.

POST Transaction Request

# EXAMPLE REQUEST
curl "{your_endpoint}/<#your_context#>" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
       "wiTrxId": 263012,
       "token": {
         "id": "536598854",
         "type": "WICODE",
         "vspReference": "SomeUniqueVSPRef"
       },
       "type": "PAYMENT",
       "storeTrxDetails": {
         "storeId": 1050,
         "remoteStoreId":"12345abc",
         "retailerId":999,
         "basketId": "basket50",
         "trxId": "trx1",
         "posId": "pos1",
         "cashierId": "admin"
       },
       "totalAmount": 10000,
       "basketAmount": 0,
       "products":[{
          "id":"example_sku_1",
          "units":1,
          "pricePerUnit":1
      },
      {
          "id":"example_sku_2",
          "units":1,
          "pricePerUnit":1
      }],
       "vspCredentials": {
         "id": "DummyVSP",
         "password": "test"
       }
     }'

This call can be used to obtain information about a wiGroup Coupon or Voucher. The Coupon/Voucher ID is specified as a path parameter in this case.

Endpoint: {your_endpoint}/<#your_context#>

Available methods: POST

Fields Description
wiTrxId The wiPlatform unique transaction identifier.
token
ID
Type vspReference		 The ID is the unique token which the wiPlatform uses to identify and route the transaction to the VSP to authorize. The token type is derived from how the token is received at the POS and can be either WICODE, WIQR or BIN. vspReference is the VSP’s reference linked to this token.
type This is the type of transaction. It can set to either PAYMENT, DEPOSIT or WITHDRAWAL.
storeTrxDetails
basketId
cashierId
posID
remoteStoreID
retailerID
storeID
trxID
These are the internal retailer ID’s for the basket, cashier and POS.
Store details:
StoreID: is the store WID assigned to you by wiGroup. If the StoreID is populated, this will be used. Alternatively, the RemoteStoreID and the RetailerID must be populated - these are used in combination.
TrxID: The internal retailers unique transaction ID
totalAmount This is the total transaction amount in cent. This is the sum of the basketAmount and the cashbackAmount.
basketAmount This is the total transaction amount in cent for all products in the basket. If the transaction type is DEPOSIT, this is the deposit amount. It the transaction type is WITHDRAWAL this is the amount to withdraw.
cashBackAmount 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. This is only for use with PAYMENT type.
products
ID
PricePerUnit
Units		 The id refers to the actual SKU number of the product. The price per unit at the POS and the number of units. It is recommended that the POS provides a list of products for each transaction.
vspCredentials The VSP’s API credentials are passed in the body of the message for authentication over and above SSL.

Transaction Response

# EXAMPLE RESPONSE
{
  "responseCode": "-1",
  "responseDesc": "Success",
  "vspTrxId": "0001",
  "totalAmountProcessed": 100,
  "basketAmountProcessed": 100,
  "cashbackAmountProcessed": 0,
  "id": 1234,
  "name": "vsp_name"
}
Fields Description
responseCode The authorization response code. ‐1 is Authorized. All other codes are treated as failed.
responseDescription Readable discription of responseCode, typically used to give the user and cashier context of the transaction outcome.
vspTrxId The VSP’s unique transaction id. It is required should the transaction on successful authorization.
totalAmountProcessed The basket amount that was used in processing the transaction.
basketAmountProcessed The basket amount that was used in processing the transaction.
cashBackAmountProcessed 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.
id The VSP id.
name The VSP name.

POST Advise Request

# EXAMPLE REQUEST
curl "{your_endpoint}/<#your_context#>" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
       "action": "FINALISE",
       "originalTrx": {
         "storeTrxDetails": {
           "storeId": 1050,
           "basketId": "Test VSP 09-05-2015 15:42:13",
           "trxId": "1543",
           "posId": "8",
           "cashierId": "Sam"
         },
         "wiTrxId": 21752,
         "type": "PAYMENT",
         "vspTrxId": 4256
       },
       "vspCredentials": {
         "id": "DummyVSP",
         "password": "test"
       }
     }'

Endpoint: {your_endpoint}/<#your_context#>

Available methods: POST

Fields Description
action Must be either FINALISE or REVERSE.
storeTrxDetails
basketId
cashierId
posID
remoteStoreID
retailerID
storeID
trxID
These are the internal retailer ID’s for the basket, cashier and POS.
Store details:
StoreID: is the store WID assigned to you by wiGroup. If the storeID is populated, this will be used. Alternatively, the RemoteStoreID and the RetailerID must be populated - these are used in combination.
trxID: The internal retailers unique transaction ID
wiTrxID The transaction ID supplied by the wiCode Platform.
This field is returned in the transaction response. This links the transaction and the advice.
type This is the type of transaction. It can set to either PAYMENT, DEPOSIT or WITHDRAWAL.
vspTrxId The transaction ID supplied by the VSP.
vspCredentials Optional

Advice Response

# EXAMPLE RESPONSE
{
  "responseCode": "-1",
  "responseDesc": "Success"
}
Fields Description
responseCode The authorization response code. ‐1 is Authorized. All other codes are treated as failed.
responseDescription Readable discription of responseCode, typically used to give the user and cashier context of the transaction outcome.

POST Token Info Request

# EXAMPLE REQUEST

curl "{your_endpoint}/<#your_context#>" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
       "token": {
         "id": "536598854",
         "type": "WICODE",
       },
       "type": "PAYMENT",
       "storeTrxDetails": {
         "storeId": 1050,
         "basketId": "basket50",
         "trxId": "trx1",
         "posId": "pos1",
         "cashierId": "admin"
       }
     }'

Endpoint: {your_endpoint}/<#your_context#>

Available methods: POST

Fields Description
storeTrxDetails
basketId
cashierId
posID
remoteStoreID
retailerID
storeID
trxID
These are the internal retailer ID’s for the basket, cashier and POS.
Store details:
StoreID: is the store WID assigned to you by wiGroup. If the StoreID is populated, this will be used. Alternatively, the RemoteStoreID and the RetailerID must be populated - these are used in combination.
token
ID
Type		 The ID is the unique token which the wiPlatform uses to identify and route the transaction to the VSP to authorize. The token type is derived from how the token is received at the POS and can be either WICODE, WIQR or BIN.
type This is the type of transaction. It can set to either PAYMENT, DEPOSIT or WITHDRAWAL.

Token Info Response

# EXAMPLE RESPONSE
{
  "responseCode": "-1",
  "responseDesc": "Success"
}
Fields Description
esponseCode The authorization response code. ‐1 is Authorized. All other codes are treated as failed.
responseDescription Readable discription of responseCode, typically used to give the user and cashier context of the transaction outcome.

Transaction Engine VSP REST API

The TE VSP API (Scan Model API) is exposed off the wiCode Platform. This API exposes two methods: a GET method named bill, and a POST method named transactions.

API credentials

This section provides interface definitions to allow for implementation on various platforms and in different programming languages. Note that:

API references

The Token Manager VSP API RESTful web service endpoints may be accessed by utilising the following WADL (<#endpointURL#>):

Test credentials

All calls to the wiCode platform must contain the issuing channel credentials in the header of the API call. This table contains a set of VSP-specific API credentials that may be used to authenticate all API calls made to CVS and wiPlatform.

API ID API Password
<#apiID#> <#apiPassword#>

/bills

GET /bills

# EXAMPLE REQUEST
curl "http://rad2.wigroup.co:8080/wigroup-transactionengine/vsp/bills?qrCode={qr_data_here}" \
  -H "apiId: <#apiId#>" \
  -H "apiPassword: <#apiPassword#>" \
  -H "Content-Type: application/json; charset=UTF-8" \
  -X GET

# EXAMPLE RESPONSE
{
  "store": {
    "id": 1050,
    "name": "wiGroup Test Merchant"
  },
  "retailer": {
    "id": 999,
    "name": "wiGroup SA"
  },
  "amount": 5000,
  "basketId": "basket01",
  "responseCode": "-1",
  "responseDesc": "Success"
}

This call is designed to accept the raw data within the QR code and trigger a decoding process in which the QR data is parsed and any additional data collected to form a bill object. This bill object contains all the data relevant to the about-to-be-performed transaction.

The app should use the returned bill object to populate the transaction screen with details, such as the: store name, transaction amount, etc.

Endpoint: {root}/bills

Available methods: GET

Response parameters Description
store
id
name
The storeId assigned to you by wiGroup.
The name of the store.
retailer
id
name
The retailerId assigned to you by wiGroup.
The name of the retailer.
amount The total financial amount associated with the bill.
basketId The store’s identifier for a particular basket.

Informal Merchant

# EXAMPLE REQUEST - Informal Merchant
curl "http://rad2.wigroup.co:8080/wigroup-transactionengine/vsp/bills?qrCode=\{"storeId":1050\}" \
  -H "apiId: <#apiId#>" \
  -H "apiPassword: <#sha1Password#>" \
  -H "Content-Type: application/json; charset=UTF-8" \
  -X GET

# EXAMPLE RESPONSE - Informal Merchant
{
  "store": {
    "id": 1050,
    "name": "wiGroup Test Merchant"
  },
  "retailer": {
    "id": 999,
    "name": "wiGroup SA"
  },
  "responseCode": "-1",
  "responseDesc": "Success"
}

At minimum, the call will return both the Store and Retailer details. This is all that is required to initiate a transaction on the wiCode Platform and should be thought of as the base case for the Scan Models. All transactions should be able to handle this case at the very least.

Response parameters Description
store
id
name
The storeId assigned to you by wiGroup.
The name of the store.
retailer
id
name
The retailerId assigned to you by wiGroup.
The name of the retailer.

/transactions

POST /transactions


# EXAMPLE REQUEST

curl "http://rad2.wigroup.co:8080/wigroup-transactionengine/vsp/transactions"
  -H "apiId: <#apiId#>"
  -H "apiPassword: <#apiPassword#>"
  -H "Content-Type: application/json; charset=UTF-8"
  -X POST
  -d {
    {
    "basketAmount": "100",
    "storeTrxDetails":    {
       "basketId": "180_63631826413",
       "cashierId": "snappy",
       "posId": "861074024300611",
       "storeId": "1050",
       "trxId": "1"
    },
    "token":    {
       "id": "7997560",
       "type": "WICODE"
    },
    "totalAmount": "100",
    "type": "PAYMENT"
 }
  }

Once the VSP has received the transaction from the mobile device (and created a Payment Token “wiCode” if needed), the VSP should initiate the transaction on the wiCode Platform. The Payment Token should form part of the request body.

The basic layout of the transaction request looks a follows:

Fields Type Required/Optional Description Request Response
apiId String Required A ID which the VSP authenticates that it is indeed the wiPlatform pushing the transaction. ✓
apiPassword String Required The password hashed by SHA. ✓
apiClientVersion String Optional This field can be used by VSP integrators to send the version of their implementation to the wiPlatform.
apiServerVersion String Optional This field allows VSP integrators to send the version of the wiGroup server in use as at their time of integration, ensuring strict backwards compatibility.
basketAmount Integer Required This is the total transaction amount (in cents) of all products in the basket. ✓ ✓
storeTrxDetails StoreTrxDetails Required This object contains information about the store in which the transaction took place. Find information about the StoreTrxDetails object here. ✓ ✓
tipAmount Integer Optional The tip amount must be included in the total amount in order for the VSP to process the full amount. Not all VSP’s support tip amount.
token Token Required This object contains information about the token. Find information about token object here. ✓ ✓
totalAmount Integer Required This is the total transaction amount in cent. This is the sum of the BasketAmount and TipAmount. ✓ ✓
type String Required The type of transaction; either Payment, Deposit or Withdrawal. ✓ ✓ 
# EXAMPLE SUCCESS RESPONSE

{
   "token":    {
      "id": "7997560",
      "type": "WICODE"
   },
   "type": "PAYMENT",
   "storeTrxDetails":    {
      "storeId": 1050,
      "remoteStoreId": "1234512345",
      "retailerId": 999,
      "basketId": "180_63631826413",
      "trxId": "1",
      "posId": "861074024300611",
      "cashierId": "snappy"
   },
   "wiTrxId": 87153,
   "totalAmountProcessed": 100,
   "basketAmountProcessed": 100,
   "tipAmountProcessed": 0,
   "amountToSettle": 100,
   "vsp":    {
      "id": 50099,
      "name": "Eben VSP",
      "trxId": "test_vsp_17-x",
      "responseCode": "-1",
      "responseDesc": "Redemption successful!"
   },
   "discount": [],
   "loyalty": [],
   "responseCode": "-1",
   "responseDesc": "Success"
}

# EXAMPLE FAILURE RESPONSE

{
   "token":    {
      "id": "7997560",
      "type": "WICODE"
   },
   "type": "PAYMENT",
   "storeTrxDetails":    {
      "storeId": 1050,
      "remoteStoreId": "1234512345",
      "retailerId": 999,
      "basketId": "180_63631826413",
      "trxId": "1",
      "posId": "861074024300611",
      "cashierId": "snappy"
   },
   "wiTrxId": 87154,
   "totalAmountProcessed": 0,
   "basketAmountProcessed": 0,
   "responseCode": "02120",
   "responseDesc": "Invalid token"
}

Each transaction type uses the XML in a (slightly) different manner.

Fields Type Description
token Token This object contains information about the token. Find information about products object here.
type String The type of transaction; either Payment, Deposit or Withdrawal.
storeTrxDetails storeTrxDetails This object contains information about the store in which the transaction took place. Find information about the StoreTrxDetails object here.
wiTrxId Long This is the unique wiGroup transaction ID assigned to the transaction. This field is important for processing a subsequent Advice call.
totalAmountProcessed Integer This is the total transaction amount in cent. This is the sum of the BasketAmount and TipAmount.
BasketAmountProcessed Integer The basket amount that was used in processing the transaction.
tipAmountProcessed Integer The tip amount must be included in the total amount in order for the VSP to process the full amount. Not all VSP’s support tip amount.
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.
vspDetails VspDetails This object contains information about the vsp. Find information about vsp object here.
discountProductDetails DiscountProductDetails This object contains information about the products on which discounts are applied in this transaction. Find information about discount-product object here.
loyaltyDetails LoyaltyDetails This object contains information about the loyalty earned on this transaction. Please find information about the Loyalty object here.here.
responseCode Integer 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. Find information about responseCode object here.
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. Find information about responseDesc object here.

Objects

Product

{
   "id": [],
   "pricePerUnit": [],
   "units": []
}

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

{
   "basketId": [],
   "cashierId": [],
   "posId": [],
   "remoteStoreId": [],
   "retailerId": [],
   "storeId": [],
   "trxId": []
}

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

{
   "id": [],
   "type": []
}

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

{
   "id": [],
   "message": [],
   "name": [],
   "responseCode": [],
   "responseDesc": [],
   "trxId": []
}

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

{
   "amount": [],
   "name": [],
   "product": {
      "id": [],
      "units": []
   }
}

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

{
   "id": [],
   "units": []
}

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

{
   "name": [],
   "type": [],
   "earned": []
}

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.

Recon and Settlement

The wiPlatform settlement engine aggregates transactions at a merchant across many providers, and facilitates a settlement of the net amount due to the merchant. This section provides a high-level description of the recon process and the settlement process.

Reconsiliation

To ensure the final transaction state is consistent throughout all the entities involved, the platform performs a recon process with both the retailer and the VSP. Methods of recon supported include:

Depending on the capabilities of the retailer, the wiCode Platform supports an automated recon and allows the status of transactions to be updated based on discrepancies identified by the retailer.

Settlement

Settlement (payment/debit order) occurs independently from the recon process. Transactions will only be settled once finalised. Due to the different recon times from retailers
and daily deadlines for submitting debit orders
and EFT payments to the banking systems, some transactions may only be settled the following day.

Settlement of the store owner and the VSP is processed independently and do not effect each other. The store owner will be settled/debited for all transactions over all of its stores over all the VSPs in one single settlement batch. The VSP will be debited/settled for all transactions successfully authorized and finalised across all stores linked to the VSP in one single settlement batch.

Due to the timing differences between the store owner and VSP settlements, wiGroup will float the difference between what has been settled to the store owner and what has been debited from the VSP. wiGroup cannot support a float over a certain amount, thus the VSP settlement (debits) are typically processed on a daily basis. Additionally, when retailers accept deposits via the wiPlatform, a retailer-maintained float is typically required.

Integration Requirements

The following list states the minimum requirement required to complete and go live on the wiGroup platform:

shell