Introduction

Empower your business with Yoyo Group's comprehensive API platform. Our suite of APIs enables you to seamlessly issue, manage, and redeem Vouchers, Coupons, and Gift Cards, transforming how you engage with customers through digital rewards and loyalty solutions.

Designed with developers in mind, Yoyo Group APIs offer a robust, intuitive integration that simplifies complex loyalty and payment ecosystems. We abstract away technical intricacies, providing you with powerful tools that let you focus on what matters most—growing your business and delighting your customers.

Need help? Our dedicated integration team is always ready to support you.

Key Features

🚀 Unlock the Full Potential of Yoyo Group APIs

Getting Started

📖 Your Integration Journey in 3 Straightforward Steps:

1. 🔑 Secure Authentication

   • Generate and manage API credentials
     
   • Implement robust security protocols
     
   • Validate and test initial connection
     

2. 🚧 Streamlined Integration

   • Provision a comprehensive test environment
     
   • Implement core API endpoints
     
   • Thoroughly validate transaction flows
     

3. 🔍 Advanced Optimization

   • Configure intelligent webhooks
     
   • Establish comprehensive reporting
     
   • Activate advanced analytics capabilities

Platform Architecture

In the Yoyo Group ecosystem, three key entities collaborate to facilitate seamless transactions:

1. Value Store Provider (VSP): Manages and stores redeemable customer value
2. Retailer: The merchant conducting the transaction
3. YoyoPlatform: The central orchestrator handling routing and settlement

Key Integration Principles

The YoyoPlatform provides a unified integration solution that: - Aggregates multiple Value Store Providers - Offers retailers a single technical integration point - Enables cross-platform value redemption - Simplifies complex transaction routing

Architectural Diagram

Transaction Flow Overview

The platform leverages a sophisticated, multi-step process to ensure secure and efficient transactions:

VSP Interaction

• Each VSP manages its own customer treasury system
• Provides mobile channels (app, USSD, mobisite) for customer access
• Maintains individual customer wallet interfaces

Platform Capabilities

• Centralized token management
• Multi-provider transaction routing
• Real-time transaction processing
• Secure settlement mechanisms

Transactional Process Flow

Transaction Steps

1. Customer Initiation

   • Customer signs into their mobile wallet via VSP channel
   • Prepares to make a payment at a store

2. Token Generation

   • VSP requests a transactional token from YoyoGroup Token Manager
   • Token displayed to customer through mobile channel

3. Point of Sale (POS) Integration

   • Cashier selects mobile tender option
   • Transaction routed through:
     • Direct YoyoPlatform POS API integration
     • Retail switch using standard card transaction protocol

4. Transaction Processing

   • Transaction Engine receives POS request
   • Identifies associated VSP via Token Manager
   • Sends processing request to VSP POST API
   • Includes critical transaction details:
     • Token
     • Basket value
     • Basket Information
     • Merchant information

5. Customer Confirmation

   • Optional customer transaction confirmation
   • VSP-managed interface
   • Benchmark response time: 1.5 seconds

6. Transaction Authorization

   • VSP validates transaction
   • Checks fund sufficiency
   • Responds within standard timeout (< 15s)

7. Finalization

   • YoyoPlatform provides transaction response to POS
   • Transaction advice sent to finalize
   • Option for transaction reversal if needed

Performance Considerations

• Ultrafast token generation
• Rapid transaction confirmation
• Seamless multi-provider integration
• Robust error handling and reversal mechanisms

Dual Messaging Approach

Yoyo Group's platform architecture employs a dual messaging flow to ensure seamless and reliable transaction processing. This system coordinates interactions between the Point of Sale (POS) system, the Yoyo wiCode platform, and the Value Store Provider (VSP).

Key Transaction Phases

The platform supports two primary request types to manage transactions:

1. Transaction Request:

   • Initiates a payment, deposit, or withdrawal request.
   • The Yoyo Platform forwards the request to the designated VSP for authorization.
   • The response reflects the VSP's authorization status or any encountered errors.

2. Advice Request:

   • Confirms the final state of the transaction (e.g., successful or reversed).
   • Sent after the initial transaction request to update the Yoyo Platform and VSP:
     • Finalized: Indicates a successfully completed transaction.
     • Reversed: Indicates a canceled or timed-out transaction.

Typical Transaction Flow

The diagram below demonstrates the interaction flow among the POS, Yoyo Platform, and VSP:

Important Note:
The YoyoPlatform and the VSP must record and act on the advice instruction, as it represents the final "real-world" state of the transaction. This state must be accurately reflected in all systems upstream from the POS, including the YoyoPlatform and the VSP system.

The VSP cannot decline the advice based on its own business logic (e.g., insufficient funds or user restrictions) because the original transaction has already been approved.

Exception: If the VSP system is unable to log the advice message due to system downtime, the YoyoPlatform will retry sending the advice multiple times until it is successfully logged and processed. This includes cases where the advice is declined or not delivered to the VSP system successfully.

Flexible Integration Models

Yoyo Group's architecture accommodates various integration models tailored to specific VSP and retailer requirements. These models will be detailed in the subsequent section.

Transaction Types

The YoyoPlatform supports the following transaction types:

• Pay in Store
  
• Earn Loyalty
  
• Redeem Loyalty / Coupon / Voucher / Giftcard
  
• Cash Withdrawal
  
• Cash Deposit

Key Benefits

• Unified Transaction Process:
  All transactions, regardless of the value store provider, follow the same process at the point of sale. This eliminates the need for cashiers to learn specific procedures for each provider.

• Simplified Cashier Training:
  Cashiers do not require additional training for each application accepted by the merchant, reducing onboarding time and operational overhead.

• Consolidated Recon and Settlement:
  Recon and settlement are aggregated across all providers, allowing merchants to process them once, instead of per provider.

  • Detailed, low-level reporting is available for each transaction provider, ensuring merchants have access to all data necessary for business intelligence and analytics.

This seamless and standardized approach enhances efficiency and reduces complexity for both merchants and cashiers.

Quick Start for Retailer - Merchant Integration Guide

This is a quick start guide. For more detailed information on any of the requests, refer to the relevant sections below in this document.

A point-of-sale integration can be achieved with as few as two API requests.

Point of Sale - Transaction Request & Response

#Authentication Required on every request:

{
    "id": "POS_ID_GOES_HERE",
    "password": "POS_PASSWORD_GOES_HERE",
    "apiServerVersion": "1.14",
    "apiSClientVersion": "this will be your software version identifier",
    "Content-Type": "application/json"
}

#Transaction Request Example:

{
    "token": {
        "id": "1234567",
        "type": "WICODE"
    },
    "storeTrxDetails": {
        "retailerId": 999,
        "storeId": 1050,
        "basketId": "basket1",
        "cashierId": "cashier1",
        "posId": "workstation1",
        "trxId": 12345
    },
    "product": [
        {
            "id": "coffee1",
            "pricePerUnit": 5000,
            "units": 1
        },
        {
            "id": "coffee2",
            "pricePerUnit": 5000,
            "units": 1
        }
    ],
    "type": "PAYMENT",
    "basketAmount": 10000,
    "billAmount": 10000,
    "totalAmount": 10000
}

#Transaction Response Example:

{
    "token": {
        "id": "1234567",
        "type": "WICODE"
    },
    "type": "PAYMENT",
    "storeTrxDetails": {
        "storeId": 1050,
        "remoteStoreId": "10501",
        "retailerId": 999,
        "basketId": "basket1",
        "trxId": "12345",
        "posId": "workstation1",
        "cashierId": "cashier1"
    },
    "wiTrxId": 431711,
    "totalAmountProcessed": 10000,
    "basketAmountProcessed": 10000,
    "cashbackAmountProcessed": 0,
    "tipAmountProcessed": 0,
    "amountToSettle": 0,
    "billAmount": 10000,
    "vsp": {
        "id": 20016,
        "name": "wiCoupon",
        "trxId": "569023",
        "responseCode": "-1",
        "responseDesc": "Success",
        "vspRef": "CVS_20230606150456819_Grant Test"
    },
    "discount": [
        {
            "name": "API Voucher Documentation",
            "amount": 10000,
            "product": []
        }
    ],
    "loyalty": [],
    "balance": [],
    "redemptions": [
        {
            "description": "API Voucher Documentation",
            "processedAmount": 10000,
            "settleAmount": 0,
            "type": "VOUCHER",
            "vspId": 20016,
            "wiVspTrxId": 658779
        }
    ],
    "responseCode": "-1",
    "responseDesc": "Success"
}

Step 1: Transaction Request

The merchant identifiers (storeId and retailerId) will be provided by Yoyo. The authentication details found in the header (id and password) will also be provided by Yoyo. The product array list is required for coupons. Please refer to the transaction details for more information.

Host URL: https://rad2.wigroup.co:8181/wigroup-transactionengine/pos-providers/transaction
HTTP Method: POST

All responses with a "responseCode": "-1" is considered successful. Anything other than "-1" is considered failed. Please refer to "responseDesc" for more information

Point of Sale - Advise Request & Response

Step 2: Advise Request

Please note that the same header details mentioned above apply to this request.

Host URL: https://rad2.wigroup.co:8181/wigroup-transactionengine/pos-providers/advise
HTTP Method: POST

All responses with a "responseCode": "-1" is considered successful. Anything other than "-1" is considered failed. Please refer to "responseDesc" for more information

#Authentication Required on every request:

{
    "id": "POS_ID_GOES_HERE",
    "password": "POS_PASSWORD_GOES_HERE",
    "apiServerVersion": "1.14",
    "apiSClientVersion": "this will be your software version identifier",
    "Content-Type": "application/json"
}

#Advise Request Example:

{
    "action": "FINALISE",
    "originalTrx": {
        "wiTrxId": 431342,
        "type": "PAYMENT",
        "storeTrxDetails": {
            "retailerId": 999,
            "storeId": 10501,
            "basketId": "basket1",
            "cashierId": "cashier1",
            "posId": "workstation1",
            "trxId": "12345"
        }
    }
}

Advise Response Example:

{
    "originalTrx": {
        "storeTrxDetails": {
            "storeId": 10501,
            "retailerId": 999,
            "basketId": "basket1",
            "trxId": "12345",
            "posId": "workstation1",
            "cashierId": "cashier1"
        },
        "wiTrxId": 431342,
        "type": "PAYMENT"
    },
    "action": "FINALISE",
    "wiTrxId": 431342,
    "responseCode": "-1",
    "responseDesc": "Success"
}

Quick Setup - eCommerce

Integrating eCommerce functionality into your application involves a straightforward process that mirrors the steps taken for point-of-sale (POS) integration, with one key addition: the tokenInfo request. This request is essential for validating the wiCode entered by the user, ensuring it can be redeemed on the eCommerce platform.

Purpose of the tokenInfo Request

The tokenInfo request serves multiple purposes:

• Validation: It checks whether the provided wiCode is valid and eligible for redemption.
• Monetary Value Retrieval: The response typically includes the monetary value associated with the coupon, voucher, or gift card. This information is crucial for displaying potential discounts to users during their shopping experience.
• Special Cases: Note that if a coupon applies to specific items or offers a percentage discount, the response may differ from standard cases.

Host URL: https://rad2.wigroup.co:8181/wigroup-transactionengine/pos-providers/token-info
HTTP Method: POST

Point of Sale - Token Info Response

All responses with a "responseCode": "-1" indicate a successful operation. Any other response code signifies a failure, and you should refer to the "responseDesc" for further details.

 Every request must include the following authentication details:
 Authentication Required
{
    "id": "POS_ID_GOES_HERE",
    "password": "POS_PASSWORD_GOES_HERE",
    "apiServerVersion": "1.14",
    "apiSClientVersion": "this will be your software version identifier",
    "Content-Type": "application/json"
}

Here’s an example of how to structure the tokenInfo request:

 Token Info Request Example
{
    "token": {
        "id": "1234567",
        "type": "WICODE"
    },
    "storeTrxDetails": {
        "storeId": 1050,
        "basketId": "basket1",
        "cashierId": "cashier1",
        "posId": "workstation1",
        "trxId": "1"
    }
}

Response Examples

This response indicates the details of a coupon associated with the provided wiCode:
Coupon Response Example
{
    "vsp": {
        "id": 20016,
        "name": "wiCoupon",
        "coupons": {
            "coupon": [
                {
                    "product": [
                        {
                            "id": "coffee1"
                        },
                        {
                            "id": "coffee2"
                        },
                        {
                            "id": "coffee3"
                        }
                    ],
                    "name": "API Coupon Documentation",
                    "discount": 1750
                }
            ]
        },
        "hasVoucher": false,
        "hasCoupon": true,
        "hasWallet": false,
        "hasGiftCard": false
    },
    "responseCode": "-1",
    "responseDesc": "Success"
}

This response provides details about a voucher associated with the provided wiCode:
Voucher Response Example

{
    "vsp": {
        "id": 20016,
        "name": "wiCoupon",
        "coupons": {
            "coupon": [
                {
                    "name": "API Voucher Documentation",
                    "discount": 10000
                }
            ]
        },
        "hasVoucher": true,
        "hasCoupon": false,
        "hasWallet": false,
        "hasGiftCard": false
    },
    "responseCode": "-1",
    "responseDesc": "Success"
}

 This response outlines the details of a gift card associated with the provided wiCode:
 Gift Card Response Example
{
    "vsp": {
        "id": 20016,
        "name": "wiCoupon",
        "balances": {
            "balance": [
                {
                    "name": "API Gift Card Documentation",
                    "type": "CENT",
                    "value": 50000
                }
            ]
        },
        "hasVoucher": false,
        "hasCoupon": false,
        "hasWallet": true,
        "hasGiftCard": false
    },
    "responseCode": "-1",
    "responseDesc": "Success"
}

Error Handling

Here are some common error responses you might encounter:

Invalid wiCode Format

{
    "responseCode": "2",
    "responseDesc": "Invalid wiCode format"
}

Invalid Credentials

{
    "responseCode": "3",
    "responseDesc": "Invalid credentials"
}

wiCode Not Found

{
    "responseCode": "4",
    "responseDesc": "wiCode not found"
}

wiCode Already Used

{
    "responseCode": "5",
    "responseDesc": "wiCode has already been used"
}

wiCode Expired

{
    "responseCode": "6", 
    "responseDesc": "wiCode has expired"
}

For a complete list of error codes and their descriptions, please contact wiGroup support.

Security Best Practices

When integrating with the wiGroup API, follow these security best practices:

Authentication

• Store your API credentials securely.
• Never expose credentials in client-side code.
• Rotate passwords periodically.
• Use environment variables for credential storage.

Request/Response Handling

• Always validate wiCodes before processing.
• Implement proper error handling.
• Log all transactions for audit purposes.
• Implement request timeouts.
• Use HTTPS for all API calls.

Data Protection

• Never store wiCodes permanently.
• Implement session timeouts.
• Clear sensitive data after use.
• Follow PCI compliance guidelines if handling payment data.

Integration Testing

• Test all error scenarios.
• Validate response codes.
• Test timeout scenarios.
• Use the test environment before going live.

For additional security guidelines or integration support, please contact wiGroup support.

Overview - Point of Sale Integration

The Yoyo Platform is an open, interoperable system that enables mobile and card-initiated transactions directly at point-of-sale. Through a single integration, merchants can: - Accept transactions from any integrated mobile application - Process multiple transaction types - Handle various payment methods - Manage loyalty programs

Transaction Flow

1. Token Validation

   • Customer presents wiCode/QR code
   • System validates token authenticity
   • Checks expiry and status

2. Transaction Processing

   • System processes payment
   • Applies any discounts
   • Calculates loyalty points
   • Updates balances

3. Confirmation

   • Sends confirmation to all parties
   • Updates transaction records
   • Issues digital receipt

Integration Benefits

1. Unified Integration

   • One integration handles all transaction types
   • Supports multiple payment providers
   • Common API for all services

2. Enhanced Security

   • Secure token generation
   • Real-time validation
   • Encrypted communication

3. Flexible Configuration

   • Customizable transaction flows
   • Configurable business rules
   • Adaptable to merchant needs

Token Validation

{
    "token": {
        "id": "123456789",
        "type": "WICODE"
    },
    "storeTrxDetails": {
        "storeId": "STORE123",
        "basketId": "BASKET001",
        "cashierId": "CASHIER001",
        "posId": "POS001",
        "trxId": "TRX001"
    }
}

Process Transaction

{
    "token": {
        "id": "123456789",
        "type": "WICODE"
    },
    "type": "PAYMENT",
    "storeTrxDetails": {
        "storeId": "STORE123",
        "retailerId": "RETAIL001",
        "basketId": "BASKET001",
        "trxId": "TRX001",
        "posId": "POS001",
        "cashierId": "CASHIER001"
    },
    "billAmount": 10000,
    "basketItems": [
        {
            "id": "PROD001",
            "description": "Coffee",
            "quantity": 2,
            "unitPrice": 2500,
            "totalAmount": 5000
        },
        {
            "id": "PROD002",
            "description": "Muffin",
            "quantity": 1,
            "unitPrice": 5000,
            "totalAmount": 5000
        }
    ]
}

Transaction Response

{
    "wiTrxId": 431711,
    "totalAmountProcessed": 10000,
    "basketAmountProcessed": 10000,
    "cashbackAmountProcessed": 0,
    "tipAmountProcessed": 0,
    "amountToSettle": 10000,
    "billAmount": 10000,
    "vsp": {
        "id": 20016,
        "name": "Example VSP",
        "trxId": "569023",
        "responseCode": "-1",
        "responseDesc": "Success",
        "vspRef": "VSP_REF_001"
    },
    "discount": [],
    "loyalty": [
        {
            "points": 100,
            "balance": 500
        }
    ],
    "balance": [],
    "redemptions": [],
    "responseCode": "-1",
    "responseDesc": "Success"
}

Finalize Transaction

{
  "action": "FINALISE",
  "originalTrx": {
    "wiTrxId": "exampleTransactionId123",
    "type": "PAYMENT",
    "storeTrxDetails": {
      "storeId": "store123",
      "cashierId": "cashier456",
      "timestamp": "2024-12-11T10:00:00Z",
      "amount": 10000
    }
  },
  "status": {
    "code": "SUCCESS",
    "message": "Transaction finalized successfully"
  }
}

Error Handling

{
    "responseCode": "001",
    "responseDesc": "Invalid token",
    "errors": [
        {
            "code": "TOKEN_001",
            "message": "Token has expired"
        }
    ]
}

Common error codes: - TOKEN_001: Invalid or expired token - TRX_001: Invalid transaction type - TRX_002: Invalid amount - TRX_003: Insufficient funds - AUTH_001: Invalid POS credentials

Best Practices

1. Token Validation

   • Always validate tokens before processing
   • Check expiry and status
   • Verify store details match

2. Transaction Processing

   • Include detailed basket information
   • Handle discounts and loyalty properly
   • Process in correct order (discounts → payment → loyalty)

3. Error Handling

   • Implement proper error handling
   • Show clear error messages to cashiers
   • Log all errors for troubleshooting

4. Security

   • Keep credentials secure
   • Use HTTPS for all API calls
   • Validate all input data

5. User Experience

   • Clear interface for cashiers
   • Quick error resolution
   • Proper receipt printing

Integration models

There are generally two manners of performing mobile transactions, namely:

• Over the Counter model
• Sit-down model

Over the Counter Model

The over-the-counter model is built on the principle that the client provides a wiCode (usually in the form of a QR code) to the cashier at the POS. Ideally the POS has the capability of scanning a QR code and processing the wiCode contained in the QR by making use of the YoyoDetect.dll, or manually entering the wiCode on the POS software to process a mobile payment.

For access to the YoyoGroup Detect SDK, please contact YoyoGroup integrations.

Sit Down Model

Sit-down payments requires the POS to print a unique QR code on each till slip. POS software providers can use Yoyo Bill Service REST API to generate this QR code.

The clients may then scan the QR code (making use of a registered mobile application) and proceed to make partial payments on the bill. The POS software requires to be integrated to the transaction history call to retrieve payments made on the basket.

POS Provider API

This RPC API (also referred to as REST) enables the Point of Sale to communicate with the Yoyo Platform in order to process transactions. Each transaction at Point of Sale typically requires the POS to communicate with the Yoyo Platform twice:

1. A Transaction Request - in order to authorise the transaction.
2. An Advice Request with either finalise or reversal as the action - a finalise is to close off the transaction whereas a reversal is to cancel the transaction.

Header Parameters

The following table specifies the header parameters which are required in each web service call.

HOST URL

The QA wiCode platform exposes REST service endpoints by utilizing the following host and path:

Monetary values

Monetary amounts are both accepted and returned in minor denominations.

Versioning

This API exposes two required versioning fields.

#HEADER 

id: {{api_id}}
password: {{api_password}}
apiClientVersion: {{api_client_version}}
apiServerVersion: {{api_server_version}}
Content-Type: application/json

API server versions

The following API server versions are currently being supported:

Transaction API

Create Transaction

This endpoint handles the creation of new transactions.

{
    "type": "PAYMENT",
    "switchTrxId": "TRX123",
    "totalAmount": 10000,
    "basketAmount": 10000,
    "cashbackAmount": 0,
    "tipAmount": 0,
    "billAmount": 10000,
    "products": [
        {
            "id": "PROD001",
            "units": 2,
            "pricePerUnit": 5000
        }
    ],
    "token": {
        "id": "1234567",
        "type": "WICODE",
        "payload": "SAMPLE_PAYLOAD"
    },
    "storeTrxDetails": {
        "storeId": 1050,
        "remoteStoreId": "STORE123",
        "retailerId": 999,
        "basketId": "BASKET123",
        "trxId": "TRX123",
        "posId": "POS001",
        "cashierId": "CASH001",
        "billId": 12345,
        "posBillId": "BILL123"
    }
}

Example request

curl -X POST "https://rad2.wigroup.co:8181/wigroup-transactionengine/pos-providers/transaction"
  -H "Content-Type: application/json"
  -H "id: <#apiId#>"
  -H "password: <#apiPassword#>"
  -H "apiClientVersion: <#version#>"
  -H "apiServerVersion: <#version#>"
  -d {
    "type": "PAYMENT",
    "switchTrxId": "TRX123",
    "totalAmount": 10000,
    "basketAmount": 10000,
    "cashbackAmount": 0,
    "tipAmount": 0,
    "billAmount": 10000,
    "products": [
        {
            "id": "PROD001",
            "units": 2,
            "pricePerUnit": 5000
        }
    ],
    "token": {
        "id": "1234567",
        "type": "WICODE",
        "payload": "SAMPLE_PAYLOAD"
    },
    "storeTrxDetails": {
        "storeId": 1050,
        "remoteStoreId": "STORE123",
        "retailerId": 999,
        "basketId": "BASKET123",
        "trxId": "TRX123",
        "posId": "POS001",
        "cashierId": "CASH001",
        "billId": 12345,
        "posBillId": "BILL123"
    }
  }

Example response

{
    "responseCode": "-1",
    "responseDesc": "Success",
    "wiTrxId": 87153,
    "totalAmountProcessed": 10000,
    "basketAmountProcessed": 10000,
    "tipAmountProcessed": 0,
    "amountToSettle": 10000,
    "vsp": {
        "id": 50099,
        "name": "Sample VSP",
        "trxId": "TRX123",
        "responseCode": "-1",
        "responseDesc": "Transaction successful!"
    },
    "discount": [],
    "loyalty": []
}

Request Parameters

Response Parameters

Advise request

#REQUEST

curl --location 'https://rad2.wigroup.co:8181/wigroup-transactionengine/pos-provider/advise' \
--header 'id: <string>' \
--header 'password: <string>' \
--header 'apiClientVersion: <string>' \
--header 'apiServerVersion: <string>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "action": "<string>",
  "originalTrx": {
    "storeTrxDetails": {
      "basketId": "<string>",
      "cashierId": "<string>",
      "posId": "<string>",
      "trxId": "<string>",
      "storeId": "<long>",
      "remoteStoreId": "<string>",
      "retailerId": "<long>",
      "billId": "<long>",
      "posBillId": "<string>"
    },
    "type": "<string>",
    "wiTrxId": "<long>",
    "token": {
      "id": "<string>",
      "type": "<string>",
      "payload": "<string>"
    },
    "switchTrxId": "<string>",
    "vspTrxId": "<string>",
    "totalAmountProcessed": "<integer>",
    "basketAmountProcessed": "<integer>",
    "cashbackAmountProcessed": "<integer>",
    "tipAmountProcessed": "<integer>"
  },
  "apiCredentials": "sunt consectetur"
}'

The advise request must be sent after the transaction has completed at POS (tender is completed). The advise request determines whether the state of a pending transaction is set to either to complete the transaction or to cancel the entire bill. This is done by means of setting the action field to REVERSE or FINALISE. This will change the transaction from pending to finalised / reversed state on the YoyoGroup platform.

The POS will receive a response from YoyoGroup as the final leg of the transaction. It is important to note that the wiTrxId received in the transaction response should be carried over and used on the advise request in order to advise that transaction. The only time an advise will not included the wiTrxId is when the advise Type is a reversal.

Parameters:

Advise response

#RESPONSE

{
    "responseCode": "<string>",
    "responseDesc": "<string>",
    "originalTrx": {
        "storeTrxDetails": {
            "basketId": "<string>",
            "cashierId": "<string>",
            "posId": "<string>",
            "trxId": "<string>",
            "storeId": "<long>",
            "remoteStoreId": "<string>",
            "retailerId": "<long>",
            "billId": "<long>",
            "posBillId": "<string>"
        },
        "type": "<string>",
        "wiTrxId": "<long>",
        "token": {
            "id": "<string>",
            "type": "<string>",
            "payload": "<string>"
        },
        "switchTrxId": "<string>",
        "vspTrxId": "<string>",
        "totalAmountProcessed": "<integer>",
        "basketAmountProcessed": "<integer>",
        "cashbackAmountProcessed": "<integer>",
        "tipAmountProcessed": "<integer>"
    },
    "action": "<string>",
    "wiTrxId": "<long>"
}

Parameters:

Transaction History request

The transaction history request returns a list of transactions that have been processed. Transaction history may 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 even a combination of the two).

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

#REQUEST
curl --location --globoff 'https://rad2.wigroup.co:8181/wigroup-transactionengine/pos-providers/transaction-history' \
--header 'id: {{api_id}}' \
--header 'password: {{api_password}}' \
--header 'apiClientVersion: {{api_client_version}}' \
--header 'apiServerVersion: {{api_server_version}}' \
--header 'Content-Type: application/json' \
--data '{
    "storeTrxDetails": {
        "storeId": "<long>",
        "retailerId": "<long>",
        "basketId": "<long>",
        "trxId": "<long>",
        "posId": "<string>",
        "cashierId": "<string>"
    },
    "dateFrom": "<string>",
    "dateTo": "<string>",
    "pageSize": 10,
    "pageOffset": 0 
}'

The transaction history request provides a summary of the transactions associated with the storeTrxDetails provided. It is recommended that the storeID (or both the remoteStoreID and retailerID) as well as the basketID is provided in the transaction history request to find all the (partial) transactions associated with a particular basket. It is, however, required that the storeID (or both the remoteStoreID and retailerID) be provided at the very minimum. The basic layout of the transaction history request looks a follows:

^* If no date range is specified, the call will default to returning the transaction history for the past 24 hours.

Transaction history response

#RESPONSE

{
    "storeTrxDetails": {
        "storeId": "<long>",
        "retailerId": "<long>",
        "basketId": "<string>",
        "trxId": "<string>",
        "posId": "<string>",
        "cashierId": "<string>"
    },
    "dateFrom": "2022-02-24 00:00:00",
    "dateTo": "2022-02-26 00:00:00",
    "pageSize": 10,
    "pageOffset": 0,
    "transactions": [
        {
            "id": "<long>",
            "type": "<string>",
            "state": "S",
            "vspId": "<long>",
            "vspName": "<string>",
            "token": {
                "id": "<string>",
                "type": "WICODE"
            },
            "billAmount": "<integer>",
            "totalAmountProcessed": "<integer>",
            "basketAmountProcessed": "<integer>",
            "cashbackAmountProcessed": "<integer>",
            "tipAmountProcessed": "<integer>",
            "amountToSettle": "<ingintegereter>",
            "createDate": "2022-02-25 12:57:13.0",
            "lastModifiedDate": "2022-10-19 09:55:43.0",
            "responseCode": "-1",
            "adviceResponseCode": "-1"
        }
    ],
    "responseCode": "-1",
    "responseDesc": "Success"
}

Transaction History V2 request

The transaction history V2 request returns details on a single transaction that have been processed. Transaction history may be linked to a specific retail store and is used to request details of a specific transaction.

#REQUEST

curl --location --globoff 'https://rad2.wigroup.co:8181/wigroup-transactionengine/pos-providers/transaction-history/v2 \
--header 'id: {{api_id}}' \
--header 'password: {{api_password}}' \
--header 'apiClientVersion: {{api_client_version}}' \
--header 'apiServerVersion: {{api_server_version}}' \
--header 'Content-Type: application/json' \
--data '{
    "storeTrxDetails": {
        "storeId": "<long>",
        "retailerId": "<long>",
        "basketId": "<long>",
        "trxId": "<long>",
        "posId": "<string>",
        "cashierId": "<string>"
    },
     "transactionId": "<long>"
}'

The transaction history request provides details of the transaction stecified by the transasctionId and associated with the storeTrxDetails provided. It is mandatory to provide the transasctionId as well as the storeID (or both the remoteStoreID and retailerID). The basic layout of the transaction history request looks a follows:

#RESPONSE

{
  "responseCode": "<string>",
  "responseDesc": "<string>",
  "token": {
    "id": "<string>",
    "type": "<string>",
    "payload": "<string>"
  },
  "type": "<string>",
  "storeTrxDetails": {
    "basketId": "<string>",
    "cashierId": "<string>",
    "posId": "<string>",
    "trxId": "<string>",
    "storeId": "<long>",
    "remoteStoreId": "<string>",
    "retailerId": "<long>",
    "billId": "<long>",
    "posBillId": "<string>"
  },
  "switchTrxId": "<string>",
  "wiTrxId": "<long>",
  "totalAmountProcessed": "<integer>",
  "basketAmountProcessed": "<integer>",
  "cashbackAmountProcessed": "<integer>",
  "tipAmountProcessed": "<integer>",
  "amountToSettle": "<integer>",
  "billAmount": "<integer>",
  "vsp": {
    "id": "<long>",
    "name": "<string>",
    "message": "<string>",
    "trxId": "<string>",
    "responseCode": "<string>",
    "responseDesc": "<string>",
    "balances": {
      "balance": [
        {
          "name": "<string>",
          "type": "<string>",
          "value": "<integer>"
        },
        {
          "name": "<string>",
          "type": "<string>",
          "value": "<integer>"
        }
      ]
    },
    "coupons": {
      "coupon": [
        {
          "product": [
            {
              "id": "<string>",
              "units": "<integer>",
              "discount": "<integer>"
            },
            {
              "id": "<string>",
              "units": "<integer>",
              "discount": "<integer>"
            }
          ],
          "name": "<string>",
          "discount": "<integer>",
          "id": "<string>"
        },
        {
          "product": [
            {
              "id": "<string>",
              "units": "<integer>",
              "discount": "<integer>"
            },
            {
              "id": "<string>",
              "units": "<integer>",
              "discount": "<integer>"
            }
          ],
          "name": "<string>",
          "discount": "<integer>",
          "id": "<string>"
        }
      ]
    },
    "hasVoucher": "<boolean>",
    "hasCoupon": "<boolean>",
    "hasWallet": "<boolean>",
    "hasGiftCard": "<boolean>",
    "vspRef": "<string>"
  },
  "discount": [
    {
      "name": "<string>",
      "amount": "<integer>",
      "product": [
        {
          "id": "<string>",
          "units": "<integer>",
          "discount": "<integer>"
        },
        {
          "id": "<string>",
          "units": "<integer>",
          "discount": "<integer>"
        }
      ]
    },
    {
      "name": "<string>",
      "amount": "<integer>",
      "product": [
        {
          "id": "<string>",
          "units": "<integer>",
          "discount": "<integer>"
        },
        {
          "id": "<string>",
          "units": "<integer>",
          "discount": "<integer>"
        }
      ]
    }
  ],
  "loyalty": [
    {
      "name": "<string>",
      "type": "<string>",
      "earned": "<integer>"
    },
    {
      "name": "<string>",
      "type": "<string>",
      "earned": "<integer>"
    }
  ],
  "balance": [
    {
      "name": "<string>",
      "type": "<string>",
      "value": "<integer>"
    },
    {
      "name": "<string>",
      "type": "<string>",
      "value": "<integer>"
    }
  ],
  "redemptions": [
    {
      "id": "<long>",
      "description": "<string>",
      "processedAmount": "<integer>",
      "settleAmount": "<integer>",
      "type": "GIFTCARD",
      "products": [
        {
          "id": "<string>",
          "units": "<integer>"
        },
        {
          "id": "<string>",
          "units": "<integer>"
        }
      ],
      "vspId": "<long>",
      "wiVspTrxId": "<long>",
      "thirdPartySettleAmount": "<integer>",
      "thirdPartySettleReference": "<string>"
    },
    {
      "id": "<long>",
      "description": "<string>",
      "processedAmount": "<integer>",
      "settleAmount": "<integer>",
      "type": "CARD",
      "products": [
        {
          "id": "<string>",
          "units": "<integer>"
        },
        {
          "id": "<string>",
          "units": "<integer>"
        }
      ],
      "vspId": "<long>",
      "wiVspTrxId": "<long>",
      "thirdPartySettleAmount": "<integer>",
      "thirdPartySettleReference": "<string>"
    }
  ]
}

Transaction callback

The transaction callback URL provides the Yoyo platform with a means of notifying third parties that a transaction has been completed. Whenever a transaction is completed, successfully or not, a callback can be POSTed to a provided URL. A callback address can be setup on a retailer level, this means that on one callback address can be set for a defined retailer on the Yoyo platform.

Use case

The transaction callback is intended for retailers that support SITDOWN payments and require a notification when payment for an open bill has been completed. This notification could trigger an action by the merchant to close the bill or in the case of a none successful transaction, assist the client with an alternative payment method. More details regarding the transaction can requested using the Transaction History V2 request.

Transaction Callback failure

To facilitate synchronisation, the Yoyo Platform has a built-in finite redemption callback retry policy. This is enables better state synchronisation by minimising the number of redemption callback failures. If, for some reason, no response is received across all redemption callback requests, a redemption fallback policy must be followed.

Webhook URL

The transaction callback should be built using RESTful JSON programming language.

# Example request

{
   "transactionId": 1,
   "basketId": "STRING",
   "storeId": 1050,
   "totalAmountProcessed":100,
   "state":"STRING"
 }

# Example response

HTTP 200 (OK)

Endpoint: {your_webhook_url}/

Bills API

Create Bill

This endpoint creates a new bill in the system.

{
    "amount": 2300,
    "basketId": "9eebc2fd-0d26-4680-b54e-f1d66862569b",
    "cashierId": "Cathrine",
    "storeId": "1050",
    "posId": "0672ceb2-5b00-440c-8060-512822a558bh",
    "basket": [
        {
            "product": {
                "sku": "9999",
                "desc": "Espresso",
                "qty": 1,
                "price": 2300
            }
        },
        {
            "product": {
                "sku": "9991",
                "desc": "Espresso",
                "qty": 2,
                "price": 2300
            }
        }
    ]
}

Example request

curl --location 'https://rad2.wigroup.co:8181/wigroup-bill/bills' \
--header 'Content-Type: application/json' \
--data '{
    "amount": 2300,
    "basketId": "9eebc2fd-0d26-4680-b54e-f1d66862569b",
    "cashierId": "Cathrine",
    "storeId": "1050",
    "posId": "0672ceb2-5b00-440c-8060-512822a558bh",
    "basket": [
        {
            "product": {
                "sku": "9999",
                "desc": "Espresso",
                "qty": 1,
                "price": 2300
            }
        },
        {
            "product": {
                "sku": "9991",
                "desc": "Espresso",
                "qty": 2,
                "price": 2300
            }
        }
    ]
}'

Example response

{
    "id": 44,
    "amount": 2300,
    "basketId": "9eebc2fd-0d26-4680-b54e-f1d66862569b",
    "createDate": "2024-01-18T14:05:58.009Z",
    "footer": "|Apps accepted:|Example App",
    "header": "| |*** Scan the QR code below: ***| |",
    "mobilePaymentUrl": "http://rad2.wigroup.co/bill/9999",
    "posId": "0672ceb2-5b00-440c-8060-512822a558bh",
    "qrData": "sampledata",
    "qrImage": "",
    "state": "A",
    "storeId": "1050"
}

Request Parameters

Response Parameters

Get Bill

Retrieve a bill using store ID, POS ID, and basket ID.

Example request

curl --location 'https://rad2.wigroup.co:8181/wigroup-bill/bills?storeId=1050&posId=1&basketId=basket_123'

Example response

{
    "id": 44,
    "amount": 2300,
    "basketId": "basket_123",
    "createDate": "2024-01-18T14:05:58.009Z",
    "footer": "|Apps accepted:|Example App",
    "header": "| |*** Scan the QR code below: ***| |",
    "mobilePaymentUrl": "http://rad2.wigroup.co/bill/9999",
    "posId": "1",
    "qrData": "sampledata",
    "qrImage": "",
    "state": "A",
    "storeId": "1050"
}

Query Parameters

User Interface Guide

Although mobile transacting technology has existed for several years, transacting at point of sale using only your mobile device is still a relatively new concept for many consumers and cashiers alike. Furthermore, as more applications enter the market, consumers are being asked to transact in many different ways. Similarly, cashiers are being asked to understand many different payment processes, and as well as many different types of transactions (from pay to deposit to loyalty accumulation).

The following documentation can be viewed as guidelines for best practices when integration in to the Yoyo Group platform for POS transactions:

• User Interface Guide, PDF document.
• POS Screen Flow Walkthrough, PDF document.

Objects

API credentials

<apiCredentials>
  <apiClientVersion></apiClientVersion>
  <apiServerVersion></apiServerVersion>
  <id></id>
  <password></password>
</apiCredentials>

Product

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

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

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.

Token

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

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

VSP

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

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

Discount

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

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

Discount product

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

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

Loyalty

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

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

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.

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>

Basket

Response Codes

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

Transaction Engine

Bill Server

Overview - Value Store Provider

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

Dual Messaging Architecture

{
  "transaction_flow": {
    "phase1": {
      "name": "Transaction Request",
      "purpose": "Initial authorization",
      "flow": [
        "POS initiates transaction",
        "Platform routes to VSP",
        "VSP authorizes or declines"
      ]
    },
    "phase2": {
      "name": "Advice Request",
      "purpose": "Final transaction state",
      "types": {
        "FINALISE": "Confirms successful completion",
        "REVERSE": "Cancels/voids transaction"
      }
    }
  },
  "important_rules": {
    "advice_handling": {
      "mandatory": true,
      "cannot_decline": true,
      "represents": "Real-world transaction outcome"
    },
    "retry_mechanism": {
      "enabled": true,
      "condition": "VSP system unavailable",
      "action": "Platform retries until successful"
    }
  }
}

The Yoyo Platform implements a dual messaging architecture to ensure reliable transaction processing:

1. Transaction Request

   • Initiates payment, deposit, or withdrawal
   • Platform routes request to VSP for authorization
   • VSP validates and responds with approval/decline

2. Advice Request

   • Confirms final transaction state
   • Types:
     • FINALISE: Confirms successful completion
     • REVERSE: Indicates cancellation or timeout
   • Cannot be declined by VSP
   • Represents real-world transaction outcome

Important Implementation Notes

1. VSP Responsibilities

   • Must implement both message types
   • Cannot decline advice requests
   • Must handle retry attempts
   • Should reserve funds on initial authorization

2. Timing Considerations

   • Transaction timeout: 15 seconds
   • Advice may be delayed up to 24+ hours
   • Must maintain transaction state until advice received

3. Fund Management

   • Reserve funds on successful authorization
   • Deduct/add funds only on FINALISE
   • Release reserved funds on REVERSE

Transaction Types

The platform facilitates various transaction types including: - Pay in store - Earn & Burn loyalty - Redeem coupon/voucher/gift card - Cash Withdrawal/Cashback - Cash Deposit

All transactions across different value store providers occur at point of sale through the exact same transaction process, ensuring: - Cashiers don't need special training per provider - Unified recon and settlement mechanisms - Detailed per-provider reporting for business intelligence

Platform Architecture

For any transaction to occur, there are three primary entities: 1. Value Store Provider (VSP): Manages and stores redeemable customer value 2. Retailer: The merchant conducting the transaction 3. YoyoPlatform: The central orchestrator handling routing and settlement

Key Integration Principles

The YoyoPlatform provides a unified integration solution that: - Aggregates multiple Value Store Providers - Offers retailers a single technical integration point - Enables cross-platform value redemption - Simplifies complex transaction routing

VSP Types

There are typically three types of VSPs that integrate with the platform:

1. Treasury / Value Store

These are typically 'wallets' where funds are allocated through: - Insurance payouts - Lotto winnings - Micro job earnings - Employee benefit rewards - Loyalty and coupon/voucher systems

2. Direct Bank

For direct integrations into Bank Accounts through a middleware API layer.

3. Payment Gateway

For payments in apps that store users' banking cards (credit or debit), routing payments through to relevant banks.

Integration Requirements

When integrating as a VSP with the Yoyo Platform, the following requirements must be met:

1. Environment Setup

   • Maintain both test and production environments
   • SSL certification with 128-bit encryption for production
   • Connect to secure DNS endpoints provided by Yoyo Group

2. Technical Requirements

   • All communication via HTTPS (TLS 1.2 minimum)
   • Response time within 10 seconds
   • Support for Dual Messaging
   • Never reject advice calls
   • Prevent transaction cancellation during processing

3. Implementation Guidelines

   • Document and get approval for user journey
   • Follow "Powered by Yoyo Group" guidelines
   • Submit final implementation for QA testing
   • No code changes during test cycles
   • Recommended 15-minute wiCode validity period

Auto-Redeem Functionality

The platform supports linking multiple VSPs to enable auto-redeem functionality:

{
  "auto_redeem_features": {
    "discount_vouchers": {
      "triggers": [
        "First-time registration",
        "First payment",
        "Campaign-specific"
      ]
    },
    "loyalty_points": {
      "earning_methods": [
        "Specific product purchases",
        "Total transaction amount",
        "Payment or deposit amount"
      ]
    }
  }
}

This functionality allows: - Grouping multiple wiCodes into one - Reducing number of QR scans at POS - Enhancing user journey - Minimizing transaction time

Bills Request

# Request Example
{
  "endpoint": "/vsp/bills",
  "method": "GET",
  "headers": {
    "apiId": "<your_api_id>",
    "apiPassword": "<your_api_password>",
    "Content-Type": "application/json; charset=UTF-8"
  },
  "parameters": {
    "qrCode": "<qr_data>"
  }
}

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

The bills request accepts QR code data and returns a bill object containing transaction details. This enables: - QR code parsing and validation - Collection of transaction details - Population of transaction screens - Initiation of payment process

Transaction Models

The Yoyo Platform supports three distinct transaction models, each designed for specific use cases and environments.

Over-the-Counter (OTC)

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

The OTC model involves three main components: 1. Retailer (POS) 2. Yoyo Platform 3. VSP System

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 Yoyo 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 YoyoPlatform, the transaction request will be sent to the Transaction Engine via the YoyoPlatform POS API. If the POS is integrated to the YoyoPlatform 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 YoyoPlatform BIN number). It is then routed by the switch to the YoyoPlatform.
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 YoyoPlatform in [7]. This will need to occur within the standard transaction timeout range of less than 15 seconds.
10. The YoyoPlatform 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 YoyoPlatform, to FINALISE the transaction with the VSP. Should the POS need to cancel the pending transaction, a REVERSE advice is sent to the YoyoPlatform, and to the VSP.

Important Notes

{
  "timeout": {
    "limit": "15 seconds",
    "action": "Transaction reversed if exceeded"
  },
  "advice_handling": {
    "finalize": "Confirms successful transaction",
    "reverse": "Cancels pending transaction",
    "rules": [
      "Cannot be declined",
      "Indicates final real-world outcome",
      "May be delayed up to 24+ hours"
    ]
  },
  "fund_management": {
    "on_request": "Reserve funds",
    "on_finalize": "Deduct/add funds",
    "on_reverse": "Release reserved funds"
  }
}

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 YoyoPlatform 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 YoyoPlatform by doing the POST /transactions call to the Transaction Engine VSP API.

Once the transaction is initiated the YoyoPlatform will route the request to the VSP's Transactional Gateway for authorisation. Upon a successful transaction response form the VSP the YoyoPlatform 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

Implementation Notes

{
  "qr_code": {
    "type": "Static",
    "placement": "Store wobbler/display",
    "content": "Unique store identifier"
  },
  "limitations": {
    "functionality": "Reduced compared to OTC",
    "integration": "No POS system required",
    "verification": "Manual amount entry"
  }
}

Token Manager REST API

The Token Manager API is used by VSPs to reserve tokens (wiCodes) for specific time frames. Tokens automatically expire and return to the available pool. The wiCode length is determined by the token lifespan and availability.

Important Notes

1. Date Format: Strict ISO 8601 format is required for dates. Example in Java:

1. Monetary Format: All amounts are 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'.

1. Required in request headers:

   • apiId: Your API ID
   • apiPassword: Your API Password
   • Content-Type: application/json

2. Token Types:

   • PAYMENT: Standard payment token
   • DEPOSIT: For cash deposits
   • WITHDRAWAL: For cash withdrawals

3. Auto-Redeem Feature: Multiple VSP services can be linked:

   • Discount wiCodes (from CVS)
   • Loyalty wiCodes (from wiLoyalty)
   • Both can be included in a single transaction

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 YoyoPlatform.

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 Yoyo Coupon Voucher Service and the Yoyo 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 discount wiCode.

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.

Common error codes:

• TOKEN_001: Invalid token type
• TOKEN_002: Invalid amount
• TOKEN_003: Invalid expiry date
• TOKEN_004: Invalid discount wiCode
• TOKEN_005: Invalid loyalty wiCode
• AUTH_001 : Invalid API credentials

Tokens request

    # EXAMPLE REQUEST

    curl "https://token-manager-api-int.wigroup.co/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

Transaction Gateway

POST Transaction Request

Transactional Gateway (callback)

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 YoyoPlatform 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 Callback

# Request Example
{
    "token": {
        "id": "1234567",
        "type": "WICODE"
    },
    "storeTrxDetails": {
        "storeId": 1050,
        "basketId": "basket1",
        "cashierId": "cashier1",
        "posId": "workstation1",
        "trxId": "1"
    }
}

This call can be used to obtain information about a YoyoGroup 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

Transaction Response

# Response Example
{
    "responseCode": "-1",
    "responseDesc": "Success",
    "vspTrxId": "0001",
    "totalAmountProcessed": 100,
    "basketAmountProcessed": 100,
    "cashbackAmountProcessed": 0,
    "id": 1234,
    "name": "vsp_name"
}

POST Advise Request Callback

# 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"
       }
     }'