Currency Engine (Hubble Managed)

Hubble's managed coin system provides a complete solution for your digital coin wallets. Credit coins to users, debit coins for purchases, and track all transactions with full audit trails.

This is ideal if you don't have your own in-app currency infrastructure and want to quickly implement a robust currency system.

Base URLs

Environment	Base URL
Development	https://api.dev.myhubble.money
Production	https://api.myhubble.money

Authentication

All API requests require authentication using a Bearer token obtained from the login API.

Required Headers:

Header	Description	Required
Authorization	Bearer token obtained from login API	Yes
Content-Type	application/json	Yes
X-Request-Id	Request tracking ID	Recommended

---

Endpoints

1. Get Coin Balance

Retrieve the coin balance for a specific user.

GET/v1/partners/coins/{userId}/balance

Path Parameters:

Parameter	Type	Description
userId	string	Your unique user identifier

Response (200 OK):

{
  "userId": "USR-001",
  "available": 1500.00,
  "held": 0.00,
  "consumed": 500.00,
  "expired": 100.00,
  "total": 1500.00
}

Response Fields:

Field	Type	Description
userId	string	User identifier
available	decimal	Coins available for use
held	decimal	Coins reserved (for future use)
consumed	decimal	Total coins spent
expired	decimal	Total coins expired
total	decimal	Sum of available + held

---

2. Credit Coins

Credit coins to a user's wallet.

POST/v1/partners/coins/credit

Request Body:

{
  "userId": "USR-001",
  "idempotencyKey": "REWARD-2025-Q1-001",
  "amount": 500.00,
  "remarks": "Q1 Performance Bonus",
  "expiresOn": "2025-12-31"
}

Request Fields:

Field	Type	Required	Description
userId	string	Yes	Your unique user identifier
idempotencyKey	string	Yes	Unique key to prevent duplicates
amount	decimal	Yes	Coins to credit (> 0)
remarks	string	No	Transaction notes
expiresOn	date	No	Expiry date (YYYY-MM-DD). Uses default if not provided

Response (201 Created):

{
  "transactionId": "01HKXYZ123ABC456DEF789GHI",
  "userId": "USR-001",
  "type": "CREDIT",
  "status": "SUCCESS",
  "amount": 500.00,
  "remarks": "Q1 Performance Bonus",
  "transactedAt": "2025-01-16T10:30:00",
  "expiresOn": "2025-12-31"
}

---

3. Bulk Credit Coins

Credit coins to multiple users in a single request. Maximum 100 credits per request.

POST/v1/partners/coins/bulk-credit

Request Body:

{
  "credits": [
    {
      "userId": "USR-001",
      "idempotencyKey": "WELCOME-2025-001",
      "amount": 100.00,
      "remarks": "Welcome bonus",
      "expiresOn": "2025-12-31"
    },
    {
      "userId": "USR-002",
      "idempotencyKey": "WELCOME-2025-002",
      "amount": 150.00,
      "remarks": "Referral reward"
    }
  ]
}

---

4. Debit Coins

Debit coins from a user's wallet. Coins are consumed in FIFO order (oldest expiring coins first).

POST/v1/partners/coins/debit

Request Body:

{
  "userId": "USR-001",
  "idempotencyKey": "ORDER-2025-ORD456",
  "amount": 200.00,
  "remarks": "Gift card purchase"
}

Response (200 OK):

{
  "transactionId": "01HKXYZ123ABC456DEF789GHI",
  "userId": "USR-001",
  "type": "DEBIT",
  "status": "SUCCESS",
  "amount": 200.00,
  "remarks": "Gift card purchase",
  "transactedAt": "2025-01-16T10:30:00"
}

---

5. Reverse Transaction

Reverse a completed (SUCCESS) transaction.

POST/v1/partners/coins/reverse

Request Body:

{
  "transactionId": "01HKXYZ123ABC456DEF789GHI",
  "reason": "Order refund"
}

Reversal Behavior:

• CREDIT reversed: Deducts coins from available balance. Only allowed if coins are fully intact (not consumed or expired).
• DEBIT reversed: Restores coins back to available balance.

---

6. Get Transaction History

Retrieve transaction history for a user with optional filtering.

GET/v1/partners/coins/{userId}/transactions

Query Parameters:

Parameter	Type	Default	Description
type	enum	All	Filter: CREDIT or DEBIT
pageNo	integer	0	Page number (0-indexed)
limit	integer	20	Page size (max: 100)

---

Transaction States

Status	Description
SUCCESS	Transaction completed successfully
REVERSED	Completed transaction has been reversed

---

Error Responses

{
  "code": "INSUFFICIENT_BALANCE",
  "message": "Insufficient balance. Required: 200.00, Available: 150.00",
  "requestId": "req-abc123"
}

Common Error Codes

Code	HTTP Status	Description
INVALID_INPUT	400	Request validation failed
INSUFFICIENT_BALANCE	400	Not enough coins for debit
ENTITY_NOT_FOUND	404	User, transaction, or resource not found
INVALID_OPERATION	400	Operation not allowed for current state
UNAUTHORIZED	401	Invalid credentials
INTERNAL_ERROR	500	Server error

---

Best Practices

1. Use Descriptive Idempotency Keys

Format your keys for easy tracking:

{TYPE}-{DATE}-{UNIQUE_ID}

Examples:

• WELCOME-2025-Q1-USR001
• REWARD-20250116-USR042
• REFUND-ORDER123-USR007

2. Store Transaction IDs

Always store transaction IDs for reconciliation, reversals, and support inquiries.

3. Set Appropriate Expiry Dates

Setting expiry dates creates urgency for users to spend coins and manages your liability.

4. Check Balance Before Debit

Provide better UX by checking balance before attempting debit.

---

Rate Limits

Endpoint	Limit
All endpoints	1000 requests/minute per client
Bulk credit	100 credits per request
Transaction history	100 records per page (max limit)