Hybrid Service Model

The Hawk Marketplace APIs support an asynchronous request-response model for most resources. This is more accurately referred to as a hybrid synchronous-asynchronous model, where response behavior may be either synchronous or asynchronous depending on current processing load, request complexity, and input from your client application. That client input takes the form of a millisecondsToWait parameter indicating how long your client application is willing to wait for a response. A Response object or Error object (if the operation was unsuccessful) will be returned within that time frame. If the request is still in process, the interaction becomes asynchronous.

This hybrid synchronous-asynchronous model provides for an additional measure of availability and scalability at the server level, and resilience and performance for your client application. Adjust the millisecondsToWait value to suit the needs of your application while following Blackhawk Network best practices.

• A millisecondsToWait value of 0 causes your request to be validated, queued for processing and a response returned immediately. These requests will always be treated asynchronously.
• If omitted, the value of millisecondsToWait defaults to 2000 (2 seconds).
• The maximum value of millisecondsToWait is 30000 (30 seconds).

📘

The recommended minimum value for the millisecondsToWait header is 15000 (15 seconds).

Example

To illustrate the asynchronous request-response model, consider the following submitOpenLoopAnonymous request:

Content-Type: application/json
merchantId: 60300003779
requestId: 2019-08-21T15:21:45-0600
millisecondsToWait: 20000

POST: https://apipp.blackhawknetwork.com/rewardsOrderProcessing/v1/submitOpenLoopAnonymous

{
    "clientProgramNumber": "43240104",
    "paymentType": "ACH_DEBIT",
    "poNumber": "A887622-B1",
    "orderDetails": [{
        "description": "test",
        "clientRefId": "ABC0001",
        "fourthLineEmbossText": "Congratulations on your award!",
        "cardCarrierMessage": "Congratulations on your award!",
        "shippingMethod": "UPS_GROUND", 
        "amount": "25",        
        "deliveryAddress": {
            "company": "company",
            "line1": "line1",
            "line2": "line2",
            "line3": "line3",
            "city": "St Louis",
            "region": "MO",
            "postalCode": "63368",
            "postalCodeExt": "",
            "country": "USA"
        }
        "quantity": 3,        
    }]
}

The millisecondsToWait HTTP header value indicates your client application is willing to wait up to twenty seconds for a response. On receipt, the server validates the request. If parameters are missing or invalid, an ErrorResponse object is immediately returned. Otherwise, the request is queued for processing. Within the wait period, the server checks for completion.

If the submitOpenLoopAnonymous operation has completed before the expiration of the specified millisecondsToWait time, a response object is returned and the operation completed synchronously.

{
    "transactionId": "D6R6K64BYKHWWGGZQP57XRT1SC",
    "isCompleted": true,
    "percentComplete": 100,
    "success": true,
    "orderNumber" : "123456789"
}

Note that isCompleted is true, percentComplete is 100, and the success property indicates a final status for this request.

If the submitOpenLoopAnonymous operation has NOT completed before the expiration of the specified millisecondsToWait time a response object is returned at the expiration time indicating the request will be completed asynchronously.

{
    "transactionId": "D6R6K64BYKHWWGGZQP57XRT1SC",
    "isCompleted": false,
    "percentComplete": 66,
    "success": false
}

When this happens the transaction becomes asynchronous. You need to wait some time and then make an HTTP GET request to the orderInfo API to see if the order has completed processing.

The response to this GET request will indicate the current processing status for the order.

For more information review the orderInfo API.