Order

Order management APIs

1. The Order Object

id string
Unique identifier for the order.

referenceId string
Idempotency key from source system.

status string
Order status. Values: SUCCESS, FAILED, PROCESSING, CANCELLED, REVERSED

vouchers Voucher[] nullable
List of vouchers. See Voucher object.

failureReason string nullable
Error message. Only populated when order status is FAILED.

2. The Voucher Object

id string
Unique identifier for the voucher.

cardType string
Type of card. Values: CARD_NUMBER_SECURED, PIN_NO_SECURED, CARD_AND_PIN_NO_SECURED

cardPin string
PIN for the voucher.

cardNumber string
Card number for the voucher.

validTill date nullable
Expiry date of the voucher. Format: YYYY-MM-DD

amount number
Voucher amount.

3. Place an Order

Endpoint: /v1/partners/orders
Description: API to generate voucher.
- If vouchers are successfully generated, the status will be SUCCESS and the vouchers list will contain voucher data.
- If status is PROCESSING the voucher generation is taking time and the status can be polled by the client / hubble can intimate the client using the Order reached terminal state - Webhook.
- In case of status PROCESSING voucher list will be empty.
- Partners manage voucher distribution to end customers, by default. Alternatively, Hubble can also handle voucher delivery. For this, partners need to send recipientDetails in the place order API. For this service option, please reach out to our business team.
Method: POST

Request Body

productId string
ID of the brand/product to order.

referenceId string
Idempotency key from source system.

amount number
Total order amount.

denominationDetails object[]
List of denomination and quantity pairs.

Show child attributes

denominationDetails[].denomination number
Denomination value.

denominationDetails[].quantity integer
Quantity of this denomination.

customerDetails object
Customer information.

Show child attributes

customerDetails.name string
Customer name.

customerDetails.phoneNumber string
Customer phone number.

customerDetails.email string
Customer email address.

deliveryDetails object optional
Voucher delivery details. Required only if Hubble handles voucher delivery.

Show child attributes

deliveryDetails.recipientName string optional
Name of the recipient.

deliveryDetails.recipientType string
Recipient type. Values: SELF, OTHER

deliveryDetails.recipientPhoneNumber string
Recipient phone number.

deliveryDetails.senderName string optional
Name of the sender.

deliveryDetails.wishMessage string optional
Personalized message for the recipient.

Example:

{
    "productId": "brand_id",
    "referenceId": "idempotency key from source system",
    "amount": 1000,
    "denominationDetails": [
        {
            "denomination": 500,
            "quantity": 2
        }
    ],
    "customerDetails": {
        "name": "Hubble User",
        "phoneNumber": "9999999999",
        "email": "example@gmail.com",
    },
    //optional
    "deliveryDetails": {
        "recipientName": "Recipient User", //Optional
        "recipientType": "SELF/OTHER",
        "recipientPhoneNumber": "9999999999",
        "senderName": "Sender Name", //Optional
        "wishMessage": "A gift for you!", //Optional
    }
}

Response Body

Returns The Order Object.

Example:

{
  "id": "order_id",
  "referenceId" : "idempotency key from source system",
  "status": "SUCCESS/FAILED/PROCESSING/REVERSED",
  "vouchers": [
        {
            "id": "voucher_id",
            "cardType" : "PIN_SECURED/CARD_NO_AND_PIN",
            "cardPin": "112233",
            "cardNumber": "2359481287412",
            "validTill": "2022-11-22",
            "amount": "500"
        },
        {
            "id": "voucher_id",
            "cardType" : "PIN_SECURED/CARD_NO_AND_PIN",
            "cardPin": "112233",
            "cardNumber": "2359481287412",
            "validTill": "2022-11-22",
            "amount": "500"
        }
    ],
  "failureReason": "Error message",//Optional
}

4. Get an Order

Endpoint: /v1/partners/orders/:orderId OR / /v1/partners/orders/by-reference/:referenceId
Description: Get the order details based on order ID or reference ID
Method: GET

Response Body

Returns The Order Object.

Example:

{
    "id": "order_id",
    "referenceId" : "idempotency key from source system",
    "status": "SUCCESS/FAILED/PROCESSING/REVERSED",
    "vouchers": [
        {
            "id": "voucher_id",
            "cardType" : "PIN_SECURED/CARD_NO_AND_PIN",
            "cardPin": "112233",
            "cardNumber": "2359481287412",
            "validTill": "2022-11-22",
            "amount": "100"
        },
        {
            "id": "voucher_id",
            "cardType" : "PIN_SECURED/CARD_NO_AND_PIN",
            "cardPin": "112233",
            "cardNumber": "2359481287412",
            "validTill": "2022-11-22",
            "amount": "100"
        }
    ]
    "failureReason": "Error message",//Optional
}

5. Get a Voucher

Endpoint: /v1/partners/orders/vouchers/:id
Description: Get details of individual voucher.
Method: GET

Response Body

Returns The Voucher Object.

Example:

{
    "id": "voucher_id",
    "cardType": "PIN_SECURED/CARD_NO_AND_PIN",
    "cardPin": "112233",
    "cardNumber": "2359481287412",
    "validTill": "2022-11-22",
    "amount": "100"
}

6. Retry Voucher Delivery

Endpoint: /v1/partners/orders/:orderId/resend-delivery
Description: Retrigger voucher details delivery to the user. You can target specific communication channels.
Method: POST

Note: Channel availability is determined by the details provided during order creation. EMAIL requires a valid customerDetails.email, and SMS or WHATSAPP requires a valid customerDetails.phoneNumber or deliveryDetails.recipientPhoneNumber.

Request Body

channels string[]
List of communication channels to use. Values: EMAIL, SMS, WHATSAPP

Example:

{
    "channels": ["EMAIL", "SMS"]
}

Response Body

success boolean
Indicates if the resend request was accepted.

message string
Status message.

Example:

{
    "success": true,
    "message": "Voucher details resent successfully"
}