Loyalty Earn Gateway

Enable loyalty integration for cash back or instant rewards

Which Integration Should I Use?

Choose your integration model based on how you identify customers:

If you identify users by	Use this model	Best for
Bank card or payment token	`Card-Linked Earn`	Banks, terminals, payment networks
Mobile number or user account	`User-Referenced Earn`	eCommerce, apps, POS systems

Card-Linked Earn

For banks, terminals, and payment networks using tokenized cards

Customer identity is derived from a tokenized bank card. When a transaction occurs, you send the card token (ALIAS) and the loyalty platform automatically rewards the customer.

Key Concept

The payment instrument identifies the customer.

Scope of the ALIAS: The ALIAS is the persistent identifier used to recognise the customer's payment card. The same card must produce the same ALIAS consistently across all participating stores within a retailer group. If the value differs from store to store, the same card is seen as a new card at each one and the customer will not be recognised.

Integration Flow

1Customer registers bank card with partner or issuing bank
2Card is tokenized and stored as an ALIAS
3At transaction, partner sends ALIAS to Earn Gateway
4Platform resolves card to customer and awards cash back or instant rewards

End to end, including what happens when the card is not yet registered:

Payment Partner

Yoyo

Earn Gateway

Customer

1Transaction processed

2Payment notification (card ALIAS)

3Card registered?

Card registered — 200 OK

4Allocate loyalty points

5Notify loyalty earned

Card not registered — 400, error 0103

4Prompt for mobile number (MSISDN)

5Provide MSISDN

6Payment notification (card ALIAS + MSISDN)

7Create or match user profile

8Allocate loyalty points

9Notify loyalty earned + app link

Request Response Yoyo-side action

Standard Transaction

To confirm whether a card is already registered and, if so, automatically award loyalty:

POST /api/earngateway/channel/events/transactional

# Card-Linked: Send transaction with card token
curl -X POST "https://xx-vsp-int.wigroup.co/api/earngateway/channel/events/transactional" \
  -H "X-consumer-id: YOUR_CONSUMER_ID" \
  -H "apiKey: {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "f452020a-ef77-47e2-93dd-2ede566f3d01",
    "amount": 2000,
    "customer": {
        "type": "ALIAS",
        "reference": "760e2e3c-2489-4158-aa7c-b097dacbf7c1"
    },
    "store": {
        "type": "WIGROUP",
        "reference": "123469"
    }
}'

Transaction Amount: The amount is in cents, never rands (above, 2000 = R20.00), and must exclude tips and gratuities — send the purchase value only.

Response: 200 Success

Card recognized. Cash back or instant rewards awarded.

Response: 400 Bad Request

Card not registered — error code 0103 (Customer does not exist). Proceed to registration flow.

Registration Flow

A 400 response always returns the 0103 error. Some offerings also support a self-service registration flow — where that is supported, we return a registrationUrl on the error object:

Response: 400 Bad Request

{
  "errors": [
    {
      "code": "0103",
      "message": "Customer does not exist.",
      "registrationUrl": "https://yoyorewards.register.com/<jwtToken>"
    }
  ]
}

Depending on what your offering supports, the customer can register in one of two ways:

Option 1 — Enter mobile number on the terminal (always available)

Capture the customer's mobile number and resend the same request — identical reference — with the msisdn field added:

POST with msisdn field added

# Card-Linked: Register new card — reuse the reference from the original lookup request
curl -X POST "https://xx-vsp-int.wigroup.co/api/earngateway/channel/events/transactional" \
  -H "X-consumer-id: YOUR_CONSUMER_ID" \
  -H "apiKey: {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "f452020a-ef77-47e2-93dd-2ede566f3d01",
    "amount": 2000,
    "customer": {
        "type": "ALIAS",
        "reference": "760e2e3c-2489-4158-aa7c-b097dacbf7c1",
        "msisdn": "+27841234567"
    },
    "store": {
        "type": "WIGROUP",
        "reference": "123469"
    }
}'

Reuse the original reference: The top-level reference must be the same value you sent in the initial lookup request — it links the registration back to that transaction. Generating a new reference here is a common integration error. Note this is distinct from customer.reference (the card ALIAS), which is also unchanged.

Mobile Number Format: Must be in international format (e.g., +27841234567). Yoyo will create the account and link the card.

Option 2 — Scan the QR code (where supported)

Display the registrationUrl from the 400 response as a QR code. The customer scans it and completes registration on their own device — no further API call is required from you. Useful where entering a mobile number on the terminal isn't practical.

This field is only returned where self-service registration is supported. Check whether errors[0].registrationUrl is present in the response before offering this option, and fall back to Option 1 if it is absent.

Adding Another Card to an Existing Customer

A customer who is already registered but pays with a new card returns the same 400 and error 0103 as a brand-new customer. The response means the card is unrecognised, not the customer — so there is no separate endpoint or flow for this case. Use the registration flow above to add the new card to the existing customer account.

Reuse the original reference. Capture the customer's mobile number and resend with msisdn added. Yoyo matches the mobile number to the existing account and associates the additional card with it, rather than creating a second customer. A customer can have several cards linked to one account this way.

User-Referenced Earn

For eCommerce, apps, and POS systems using mobile or User ID

Customer identity is provided directly by the partner using a user reference (mobile number, user ID, email, etc.). You send this reference with the transaction details and the loyalty platform automatically rewards the customer.

Key Concept

The partner account identifies the customer.

Integration Flow

1Partner identifies user in their system (mobile number, user ID, email, etc.)
2At checkout or purchase completion, partner calls Earn Gateway API
3Request includes user reference and transaction details
4Platform resolves user and awards cash back or instant rewards

Transaction Examples

Send transaction with user reference:

Using User ID:

POST with USERREF type

# User-Referenced: Send transaction with user ID
curl -X POST "https://xx-vsp-int.wigroup.co/api/earngateway/channel/events/transactional" \
  -H "X-consumer-id: YOUR_CONSUMER_ID" \
  -H "apiKey: {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order-12345",
    "amount": 5000,
    "customer": {
        "type": "USERREF",
        "reference": "+27841234567"
    },
    "store": {
        "type": "WIGROUP",
        "reference": "123469"
    }
}'

Using Mobile Number:

POST with mobile as USERREF

# User-Referenced: Send transaction with mobile number
curl -X POST "https://xx-vsp-int.wigroup.co/api/earngateway/channel/events/transactional" \
  -H "X-consumer-id: YOUR_CONSUMER_ID" \
  -H "apiKey: {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order-12345",
    "amount": 5000,
    "customer": {
        "type": "USERREF",
        "reference": "+27841234567",
        "msisdn": "+27841234567"
    },
    "store": {
        "type": "WIGROUP",
        "reference": "123469"
    }
}'

Transaction Amount: The amount is in cents, never rands (above, 5000 = R50.00), and must exclude tips and gratuities — send the purchase value only.

Response: 200 Success

User found. Cash back or instant rewards awarded automatically.

Store Identification

Both models support two store identifier options

WIGROUP Type

Use Yoyo's internal store identifiers (provided by Yoyo)

Store Object

# Using Yoyo's internal store identifier
"store": {
  "type": "WIGROUP",
  "reference": "yoyo123469"
}

REMOTE Type

Use your own store identifiers (Yoyo will map them)

Store Object

# Using your own store identifier
"store": {
  "type": "REMOTE",
  "reference": "paymentpartner567x"
}

Common Error Codes

Code	Message
0103	Customer does not exist
0127	Mobile number is invalid
0126	Transaction amount is invalid
0109	Store not present or not linked to channel
0100	Store ID is required
0128	Maximum payment cards reached for account

Handling Downtime

In the unlikely event the Earn Gateway is unavailable:

Store and Forward: Queue loyalty requests locally and forward once service is restored
Customer Messaging: Display "Loyalty service temporarily unavailable. Rewards will be applied once restored."

Basket Data Support

The Earn Gateway API supports an optional basket data object for product-level rewards. Contact your Yoyo integration manager for SKU-level reward configuration.