Yoyo Developer Portal

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.

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

Standard Transaction

For customers already registered in the system:

POST /api/earngateway/channel/events/transactional

# Card-Linked: Send transaction with card token
curl -X POST "https://api.yoyogroup.com/api/earngateway/channel/events/transactional" \
  -H "X-consumer-id: YOUR_CONSUMER_ID" \
  -H "apiKey: YOUR_API_KEY" \
  -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"
    }
  }'

Response: 200 Success

Card recognized. Cash back or instant rewards awarded.

Response: 404 Not Found

Card not registered. Proceed to registration flow.

Registration Flow

When response is 404, capture customer's mobile number and resend:

POST with msisdn field added

# Card-Linked: Register new card with mobile number
curl -X POST "https://api.yoyogroup.com/api/earngateway/channel/events/transactional" \
  -H "X-consumer-id: YOUR_CONSUMER_ID" \
  -H "apiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "f452020a-ef77-47e2-93dd-2ede566f3d02",
    "amount": 2000,
    "customer": {
      "type": "ALIAS",
      "reference": "760e2e3c-2489-4158-aa7c-b097dacbf7c1",
      "msisdn": "+27841234567"
    },
    "store": {
      "type": "WIGROUP",
      "reference": "123469"
    }
  }'

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

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://api.yoyogroup.com/api/earngateway/channel/events/transactional" \
  -H "X-consumer-id: YOUR_CONSUMER_ID" \
  -H "apiKey: YOUR_API_KEY" \
  -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://api.yoyogroup.com/api/earngateway/channel/events/transactional" \
  -H "X-consumer-id: YOUR_CONSUMER_ID" \
  -H "apiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order-12345",
    "amount": 5000,
    "customer": {
      "type": "USERREF",
      "reference": "+27841234567",
      "msisdn": "+27841234567"
    },
    "store": {
      "type": "WIGROUP",
      "reference": "123469"
    }
  }'

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