Individual Merchant Gift Card Orders
This method is for ordering merchant gift cards only. If you're trying to order Visa, Mastercard or Discover cards review the Physical Prepaid Cards documentation instead.
Introduction
Individual ordering allows you to order one or many gift cards at the same time that are associated to an individual. Blackhawk Network will mail the gift cards directly to the individual.
In this guide we will be placing an order for two $25 Best Buy® Gift Cards.
Note: Blackhawk Network recommends a maximum of 1,000 order line items per order request. If you have more than 1,000 line items you will need to break your order into multiple order requests of 1,000 records each.
Want to skip the details? Jump right to the full order JSON
Placing the Gift Card Order
To place the individual order we will be using submitClosedLoopIndividual
Method | Service | API | Type |
---|---|---|---|
POST | rewardsOrderProcessing | submitClosedLoopIndividual → Explore | Hybrid synchronous/asynchronous based on millisecondToWait parameter. |
URI: https://apipp.blackhawknetwork.com/rewardsOrderProcessing/v1/submitClosedLoopIndividual
HTTP Header
From our application we need to send the following parameters in the HTTP header:
Parameter | Description | Type | Required | Default Value |
---|---|---|---|---|
merchantId | The Merchant ID (MID) is a string identifier, provided to you by your account manager that varies based on the product type you are ordering. | String | Yes | None |
requestId | A unique identifier for each order provided by you (the caller). The requestId value must be unique for each request and can have a maximum of 50 characters. | String | Yes | None |
millisecondsToWait | Provide a value between 0 - 30000 to indicate how long your application or service will wait for a response. Once this time is exceeded the request will become asynchronous. The recommended value is 15000 (15 seconds). | Integer | No | 2000 |
In our example we will be sending the following values in the header:
Content-Type: application/json
merchantId: 60300003779
requestId: 2019-08-21T14:42:09-0600
millisecondsToWait: 30000
Body Parameters
In the body of the POST request we need to send all the information needed to complete the order:
Parameter | Description | Type | Required | Allowed Values |
---|---|---|---|---|
clientProgramNumber | The client program number supplied by your Account Manager for the program you are placing your order under. | Integer | Yes | Must be a valid client program number / quote number assigned to you. |
financialAccountId | The financial account ID (FAID) specifies the financial account associated with your sub-organization to be used for the order. When a value is provided for the financialAccountId , the paymentType attribute is required.A value for financialAccountId only needs to be provided when there are multiple financial accounts setup for a sub-organization. Your Implementation Project Manager or Account Manager will direct when you need to provide a value in this field. | String | No | The value provided must match a valid financial account ID configured for your sub-organization. |
paymentType | This value in this attribute specifies the payment method to be used for the order. Note: The payment type value provided must match one of the payment types setup on the client program you are placing an order in or your order request will be rejected. | String | No | ACH_DEBIT BANK_TRANSFER DRAW_DOWN |
orderDetails | The products and quantities you wish to order. | Object | Yes | |
poNumber | PO numbers must be 50 characters or less. | String | No | Digits 0-9, alpha (a-z, A-Z), space, period and hyphen. |
Providing the Order Details
We will pass the details for the order in the orderDetails
object:
Parameter | Description | Type | Required | Allowed Values |
---|---|---|---|---|
clientRefId | Unique client reference to identify duplicates. Must be 30 characters or less. | String | No | Digits 0-9, alpha (a-z, A-Z), space, period, comma, hyphen, forward slash (/) and apostrophe. |
recipient | Information about the recipient for this gift card. | Object | Yes | Valid Recipient Object |
amount | Specify the value of the gift card. | Number | Yes | Digits 0-9 and period. May not contain symbols and may have up to two digits after the decimal separator. Example: 25.00 |
description | Must be 40 characters or less. | String | No | Digits 0-9, alpha (a-z, A-Z), space and period. |
fourthLineEmbossText | Fourth line emboss text must be 21 characters or less. | String | No | Digits 0-9, alpha (a-z, A-Z), space, period, comma, and hyphen. |
cardCarrierMessage | Card carrier message must be 80 characters or less. | String | No | Digits 0-9, alpha (a-z, A-Z), space, period, comma, and hyphen. |
shippingMethod | Specify the shipping method to use for this order. | String | No | USPS_FIRST_CLASS DHL_INTERNATIONAL USPS_PRIORITY_MAIL |
contentProvider | This identifier specifies which product you are ordering. | String | No | A valid content provider code as provided by your account manager or returned by the Catalog API. |
Providing the Recipient Information
We need to provide information about each recipient we are delivering a gift card to:
Parameter | Description | Type | Required | Allowed Values |
---|---|---|---|---|
id | Id must be 30 characters or less. | String | No | Digits 0-9, Alpha (a-z, A-Z), period and comma. |
firstName | First name of the recipient, this must be 25 characters or less. | String | Yes | Digits 0-9, alpha (a-z, A-Z), space period, comma and hyphen. |
lastName | Last name of the recipient, this must be 25 characters or less. | String | Yes | Digits 0-9, alpha (a-z, A-Z), space period, comma and hyphen. |
prefix | Prefix must be 5 characters or less. | String | No | Mr Mrs Miss Ms Blank (empty string) |
middleName | Middle name must be 25 characters or less. | String | No | Digits 0-9, alpha (a-z, A-Z), space period, comma and hyphen. |
suffix | Suffix must be 5 characters or less. | String | No | Alpha (a-z, A-Z) |
email | The email address of the individual recipient. Must be 254 characters or less. | String | No | Digits 0-9, alpha (a-z, A-Z), period and hyphen. Format: Must have an @ symbol and at least one period. |
phoneNumber | Recipient phone number. Formatting: (1) Include numbers only, no spaces, hyphens or parenthesis. (2) Must be 10 digits. (3) For North American phone numbers do not include the leading "1". | String | No | Digits 0-9 |
address | Specifying the delivery address for the recipient. | Object | Yes | Valid Address Object. |
Specifying the Recipient Address
We need to provide the address for each card recipient:
Parameter | Description | Type | Required | Allowed Values |
---|---|---|---|---|
line1 | First line of the recipient's address. This must be 35 characters or less. | String | Yes | Digits 0-9, alpha (a-z, A-Z), space, period. comma, hyphen, forward slash (/), and apostrophe. |
line2 | Second line of the recipient's address. This must be 35 characters or less. | String | No | Digits 0-9, alpha (a-z, A-Z), space, period. comma, hyphen, forward slash (/), and apostrophe. |
line3 | Use this to specify an "Attention To:" line. Must be 35 characters or less. | String | No | Digits 0-9, alpha (a-z, A-Z), space, period. comma, hyphen, forward slash (/), colon and apostrophe. |
city | City must be 30 characters or less. | String | Yes | Digits 0-9, alpha (a-z, A-Z), space, period, hyphen, and apostrophe. |
region | Address region must be a valid 2-character uppercase abbreviation for a U.S. state, territory, or military base; a Canadian province; or contain an international region less than 36 characters. | String | Yes | See Accepted Region Abbreviations by Country Code for more information. |
postalCode | Postal code must be 10 characters or less. | String | Yes | Digits 0-9 and alpha (a-z, A-Z). For US addresses this must include the five digit US ZIP Code only. |
postalCodeExt | Postal code extension must be 4 characters or less. | String | No | Digits 0-9 |
country | Country must be the 3 alphabetic ISO code corresponding to the country. | String | Yes | Three character alphabetic ISO code corresponding to the country. |
For example our JSON might look like this:
"address": {
"line1": "700 State Highway 121 Byp",
"line2": "Ste. 200",
"line3": "Attn. To: Minnie Mouse",
"city": "Lewisville",
"region": "TX",
"postalCode": "75067",
"country": "USA"
}
Combining that with the rest of the recipient information gives us the following JSON:
"recipient": {
"firstName": "Mickey",
"lastName": "Mouse",
"address": {
"line1": "700 State Highway 121 Byp",
"line2": "Ste. 200",
"line3": "Attn. To: Minnie Mouse",
"city": "Lewisville",
"region": "TX",
"postalCode": "75067",
"country": "USA"
},
"phoneNumber": "1231231234",
"email": "[email protected]"
}
Combining that with the order line item information gives us:
"orderDetails": [{
"recipient": {
"firstName": "Mickey",
"lastName": "Mouse",
"address": {
"line1": "700 State Highway 121 Byp",
"line2": "Ste. 200",
"line3": "Attn. To: Minnie Mouse",
"city": "Lewisville",
"region": "TX",
"postalCode": "75067",
"country": "USA"
},
"phoneNumber": "1231231234",
"email": "[email protected]"
},
"fourthLineEmbossText": "Congratulations.",
"amount": "25",
"contentProvider": "BestBuy"
}
In this example we're placing two orders so we need to include all the information for each recipient.
"orderDetails": [{
"recipient": {
"firstName": "Mickey",
"lastName": "Mouse",
"address": {
"line1": "700 State Highway 121 Byp",
"line2": "Ste. 200",
"line3": "Attn. To: Minnie Mouse",
"city": "Lewisville",
"region": "TX",
"postalCode": "75067",
"country": "USA"
},
"phoneNumber": "1231231234",
"email": "[email protected]"
},
"fourthLineEmbossText": "Congratulations.",
"amount": "25",
"contentProvider": "BestBuy"
},
{
"recipient": {
"id": "0002",
"prefix": "Mr",
"firstName": "Daffy",
"middleName": "B",
"lastName": "Duck",
"suffix": "",
"address": {
"line1": "4444 Centerville Rd",
"line2": "",
"line3": "Attn. To: Walt Disney",
"city": "White Bear Lake",
"region": "MN",
"postalCode": "55127",
"country": "USA"
},
"phoneNumber": "1231231234",
"email": "[email protected]"
},
"fourthLineEmbossText": "Congratulations.",
"amount": "25",
"contentProvider": "BestBuy"
}]
Submitting the Order
Now we will go ahead and place the order using the JSON we have assembled.
Here is the final JSON object we will be submitting:
{
"clientProgramNumber": "43287998",
"paymentType" : "ACH_DEBIT",
"orderDetails": [{
"recipient": {
"firstName": "Mickey",
"lastName": "Mouse",
"address": {
"line1": "700 State Highway 121 Byp",
"line2": "Ste. 200",
"line3": "Attn. To: Minnie Mouse",
"city": "Lewisville",
"region": "TX",
"postalCode": "75067",
"country": "USA"
},
"phoneNumber": "1231231234",
"email": "[email protected]"
},
"fourthLineEmbossText": "Congratulations.",
"amount": "25",
"contentProvider": "BestBuy"
},
{
"recipient": {
"firstName": "Daffy",
"lastName": "Duck",
"address": {
"line1": "4444 Centerville Rd",
"line2": "",
"line3": "Attn. To: Walt Disney",
"city": "White Bear Lake",
"region": "MN",
"postalCode": "55127",
"country": "USA"
},
"phoneNumber": "1231231234",
"email": "[email protected]"
},
"fourthLineEmbossText": "Congratulations.",
"amount": "25",
"contentProvider": "BestBuy"
}]
}
To submit the order we will make an HTTP POST request to https://apipp.blackhawknetwork.com/rewardsOrderProcessing/v1/submitClosedLoopIndividual
, sending the header parameters as we outlined above, with the complete JSON as reviewed above in the body of the request.
The API will return a response containing an HTTP status code in the header and a JSON object in the body. This response will tell us if the order was successful and if it has been completed or not.
The following HTTP status codes may be returned in the response header.
HTTP Status Code | Meaning | Notes |
---|---|---|
201 | Operation Complete | If isCompleted is not equal to "true" and percentComplete is not 100 check the status of the order before retrieving the codes to ensure it has completed. |
202 | Operation is in Process | If isCompleted is not equal to "true" and percentComplete is not 100 check the status of the order before retrieving the codes to ensure it has completed. |
4XX | Invalid Request | Check the JSON error response provided. In most cases you will find the request had missing information or was formatted improperly. If you have any questions reach out to your Account Manager. |
5XX | System Error | Blackhawk Network encountered an internal error trying to process your order. Reach out to your Account Manager for more information. |
What to do when the order is still processing
If the order is still processing and we have exceeded the millisecondsToWait value (or the maximum timeout of 30 seconds) the JSON in the response returned will indicate that the order has not yet completed and will return the current percent complete. For example we may see a response like this:
{
"transactionId": "435LYTF8GAS6NCB3R9TLCXWY30",
"isCompleted": false,
"percentComplete": 66,
"success": false
}
When this happens the transaction becomes asynchronous. We need to wait some time and then make an HTTP GET request to orderInfo to see if the order has completed processing.
Next steps when the order has completed processing
Assuming our order was placed successfully we receive the following JSON in the response:
{
"transactionId": "435LYTF8GAS6NCB3R9TLCXWY30",
"isCompleted": true,
"percentComplete": 100,
"success": true,
"orderNumber": "401087290"
}
This indicates we have successfully placed the order. The order will now be processed and the cards mailed to the recipient addresses we provided.
Updated 5 months ago