Skip to main content

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