Coins (Partner Managed)

Integrate your own in-app coin system with Hubble to let users earn discounts on gift card purchases.

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.

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.

Request

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.

Request

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

Idempotency Rules:

referenceId must be unique per transaction
Duplicate referenceId requests must:
- Return the original response
- Not debit coins again

3. Reverse Debit

Refund coins for a previously debited transaction.

Request

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