Coins Integration (Partner Managed)

This guide defines the API contract partners must implement to integrate with Hubble's Coin Redemption System. Once integrated, users can redeem coins on the Hubble platform via your system.

Integrate your existing coin system with Hubble to let users burn their coins for discounts on gift card purchases. You maintain full control of your coin infrastructure while Hubble handles the gift card transactions.

Do You Need Coins Integration?

The Hubble SDK works in two modes:

1. Plain SDK (no coins): If your app does not have any in-app currency (coins, points, rewards, cashback, etc.), you are using the plain SDK. Gift card purchases are paid entirely through the payment gateway. You can skip this page entirely.

2. SDK with Coins: If your app has its own in-app currency that users should be able to spend on gift card purchases, read on. You will need to build three API endpoints on your backend.

Don't Have Coins Yet but Want Them?

If you don't currently have a coin or rewards system in your app but want to offer one, Hubble provides a managed currency engine. With Currency Engine, Hubble manages the coin infrastructure for you - you don't need to build balance, debit, or reverse APIs. See Hubble Currency Engine to learn more about this option.

Coin Burn Models

We support two primary models for burning coins, which can be configured based on your needs:

1. Coins as Additional Discount

In this model, coins provide an additional discount on top of any existing offers.

Example: A user is buying a voucher that already has a 5% discount, saving them ₹100. If the user has 100 coins, they can use them to get an additional ₹100 off, increasing their total savings.

2. Coins to Enable Discount

In this model, coins are required to unlock the discount in the first place.

Example: A user is buying an Amazon voucher worth ₹1000 with a discount of ₹20. To avail this discount, the user must have and spend at least 20 coins.

The conversion ratio (e.g., 1 coin = ₹1), limits on coin usage, and other rules can be configured from our end.

Base Requirements

Authentication

All requests from Hubble include the following header:

• X-Hubble-Secret — Pre-shared secret provided during onboarding. Must be validated on every request.

Content Type

• All requests and responses must use Content-Type: application/json
• Responses must be valid JSON

HTTPS

• HTTPS is required for all endpoints
• TLS 1.2+ is mandatory

Required APIs

Partners must implement the following endpoints:

• GET /balance — Fetch user coin balance
• POST /debit — Debit coins from user
• POST /reverse — Reverse a previous debit

note

The partner is expected to implement this interface and share the base URL with our team. Our system will invoke the /sso API as well as above API endpoints using the provided base URL.

1. Get Coin Balance

Retrieve the current coin balance for a user.

GET/balance?userId={partnerUserId}

Headers:

• X-Hubble-Secret (required)

Query Parameters:

• userId (string, required) — Partner's user ID

Response (200 OK):

{
  "userId": "partner_user_123",
  "totalCoins": 1500.0
}

Response Fields:

• userId — User identifier
• totalCoins — Available balance

Example:

curl -X GET "https://partner-api.example.com/balance?userId=partner_user_123" \
  -H "X-Hubble-Secret: your-secret-key"

2. Debit Coins

Deduct coins from a user for redemption.

POST/debit

Headers:

• X-Hubble-Secret (required)
• Content-Type: application/json

Request Body:

{
  "userId": "partner_user_123",
  "coins": 500.0,
  "referenceId": "hubble_txn_abc123",
  "note": "Redemption for Amazon Gift Card"
}

Request Body Fields:

• userId (string, required)
• coins (number, required)
• referenceId (string, required) — Used for idempotency
• note (string, optional)

Response (200 OK):

{
  "status": "SUCCESS",
  "transactionId": "partner_txn_789",
  "balance": 1000.0,
  "referenceId": "hubble_txn_abc123"
}

CRITICAL: Implement Idempotency on Debit

Use the referenceId as an idempotency key. If you receive a duplicate debit request with the same reference ID:

1. Do NOT deduct coins again
2. Return the original response with the same transactionId

Hubble may retry debit requests due to network issues. Without idempotency, users could be double-charged.

3. Reverse Debit

Refund coins for a previously debited transaction.

POST/reverse

Headers:

• X-Hubble-Secret (required)
• Content-Type: application/json

Request Body:

{
  "userId": "partner_user_123",
  "referenceId": "hubble_txn_abc123",
  "note": "Redemption cancelled by user"
}

Response (200 OK):

{
  "status": "SUCCESS",
  "transactionId": "partner_txn_rev_456",
  "balance": 1500.0,
  "referenceId": "hubble_txn_abc123"
}

Reversal Idempotency:

• Reversal requests must also be idempotent
• Duplicate reversals must:
  • Return the same response
  • Not credit coins again

---

Advanced Features

Controlling Coin Consumption Eligibility

Some partners need to restrict certain users from spending coins even when they have a non-zero balance — for example, until a KYC check is complete, a cooling period has passed, or some other condition is met on the partner's system.

To support this, the /balance response accepts an optional consumptionEligibility object. When present, Hubble uses it to decide whether to allow the user to apply coins at checkout.

Extended Response (200 OK):

{
  "userId": "partner_user_123",
  "totalCoins": 1500.0,
  "consumptionEligibility": {
    "allowed": false,
    "message": "Complete your KYC to start redeeming coins"
  }
}

consumptionEligibility Fields:

Field	Type	Required	Description
allowed	boolean	Yes	Whether the user can spend coins right now
message	string	No	Human-readable reason shown to the user when allowed is false

Behaviour:

• If consumptionEligibility is omitted, Hubble treats the user as eligible — existing integrations are unaffected.
• If allowed is true, the user can apply coins normally.
• If allowed is false, Hubble hides the coin redemption option and, if message is provided, surfaces it to the user as the reason.

When allowed is true:

{
  "userId": "partner_user_123",
  "totalCoins": 1500.0,
  "consumptionEligibility": {
    "allowed": true
  }
}

Example reasons partners have used:

Scenario	message
KYC not completed	"Complete your KYC to start redeeming coins"
Account under review	"Your account is under review. Coin redemption is temporarily unavailable"
Cooling period active	"Coins unlock after your first repayment"
Subscription inactive	"Renew your subscription to redeem coins"
Minimum activity not met	"Make your first purchase to unlock coin redemption"

note

Eligibility is enforced at checkout display time. Hubble's debit endpoint still performs its own server-side validation — never rely solely on the balance response to gate redemptions.