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:
- Pay in store
- Earn loyalty
- Redeem loyalty / coupon / voucher
- Cash withdrawal
- Cash deposit
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.
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:
- Transaction request
- Advice request
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
- 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).
- The VSP requests a transactional token from the wiGroup Token Manager via the Token Manager API.
- The token is displayed to the customer through the appropriate mobile channel.
- 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.
- 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.
- 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.
- 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).
- 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.
- 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.
- The WP will provide the response of the transaction to the POS.
- 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.
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.
Example 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.
Example 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:
- Our APIs were designed using the RESTful architectural style.
- Request and response bodies are formatted as JSON exclusively.
- Variables are indicated between angle brackets and the pound sign, e.g. <#variable#>.
- Different request -‐ response combinations are explored using ‘Cases’.
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
- A single discount voucher is issued per user for registering or paying with their app for the first time.
- A number of coupon campaigns linked to a channel for redemption against each purchase.
- Loyalty is earned on specific products purchased and vouchers or coupons are issued as rewards.
- Loyalty is earned on specific products purchased and vouchers or coupons are issued as rewards.
- Loyalty is earned on total amount of Payment or Deposit and vouchers or coupons are issued as rewards
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.
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.
/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.
- Requests authorisation of funds against the wiCode.
- The VSP is required to reserve the funds on a successful Transaction Request Response.
- A successful transaction Request will also put the wiCode into a SPR (success pending recon) state.
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"
}
}'
- The Advise request has two types of calls, a Finalise and a Reverse.
- The Advise Finalise indicates a completed transaction.
- The Advise Reverse is used to cancel a transaction and restore the funds balance in the user account.
- Once a transaction has been finalised it cannot be reversed.
- Once either the Finalise and a Reverse has taken place the wiCode then gets freed and returns to the wiCode pool.
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"
}
}'
- Requests information and seeks validity of the wiCode from the VSP. Predominantly used in the “Over the Counter” transactional model.
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:
- Our APIs were designed using the RESTful architectural style.
- Request and response bodies are formatted as JSON exclusively.
- Variables are indicated between angle brackets and the pound sign, e.g. <#variable#>.
- Different request -‐ response combinations are explored using ‘Cases’.
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:
- Daily markoff file via SFTP (on request)
- Daily Recon summary (PDF) and transactional (csv) report via email (automated)
- Recon transactional report via wiGroup merchant portal (manual retrieval)
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:
- You must have a test and production environment.
- All communication to wiGroup need to be done via HTTPS.Only 128 bit encrypted, certificates from 3rd party Certification Authorities (CA) will be accepted.
- You must connect to the secure DNS endpoint that will be provided by wiGroup.
- VSP must respond to wiGroup requests within 10 seconds.
- User journey must be documented, and signed off by wiGroup before development starts. Any part of the VSPs customer facing GUI that includes wiGroup elements must follow the “Powered by wiGroup” guidelines.
- A VSP must support Dual messaging for transaction processing.
- VSP must never reject an advice call.
- The final version of the Customer facing implementation must be submitted to wiGroup for QA testing, and a test-slot needs to be planned and provisioned via the relevant wiGroup project team.
- No code changes during a wiGroup test cycle.
- It is recommended that the wiCodes issued by the VSP have a 15-minute validity period if the VSP uses a mobile app or USSD.