Yoyo Logo

Redemption

Redeem loyalty vouchers and gift cards at POS or online

Understanding the Dual-Message Flow

All redemptions use a two-step process to ensure reliable transaction handling:

1Transaction Request

Sends the wiCode and basket amount. Returns authorization and amount processed.

2Advise Request

Confirms final state (FINALISE or REVERSE). Must always be sent.

In-Store Point of Sale

Integrate with your POS system for in-store redemptions

Integration Flow

  1. 1Customer presents wiCode at checkout (scanned or entered manually)
  2. 2POS captures wiCode and sends Transaction Request to Yoyo with basket amount
  3. 3Yoyo authorises and returns the discount amount to apply
  4. 4POS applies discount to basket and completes the sale
  5. 5POS sends Advise Request to finalize (FINALISE or REVERSE)
Step 1: Transaction Request
# Step 1: Send Transaction Request with wiCode, basket amount, and product data
curl -X POST "https://rad2.wigroup.co:8181/wigroup-transactionengine/pos-providers/transaction" \
  -H "id: YOUR_POS_ID" \
  -H "password: YOUR_POS_PASSWORD" \
  -H "apiClientVersion: your_version_here" \
  -H "apiServerVersion: 1.14" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "PAYMENT",
    "totalAmount": 10000,
    "basketAmount": 10000,
    "products": [
      {
        "id": "COFFEE345",
        "units": 1,
        "pricePerUnit": 5000
      },
      {
        "id": "TEA346",
        "units": 1,
        "pricePerUnit": 5000
      }
    ],
    "token": {
      "id": "wicode_here",
      "type": "WICODE"
    },
    "storeTrxDetails": {
      "storeId": 1050,
      "basketId": "basket_1",
      "trxId": "1",
      "posId": "online",
      "cashierId": "online"
    }
  }'
Transaction Response
# Transaction Response Example
{
  "token": { "id": "1234567", "type": "WICODE" },
  "type": "PAYMENT",
  "storeTrxDetails": {
    "storeId": 1050,
    "retailerId": 999,
    "basketId": "basket1",
    "trxId": "12345"
  },
  "wiTrxId": 431711,
  "totalAmountProcessed": 10000,
  "basketAmountProcessed": 10000,
  "amountToSettle": 0,
  "billAmount": 10000,
  "vsp": {
    "id": 20016,
    "name": "wiCoupon",
    "trxId": "569023",
    "responseCode": "-1",
    "responseDesc": "Success"
  },
  "discount": [
    { "name": "API Voucher Documentation", "amount": 10000 }
  ],
  "redemptions": [
    {
      "description": "API Voucher Documentation",
      "processedAmount": 10000,
      "type": "VOUCHER",
      "vspId": 20016
    }
  ],
  "responseCode": "-1",
  "responseDesc": "Success"
}
Step 2: Advise Request
# Step 2: Finalize the transaction (FINALISE or REVERSE)
curl -X POST "https://rad2.wigroup.co:8181/wigroup-transactionengine/pos-providers/advise" \
  -H "id: POS_ID" \
  -H "password: POS_PASSWORD" \
  -H "apiServerVersion: 1.14" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "FINALISE",
    "originalTrx": {
      "wiTrxId": 431711,
      "type": "PAYMENT",
      "storeTrxDetails": {
        "retailerId": 999,
        "storeId": 1050,
        "trxId": "12345"
      }
    }
  }'
Response Codes
-1 = Success
!Any other code = Failed
Notes
basketAmount

The value of the items in the basket before any discounts are applied.

totalAmount

The final amount the customer pays after the loyalty discount has been applied. Send basketAmount upfront; use totalAmount when finalising the transaction.

Online Checkout

Accept wiCodes in your eCommerce checkout flow

Integration Flow

  1. 1Customer enters wiCode at checkout → discount instantly applied to basket
  2. 2Customer pays remaining balance with card or other payment method
  3. 3Advise Request sent to finalize (FINALISE on success, REVERSE if cancelled)
Step 1: Transaction Request
# Step 1: Send Transaction Request with wiCode, basket amount, and product data
curl -X POST "https://rad2.wigroup.co:8181/wigroup-transactionengine/pos-providers/transaction" \
  -H "id: YOUR_POS_ID" \
  -H "password: YOUR_POS_PASSWORD" \
  -H "apiClientVersion: your_version_here" \
  -H "apiServerVersion: 1.14" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "PAYMENT",
    "totalAmount": 10000,
    "basketAmount": 10000,
    "products": [
      {
        "id": "COFFEE345",
        "units": 1,
        "pricePerUnit": 5000
      },
      {
        "id": "TEA346",
        "units": 1,
        "pricePerUnit": 5000
      }
    ],
    "token": {
      "id": "wicode_here",
      "type": "WICODE"
    },
    "storeTrxDetails": {
      "storeId": 1050,
      "basketId": "basket_1",
      "trxId": "1",
      "posId": "online",
      "cashierId": "online"
    }
  }'
Transaction Response
# Transaction Response Example
{
  "token": { "id": "1234567", "type": "WICODE" },
  "type": "PAYMENT",
  "storeTrxDetails": {
    "storeId": 1050,
    "retailerId": 999,
    "basketId": "basket1",
    "trxId": "12345"
  },
  "wiTrxId": 431711,
  "totalAmountProcessed": 10000,
  "basketAmountProcessed": 10000,
  "amountToSettle": 0,
  "billAmount": 10000,
  "vsp": {
    "id": 20016,
    "name": "wiCoupon",
    "trxId": "569023",
    "responseCode": "-1",
    "responseDesc": "Success"
  },
  "discount": [
    { "name": "API Voucher Documentation", "amount": 10000 }
  ],
  "redemptions": [
    {
      "description": "API Voucher Documentation",
      "processedAmount": 10000,
      "type": "VOUCHER",
      "vspId": 20016
    }
  ],
  "responseCode": "-1",
  "responseDesc": "Success"
}
Step 2: Advise Request
# Step 2: Finalize the transaction (FINALISE or REVERSE)
curl -X POST "https://rad2.wigroup.co:8181/wigroup-transactionengine/pos-providers/advise" \
  -H "id: POS_ID" \
  -H "password: POS_PASSWORD" \
  -H "apiServerVersion: 1.14" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "FINALISE",
    "originalTrx": {
      "wiTrxId": 431711,
      "type": "PAYMENT",
      "storeTrxDetails": {
        "retailerId": 999,
        "storeId": 1050,
        "trxId": "12345"
      }
    }
  }'
Key Response Fields
  • Returns discount amount to apply
  • Partial redemptions supported
  • Includes transaction ID for advise
Important Notes
  • Always send Advise after Transaction
  • Use REVERSE if order is cancelled
  • Handle partial redemptions gracefully

Seamless Experience: When the customer enters their wiCode, the Transaction Request returns the discount amount instantly. Apply this to the basket and let the customer pay the remainder with their preferred payment method.

Ready to integrate?

Contact our integration team to get your API credentials and sandbox access.

Get API Access