Bulk Personalized Prepaid Card Orders

Introduction

Bulk ordering allows you to acquire multiple prepaid cards to distribute directly. In this guide we will be placing an order for three $25 Visa® prepaid cards for specific recipients.

📘

Want to skip the details? Jump right to the full order JSON

Placing the Prepaid Card Order

To place our order we will be using submitOpenLoopPersonalizedBulk.

Method

Service

API

Type

POST

rewardsOrderProcessing

submitOpenLoopPersonalizedBulk → Explore

Hybrid synchronous/asynchronous based on millisecondToWait parameter.

URI: https://apipp.blackhawknetwork.com/rewardsOrderProcessing/v1/submitOpenLoopPersonalizedBulk

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). This identifier will be used during reconciliation. The requestId must be unique with 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: 60300004707
requestId: 2019-02-21T16:29:11-0600
millisecondsToWait: 30000

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.

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,
WIRE_TRANSFER,
DRAW_DOWN

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.

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 Id 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 order.

Object

Yes

Valid Recipient Object

fourthLineEmbossText

Information to include on the fourth line of the card (for supported product applications). Must be 21 characters or less.

String

No

Digits 0-9, alpha (a-z, A-Z), space, period, comma, and hyphen.

amount

Specify the value for the 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

Indicative data. Must be 40 characters or less.

String

No

Digits 0-9, alpha (a-z, A-Z), space and period.

cardCarrierMessage

Message to print on the card carrier (for supported product applications). Must be 80 characters or less.

String

No

Digits 0-9, alpha (a-z, A-Z), space, period, comma, and hyphen.

shippingMethod

Specify which shipping method should be used for this order. Must be one of the accepted value.

String

No

UPS_SECOND_DAY,
UPS_NEXT_DAY,
DHL_INTERNATIONAL,
UPS_GROUND,
USPS_SECOND_DAY,
USPS_NEXT_DAY

deliveryAddress

Specify the address this bulk order will be delivered to.

Object

Yes

Valid deliveryAddress object

Providing the Recipient Information

We need to provide information for each prepaid card recipient.

Parameter

Description

Type

Required

Allowed Values

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.

id

Must be 30 characters or less.

String

No

Digits 0-9, Alpha (a-z, A-Z) and period.

prefix

Prefix must be 5 characters or less.

String

No

Mr
Mrs
Miss
Ms
Blank (empty string)

middleName

Middle name of the recipient. 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)

address

Recipient address information.

Object

Yes

Valid address object

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

email

Recipient email address. Must be 50 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.

Providing the Recipient Address Information

We need to provide the address for each recipient:

Parameter

Description

Type

Required

Allowed Values

line1

First line of the recipient 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 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 or a Canadian province or contain an international region less than 36 characters.

String

Yes

A valid 2-character uppercase abbreviation for a U.S. state or a Canadian province or contain an international region less than 36 characters.

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": "1400 South Highway Drive",
    "line2": "Suite B",
    "line3": "Attn To: Mickey Mouse",
    "city": "Fenton",
    "region": "MO",
    "postalCode": "63099",
    "postalCodeExt": "",
    "country": "USA"
},

Combining that with the rest of the recipient information gives us the following JSON:

"recipient": {
    "prefix": "Mrs",
    "firstName": "Daffy",
    "middleName": "S",
    "lastName": "Duck",
    "suffix": "",
    "address": {
        "line1": "1400 South Highway Drive",
        "line2": "Suite B",
        "line3": "Attn To: Mickey Mouse",
        "city": "Fenton",
        "region": "MO",
        "postalCode": "63099",
        "postalCodeExt": "",
        "country": "USA"
    },
    "phoneNumber": "6362262000",
    "email": "[email protected]"
},

Providing the Order Delivery Address Information

We need to provide the delivery address for this order. All cards within this order with the same order line item delivery address will be delivered in bulk to the address provided. Note: you may provide multiple different bulk delivery addresses for different line items.

Parameter

Description

Type

Required

Allowed Values

company

Company name must be 35 characters or less.

String

Yes

Digits 0-9, alpha (a-z, A-Z), space period, comma and hyphen.

firstName

First name to be used on the bulk delivery shipping label.

This must be 25 characters or less.

Allowed characters: ^[A-Za-z0-9 ,.'-]+

String

Yes

Digits 0-9, alpha (a-z, A-Z), space period, comma and hyphen.

lastName

Last name to be used on the bulk delivery shipping label.

This must be 25 characters or less.

Allowed characters: ^[A-Za-z0-9 ,.'-]+

String

Yes

Digits 0-9, alpha (a-z, A-Z), space period, comma and hyphen.

line1

First line of the delivery address. This must be 35 characters or less.

Note: PO Boxes are not allowed and will be rejected.

String

Yes

Digits 0-9, alpha (a-z, A-Z), space, period. comma, hyphen, forward slash (/), and apostrophe.

line2

Second line of the delivery 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 35 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 or a Canadian province or contain an international region less than 36 characters.

String

Yes

A valid 2-character uppercase abbreviation for a U.S. state or a Canadian province or contain an international region less than 36 characters.

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.

Combining the delivery address information with our recipient address information gives us:

"orderDetails": [{
    "recipient": {
        "prefix": "Mrs",
        "firstName": "Daffy",
        "middleName": "S",
        "lastName": "Duck",
        "suffix": "",
        "address": {
            "line1": "1400 South Highway Drive",
            "line2": "Suite B",
            "line3": "Attn To: Mickey Mouse",
            "city": "Fenton",
            "region": "MO",
            "postalCode": "63099",
            "postalCodeExt": "",
            "country": "USA"
        },
        "phoneNumber": "6362262000",
        "email": "[email protected]"
    },
    "amount": "25",
    "deliveryAddress": {
        "company": "Blackhawk Network",
        "firstName": "Walt",
        "lastName": "Disney",
        "line1": "700 State Highway 121 Bypass",
        "line2": "Ste. 200",
        "line3": "",
        "city": "Lewisville",
        "region": "TX",
        "postalCode": "75010",
        "postalCodeExt": "",
        "country": "USA"
    }
}]

In this example we're placing three orders so we need to include all the information for each recipient. Since we're shipping them all to the same address we use the same information for each deliveryAddress object.

"orderDetails": [{
    "recipient": {
        "prefix": "Mrs",
        "firstName": "Daffy",
        "middleName": "S",
        "lastName": "Duck",
        "suffix": "",
        "address": {
            "line1": "1400 South Highway Drive",
            "line2": "Suite B",
            "line3": "Attn To: Mickey Mouse",
            "city": "Fenton",
            "region": "MO",
            "postalCode": "63099",
            "postalCodeExt": "",
            "country": "USA"
        },
        "phoneNumber": "6362262000",
        "email": "[email protected]"
    },
    "amount": "25",
    "deliveryAddress": {
        "company": "Blackhawk Network",
        "firstName": "Walt",
        "lastName": "Disney",
        "line1": "700 State Highway 121 Bypass",
        "line2": "Ste. 200",
        "line3": "",
        "city": "Lewisville",
        "region": "TX",
        "postalCode": "75010",
        "postalCodeExt": "",
        "country": "USA"
    }
},
{
    "recipient": {
        "prefix": "Mr",
        "firstName": "Mickey",
        "middleName": "K",
        "lastName": "Mouse",
        "suffix": "Jr",
        "address": {
            "line1": "4444 Centerville Rd",
            "line2": "",
            "line3": "",
            "city": "White Bear Lake",
            "region": "MN",
            "postalCode": "55127",
            "postalCodeExt": "",
            "country": "USA"
        },
        "phoneNumber": "5551234567",
        "email": "[email protected]"
    },
    "amount": "25",
    "deliveryAddress": {
        "company": "Blackhawk Network",
        "firstName": "Walt",
        "lastName": "Disney",
        "line1": "700 State Highway 121 Bypass",
        "line2": "Ste. 200",
        "line3": "",
        "city": "Lewisville",
        "region": "TX",
        "postalCode": "75010",
        "postalCodeExt": "",
        "country": "USA"
    }
},
{
    "recipient": {
        "prefix": "Mr",
        "firstName": "Abraham",
        "middleName": "B",
        "lastName": "Lincoln",
        "suffix": "Jr",
        "address": {
            "line1": "1630 Stapley Drive",
            "line2": "Suite 217",
            "line3": "",
            "city": "Mesa",
            "region": "AZ",
            "postalCode": "85204",
            "postalCodeExt": "",
            "country": "USA"
        },
        "phoneNumber": "4806359400",
        "email": "[email protected]"
    },
    "amount": "25",
    "deliveryAddress": {
        "company": "Blackhawk Network",
        "firstName": "Walt",
        "lastName": "Disney",      
        "line1": "700 State Highway 121 Bypass",
        "line2": "Ste. 200",
        "line3": "",
        "city": "Lewisville",
        "region": "TX",
        "postalCode": "75010",
        "postalCodeExt": "",
        "country": "USA"
    }
}]

Submitting the Order

Now we will go ahead and place the order with the JSON we have assembled.

{
  "clientProgramNumber": "43240104",
  "poNumber": "12345678",
  "paymentType": "ACH_DEBIT",
    "orderDetails": [{
        "recipient": {
            "prefix": "Mrs",
            "firstName": "Daffy",
            "middleName": "S",
            "lastName": "Duck",
            "suffix": "",
            "address": {
                "line1": "1400 South Highway Drive",
                "line2": "Suite B",
                "line3": "Attn To: Mickey Mouse",
                "city": "Fenton",
                "region": "MO",
                "postalCode": "63099",
                "postalCodeExt": "",
                "country": "USA"
            },
            "phoneNumber": "6362262000",
            "email": "[email protected]"
        },
        "amount": "25",
        "deliveryAddress": {
            "company": "Blackhawk Network",
            "firstName": "Walt",
            "lastName": "Disney",
            "line1": "700 State Highway 121 Bypass",
            "line2": "Ste. 200",
            "line3": "",
            "city": "Lewisville",
            "region": "TX",
            "postalCode": "75010",
            "postalCodeExt": "",
            "country": "USA"
        }
    },
    {
        "recipient": {
            "prefix": "Mr",
            "firstName": "Mickey",
            "middleName": "K",
            "lastName": "Mouse",
            "suffix": "Jr",
            "address": {
                "line1": "4444 Centerville Rd",
                "line2": "",
                "line3": "",
                "city": "White Bear Lake",
                "region": "MN",
                "postalCode": "55127",
                "postalCodeExt": "",
                "country": "USA"
            },
            "phoneNumber": "5551234567",
            "email": "[email protected]"
        },
        "amount": "25",
        "deliveryAddress": {
            "company": "Blackhawk Network",
            "firstName": "Walt",
            "lastName": "Disney",
            "line1": "700 State Highway 121 Bypass",
            "line2": "Ste. 200",
            "line3": "",
            "city": "Lewisville",
            "region": "TX",
            "postalCode": "75010",
            "postalCodeExt": "",
            "country": "USA"
        }
    },
    {
        "recipient": {
            "prefix": "Mr",
            "firstName": "Abraham",
            "middleName": "B",
            "lastName": "Lincoln",
            "suffix": "Jr",
            "address": {
                "line1": "1630 Stapley Drive",
                "line2": "Suite 217",
                "line3": "",
                "city": "Mesa",
                "region": "AZ",
                "postalCode": "85204",
                "postalCodeExt": "",
                "country": "USA"
            },
            "phoneNumber": "4806359400",
            "email": "[email protected]"
        },
        "amount": "25",
        "deliveryAddress": {
            "company": "Blackhawk Network",
            "firstName": "Walt",
            "lastName": "Disney",          
            "line1": "700 State Highway 121 Bypass",
            "line2": "Ste. 200",
            "line3": "",
            "city": "Lewisville",
            "region": "TX",
            "postalCode": "75010",
            "postalCodeExt": "",
            "country": "USA"
        }
    }]
}

To do that we will make an HTTP POST request to https://apipp.blackhawknetwork.com/rewardsOrderProcessing/v1/submitOpenLoopPersonalizedBulk, 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 bulk mailed to the address we provided.


Did this page help you?